CLI Reference

The Vector Vesper CLI is the path from the component registry to your codebase. It detects your project, writes editable source, installs the dependencies a component needs, and tracks what it installed.

Run every command with npx vectorvesper <command>. With pnpm, yarn, or bun, use pnpm dlx, yarn dlx, or bunx instead. The CLI detects your package manager from its lockfile.

Quick Reference

`init`

Detect your project and write vv.config.json.

npx vectorvesper init

It writes four things: vv.config.json, your components directory, vv-manifest.json for tracking installs, and an AGENTS.md block telling your coding assistant the runtime exists — that every animation shares one frame loop, so it should never start its own. Assistants read AGENTS.md automatically, which matters because writing a private animation loop is the one mistake that silently opts a project out of the shared frame budget without producing an error.

Your own content is safe. If you already have an AGENTS.md, the block is appended between markers and everything around it is untouched. Running init again replaces only what is between those markers, and add rewrites only the "Installed" line — so notes you add inside the block survive an install. Project-specific rules still belong outside it, since init regenerates the rest.

`add `

Add a component (and its dependencies) to your project.

npx vectorvesper add physics-buttons

`list`

List every component in the registry.

npx vectorvesper list

`update [slug]`

Update installed components to the latest registry version. Omit the slug to update all.

npx vectorvesper update

`remove `

Remove an installed component and its files. Alias: rm.

npx vectorvesper remove physics-buttons

`diff [slug]`

Check installed components against the registry for available updates.

npx vectorvesper diff

`info`

Show project diagnostics and the list of installed components.

npx vectorvesper info

`login `

Save an access token so add can install Pro components.

npx vectorvesper login vv_xxxxxxxxxxxx

Generate a token from your account page. The token is written to ~/.vv/config.json and used for every project on the machine, so you log in once rather than per repository.

Nothing is validated at login time. The token is checked when the registry is next called, which keeps login instant and lets it work offline. A token that was revoked or has expired therefore fails on the next add, not here.

`logout`

Remove the stored token.

npx vectorvesper logout

Free components keep working. Only Pro access goes away.

`whoami`

Show whether you are signed in, and with what.

npx vectorvesper whoami

Prints your tier, a masked token, the account email and the expiry date when the token carries them. Signed out, it says so and tells you how to sign in. Start here when add reports that a Pro component is unavailable.

`mcp`

Run the CLI as an MCP server so your coding assistant can build components of your own on the runtime. It plans the motion before anything is written, reads any primitive's contract, and checks the code afterwards.

npx vectorvesper mcp install

With no client named, it configures every editor it finds. Supported: claude, cursor, windsurf, antigravity, opencode.

Typing npx vectorvesper mcp on its own prints setup help rather than starting a server, because a server with no client attached has nothing to do.

The tools it exposes: plan_motion decides whether a piece of motion needs a primitive at all and which ones; get_hook, get_pattern and get_component give the contract; check_motion reviews what you wrote for the problems that do not show up as build errors. Full guide, including the per-client config shapes: MCP Server.

Global flags & environment