blitzreels-cli

What this skill does

# BlitzReels CLI

Use this skill when an AI coding agent should control BlitzReels through the installed `blitzreels` command instead of hand-writing REST calls.

The CLI is a creator video-editing control surface. It is not a flat OpenAPI explorer. Prefer it for project-first workflows where the agent needs to browse state, apply edits, verify, and export.

## When To Use This Skill

Use this skill for shell-based BlitzReels work: authenticating the CLI, completing onboarding brand setup, inspecting local or production projects, editing timeline items, adding media/logo/text overlays, adjusting captions, applying preview-first destructive edits, taking snapshots, and exporting.

If a user gives a dashboard project URL and asks an agent to edit or check the video, use this skill first. Inspect with CLI reads before mutating, and verify writes with timeline/context reads or snapshots.

## How To Guide Users

Treat the CLI as an agent control surface, not something the user must memorize. Your job is to run the right commands, explain what changed, and show the user enough context to trust the result.

When introducing the CLI to a user:

1. Explain that the installed `blitzreels` command lets an agent inspect and edit their BlitzReels project from the shell.
2. Do not run package-manager launchers as a fallback. If `blitzreels` is missing, ask the user to download/install the CLI first.
3. Do not make sign-in the first CLI task. Probe with `projects list --status active --json` first; if that fails because the user is signed out, run `auth login`, then retry the same list command.
4. Tell the user whether you are targeting local or production, especially when using `--base-url http://localhost:3000/api/v1`.
5. Use read commands before edits so the user sees you are acting on the right project, timeline item, media asset, caption word, or export.
6. For potentially expensive or irreversible actions, explain the risk and use the CLI's confirmation flags only after the relevant preview or intent is clear.
7. After edits, summarize the exact visible change and the verification command or snapshot used.

Good user-facing explanations are concrete:

- "I found project `PROJECT_ID`, inspected the timeline, and updated caption word `WORD_ID` from `SUpabase` to `Supabase`."
- "I inserted this logo as a media overlay at `6.0s` for `1.6s`, then verified the timeline item exists."
- "The command failed before any API call. The CLI suggested `captions words list`, so I retried that exact command."

Avoid dumping the full command list unless the user asks for docs. Prefer giving the next useful command and why it is the right one.

## Recommended Workflow

Use this loop for most editing tasks:

1. **Require local CLI**: `command -v blitzreels`; if missing, ask the user to download/install it and stop.
2. **Probe session**: run `blitzreels projects list --status active --json` as the first BlitzReels API call.
3. **Authenticate only if needed**: if the probe says signed out, run `blitzreels auth login`, then retry the same `projects list`.
4. **Orient lightly**: prefer `projects get --project-id PROJECT_ID --json` plus `project timeline --project-id PROJECT_ID --json`; use `project inspect --mode full` only when word-level or deep metadata is required.
5. **Select IDs**: list media, text, captions, or timeline items before editing.
6. **Edit**: run the narrowest command that changes only the intended item.
7. **Verify**: inspect timeline/context or render snapshots.
8. **Report**: tell the user what changed, which IDs were touched, and what remains uncertain.

If the user asks a broad question like "check this video", inspect first, then ask what edit they want unless they already gave a concrete edit request.

## Speed Rules

Prefer fewer, narrower calls over one huge inspect. A full inspect can include large per-word caption payloads and slow down simple editing tasks.

- Run independent reads in parallel when the tool environment supports it: project metadata, timeline, text list, media list, audio list, and asset searches do not depend on each other.
- Use subagents only for sidecar work that does not block the next edit, such as searching a large media library, auditing caption overlaps, or downloading/render-checking snapshots. Keep the critical edit path in the main agent.
- Parallelize independent writes only when they touch different item families and do not rely on timeline ordering. Good examples: updating a title text item and adding music. Be more careful with multiple timeline insertions at the same layer/time.
- After attaching B-roll or any media with transcription, immediately re-read `project timeline --json` before continuing. Media attach can import source captions; delete or move unintended imported captions before adding more layers so overlaps do not compound.
- Download multiple snapshot URLs in parallel after the snapshot command returns. Do not fetch them one by one unless the environment lacks parallel tool calls.

## Safety And Consent

Be careful with actions that delete, export, consume credits, overwrite text, or apply destructive timeline edits.

- Use `silence plan` and `mistakes plan` before `apply`.
- Do not pass `--confirm-preview` until the preview/plan has been reviewed.
- Do not pass `--confirm-delete` unless deletion is clearly requested.
- Exports can consume credits and take time; inspect project state before starting one.
- Never paste raw API keys into chat, notes, PRDs, eval outputs, or handoff files.
- If local and production are both plausible, state which one you are using before editing.

When a command fails, first determine whether the failure happened before or after an API call. Validation errors happen locally and are safe to retry with the suggested command. API errors may have already reached BlitzReels; include the request id when reporting them.

## Quick Start

```bash
command -v blitzreels
blitzreels projects list --status active --json
blitzreels api docs
blitzreels api spec
```

If `projects list` reports that the user is signed out:

```bash
blitzreels auth login
blitzreels projects list --status active --json
```

For local development against a running BlitzReels app:

```bash
blitzreels projects list --status active --base-url http://localhost:3000/api/v1 --json
blitzreels auth login --base-url http://localhost:3000/api/v1 # only if the list command reports signed out
blitzreels projects list --status active --base-url http://localhost:3000/api/v1 --json
```

## Auth

Preferred auth flow:

```bash
blitzreels projects list --status active --json
```

If that reports unauthenticated:

```bash
blitzreels auth login
blitzreels projects list --status active --json
```

Run `auth login` only after a real project-list probe shows the session is unauthenticated. `auth login` opens the browser, shows a one-time CLI code, and waits for the logged-in BlitzReels user to click `Connect CLI`. Only confirm when the browser code matches the terminal code. After confirmation, the CLI stores the generated API key in macOS Keychain when available or `~/.blitzreels/config.json` as fallback.

Remote shells:

```bash
blitzreels projects list --status active --json
```

If that reports unauthenticated:

```bash
blitzreels auth login --no-browser
blitzreels projects list --status active --json
```

For remote shells, open the printed URL on a browser where you are logged into BlitzReels, verify the one-time code, then click `Connect CLI`. Do not assume that opening the URL alone completes auth.

Manual key fallback:

```bash
blitzreels auth set-key --api-key br_live_xxxxx
```

Environment variables:

```bash
export BLITZREELS_API_KEY="br_live_xxxxx"
export BLITZREELS_BASE_URL="https://www.blitzreels.com/api/v1"
```

Keys are runtime-environment bounded:

- Production accepts `br_live_...`.
- Local/development accepts `br_test_...`.
- Wrong-environment keys should be treated as invalid, not retried blindly.

Never paste ra