vs

Operate the vs CLI: submit a film's shots.json to Seedance, poll and
download the clips, and assemble them into a finished cut. Each film is a
self-contained films/<slug>/ directory holding shots.json, stills.json,
and a tasks.json manifest the CLI maintains.

• IS: running the commands, picking flags, and staging a film through the
  cost ladder.
• IS NOT: writing the shots.json / stills.json content (use seedance)
  or the story documents (use storycraft).

Run npm run build first if dist/ is stale, then node dist/cli.js <cmd>
(or vs after npm link). --help is accurate and is the authority on
flags. Generation is paid: vs doctor checks keys and ffmpeg before you
spend, and --dry-run costs nothing.

Commands

Cross-cutting: --dry-run on anything that spends money or shells out to
ffmpeg, --json everywhere (automatic when stdout is not a TTY), --verbose
for the underlying cause of an error, --draft on the generation and assembly
commands.

Read for detail

The things that bite

• vs cast sync is authoring-time codegen, and it runs BEFORE vs stills.
  Nothing at generate time reads characters.json: sync writes literal
  castPrompt text and literal sheet references into shots.json, and the
  sheet stills into stills.json, which stay the only source of truth for what
  gets sent. So review the diff, then generate the new sheets. castPrompt is
  rewritten wholesale on every run — hand-edit characters.json, never the
  block. vs cast sync --check writes nothing and exits non-zero on drift.
• A keyframed shot on Seedance 2.0 or MiniMax H3 gets the cast block as text
  only. Those models refuse a first_frame mixed with reference images, so
  sync does not bind the sheet there — it is per shot, so the same character can
  bind by ordinal in a reference-mode shot and by text in the keyframed one
  beside it. On 2.5 both modes coexist and the sheet is bound at @Image 2,
  after the frame. A character bound nowhere gets no sheet generated, and sync
  says so rather than billing you for an image nothing references.
• A plain vs stitch with no --music/--narration is an SFX-only cut and
  will sound empty. Per-shot prompts only ask for sound effects. Happy path:
  vs score → vs narrate → vs narrate assemble --xfade … →
  vs stitch --xfade … --music score-vNNN.mp3 --narration narration.mp3 (same
  --xfade on both). Re-stitch after regenerating a shot.
• 720p is the generation target, not 1080p. Generate at 720p, then
  vs upscale --shot <final-edit ids> for delivery, which is free. A prior 2.0
  run here asked for 1080p, was delivered 720p, and was billed at the 1080p
  rate.
• A Seedance 2.5 run is strictly serial. 1 concurrent task regardless of
  --concurrency, and a 30s generation takes 10 to 15 minutes, so a six-act
  film is 60 to 90 minutes. It is also about 53% dearer than 2.0 for the same
  runtime. What it buys is coherence, not price or speed.
• A 2.5 film sets no film.draftModel. There is no 2.5-fast, and 2.0-fast
  caps at 15s, so a 30s film pointed at it is refused rather than drafted.
  Unset, --draft runs the film's own model at 480p. --dry-run lints for it.
• Non-interactive runs need --yes, or the command fails fast rather than
  hanging. Pair it with --max-cost <usd>, which is a hard refusal that
  applies even with --yes.
• Never resubmit an in-flight task. The manifest re-attaches by id. Result
  URLs expire in about 24 hours, so generate downloads immediately.
• --force creates a new revision. It never replaces a clip. A failed
  retake leaves the previous downloaded revision selected.
• Title cards are macOS-only (rasterised via qlmanage and sips), and
  ffmpeg is required for animatic, review, stitch, and upscale.
• --output resolves against the cwd and refuses to replace an existing
  video. Omit it for an automatically numbered render.

Requirements

AI_GATEWAY_API_KEY (or VERCEL_OIDC_TOKEN) in .env for the default
Seedance 2.5 path; ARK_API_KEY for BytePlus Seedance 2.0 / lighthouse and
vs status <task-id>; GEMINI_API_KEY for Nano Banana stills, vs score (Lyria), and vs narrate
(Gemini 3.8 TTS; --voice/GEMINI_TTS_VOICE, default Charon).
See .env.example.

Related skills

• seedance to author the shots.json / stills.json a film runs on.
• storycraft for the treatment, beat sheet, and shot list behind it.
• nano-banana-2 to write still prompts when a film's stills model is
  gemini-*.

Explicit visual approval

For a film with film.requireVisualApproval: true, download status never
substitutes for picture review. vs use and every vs stitch path, including
--latest, require an approved receipt for the exact selected clip and current
cast sheets. Review stills alone cannot establish stable motion, eyes, anatomy
or cash handling. Inspect moving footage and record a specific verdict:

vs review films/example/shots.json --shot shot-id --version 1 \
  --verdict rejected --note "At 12–14s the cash changes from a tied bundle into a loose note."

Use --draft for a draft revision. --dry-run writes no receipt. An explicit
approved verdict permits use only while clip bytes and canonical references
remain unchanged. The film-local visual-reviews.json keeps rejection separate
from provider status. A review gate prevents unnoticed reuse; it does not
magically correct bad generated pixels or certify a film's artistic quality.