Command reference

Complete reference for all vvd commands.

Run any command with --help, or vvd help <command> for its examples. Bare vvd opens a home screen with a mini-prompt that accepts every command below.

The CLI checks its published version before every real command and updates itself in place, so you are always current — see Installation.

Environment variables

Variable	Description
`VVD_HOME`	Where the CLI installs (default `~/.vvd`). Credentials live at `$VVD_HOME/credentials.json`.
`VVD_API_URL`	Which vvd host to talk to (default `https://beta.vvd.world`). Takes precedence over the host stored at login.
`VVD_TOKEN`	A one-time sign-in code, consumed by the installer or by `vvd login`.

Authentication

Command	Description
`vvd login --token <code>`	Sign in with a one-time code from Workshop → Developer. Also reads `VVD_TOKEN`.
`vvd login --github`	Sign in with GitHub's device flow, where the host has it enabled. Headless machines can always use `--token` with a code generated in a browser elsewhere.
`vvd logout`	Sign out and delete the stored credentials. Your creations and saved versions are untouched.
`vvd whoami`	Show who you're signed in as. Flags: `--json`.

Projects

A command that acts on a project runs from inside the project's directory (it reads vvd.json there), unless it takes a path.

Command	Description
`vvd new`	Scaffold interactively — pick a kind, a template, and a name.
`vvd create <name>`	Scaffold `./<name>` and run it live. Flags: `--tool` / `--app` / `--wiki` (kind), `--template <id>` / `-t`, `--name <display name>`.
`vvd open [name]`	Re-run an existing project by (partial) name, or scaffold it if new. Flags: `--last`.
`vvd ls [path]`	List the vvd projects in this folder. Alias: `projects`. Flags: `--json`.
`vvd run [path]`	Render the project live inside a real world, hot-reloading as you save files. Flags: `--world <ref>`, `--project <ref>`, `--open=false`. Keys while running: `o` open in browser, `r` reload, `q` quit. Alias: `dev`.
`vvd info [path]`	Show every field in `vvd.json`. Flags: `--json`.
`vvd set <field> <value>`	Edit a `vvd.json` field: `name`, `description`, `icon`, `version`, `route`, `reads`, `writes`, `share`. Also `field=value` pairs, `--unset <field>`, `version --bump major\|minor\|patch`, `icon --list`.
`vvd rename <new name>`	Change the display name. The id never changes.
`vvd edit`	Walk every `vvd.json` field interactively.

Shipping

Saved versions are immutable — remove, unshare, and unpublish only change who can see a creation. The one permanent verb is vvd delete, and even it never reaches into other people's worlds: any installed copy keeps the exact version it installed.

Command	Description
`vvd save [message]`	Build and save an immutable private version. Flags: `--yes` / `-y`, `--dry-run`, `--if-changed` (skip when nothing changed). Alias: `ship`.
`vvd share`	Let your world use the latest saved version. Flags: `--version x.y.z`, `--undo`.
`vvd unshare`	Take the shared version back from your world. Saved versions are untouched.
`vvd publish`	Submit the latest saved version to the Workshop — it goes live after review. Flags: `--version x.y.z`, `--undo`.
`vvd unpublish`	Withdraw your creation from the Workshop. Saved versions are untouched.
`vvd remove`	Uninstall this creation from a world. Flags: `--world <ref>`, `--yes`. Saved versions are untouched — `vvd run` reinstalls.
`vvd delete [name]`	Delete YOUR creation from your workshop — saved versions, the Developer entry, and its Workshop listing. Worlds with it installed keep their copies. Flags: `--yes`. No undo.
`vvd status`	Who can open this creation right now: you, your world, or the Workshop — including review state.

Secrets and locales

Command	Description
`vvd secret set <NAME> [value]`	Store an encrypted secret for your `api/` handlers. Flags: `--scope dev\|published`.
`vvd secret list`	List secret names (never values). Alias: `ls`.
`vvd locales add <code>`	Add a language catalog (e.g. `fr`).
`vvd locales check`	Report missing translations. Never blocks a build.

GitHub

Connect a project to a repository so pushes become saved versions.

Command	Description
`vvd github link`	Link your GitHub account to your vvd user. `unlink` reverses it.
`vvd github connect`	Connect this project to a repo. Flags: `--repo <owner/name>`, `--branch <name>`, `--folder <path>`, `--watch` / `--no-watch`, `--deploy-as <target>`.
`vvd github status`	Show the connection and recent pushes. Flags: `--json`.
`vvd github disconnect`	Disconnect the repo. Nothing is deleted.

Worlds and documents

Work with your worlds from the terminal, no project required.

Command	Description
`vvd worlds`	List your worlds.
`vvd worlds create <name>`	Create a world. Flags: `--genre <genre>`.
`vvd docs <world>`	List a world's documents. Flags: `--type <type>`.
`vvd docs create <world> <name>`	Create a document. Flags: `--type <type>`.
`vvd search <world> <query>`	Search a world's content.
`vvd keys`	List your API keys. `create [--label <text>]` makes one, `revoke <id>` deletes one.
`vvd mcp`	Run an MCP stdio server that proxies the platform API — see the MCP docs.

Diagnostics

Command	Description
`vvd doctor`	Check Node, the bundler, your sign-in, and reachability. Flags: `--fix` (install the bundler now), `--fix-types` (repair editor types), `--json`.
`vvd version`	Print the CLI version. Flags: `--check` (compare against the latest published).
`vvd update`	Update the CLI in place right now. Alias: `upgrade`.
`vvd analytics`	Validate your declared actions and preview what usage data your creation reports. Flags: `--open`, `--tail`.
`vvd completions <shell>`	Emit a completion script for `bash`, `zsh`, or `fish`.