@dotv/cli

Command line for the DOTV creation API: every endpoint on the creation surface is one dotv command — create projects and canvases, run image / video / audio generation, look up models and their parameters, manage keys and team spaces.

npm i -g @dotv/cli

Needs Node.js 20 or later.

Sign in

dotv login

It prints a URL (carrying a short code) to confirm in any browser, then stores a long-lived key in ~/.dotv/credentials.json (mode 0600). dotv logout removes it, dotv whoami shows what's in use.

Use

dotv --help                  # command groups
dotv canvas --help           # one group's actions
dotv canvas list --help      # one command's options

dotv model list
dotv canvas list --page-size 5 --order-by createdAt
dotv generate post-image --prompt "一只在雨里的橘猫，电影感" --n 1

Output is human-readable by default; pass --json (agents: always pass it) for the raw response body.

Teaching the agent on this machine to use it

dotv skill install     # → ~/.claude/skills/dotv-cli/

That downloads the DOTV manual — the same skill package /cli hands out — and writes it where an agent reads skills from. No arguments, no credential: it is a public static file and there is exactly one thing to install. --dir .claude/skills installs into the current project instead.

Run it again to update: it asks for a 300-byte manifest first and skips the download entirely when your copy already matches, and it removes only files it wrote itself, so anything you added to that folder stays.

Upgrading the CLI does not refresh the manual — nothing runs on npm install. The daily background check watches for it: when the copy on this machine is not the one the deployment serves, dotv prints one line on stderr telling you to run it again.

Installing skills from the DOTV library is a different thing — those rows are creative material for canvases (dotv skill plaza).

Serving it to other agents (MCP)

dotv mcp --print-config    # the snippet for Claude Code / Codex / Claude Desktop / Cursor
claude mcp add "dotv" -- npx -y @dotv/cli mcp
codex mcp add "dotv" -- npx -y @dotv/cli mcp

dotv mcp speaks the Model Context Protocol over stdio (the 2026-07-28 stateless revision and the older initialize handshake alike) and exposes three tools — dotv runs one command written exactly as on this command line, dotv_help looks up the reference, dotv_wait blocks until a batch of canvas nodes has finished generating — plus the manual as resources. It uses the credential dotv login stored — including the site that credential points at — so there is nothing to put in the MCP config beyond the command itself.

With the DOTV desktop app open on the same machine, canvas commands run inside the app and appear on the open canvas as they happen (the app writes ~/.dotv/client.json, the CLI finds it, dotv whereami tells you which project and canvas are open). Without the app they go straight to the cloud API. The first time a given client (Claude Code, Cursor, …) sends a command, the app asks the user to allow it — the answer is remembered, and Agent settings lists every client that has connected with an allow switch. What an external agent does shows up in the app as it happens: a toast, a line in the canvas's conversation timeline, and a notice on the user's other devices (phone, web) signed in to the same space.

Give an agent its own key with a spending cap. A key is the whole account's authority; --budget-credits is the one place that narrows it. Every charge made through the key counts against the cap (refunds do not give it back), and once it is reached, spending calls answer 402 until you replace the key or raise the cap. The cap covers what the CLI charges on its own; a command handed to the open desktop app spends as the person logged into the app, who is asked to confirm it there instead:

dotv api-key post --name "claude-code" --budget-credits 500
DOTV_API_KEY=<the key> dotv mcp

Staying current

Each CLI carries the command contract it was built from, so new commands reach your machine by upgrading it — there is nothing else to refresh. Once a day dotv asks npm whether a newer version exists and prints one line about it on stderr when there is one (stdout stays clean, so --json keeps parsing).

That question is asked by a detached background process, so no command ever waits on the network for it — the line shows up from the next command onward. And it never installs anything by itself:

npm i -g @dotv/cli@latest

Environment variables:

| | | | ---------------------- | --------------------------------------------------------------------------------------------------- | | DOTV_API_BASE | API origin (default https://dotv.ai; dotv api-base <url> sets a machine-wide default, env wins) | | DOTV_API_KEY | A long-lived key used directly, instead of the stored credential — for CI | | DOTV_NO_UPDATE_CHECK | Set it to skip the update check (already skipped when CI is set) | | DOTV_NPM_REGISTRY | Registry the update check asks (default https://registry.npmjs.org) |

The full command manual lives at dotv.ai/skills/dotv-cli/SKILL.md.