Agent quickstart — install to first render

For an AI agent on a machine that has never run videoclaw, told "install this and make me a video". Follow it top to bottom. The §4 sequence was run end to end on a clean prefix install and produced a real clip for 0 credits; the two commands this release adds (vclaw --version and assets --text-only) stand in for the workarounds that run needed.

Two surfaces are more current than any prose, including this page: vclaw schema --json is the authoritative command index (every registered command with its usage string and flags), and skills/catalog.json is the skill index. Read both once at the start of a session and drive from them.

1. Install and prove it

npm install -g videoclaw@alpha
vclaw --version
vclaw video providers

vclaw --version (or -v) prints the bare version string and exits 0 — the same value vclaw schema --json carries as version, and the one command whose output is plain text rather than JSON. video providers needs no credentials and submits nothing; it prints every route with its availability, its missing env vars, and copy-pasteable fix text for anything it can name.

Local vocal guides for lip-sync uploads

When asked to alter a vocal only to drive lip sync, process the existing stem; do not generate new lyrics or a new song performance. Use:

vclaw video vocal-guides --input /path/to/vocal-stem.wav
vclaw video vocal-guides --project my-film --windows w00,w01 --root /path/to/workspace

This free local command exports a 150 Hz flat guide and a +4-semitone guide as 320 kbps MP3s, retaining the original articulation and decoded duration. It leaves the source and upload references unchanged and does not upload anything. Project batch export requires an existing stem-based plan; use the command directly for old projects rather than restarting production. For dependency setup, safe reruns, and automatic planning exports (VOICE_SOURCE=stem, VOICE_GUIDES=1), read the rap-video agent skill.

2. Where the keys go

Keys belong in your shell (export NAME=value) or in $VCLAW_WORKSPACE/.env.local — the file video providers, verify-env and the native provider transports read. Never put keys inside the installed package: npm update deletes that directory. The workspace root resolves as --root flag, then VCLAW_WORKSPACE, then VIDEOCLAW_WORKSPACE, then ~/videoclaw.

Route	Env vars	Renders free?
veo-useapi	USEAPI_API_TOKEN, USEAPI_ACCOUNT_EMAIL	Yes — --veo-model free selects veo-3.1-lite-low-priority at 0 credits. Provider-gated to Ultra-tier accounts; it errors clearly on others.
seedance-direct	SUTUI_API_KEY (paid xskill.ai transport)	Yes, without a key — bootstrap the in-tree Higgsfield engine (§3).
runway-useapi	USEAPI_API_TOKEN, USEAPI_ACCOUNT_EMAIL	Explore mode is free in principle, but this project has had no Runway account since 2026-08-10. The route stays registered; do not plan work on it.
dreamina-useapi	USEAPI_API_TOKEN, VCLAW_DREAMINA_ACCOUNT (e.g. CA:you@example.com)	No.
magnific-rest	MAGNIFIC_API_KEY	No — a paid image/video finishing backend.
reapi-seedance	VCLAW_REAPI_SEEDANCE_VIA=treg + TREG_TOKEN, or =direct + REAPI_API_KEY + GO_BANANAS_API_KEY	No — Seedance 2.5 with the content filter off (a real photograph + a voice clip in one render), paid per second of output. Opt-in only.
seedance-modelark	ARK_API_KEY (optional: VCLAW_MODELARK_MODEL, VCLAW_MODELARK_BASE_URL, VCLAW_MODELARK_CHAIN_MODE)	No — the official Seedance 2.5 API on BytePlus ModelArk, billed per second of output to your BytePlus account (~USD 0.93 for 4 s at 720p).

You only need the keys for the route you intend to use. Every other route reading unavailable is expected and harmless.

3. Optional sidecars

Flow sidecar (needed for veo-useapi). On a global install, copy the bundled vclaw-cli somewhere writable first. npm root -g is wrong whenever a --prefix was used, so ask npm for the package itself:

# pass the same --prefix you installed with, if any
package_dir="$(npm ls -g --parseable --depth 0 videoclaw)"
flow_sidecar_dir="$HOME/.local/share/videoclaw/flow-sidecar"
mkdir -p "$(dirname "$flow_sidecar_dir")"
cp -R "$package_dir/vclaw-cli" "$flow_sidecar_dir"
bun install --cwd "$flow_sidecar_dir" --frozen-lockfile
export VCLAW_VEO_CLI_ROOT="$flow_sidecar_dir"

vclaw video providers prints that same directory in the veo-useapi issue text, however you installed.

Seedance 2.0 for free, through your Higgsfield account. From $package_dir/engines/seedance-direct, per its README:

export HIGGS_VCLAW_PROFILE="$HOME/.local/share/videoclaw/higgsfield-session"
./bootstrap.sh                                  # Python environment + Chromium
./.venv/bin/python bootstrap/find_cookies.py    # find your Chrome profile
./.venv/bin/python bootstrap/import_cookies.py  # import the Higgsfield session

Keep that variable set for every later vclaw run: the free engine is chosen only from that session path, so a session the render shell cannot see falls back to the paid API in silence. Unset, bootstrap.sh writes both the Python environment and the session inside the installed package, where they need write access and are lost on npm update. import_cookies.py also leaves a screenshot of the signed-in page; delete it. The free engine renders one video at a time — two runs at once get in each other's way.

bootstrap.sh alone does not turn free rendering on. Only import_cookies.py proves you are signed in, so only it writes the readiness file <session>/.vclaw-engine-ready.json, and the free engine is chosen only when that file reads "loggedIn": true (plus an executable .venv/bin/python). Files merely existing is not enough: the check used to accept the directories being there, which an empty mkdir satisfies, so a machine with nothing configured reported a working free engine.

Confirm which way a route will render with providers: activeTransport reads in-tree-engine once the free Higgsfield engine is set up, custom-adapter under a VCLAW_<ROUTE>_ADAPTER override, and otherwise the route's built-in paid one. On seedance-direct there is a fourth answer, blocked: the free engine is not usable and nobody has asked for the paid API, so the route refuses to render rather than billing a transport you did not choose. Set VCLAW_SEEDANCE_DIRECT_NATIVE=1 (with SUTUI_API_KEY) to choose it. Every route also carries setupHint: the next command to type when the route has issues, and null when it has none. On seedance-direct it names the setup step that has not been done and the paid alternative; on veo-useapi it gives the Google Flow sidecar recipe with the directory videoclaw actually resolved. A machine that already holds SUTUI_API_KEY has no issues when the free rendering goes dark — the route still works, it just bills — so read the route NOTES too: one of them says free rendering is off and why.

4. The proven zero-credit first render

Free Flow, one 8-second clip, verified end to end. Substitute your own slug.

vclaw video init demo
vclaw video brief --project demo --title "Demo" \
  --intent "An 8-second cinematic shot of an empty sunlit reading room" \
  --aspect-ratio 16:9 --audio on --resolution 720p
vclaw video set-execution-profile --project demo --veo-model free
vclaw video storyboard --project demo --scene "Slow dolly-in across an empty sunlit reading room"
vclaw video assets --project demo --text-only
vclaw video produce --project demo --dry-run
vclaw video produce --project demo
vclaw video execute-status --project demo

• assets --text-only writes { projectSlug, assets: [], textOnly: true }. readiness requires asset-manifest even for a text-to-video project, so without this step produce returns status: "blocked". It also lets plan classify the run as text-to-video rather than image-to-video. When you do have files, pass --asset <kind>:<path> instead: the two flags are mutually exclusive, the kind must be one of image, video, audio, subtitle, other, and a local path that does not exist is an error.
• The dry run is the contract. It writes the resolved submit payload to artifacts/run-contract.json and reports that path as contractPath. Read the file before you drop --dry-run; the report printed on stdout is only a summary (status, routeId, taskCount).
• Plain produce is the live command. There is no --confirm-spend gate on it; removing --dry-run is what makes it real.
• produce prints nothing for roughly two minutes. That is normal. Calling execute-status from a second shell mid-flight is safe: it answers poll.status: "pending" with rawResult.reason: "execution-in-flight", names the running pid and start time, and writes nothing. Once produce returns, execute-status polls the real job.
• The clip lands at projects/demo/outputs/scene-0.mp4. Expect 1080p even though you asked for 720p — the free Flow lane upscales at no cost.

5. Which lane for which request

The request	Lane
Explainer or brand film	skills/brand-explainer/SKILL.md
Rap or avatar music video from a portrait	skills/rap-avatar-mv/SKILL.md
Kids nursery rhyme / sing-along	rhyme-factory
Animated short from a story idea	3d-animation-short
A scene prompt for Seedance or Flow	ai-film-director
Competitor ad teardown	ad-intel
Unsure, or a novice asking in plain English	concierge

skills/catalog.json is the complete lane list; this table is the common subset. Slash-command front doors are a source-checkout convenience and do not exist on a package install — read the SKILL.md directly.

5a. Plan and review a real production

The first-render example is a transport smoke test. For new agent-led films, follow Shared filmmaking workflow: prepare {filmPlan, shots} JSON and pass --film-plan <path> alongside ordinary storyboard --scene and --scene-character arguments. Match the creative format to the task; a technical test needs observable criteria, not an invented story.

Compile filmmaking-prompts after the plan and local references are settled. Execution refuses stale planned packets or changed local reference attachments; rebuild affected prompt evidence before rendering. This is not a guarantee that all standalone provider or batch paths consume the film plan.

After assembly, inspect review --project <slug> --film-edit <edit-source.json>. Watch the complete export with sound and record the actual review using --film-review <review.json> --verdict pass. Planned films need current full-playback evidence; sampled frames or technical QC alone cannot pass that gate. publish rechecks the reviewed media. The guide contains the complete JSON examples, supported route boundaries and legacy compatibility rules.

The host agent manages phases, evidence and a saved progress page. VideoClaw's durable queue manages provider work; it does not run an internal manager agent.

6. This machine vs any machine

Sections 1–4 require Node >=20.10 plus the chosen route’s credentials, account entitlement and optional runtimes described above. The production lanes do not: their prerequisites are verified on the maintainer's machine only and none of them ship with the package.

• brand-explainer — FFmpeg; Python 3.12+ with Pillow importable by the system python3, built with RAQM text shaping; ELEVENLABS_API_KEY for the voiceover and Suno keys for music; Go Bananas image generation for the icon sheet; whisper to verify the voiceover. A .brand pack in $VCLAW_WORKSPACE/packs/ is required and is authored, not generated.
• rap-avatar-mv — FFmpeg with the full codec set; Python 3.12+; whisper (the in-tree whisper.cpp shim, or openai-whisper at roughly a hundred times the wall clock); Demucs for the vocal stem; KIE_API_KEY (Suno), APIZ_API_KEY / XSKILL_API_KEY, USEAPI_API_TOKEN, VCLAW_VEO_CLI_ROOT, and a logged-in Higgsfield browser profile. A .rap.pack is required.

Treat a lane whose prerequisites you cannot satisfy as unavailable and say so, rather than substituting an improvised pipeline.