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 globally across local repositories.

The token is stored directly in local configuration without an immediate network round-trip. Credential validation occurs on subsequent registry requests (such as add).

`logout`

Remove the stored token.

npx vectorvesper logout

Removes local credentials. Free registry components remain accessible without credentials; Pro component installations will require logging in again.

`whoami`

Display current authentication status and account tier.

npx vectorvesper whoami

Outputs your tier, masked token, associated account email, and expiration timestamp. If unauthenticated, it displays login instructions.

`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.

Running npx vectorvesper mcp without arguments displays command syntax and usage instructions.

The tools it exposes include: plan_motion for interaction planning and primitive selection; get_hook, get_pattern, and get_component for contract inspection; and check_motion for static code verification. For configuration details, see the MCP Server guide.

Global flags & environment