v0-cli

Agent-first CLI for the v0 Platform API.

Single v0 binary covering stable API v1 plus the API v2 beta. Stable JSON output, trust ladder, audit trail, single-use intent tokens for destructive ops.

bun install -g @crafter/v0-cli   # or `bun link` from source
v0 doctor --json

Requires V0_API_KEY from v0.app/chat/settings/keys.

Shorthand

v0 <arg> routes by the shape of the arg — no chat create / chat init ceremony:

v0 "landing page with hero and pricing"              # → chat create (prompt)
v0 .                                                 # → chat init (cwd)
v0 ./my-project                                      # → chat init (files)
v0 https://github.com/vercel/next.js                 # → chat init (repo)
v0 https://v0.app/templates/<slug>-<id>              # → chat init (template)
v0 template_abc                                      # → chat init (template id)
v0 https://example.com/dist.zip                      # → chat init (zip)

Core workflow:

v0 msg send <chat-id> "swap the hero copy"           # iterate (streams live)
v0 version download <chat> <ver> --out ./build.zip   # pull the archive
v0 deploy create <chat> --yes                        # ship (auto version, auto project, live transcript)
v0 "hero" --background --json                        # fire-and-forget for agents

Run v0 --help for the full table.

Platform API v2 beta

v1 remains the default because v1 and v2 chat IDs are incompatible. Every v2 workflow is explicit under v0 v2 and uses the official v0 SDK plus a separate bundled schema.

v0 v2 doctor --json
v0 v2 schema --json
v0 v2 chat list --json

v0 v2 chat create "Build a product dashboard" --async --json
v0 v2 chat wait <chat-id> <message-id> --json
v0 v2 chat watch <chat-id> --json

v0 v2 chat init ./app --json
v0 v2 chat init https://github.com/vercel/next.js --branch canary --json
v0 v2 files apply <chat-id> --file app/page.tsx=./page.tsx --yes --json
v0 v2 msg resolve <chat-id> --task '{"type":"plan-exit-response","status":"approved","content":"Proceed"}' --yes --json

The v2 namespace exposes all 41 operations in the pinned schema: native sync, async and resumable streams, message traces with usage, current files, direct file edits, restore, duplicate, previews, deploys, Vercel project creation, Connect status, skills, MCP servers, webhooks, trusted preview hosts, and selected v1-version migration.

Local attachments and ZIP imports are never published implicitly. Pass a URL, stay within the 20-file inline import limit, or add --upload-public to explicitly allow Catbox upload. Use v0 v2 migrate <v1-chat-id> <v1-version-id> to create a separate v2 chat while preserving the source IDs in metadata.

Platform tools:

v0 v2 hook list --json
v0 v2 hook create --name build-events --url https://example.com/v0 --event message.finished --json

v0 v2 mcp list --json
v0 v2 mcp create --name Context7 --url https://mcp.context7.com/mcp --scope user --json

v0 v2 settings preview-hosts get --json

See the complete v2 command reference, including trust levels, every chat/message/file route, task resolution, webhook events, MCP authentication, migration, preview hosts, and environment variables.

Skill

For agents (Claude Code, Cursor, custom):

v0 skill install       # self-contained, audit-logged
v0 skill status        # check if your local copy is current
v0 skill update        # pull the latest (idempotent)
v0 skill uninstall     # remove

# Or directly:
npx skills add Railly/v0-cli

The skill teaches agents the preflight recipe (doctor → schema → rate-limits), the JSON contract, the T0/T1/T2/T3 trust ladder, and the intent-token flow for destructive operations. Source: skill/SKILL.md.

Built on cligentic

The foundation primitives (audit log, killswitch, XDG paths, error map, doctor checks, global flags, JSON mode, next-steps) are cligentic blocks, copy-pasted into src/cli/ via bunx shadcn@latest add. v0-cli dogfoods the registry: if something breaks or a pattern is missing, the fix lands upstream first, then gets re-pulled here.

Links

• Docs + design: v0-cli.crafter.run
• v0 Platform API: https://v0.app/docs/api/platform
• v0-sdk: https://github.com/vercel/v0-sdk
• cligentic registry: https://cligentic.railly.dev

License

MIT

Contributing

See CONTRIBUTING.md for the cligentic copy-paste registry pattern and what is safe to edit locally.