blitzreels

Command-line video editing control surface for BlitzReels.

Official website: https://blitzreels.com/

Official npm package: https://www.npmjs.com/package/blitzreels

Machine-readable CLI guide: https://blitzreels.com/cli.md

This CLI is designed for AI agents to edit videos inside BlitzReels.

This is the primary CLI package. The scoped package @blitzreels/cli wraps this package for users who prefer scoped installs.

Install

Global install:

npm install --global blitzreels
blitzreels version
blitzreels doctor
blitzreels agent-context --json

Run without installing:

npx blitzreels version
npx blitzreels doctor
npx blitzreels agent-context --json
npx blitzreels auth login

Local repo development:

pnpm --filter blitzreels dev auth login --base-url http://localhost:3000/api/v1

Auth

blitzreels auth login
blitzreels auth set-key --api-key br_live_...
blitzreels auth whoami

auth login opens BlitzReels in your browser, shows the one-time CLI code, and waits for you to click Connect CLI. After confirmation, it stores the generated API key in macOS Keychain when available or ~/.blitzreels/config.json as a fallback. Use --no-browser on remote shells and open the printed URL manually.

API keys are environment-bounded:

• production uses br_live_...
• local/development uses br_test_...

Commands

blitzreels workspace settings get --json
blitzreels workspace settings update --name "Creator Studio" --protected-words "Brand,Product"

blitzreels onboarding scan start --website-url "https://example.com" --json
blitzreels onboarding scan get --run-id RUN_ID --json
blitzreels onboarding profile get --json
blitzreels onboarding profile update --brand-name "Creator Studio" --protected-words "Brand,Product"
blitzreels onboarding logo import --profile-id PROFILE_ID --replace-existing false
blitzreels onboarding complete --brand-name "Creator Studio" --platforms tiktok,linkedin --save-workspace-icon true --json

blitzreels projects list --status active --json
blitzreels projects create --name "Launch short" --aspect-ratio 9:16
blitzreels projects get --project-id PROJECT_ID --json
blitzreels projects rename --project-id PROJECT_ID --name "New title"
blitzreels projects update --project-id PROJECT_ID --description "New description"
blitzreels projects delete --project-id PROJECT_ID --confirm-delete

blitzreels media list --asset-type video --json
blitzreels media get --asset-id ASSET_ID --json
blitzreels media verify --asset-id ASSET_ID --json
blitzreels media download --asset-id ASSET_ID --output ./source.mp4
blitzreels media delete --asset-id ASSET_ID --confirm-delete \
  --reason "Remove duplicate upload" --idempotency-key media-delete:ASSET_ID:v1
blitzreels media delete --search "old upload" --confirm-delete \
  --reason "Remove obsolete imports" --idempotency-key media-delete:old-upload:v1 \
  --delete-generated-clips true --delete-linked-projects true
blitzreels media upload --file ./video.mp4 --timeout-ms 300000 --auto-transcribe true
blitzreels media import-youtube --url "https://www.youtube.com/watch?v=..."
blitzreels media rename --asset-id ASSET_ID --name "New media name"
blitzreels media update --asset-id ASSET_ID --description "B-roll" --folder-id FOLDER_ID
blitzreels media move --asset-id ASSET_ID --target-folder-id FOLDER_ID
blitzreels media attach --project-id PROJECT_ID --asset-id ASSET_ID --at 0 --duration 4
blitzreels media attach --project-id PROJECT_ID --asset-id ASSET_ID --at 0 --duration 4 \
  --placement-intent overlay --volume 0.4
blitzreels media overlay update --project-id PROJECT_ID --timeline-item-id TIMELINE_ITEM_ID --mute true
blitzreels media attach --project-id PROJECT_ID --asset-id IMAGE_ID --at 6 --duration 1.6 --position-preset center --position-y -230 --width-px 561 --height-px 212 --animation-preset popIn
blitzreels media reframe apply --asset-id ASSET_ID --project-id PROJECT_ID \
  --replace-timeline-item-id TIMELINE_ITEM_ID \
  --aspect-ratio 9:16 --content-type-hint podcast --layout-strategy split \
  --idempotency-key reframe:PROJECT_ID:v1
blitzreels media reframe status --asset-id ASSET_ID --json
blitzreels media reframe analyze --asset-id ASSET_ID \
  --idempotency-key reframe-analysis:ASSET_ID:v1 --json
blitzreels media reframe get --project-id PROJECT_ID --reframe-id REFRAME_ID --json
blitzreels media reframe source-update --project-id PROJECT_ID \
  --reframe-id REFRAME_ID --source-asset-id SOURCE_ASSET_ID \
  --source-crop-json '{"x":0,"y":0,"width":0.5,"height":1}' \
  --idempotency-key reframe-source:REFRAME_ID:SOURCE_ASSET_ID:v1 --json
blitzreels media folders list --json
blitzreels media folders create --name "B-roll" --icon-type video
blitzreels media folders rename --folder-id FOLDER_ID --name "New folder name"
blitzreels media folders update --folder-id FOLDER_ID --parent-folder-id root
blitzreels media folders delete --folder-id FOLDER_ID --confirm-delete

# Upload output includes processing_run_id and accepted follow_up intent.

blitzreels clips create --asset-id ASSET_ID --output ./clips
blitzreels clips create --asset-id ASSET_ID --logo-asset-id LOGO_ASSET_ID --output ./clips --count 5
blitzreels clips create --asset-id ASSET_ID --layout-mode people_first --content-type-hint podcast
blitzreels clips create --asset-id ASSET_ID --studio-sound --output ./clips
blitzreels clips create --youtube-url "https://www.youtube.com/watch?v=..." --name "MKBHD hero loop"
blitzreels clips get --clip-id CLIP_ID --json
blitzreels clips wait --clip-id CLIP_ID --json
blitzreels clips reselect --clip-id CLIP_ID --start-seconds 52 --end-seconds 64
blitzreels clips reselect --clip-id CLIP_ID --suggestion-id SUGGESTION_ID
blitzreels clips reselect --clip-id CLIP_ID --suggestion-id SUGGESTION_ID \
  --layout-mode people_first --content-type-hint podcast --caption-style-id cinematic-film \
  --caption-word-reveal-animation fade --caption-max-lines 2 \
  --caption-words-per-line 8 --caption-page-combine-ms 3000
blitzreels clips repair --clip-id CLIP_ID
blitzreels clips export --clip-id CLIP_ID
blitzreels clips attach-export --asset-id ASSET_ID --project-id PROJECT_ID \
  --export-id EXPORT_ID --confirm-visual-qa --idempotency-key attach:EXPORT_ID:v1
blitzreels clips promote-export --clip-id CLIP_ID --export-id EXPORT_ID \
  --confirm-visual-qa --idempotency-key promote:CLIP_ID:EXPORT_ID:v1
blitzreels clip-batches recover --batch-id BATCH_ID --target-count 10 \
  --idempotency-key clip-recovery:BATCH_ID:v1
blitzreels clip-batches get --batch-id BATCH_ID --json
blitzreels clip-batches wait --batch-id BATCH_ID --json
blitzreels clip-share-pages publish --asset-id ASSET_ID \
  --allow-downloads true --idempotency-key clip-share:ASSET_ID:publish:v1
blitzreels clip-share-pages set-clip-visibility --asset-id ASSET_ID --clip-id CLIP_ID \
  --visibility hidden --idempotency-key clip-share:CLIP_ID:hidden:v1
blitzreels clip-share-pages get --asset-id ASSET_ID --json

blitzreels recording-sets create --name "Product demo" --idempotency-key recording-set:create:v1 --json
blitzreels recording-sets list --status ready --json
blitzreels recording-sets tracks attach --recording-set-id SET_ID --asset-id CAMERA_ASSET_ID \
  --role camera --primary --idempotency-key recording-set:camera:v1
blitzreels recording-sets tracks attach --recording-set-id SET_ID --asset-id SCREEN_ASSET_ID \
  --role screen --idempotency-key recording-set:screen:v1
blitzreels recording-sets finalize --recording-set-id SET_ID --idempotency-key recording-set:finalize:v1
blitzreels recording-sets get --recording-set-id SET_ID --json
blitzreels recording-sets delete --recording-set-id EMPTY_SET_ID --confirm-delete \
  --idempotency-key recording-set:delete:v1
blitzreels recording-sets clips create --recording-set-id SET_ID --max-clip-count 5 \
  --max-duration 60 \
  --layout-mode prefer_focus --content-type-hint podcast --caption-theme-id hormozi \
  --studio-sound \
  --idempotency-key recording-set:clips:v1

# `clips get|list --json` exposes `layout.segments` with time ranges, panel assets,
# crops, canvas geometry, and split-only caption placement.

blitzreels characters create --name "Virgile" \
  --reference-asset-ids CHARACTER_SHEET_ASSET_ID \
  --primary-reference-asset-id CHARACTER_SHEET_ASSET_ID \
  --idempotency-key character:virgile:v1
blitzreels characters list --json
blitzreels faceless plans create --project-id PROJECT_ID --script-file ./script.txt \
  --character-ids CHARACTER_ID --video-model seedance-2.0-ref2v \
  --idempotency-key faceless:PROJECT_ID:v1

blitzreels project inspect --project-id PROJECT_ID --json
blitzreels project timeline --project-id PROJECT_ID --json
blitzreels project snapshot --project-id PROJECT_ID --at 00:03
blitzreels project snapshots --project-id PROJECT_ID --at 00:01,00:03

blitzreels timeline transform --project-id PROJECT_ID --timeline-item-id TIMELINE_ITEM_ID --position-x 0 --position-y -230 --width-px 561 --height-px 212 --keep-aspect-ratio true
blitzreels timeline move --project-id PROJECT_ID --timeline-item-id TIMELINE_ITEM_ID --at 00:06 --layer-index 2
blitzreels timeline delete --project-id PROJECT_ID --timeline-item-id TIMELINE_ITEM_ID --auto-pack false

blitzreels effects zoom add --project-id PROJECT_ID --at 9.8 --duration 1.8 --scale-start 1 --scale-end 1.1 --easing easeInOut
blitzreels effects zoom update --project-id PROJECT_ID --timeline-item-id EFFECT_TIMELINE_ITEM_ID --scale-end 1.1 --easing easeInOut --duration 1.8
blitzreels effects mask add --project-id PROJECT_ID --settings-json '{"shape":"rounded","size":{"width":0.8,"height":0.8}}'
blitzreels effects colorgrade update --project-id PROJECT_ID --timeline-item-id EFFECT_TIMELINE_ITEM_ID --settings-json '{"brightness":1.1,"vignetteEnabled":true}'

blitzreels text add --project-id PROJECT_ID --text "Hook" --at 0 --duration 4
blitzreels text add --project-id PROJECT_ID --text "SERVEURS MCP" --at 24.33 --duration 2.8 --font-family Pacifico --font-size 82 --color "#17FFA6" --background-color "rgba(3,7,18,0.82)" --top "24%"
blitzreels text list --project-id PROJECT_ID --json
blitzreels text update --project-id PROJECT_ID --content-item-id CONTENT_ITEM_ID --text "New hook" --font-family Inter --font-size 64 --color "#FFFFFF"
blitzreels text remove --project-id PROJECT_ID --content-item-id CONTENT_ITEM_ID

blitzreels audio search --query "ambient riser" --license cc0 --json
blitzreels audio import --provider openverse --external-id AUDIO_ID --project-id PROJECT_ID --at 0 --duration 12 --volume 0.03
blitzreels audio add --project-id PROJECT_ID --asset-id ASSET_ID --at 0 --volume 0.03

blitzreels captions words list --project-id PROJECT_ID --match-text "Supabase" --json
blitzreels captions words text --project-id PROJECT_ID --word-id WORD_ID --text "Supabase"
blitzreels captions words update --project-id PROJECT_ID --word-id WORD_ID --text "Supabase"
blitzreels captions words batch-text --project-id PROJECT_ID --updates-json '[{"word_id":"WORD_ID","new_text":"Supabase"}]'
blitzreels captions words batch-text --project-id PROJECT_ID --updates-file caption-updates.json
blitzreels captions words style --project-id PROJECT_ID --word-id WORD_ID --font-family Pacifico --color "#17FFA6" --scale 1.45
blitzreels captions words style --project-id PROJECT_ID --all --style-file caption-word-style.json
blitzreels captions words emphasis --project-id PROJECT_ID --match-text "MCP" --emphasis true
blitzreels captions words delete --project-id PROJECT_ID --word-id WORD_ID
blitzreels captions words merge --project-id PROJECT_ID --word-ids WORD_ID_1,WORD_ID_2 --text "serveurs MCP"
blitzreels captions words split --project-id PROJECT_ID --word-id WORD_ID --words "serveurs,MCP"

blitzreels silence plan --project-id PROJECT_ID --timeline-item-id TIMELINE_ITEM_ID --json
blitzreels silence plan --project-id PROJECT_ID --timeline-item-id TIMELINE_ITEM_ID \
  --strategy audio --json > silence-plan.json
blitzreels silence apply --project-id PROJECT_ID --confirm-preview \
  --plan-json "$(cat silence-plan.json)"
blitzreels silence apply --project-id PROJECT_ID --timeline-item-id TIMELINE_ITEM_ID --confirm-preview

blitzreels mistakes plan --project-id PROJECT_ID --timeline-item-id TIMELINE_ITEM_ID --json
blitzreels mistakes apply --project-id PROJECT_ID --timeline-item-id TIMELINE_ITEM_ID --confirm-preview

blitzreels captions looks list --json
blitzreels captions look set --project-id PROJECT_ID --look-id editor-premium-lime
blitzreels captions style update --project-id PROJECT_ID --look-id paper-karaoke --text-stroke-enabled false

blitzreels exports start --project-id PROJECT_ID --cover-frame-seconds 1
blitzreels exports wait --export-id EXPORT_ID
blitzreels exports download --export-id EXPORT_ID --output ./short.mp4

blitzreels formats run --format video-model-benchmark \
  --prompt "A red figure walks toward a circular platform under a deep blue night sky" \
  --left-model wan-2.1 --right-model krea-wan-14b-t2v --confirm-cost
blitzreels jobs get --job-id JOB_ID --json

blitzreels api docs
blitzreels api spec

Use --json for script and AI-agent workflows. Use --fields id,name with --json to trim large responses. Export status responses include thumbnail_url, thumbnail.frame_seconds, thumbnail.rationale, and first-pass platform_metadata suggestions for YouTube, TikTok, and Instagram. Onboarding scan responses include run_id, status, optional profile, and next_actions; poll the run before completing onboarding. Mutating onboarding commands support --dry-run.

Media deletion is a batch operation even for one asset. It requires a reason and stable idempotency key, returns impact and partial-failure receipts, and only cascades when requested.

media wait --json reports skipped_for when a requested stage does not apply to the asset. project timeline --json returns normalized top-level items in snake_case while retaining legacy data.items.

Caption style receipts include verified, effective_settings, warnings, and cleared_word_overrides. Overlay attach and update accept volume; --mute true sets it to zero.

Machine-Readable Contract

blitzreels agent-context --json
blitzreels agent-context --command "media attach" --json
blitzreels agent-context --full --json
blitzreels schema --command "captions words style" --json
blitzreels media attach --project-id PROJECT_ID --asset-id ASSET_ID --at 6 --dry-run

agent-context --json is the compact machine-readable command index. It lists stable operation IDs and command names, plus write and destructive operation ID sets. Use --command for one detailed contract with typed flags, defaults, examples, safety markers, and known errors. Use --full only for compatibility or bulk tooling that explicitly needs every detailed command contract.

Agent workflow strategy lives in BlitzReels skills and docs, not in CLI command metadata or normal command output.

Retry project, clip-batch, and export creation safely with a stable key:

blitzreels projects create --name "Launch clips" --idempotency-key project:launch-clips:v1
blitzreels clips create --asset-id ASSET_ID --idempotency-key clips:ASSET_ID:v1
blitzreels clip-batches recover --batch-id BATCH_ID \
  --idempotency-key clip-recovery:BATCH_ID:v1
blitzreels exports start --project-id PROJECT_ID --idempotency-key export:PROJECT_ID:1080p:v1

Reuse a key only with identical inputs. A changed request returns a conflict.

--dry-run is available on mutating commands and prints the API request that would be made without making the write request. Destructive dry-runs still require the same explicit confirmation flags as real destructive commands.

Updates

The CLI checks https://blitzreels.com/api/cli/releases at most once per day and prints a short update notice to stderr when a newer version is available. The notice is skipped for --json, CI, non-interactive shells, and commands where it would be noisy.

blitzreels version
blitzreels doctor
npm i -g blitzreels@latest

Set BLITZREELS_NO_UPDATE_NOTIFIER=1 to disable passive update notices.

Faulty Commands

The CLI validates commands and flags before making API calls. Faulty commands print the closest known command or flag, then the command-specific usage.

blitzreels caption words list --project-id PROJECT_ID
# Unknown command: caption words list
# Did you mean?
#   blitzreels captions words list --project-id ID ...

With --json, errors are structured on stderr:

{
  "error": {
    "code": "unknown_flag",
    "message": "Unknown flag --poject-id for `projects get`.",
    "suggestions": ["--project-id"],
    "usage": "blitzreels projects get --project-id ID [--json]"
  }
}

Plan-limit failures use upgrade_required, exit code 3, and include an upgrade_url. Human output prints the same billing link after the error.

Use blitzreels <command> --help for command-specific flags without requiring auth.

Source, releases, and license

The npm package is publicly installable, but its canonical source is private and proprietary. Workspace 0.1.14 adds one compound Reframe receipt plus source-level reads and edits. It includes the 0.1.12 reusable character commands and faceless-generation character selection.

Admin recovery and other internal operator commands are not part of the public CLI artifact.

Published behavior depends on the installed version; inspect it with blitzreels version. See LICENSE for the package terms.