# CLI `volter` is the user's command: a noun, then a verb. `volter world …` acts on the world of the current directory; `volter twin …` acts on one twin, in a world or on its own; `volter remote …` names the worlds this one pushes to and fetches from. `volter-world` is the operator's command and names worlds and configs explicitly. Both come from `@volter/world` (`volter`) and `@volter/world-runtime` (`volter-world`). The `volter` section below is checked against the command's own help text by `scripts/docs-reference.test.ts`: every verb the command knows appears here. ## `volter world` Every verb finds the world by walking up from the current directory to the nearest `.volter/world.json`, and acts on the checked-out branch. Global flags: | flag | meaning | |---|---| | `--world ` | the world root, when the cwd is not inside it | | `--branch ` | act on that branch instead of the checked-out one | | `--json` | machine-readable output, where a verb offers it | ### Lifecycle | verb | does | |---|---| | `volter world init [--install] [--name ] [--allow-unknown] [--force]` | detect the app's vendors from its manifests and env names (in an app with no twins installed yet, name the twins for them and install them with the app's package manager: asked at a terminal, at once with `--install`); write `.volter/world.json`, the handlers, the seeds and the ignore file. Byte-deterministic for a repo and a catalog | | `volter world init --bare /` | a world with no app: a shared world for a team, or a world standing in for a vendor | | `volter world up [--sandbox] [--no-seed]` | start the twins on this branch. A branch that has run before resumes with its state; a fresh branch loads the default data | | `volter world run [--verbose] -- ` | run the command inside the world: the twins' URLs, the fake credentials and the SDK redirect in its env. Exits with the command's code | | `volter world activate` | print the script that activates the world in the current shell: `eval "$(volter world activate)"` | | `volter world shell` | a subshell with the world active | | `volter world serve [--port

] [--host ] [--console-port ]` | serve this world on a URL, under `////…`, for apps and scripts; prints the token that opens it and writes it to `.volter/token`. On loopback (the default) it is the same local front as `view`, without opening the browser: the console it prints opens with no token. A non-loopback `--host`, or `--console-port`, serves it for others, and its console (its own origin, port p+1 by default) asks for the token | | `volter world view [--port

] [--host ] [--no-open] [--no-origins]` | serve this world to step into: its HTTP API, each twin's mirror, the branches made of it and, with `@volter/world-console` installed, the console, opened in the browser at the world's own origin (`http://--.localhost:/-/console//`, where its browser session lives; `--no-origins` serves every world on one origin). On loopback the browser never needs a token: the World's own page opens its session, after a restart or a rotated token too (a non-loopback `--host` is a World served for others, and its console asks for one; with `--no-origins` the browser is opened with the token in the URL's fragment). Anything that can reach the port can open that session, so never forward or expose it; see the architecture's "A local World asks for no token". Branches it makes live under `.volter/branches/` until their time runs out | | `volter world console [] [--port

]` | the console on this machine for a World served elsewhere (a hosted World), on two local origins as `serve` has: the console (port p), its endpoints forwarded to the host, and the Worlds (port p+1), forwarding a twin's mirror and the session endpoint; defaults to this world's origin, and needs no world when a URL is given; open the World with its token; needs `@volter/world-console` | | `volter world status [--json]` | the world, the branch, whether it runs, the origin, the base, unpushed changes, each twin's URL and root | | `volter world down [--purge]` | stop the twins; the branch's state stays. `--purge` deletes it if no dependent local branch references it | ### State | verb | does | |---|---| | `volter world log [--receipts] [--json]` | every write the app made, across the twins, oldest first; `--receipts` adds each change's receipt | | `volter world diff [--json]` | the changes since the base, grouped by twin | | `volter world seed` | load the default data | | `volter world reset` | back to the default data: forget the branch's changes, boot, seed | ### Branches | verb | does | |---|---| | `volter world branch` | list branches; `*` marks the checked-out one | | `volter world branch [--at ]` | a new branch from here — or from any point in the history: an instant, or a position within the current or named view per twin — checked out; the current branch stops. Nothing is copied | | `volter world checkout ` | switch to a branch: it resumes with its state, the current one stops | | `volter world replay --into ` | feed a changeset's changes into another branch's twins, in order, with the same ids; replaying twice is a no-op | ### Time | verb | does | |---|---| | `volter world clock show` | the world's clock: the frozen instant every twin stamps from, or the wall clock when none is set | | `volter world clock set ` | set it; every twin stamps from it until it moves, and so does the World's application, whose time then stands still (a World serving an application moves time with `shift`) | | `volter world clock advance ` | move a set clock forward: `30d`, `12h` | | `volter world clock shift ` | move a World forward while its time keeps running (a World serving an application, which follows the World's time) | | `volter world clock clear` | return the World to the machine's time | ### Remotes and changesets | verb | does | |---|---| | `volter world clone --token ` | record the world at `` as origin, remember the token, and bring its whole history in | | `volter world fetch [] [--token ]` | cache the remote's current snapshot without changing reads (clone before branching to inherit its origin); `pull` integrates origin history, and named changeset rebase can use the fetched snapshot | | `volter world origin [--json]` | the remote this world clones from and pushes to; `default data` when it has none | | `volter world changeset [] -m ""` | cut the unpushed changes into a changeset, named from the message unless given | | `volter world push [] [] [--token ] [--force]` | send changesets to the remote, oldest first, and move the base; refused on drift | | `volter world pull [--token ]` | fetch and integrate the origin snapshot, preserving inherited local layers and naming conflicts | | `volter world rebase []` | without a name, move onto the local base's current position; with a changeset, integrate the fetched origin snapshot and re-check that changeset. Both name conflicts by record and field | ### Deploying On a world whose twins have a root. The receipts land on the changes. | verb | does | |---|---| | `volter world verify ` | run the world's checks over the changeset and record the result | | `volter world approve --as [--note ]` | sign the changeset's current hash | | `volter world deploy []` | perform landed changes against each twin's root, by its policy: every deployable changeset, or the named one | Tokens come from `~/.config/volter/credentials.json` (or `$XDG_CONFIG_HOME/volter/`), written by `remote add` and `clone --token`; `--token` overrides the store for one call. ## `volter remote` The worlds this world pushes to and fetches from, by name, like git's remotes. A remote is a URL a served world printed, or a path to another world's directory on this machine. | verb | does | |---|---| | `volter remote add [--token ]` | name a remote; `origin` is the one `fetch` and `push` use by default. A path is a world on this machine, reached with no server and no token | | `volter remote remove ` | forget it | | `volter remote list` | every remote, with its URL and whether a token is stored | | `volter remote add / [--create]` | a world the hosted platform holds for your org, its address resolved through the platform you signed in to. One that is not there yet is made there with this world's twins: asked at a terminal, or at once with `--create` (without either, the command stops and names `--create`). `` alone names it in your only org | ## `volter login` | command | does | |---|---| | `volter login [--no-open]` | sign the command into the hosted platform as you, through the browser: it shows a code, opens the platform's approval page (where you sign in with your Volter account, making one if you are new), and on approval keeps a personal token named for this machine, for 30 days | | `volter login --token ` | the same without a browser, with a token made on the platform under Account (CI) | | `volter whoami` | the platform the command is signed into, as whom, and the orgs it reaches | | `volter logout` | revoke the command's token at the platform and forget it here | ## `volter open` | command | does | |---|---| | `volter open [/] [--no-open]` | a World's dashboard: a hosted one (named, or this world's origin on the platform you signed in to) through the platform, which signs you in; otherwise this world's own, as `volter world view` serves it. The address is printed; `--no-open` only prints it | ## `volter completion` | command | does | |---|---| | `volter completion bash\|zsh\|fish\|powershell` | print a script that completes volter's nouns and verbs: `eval "$(volter completion bash)"` in `~/.bashrc` (or zsh), `volter completion fish \| source`, `volter completion powershell \| Out-String \| Invoke-Expression` in your profile | ## Installing and updating `npm install -g @volter/world` (or `bun add -g`), or the site's install script, which checks for Node 22.3 or later (or Bun) and runs the same install: `curl -fsSL https://world.volter.ai/install.sh | sh`, or `irm https://world.volter.ai/install.ps1 | iex` in PowerShell. Once a day at most, the command asks the npm registry for the latest version while it works and says in one line on stderr when a newer one is out. It never asks in CI, for `--json`, or away from a terminal, and `VOLTER_NO_UPDATE_NOTIFIER=1` turns it off. ## Agents | command | does | |---|---| | `volter agents install [--claude] [--cursor] [--vscode] [--codex] [--yes]` | put the `volter-world` skill and the MCP server into the coding agents found here (or those named): Claude Code (`claude mcp add --scope user`, else `~/.claude.json`; the skill in `~/.claude/skills/volter-world`), Cursor (`~/.cursor/mcp.json`), VS Code (`.vscode/mcp.json` in this project), Codex (`~/.codex/config.toml`, the skill's instructions in `~/.codex/AGENTS.md`); only its own entries are written, and running it again changes nothing; without `--yes` it asks first, and at no terminal it only says what it would do | | `volter mcp` | the MCP server an agent starts, over stdio: tools `world_status`, `world_init`, `world_up`, `world_run`, `world_down`, `world_view`, `world_log`, `world_diff`, `world_branch`, `world_checkout`, `world_reset`, `platform_login`, `platform_whoami`, `remote_link`, `world_changeset`, `world_push` (each takes the app's folder as `dir`), and the prompt `get-started`; a tool that acts runs `volter` itself, so it answers and refuses as the command does | `volter world init` ends by offering `volter agents install` at a terminal. [Use Volter World with a coding agent](../guides/use-with-a-coding-agent.md) walks through it. ## `volter twin` One twin: in the world of the current directory, or on its own. | verb | does | |---|---| | `volter twin ` | the twin in this world: its URL, its root and deploy policy, whether a credential is sealed | | `volter twin root [--deploy auto\|gated\|hold] [--scope ] [--refresh ] [--at-most ]` | set the twin's root to the vendor at `` and its deploy policy; `--scope` names the one resource the account is (`repos/acme/web`); `--none` clears it `--scope` names the one resource the account is (github: `repos//`; slack: the channel ids a refresh reads, `C123,C456` — a workspace's rate budget is the reason) | | `volter twin credential` | read a credential from stdin and seal it beside the world; never readable back | | `volter twin refresh [--force]` | observe the root now — the twin observes, the kernel folds what changed; throttled to the root's `atMost` (else the twin's) unless `--force` | | `volter twin serve [--port

] [--read-only]` | serve the twin at `http://127.0.0.1:

` without a world; `--read-only` refuses every write | | `volter twin mirror [--port

]` | the twin's UI mirror: its live state in a vendor-styled dashboard | | `volter twin conformance` | check the twin against the vendor's spec contract | ## `volter-world` The operator's surface. Every verb takes the world's name and, where a config is needed, its path. `--root

` is the world root (default: the cwd). The verbs the user surface wraps are listed first, then the ones only an operator needs. Write the env file as `--env-file=`: Node reads a separate `--env-file ` pair from any program's arguments and exits when that file does not exist yet, which it does not before the first `up` writes it. ### The same verbs, addressed explicitly ```text volter-world init --repo [--out ] [--force] [--allow-unknown] [--acknowledge vendor=reason]... [--json] volter-world up --env-file= [--name ] [--mode local|share|sealed] [--isolation process|colocated|worker] [--keep-state] volter-world down [--grace-ms ] [--purge] volter-world status [--json] volter-world env -- volter-world log [service...] [--no-follow] [--json] [--requests] volter-world diff [--json] volter-world seed [--entry ] [--cwd ] volter-world reset [--entry ] [--cwd ] volter-world branch [--env-file=] volter-world checkout volter-world fetch [--remote ] --key volter-world origin volter-world activate volter-world shell volter-world serve [--port

] volter-world changeset create [--verifier " : [value]"]... volter-world changeset push --key [--to ] [--force] ``` ### Review and deploy ```text volter-world changeset show|list|status volter-world changeset verify volter-world changeset approve --as [--note ] volter-world changeset rebase volter-world changeset replay --into volter-world deploy [] volter-world twin root [--deploy auto|gated|hold] | credential | refresh ``` ### The world itself ```text volter-world clock show | set | advance | shift | clear the world's clock (frozen, or running after shift; its application follows it) volter-world urls [--json] every service's URL volter-world url [service] one service's URL, bare volter-world app-url [--set | --detect ] [--host ...] the app's URL; --host: a hostname it answers as in production, routed to it inside the World (`*.example.com`: every name below, as a DNS wildcard) volter-world doctor [--verify-public] volter-world doctor-prereqs --require local-execution volter-world run --env-file= [--owner

] [--resolver-port

] volter-world share [--service app] [--verify /path | --no-verify] [--provider cloudflare-quick|command] volter-world unshare [--service app] ``` `attach [--token ] -- ` runs the command against a world served elsewhere: the world's twin URLs, its endpoint variables and its key in the environment, the injector preloaded, and a loopback listener for each of the world's streams (its TCP twins: smtp, PlanetScale's MySQL wire) with the variables its client reads pointed there, so a command in any language connects to `127.0.0.1` ([HTTP API](./http-api.md), the attach manifest). `volter world run`, `volter-world run`, `attach --via env` and `env` suppress the injector's informational routing banner by default, including in child processes. Pass `--verbose` before `--` to show it. An admitted `VOLTER_TWIN_INJECT_QUIET` environment setting is preserved unless `--verbose` overrides it (`1` hides the banner, `0` shows it). Routing, warnings and errors are unchanged. A config can use `runtime.environment.strip: ["*"]` to discard the caller's inherited environment, including caller Node preloads. Declare needed variables such as `PATH` and `HOME` in `runtime.environment.values`. World still supplies its vendor URLs, credentials and injection to services and commands run within it. Named filters and prefix filters such as `HERMES_*` remain available. This filters environment inheritance; it does not isolate files or OS credentials. `covers` checks detected SDKs, vendor endpoints and native database connections. For example, a PlanetScale HTTP twin does not cover Prisma's separate MySQL connection. Database URL schemes identify native connections; Prisma schema evidence and unresolved clients also appear. Native coverage requires the app's endpoint variable to be wired to a declared service. External endpoint discovery stays unknown until `up` records it. Unknowns fail by default; `--allow-unknown` leaves them visible and explicitly accepts them. Configuration-driven or dynamically selected clients can remain unknown. This static check does not prove application behavior or that two interfaces share state; verify those with an app scenario. `init` classifies repository evidence by usage and saves `discovery.selection`; `covers` applies the same saved selection from the config or running instance. Excluded evidence stays visible but does not fail coverage. Declared twins are checked for routing even when discovery does not find them. `volter-world up --keep-state` boots over the state the World's directory already holds instead of starting it empty: the way a World carried elsewhere with its data (a browser tab's image of it) comes up. `volter-world up`, `run`, `env` and local `attach --via env` accept `--owner

` | the port to bind; one the system picks by default | | `--url ` | the origin the host is reached at when that differs from its bind address (a container behind a port map, a proxy): every world's base URL and the printed addresses use it | | `--console-port ` | the dashboard's own port (it is served on a listener of its own, so no twin's script shares its origin); the host's port + 1 by default | | `--console-url ` | the origin the dashboard is reached at, as `--url` is for the host; on the same site as `--url`, or its links into the twins' screens are refused | | `--no-origins` | no origin of its own per world: every world's pages on the host's origin (on a loopback host each world is `--.localhost` by default) | | `--trust ` | repeatable: a platform whose passes open these worlds for a person, over https or loopback http; none, and only tokens do | | `--world-origins ` | each world at an origin of its own under the domain (`--.`, a wildcard name and certificate pointing at the host), which a browser session and a pass need on a host reached at `--url` | ### `volter-platform serve` `@volter/world-platform` is where people and orgs are: sign-in through one access provider, orgs, members, invitations, tokens, the hosts it makes Worlds on, and opening a World for a person with a pass. Its endpoints are the [platform API](./platform-api.md). It prints its address, the provider, whether it bills, and the operator token (`

/admin`). | Flag | Meaning | |---|---| | `--dir ` | required: the platform's state — `platform.db` (SQLite: sessions, tokens, its directory for `oidc` and `github`, the enrolled hosts, the audit log), and the key it signs passes with | | `--host ` | the address to bind; `127.0.0.1` by default | | `--port

` | the port to bind; one the system picks by default | | `--url ` | the origin people reach it at (behind a proxy); the provider's callback is `/-/sign-in/callback`. The bind address by default | | `--provider volter\|oidc\|github` | the access provider (below); `oidc` when `OIDC_ISSUER` is set, else `volter` | | `--site ` | the product's site: its docs and legal pages are linked, and making an org asks for its terms. Absent, no terms are asked for | | `--mail-from ` | the sender of the platform's mail (invitations it keeps, a member added, a World deleted, billing notices); a sender the Resend account behind `RESEND_API_KEY` has verified. `Volter World ` by default | | `--support-to

` | where the Help form's requests are mailed; without it the platform shows no Help form | | `--client-ip-header ` | the header the deploy's own proxy sets to the client's address: `cf-connecting-ip` on Cloudflare, or `x-forwarded-for` behind a proxy that appends to it (its last entry is read). The rate limit keys a request without a token on it; unset, no request names its own address and those requests share one limit, and a platform on a public address says so when it starts | | `--backup-bucket ` | archive the state to this S3 bucket nightly, the database as a consistent snapshot (credentials from `AWS_*`); a restore is put in place at the next start | | `--backup-at ` | the backup's time of day, UTC; `00:00` by default | | `--tick-every ` | the billing tick's period, where the platform bills; 3600 by default, 0 never | | `--deliver-every ` | how often due webhook deliveries are attempted; 5 by default | Its environment: | Names | For | |---|---| | `VOLTER_ISSUER`, `VOLTER_CLIENT_ID`, `VOLTER_CLIENT_SECRET` | `--provider volter`: Volter Identity (`https://id.volter.ai` by default) and the client registered for this platform there | | `OIDC_ISSUER`, `OIDC_CLIENT_ID`, `OIDC_CLIENT_SECRET`, `OIDC_NAME`, `OIDC_TRUST_EMAIL_DOMAINS` | `--provider oidc`: the issuer, its client, the sign-in button's name, and the domains (comma-separated) in which an address the issuer does not mark verified still counts, for an issuer that sends no `email_verified` (Microsoft Entra) | | `GITHUB_CLIENT_ID`, `GITHUB_CLIENT_SECRET`, `GITHUB_URL`, `GITHUB_API_URL` | `--provider github`: the OAuth app, and for GitHub Enterprise Server its web address (https) and API (`/api/v3` by default) | | `RESEND_API_KEY` | send the platform's mail through Resend; without it every mail is written to the log instead | | `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `AWS_REGION`, `AWS_ENDPOINT_URL` | `--backup-bucket`'s S3 (`AWS_ENDPOINT_URL` for an S3-compatible store) | | `POLAR_ACCESS_TOKEN`, `POLAR_SERVER` | Volter's cloud only: bill through Polar with Volter's biller (`@volter/world-billing`, which is not published). Set where that biller is not installed, the platform refuses to start | `volter-world --help` prints every flag. ## Retiring names `volter remote serve` is the hosting product's verb under its old name; it answers for one release beside `volter-host`.