> ## Documentation Index
> [HTML page](https://video-studio.blode.md/cli)
> [Documentation index](https://video-studio.blode.md/llms.txt)
> Use the index to discover all available pages before exploring further.

# CLI reference

Every vs command and the flags that matter across the pipeline.

`--help` on each command is the authority on flags. Generation is paid: run `vs doctor` before you spend, and use `--dry-run` when you want payloads and lint for free.

## Commands

| Command | What it does |
| --- | --- |
| `vs init <dir>` | Scaffold a film (`shots.json`, `stills.json`, README) |
| `vs doctor [task-id]` | Check Node, `.env`, keys, ffmpeg, card tools |
| `vs stills <stills-file>` | Generate reference stills into `stills/` |
| `vs generate <shots-file>` | Submit, poll, download clips to `output/clips/<shot>/vNNN.mp4` |
| `vs score <prompt>` | Lyria instrumental bed → `score-vNNN.mp3` |
| `vs narrate <lines.tsv>` | ElevenLabs per-line VO (`NN\ttext` TSV) |
| `vs narrate assemble <shots>` | Place lines on the cut → `narration.mp3` |
| `vs status [shots-or-task]` | Show the manifest, or fetch one task |
| `vs use <shots> <shot> <version>` | Select or roll back a clip revision |
| `vs download [shots-file]` | Fetch succeeded clips not yet on disk |
| `vs animatic <shots-file>` | Story reel from stills — $0 of video |
| `vs review <shots-file>` | Frame contact sheet plus delivery flags |
| `vs stitch <shots-file>` | Assemble clips and title cards |
| `vs upscale <shots-file>` | Lanczos-upscale finals for delivery (free) |
| `vs share <video>` | Two-pass compress under a size ceiling |

## Cross-cutting flags

| Flag | Use |
| --- | --- |
| `--dry-run` | Print payloads / lint; no network spend; no ffmpeg write |
| `--draft` | 480p pass beside the final (namespaced outputs) |
| `--max-cost <usd>` | Hard refusal if the estimate exceeds the ceiling |
| `--yes` | Skip confirmation (required when stdout is not a TTY) |
| `--force` | Create a new revision; never replaces a file |
| `--shot` / `--still` | Narrow a run to specific ids |
| `--json` | Machine-readable output (automatic when not a TTY) |
| `--verbose` | Underlying cause of an error |
| `--xfade` | Crossfade duration on stitch / narrate assemble |

## Outputs

- Clips: `output/clips/<shot>/vNNN.mp4`
- Finals: `output/renders/final/vNNN.mp4`
- Animatics: `output/animatics/vNNN.mp4`

`--output` resolves against the cwd and refuses to replace an existing video. Omit it for automatic versioning.

## Things that bite

- A plain `vs stitch` with no `--music` / `--narration` is SFX-only and sounds empty
- Generate at **720p**, then `vs upscale` for delivery (free) — do not default to 1080p generation
- Seedance 2.5 runs are **strictly serial** (1 concurrent), regardless of `--concurrency`
- Title cards are **macOS-only** (rasterised via `qlmanage` and `sips`)
- `vs narrate assemble --xfade` must match `vs stitch --xfade`

## Requirements

| Key | Needed for |
| --- | --- |
| `ARK_API_KEY` | Seedance video, Seedream stills |
| `GEMINI_API_KEY` | Nano Banana stills, `vs score` |
| `ELEVENLABS_API_KEY` (+ voice) | `vs narrate` |

See [Installation](/installation) and `.env.example`.