Install & setup

Use the npm package to run the CLI, or a source checkout to develop it and run its tests. Both need Node >=20.10. Optional video workflows require additional runtimes and provider accounts; installing the CLI alone does not configure them.

Install the package

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

vclaw --version prints the installed package version — the same value vclaw schema --json reports as version. Run it first; it is the quickest proof the install landed and tells you which alpha you got.

Without a global install, core discovery is available with:

npx -p videoclaw@alpha vclaw video providers

These discovery commands need no provider keys and do not submit a render. A route reported as not ready normally means its local configuration is incomplete. A ready report is not proof of current account entitlement or a successful live generation.

The alpha tag selects a published prerelease; it may differ from the source checkout's version. Package installation does not require running the source test suite. See release readiness for the separate package, local test and live-provider acceptance boundaries.

Build a source checkout

git clone https://github.com/davendra/videoclaw-v3.git
cd videoclaw-v3
npm ci
npm run build
node dist/cli/vclaw.js schema --json
node dist/cli/vclaw.js video providers

npm ci installs locked Node dependencies. npm run build compiles TypeScript into dist/; rerun it after source changes. Edit src/, not generated dist/.

Commands in these guides use the source form node dist/cli/vclaw.js …. Installed-package users run the same core commands as vclaw …. Optional helper files and runtime dependencies must still be configured for that workflow.

Add only the runtimes your workflow needs

Workflow	Requirements beyond the core Node installation
Local assembly, clip inspection, audio/video post-production	FFmpeg and ffprobe on PATH; fonts where used
Flow/Veo sidecar	Bun >=1.3.5, sidecar dependencies, UseAPI token and account
Python workflow helpers	Python 3.12+, the workflow's Python dependencies, and any media/provider tools it calls
Local provider-account lane coordination	sqlite3 CLI on PATH
Multi-computer account-slot coordination	Separately deployed, authenticated shared lane coordinator
Hosted image/audio/video generation or finishing	Selected provider's credentials, current account entitlement and the command's authorisation requirements

Bundled scripts are source, not a preconfigured Python or browser environment. Personal presets and external factory workflows can need additional resources; read the selected skill's setup section. FFmpeg and sqlite3 are external tools, not Node packages installed by npm ci.

Optional Flow sidecar

In a source checkout, after installing Bun:

bun install --cwd vclaw-cli --frozen-lockfile

For the global npm installation above, use a writable copy if the package installation directory is protected. Choose a new destination for an existing sidecar installation rather than copying over its local state:

# 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"

Do not use npm root -g here. It reports npm's default global root, which is not where the package lives when you installed with --prefix, and the cp -R then fails naming a directory you never chose. npm ls -g --parseable asks npm where this package actually is — give it the same --prefix you installed with. vclaw video providers also prints the real sidecar directory inside the veo-useapi issue text, and that works however you installed.

Keep that environment setting in the shell/session that runs vclaw. It selects application code; --root / VCLAW_WORKSPACE selects project data. verify-env already resolves the workspace that way. video providers did not: it read --workspace-root alone and otherwise fell back to the current directory, so the two commands could describe different workspaces. From this release providers follows the same chain; pass --workspace-root to point either of them somewhere else. Configure USEAPI_API_TOKEN and the appropriate account variables separately. This setup installs dependencies; it does not prove provider access or generate media. A published version must contain the bundled sidecar for this procedure; if it predates that packaging change, use a source checkout instead.

Optional: Seedance 2.0 for free, through your Higgsfield account

The seedance-direct route has two ways to render: the paid API that SUTUI_API_KEY buys, and a browser engine that ships with videoclaw and renders on your own Higgsfield account for $0 a clip. The free one is chosen automatically once it is set up, and never before. Full detail lives in engines/seedance-direct/README.md.

# pass the same --prefix you installed with, if any
package_dir="$(npm ls -g --parseable --depth 0 videoclaw)"
export HIGGS_VCLAW_PROFILE="$HOME/.local/share/videoclaw/higgsfield-session"
cd "$package_dir/engines/seedance-direct"
./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

import_cookies.py copies the session from a Chrome profile that is already logged in to higgsfield.ai on this machine. It reads Chrome "Profile 1" by default (CHROME_COOKIE_FILE=… picks another) and leaves a screenshot of the signed-in page beside the session: look at it once, then delete it.

Set HIGGS_VCLAW_PROFILE before the import and keep it set for every later vclaw run. It stores the session outside the package, where npm update cannot delete it and a system-wide prefix does not need to be writable; videoclaw reads the same variable to find the session again.

bootstrap.sh alone does not turn the 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. Files merely existing is not enough: without that check, an empty directory looked like a working free engine.

The free engine renders one video at a time; two runs at once get in each other's way.

Check it worked: vclaw video providers shows activeTransport: in-tree-engine and setupHint: null for seedance-direct. Until then that route reads blocked: it refuses to render rather than moving your work onto the paid Ark/xskill API that nobody chose, even on a machine where SUTUI_API_KEY is already set. The setupHint names the setup step that is missing. To use the paid API on purpose, set VCLAW_SEEDANCE_DIRECT_NATIVE=1 alongside SUTUI_API_KEY; the route then reads native-seedance and bills normally.

Set that variable in the shell that runs vclaw, not only in .env.local. Rendering reads the shell environment, so a value that lives only in the file shapes what providers reports and not what a render does — providers says so when it spots the difference.

Contributor tests

The Node suite invokes Python and real local media helpers. Install Python 3.12+, FFmpeg/ffprobe, and the required fonts before running it. Use a virtual environment rather than modifying system Python:

python3.12 -m venv .venv
source .venv/bin/activate
python -m pip install -r requirements-test.txt
npm run check:test-python
npm test

check:test-python reports missing Python dependencies/capabilities. Follow its error details for font/shaping requirements. npm test runs lint, module-size checks, a build and the Node suite; it does not run the Bun sidecar suite or validate paid provider access. Sidecar checks are separate:

(cd vclaw-cli && bun run typecheck && bun test)

For the broader local Node smoke/coverage/guardrail bundle:

npm run check:release-readiness-lite

Keep the Python environment active for these checks. See the release-readiness page for additional package and deployment gates; this command alone is not a production certification.

Explore without submitting a render

Start with discovery, project planning and a documented preview command. Plain produce --dry-run previews direct execution; missing artifacts or route configuration may still produce a blocked-readiness report. pool --dry-run previews queue compilation. produce --auto-chain compiles tasks without provider submission and rejects --dry-run; new queued tasks require their own quotation/authorisation/execution flow.

Do not assume every command supports --dry-run. Plain produce without it is a live command when project readiness permits. The CLI reference and capability map explain the distinction between direct execution and durable queued work.

Next steps

• Agent quickstart — the condensed install-to-first-render path, written for an AI agent on a fresh machine.
• Make your first video — plan a video using the documented preview path.
• Providers — configure the chosen route.
• Troubleshooting — resolve installation or command errors.