Command cheat sheet

This page is for fast copy-paste. Every command is ready to run. If you ever want the why behind a step, follow the links: how it works, modes, first video, review & publish, assemble, providers, troubleshooting.

One thing to know first

All commands below use the source-checkout form node dist/cli/vclaw.js video .... If you installed the published package, just replace node dist/cli/vclaw.js with vclaw everywhere — e.g. vclaw video status --project demo. Everything else is identical.

Rehearse for free

Almost every expensive step accepts --dry-run. It plans the whole thing and spends zero credits. When in doubt, add --dry-run first.

---

Setup

npm install

Installs dependencies. Needs Node 20+. Expect a populated node_modules/ and no errors.

npm run build

Compiles the CLI into dist/. Expect a clean dist/ folder and an executable vclaw bin.

npm test

Builds, then runs the full test suite. Expect a list of passing tests and exit code 0.

node dist/cli/vclaw.js video providers

Shows which AI providers (Veo, Seedance, Runway, Dreamina) are ready to use. Expect a JSON list of routes with a readiness status for each — check this before any real render.

node dist/cli/vclaw.js schema --json

Dumps the entire command contract (commands, flags, exit codes) in one call. Expect a large JSON blob — handy for agents and for looking up exact flag names.

---

One full dry-run lifecycle

This runs the whole assembly line on a throwaway project and never spends a credit (note the --dry-run on produce). Great for your first run.

1. 1
   init

   Creates projects/demo/

   free
2. 2
   brief

   Writes brief.json from your one-line idea

   free
3. 3
   storyboard

   Writes storyboard.json and story-bible.json

   free
4. 4
   plan

   Picks the route, writes execution-plan.json

   free
5. 5
   produce --dry-run

   Rehearses the render, spends nothing, no clips

   free
6. 6
   status

   Shows the current stage, checkpoints, review state

   free

The whole assembly line, in order. Every step here is free; drop --dry-run on produce to render for real.

node dist/cli/vclaw.js video init demo

Creates a new project folder at projects/demo/. Expect JSON confirming the project was created.

node dist/cli/vclaw.js video brief --project demo --title "Demo" --intent "A 15s product tease"

Turns your one-line idea into a written brief. Expect a brief.json artifact and JSON output.

node dist/cli/vclaw.js video storyboard --project demo --scene "open on product" --scene "close on logo"

Breaks the brief into scenes and auto-writes a story bible for consistency. Expect storyboard.json and story-bible.json artifacts.

node dist/cli/vclaw.js video plan --project demo

Picks the provider route and prepares the exact request to send. Expect an execution-plan.json artifact. (plan and execution-plan are the same command.)

node dist/cli/vclaw.js video produce --project demo --dry-run

Rehearses the real render without spending anything. Expect a planned-only JSON result, no clips. (produce and execute are the same command. Drop --dry-run to render for real.)

node dist/cli/vclaw.js video status --project demo

Shows where the project is right now. Expect JSON with the current stage, checkpoints, and review state.

---

Director mode + approval

Director mode adds a safety gate: it refuses to spend money on the real render until a human approves the storyboard. Add --mode director to your commands.

node dist/cli/vclaw.js video init demo --mode director

Creates the project in director mode. Expect JSON confirming mode: director.

node dist/cli/vclaw.js video storyboard-review --project demo --mode director

Runs the preflight checks and writes a human-readable storyboard.md to review. Expect the project to move to awaiting-approval when preflight passes.

node dist/cli/vclaw.js video director-preflight --project demo --apply-content-fixes

Re-checks the storyboard for hazards (risky phrases, missing references, pronoun drift) and auto-rewrites known problem phrases. Expect a JSON preflight report.

VIDEOCLAW_APPROVE_STORYBOARD=1 node dist/cli/vclaw.js video produce --project demo --mode director

This is the "yes, go" button. The env var unlocks the gate so the real render can run. Expect submission to the provider (omit the env var and it stops at the gate instead).

The gate is real

Without VIDEOCLAW_APPROVE_STORYBOARD=1, director-mode produce/execute stops before spending anything and exits with a gate code. That is by design.

---

Status & next steps

These never spend credits. Use them to find the single safest next action.

node dist/cli/vclaw.js video status --project demo

Full state of one project: stage, checkpoints, review state, character bindings. Expect JSON.

node dist/cli/vclaw.js video next-actions

An urgency-ordered to-do queue across all your projects. Expect JSON listing what to do next.

node dist/cli/vclaw.js video doctor-project --project demo

Health check for one project — flags missing artifacts, stale reviews, broken stages. Expect a JSON list of findings (empty means healthy).

node dist/cli/vclaw.js video readiness --project demo

Tells you whether the project is ready to plan/produce, plus any non-blocking warnings. Expect a readiness.json artifact and JSON output.

---

Assemble & polish

The assemble step stitches clips + narration + music into one MP4 and auto-checks the result.

node dist/cli/vclaw.js video assemble --project demo --dry-run

Plans the full assembly pipeline (every FFmpeg command + provider call) without running anything or needing FFmpeg/API keys. Expect a planned assemble-report.json. Safest first step.

node dist/cli/vclaw.js video assemble --project demo --brand-profile ./brand.json

Runs the real assembly: title card, narration, music, FFmpeg stitch, then a media quality-check. Expect a rendered MP4 plus an assemble-report.json with any QC warnings. (Real assembly needs FFmpeg and TTS/music keys — eyeball the MP4 yourself.)

node dist/cli/vclaw.js video review --project demo --verdict pass

Marks the project approved (only for projects already reviewed elsewhere). Expect a review-report.json with metrics.publishReady: true.

node dist/cli/vclaw.js video publish --project demo --status ready

Marks the project done and hands it off. Expect a publish-report.json. Publishing is blocked unless review-report.json has verdict: "pass" and metrics.publishReady: true.

---

Portfolio / ops

For when you have many projects. None of these spend credits.

node dist/cli/vclaw.js video list

Lists every project in the workspace. Expect JSON with one entry per project.

node dist/cli/vclaw.js video metrics

Counts and rates across the whole portfolio (active, blocked, needs-review, ready). Expect a JSON summary with a byReviewState breakdown.

node dist/cli/vclaw.js video report

A full portfolio report: state, owners, blockers, review freshness. Expect JSON.

node dist/cli/vclaw.js video sync-obsidian --root . --output-dir ./ops/obsidian

Regenerates the whole Obsidian dashboard vault (12 notes + one note per project) from canonical state. Expect markdown files written under ./ops/obsidian you can browse in Obsidian.

---

Key environment variables

Set these in your shell (e.g. export NAME=value) before running. Only set what you need.

Variable	Purpose
VIDEOCLAW_APPROVE_STORYBOARD	Set to 1 to approve the storyboard and unlock real provider submission in director mode (the "go" button).
DIRECTOR_AUTO_FIX_CONTENT	Set to 1 to auto-rewrite known provider-risk phrases in the storyboard before director preflight re-checks it.
SUTUI_API_KEY	Credentials for the native seedance-direct transport (XSkill / Seedance API).
USEAPI_API_TOKEN	Token for the runway-useapi and dreamina-useapi routes (one token, shared by both).
GEMINI_API_KEYS	Comma-separated Gemini keys (round-robin pool) used by analyze, analyze-template --auto, multi-shot --auto, and brand-extract.

Need the full list of provider env vars?

See providers for adapter overrides (VCLAW_*_ADAPTER), command shims (VCLAW_*_SUBMIT_CMD / _POLL_CMD / _CANCEL_CMD), and Dreamina account settings (VCLAW_DREAMINA_ACCOUNT, VCLAW_DREAMINA_REGION, VCLAW_DREAMINA_MODEL).

---

Lost? Jump to the troubleshooting page, or start at the first video walkthrough.