Using the CLI

Using the CLI

The CLI is for the cases where the browser is too slow or too closed — agentic flows, headless rendering, automation pipelines.

Install

npm install -g @varosity/cli
varosity --version

Pair with your account

varosity login
# → prints https://varosity.ai/app/keys/api-keys — open it and issue a token
# → paste your vsk_… token when prompted

non-interactive (CI, agents):

varosity login --token "$VAROSITY_API_KEY" ```

Token is stored at ~/.varosity/config.json (mode 0600). Never commit this file. Setting the VAROSITY_API_KEY environment variable overrides the stored token.

Common commands

Render one video

varosity models list --kind video        # real model ids + pricing

varosity generate video kling-3.0 \ --prompt "wide cinematic establishing shot of a desert at golden hour" \ --duration 5 \ --out shot1.mp4 ```

With --out, the CLI submits, polls every few seconds, and downloads when done. Without it, the command prints the jobId and returns immediately.

Generate a voiceover

varosity voices list --json | jq -r '.[].voiceId' | head -3
# → 21m00Tcm4TlvDq8ikWAM
# → alloy
# → echo

varosity generate voice \ --text "Welcome back. Here's what's new this week." \ --voice 21m00Tcm4TlvDq8ikWAM \ --out vo.mp3 ```

Background music

varosity generate music elevenlabs-music \
  --prompt "cinematic synth, slow build, hopeful" \
  --duration 30 \
  --out bg.mp3

Smart Route

varosity route suggest --shot "talking head close-up with synced lips" --json

Watch a long render

varosity generate video veo-3.1 --prompt "..." --duration 8
# → Submitted · jobId <jobId>
varosity job wait <jobId>
# blocks until the job succeeds or fails, printing each status change and
# the final output URL
varosity job status <jobId> --json
# one-shot status check: { status, outputUrl, … }

Start from a template

varosity templates is coming in CLI 0.1.1 — the published 0.1.0 doesn't have it yet. Until then, use the MCP tools list_templates and create_project_from_template to clone a template; varosity render works today.

# CLI 0.1.1+
varosity templates list
varosity templates use <slug> --name "Spring launch"
# → clones the template into a new project and prints its id
varosity render <projectId> --out final.mp4
# → stitches the project's rendered shots into one MP4

render only stitches — every shot in the project has to be rendered first (open the project in the studio, or drive it from an MCP host).

Agent mode

--json on any command makes the output stable and machine-parseable. For Claude Code / Cursor / any MCP host, run:

varosity mcp

…which prints the JSON snippet to drop into Claude Desktop's claude_desktop_config.json. The MCP endpoint exposes 46 tools (see the agent-mode guide); per-host setup instructions are at varosity.ai/connect.

Override the API base

VAROSITY_API_BASE=https://staging.varosity.ai varosity models list

Useful for staging environments or self-hosted instances.