CLI reference

--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 and .env.example.