CLI

volter is the user's command: a noun, then a verb. volter world … acts on the world of the current directory; volter twin <vendor> … 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:

Lifecycle

State

Branches

Time

Remotes and changesets

Deploying

On a world whose twins have a root. The receipts land on the changes.

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.

volter login

volter open

volter completion

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

volter world init ends by offering volter agents install at a terminal. Use Volter World with a coding agent walks through it.

volter twin

One twin: in the world of the current directory, or on its own.

volter-world

The operator's surface. Every verb takes the world's name and, where a config is needed, its path. --root <dir> 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=<path>: Node reads a separate --env-file <path> 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

volter-world init <name> --repo <path> [--out <dir>] [--force] [--allow-unknown] [--acknowledge vendor=reason]... [--json]
volter-world up <config> --env-file=<path> [--name <name>] [--mode local|share|sealed] [--isolation process|colocated|worker] [--keep-state]
volter-world down <name> [--grace-ms <ms>] [--purge]
volter-world status <name> [--json]
volter-world env <name> -- <command...>
volter-world log <name> [service...] [--no-follow] [--json] [--requests]
volter-world diff <name> [--json]
volter-world seed <name> [--entry <file>] [--cwd <dir>]
volter-world reset <name> [--entry <file>] [--cwd <dir>]
volter-world branch <name> <new> [--env-file=<path>]
volter-world checkout <name>
volter-world fetch <name> [--remote <name>] --key <token>
volter-world origin <name>
volter-world activate <name>
volter-world shell <name>
volter-world serve <name> [--port <p>]
volter-world changeset create <name> <changeset> [--verifier "<service> <type>:<id> <field> <op> [value]"]...
volter-world changeset push <changeset> --key <token> [--to <remote>] [--force]

Review and deploy

volter-world changeset show|list|status <changeset>
volter-world changeset verify <changeset>
volter-world changeset approve <changeset> --as <principal> [--note <text>]
volter-world changeset rebase <changeset>
volter-world changeset replay <changeset> --into <world>
volter-world deploy <name> [<changeset>]
volter-world twin <name> <vendor> root <url> [--deploy auto|gated|hold] | credential | refresh

The world itself

volter-world clock <name> show | set <iso> | advance <N s|m|h|d> | shift <N s|m|h|d> | clear   the world's clock (frozen, or running after shift; its application follows it)
volter-world urls <name> [--json]        every service's URL
volter-world url <name> [service]        one service's URL, bare
volter-world app-url <name> [--set <url> | --detect <pid|port>] [--host <name>...]   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 <name> [--verify-public]
volter-world doctor-prereqs --require local-execution
volter-world run <config> --env-file=<path> [--owner <label>] [--mode ...] [--keep] [--verbose] -- <command...>   a disposable world around one command
volter-world resources [--root <repo>] [--json]   reservations, owner labels and registered attachments
volter-world prune [<name>] [--root <repo>] [--apply] [--json]   preview or delete stopped instance files
volter-world list [--json]
volter-world outdated <name> | audit <name>   each twin's pinned, mounted and catalog version; the catalog's verdicts
volter-world fake-env <NAME...>          structurally valid fake values for env names
volter-world inspect-project [path]      read-only discovery of an app's vendors
volter-world migrate-config <config>     backed-up, atomic format-1 to format-2 migration
volter-world covers <name> --repo <path> check detected vendors and connections against a config or instance

Reaching the world from elsewhere

volter-world attach [<world-ref>] [--owner <label>] [--via env|direct] [--verbose] [-- <command...>]
volter-world manifest <name>
volter-world route <name> add|rm|ls [host]
volter-world reflect <name> --target-ip <ip> [--port <p>] [--resolver-port <p>]
volter-world share <name> [--service app] [--verify /path | --no-verify] [--provider cloudflare-quick|command]
volter-world unshare <name> [--service app]

attach <url> [--token <t>] -- <command> 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, 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 <label> to identify the task using the world. Commands started by env or local attach --via env inherit the world's label unless overridden; each command has its own record. resources shows registered commands and identifies untracked consumers as unknown. The label describes ownership; it does not grant access. Finish active commands before down; uncertain command records also prevent teardown. volter-world consumers retire <world> [--consumer <id>] resolves an uncertain record whose runner, command and process group are all gone on this host (a runner killed before it recorded completion), and keeps any other with its reason; it never runs on its own. prune only deletes files after a successful teardown, preserving source configs and seeds. resources reports actual filesystem free bytes and lifecycle ownership. Its JSON schema version 2 distinguishes observed capacity from declarations; it exposes no synthetic reserved or admission-available totals. Legacy records are listed for migration, never subtracted from free space or removed by inspection. Unreadable unrelated records do not block startup. An unfinished lifecycle blocks replacement/pruning of that instance until verified teardown. Runtime v3 accepts config resources with a deprecation warning; it does not turn declarations into OS limits. Hosted Worlds with legacy declarations require reviewed migration first. Stop a legacy installation with its pinned old runtime before upgrading all its entrypoints; resume retained state with volter world up, not a fresh operator up/run. Keep old ownership records until verified cleanup. Mixed-version ownership of one instance is unsupported. run cleans up when its caller is killed, provided its cleanup process survives; other registered commands remain protected. up and run --keep require explicit teardown. Prune removes stopped instance data separately, so command logs remain available after a failed run. list, status and resources show instance creation and last observed command use, including its source and partial coverage. Command heartbeats indicate a command's presence, not user interaction or vendor traffic; its latest observation survives command completion. Foreground runs contribute their start and finish times. Inspection does not refresh use, and a new instance starts with unknown use. Legacy, activated-shell and remote use remain unknown; an old timestamp does not prove that a world is safe to stop.

The hosting product

Many worlds on one host, and the platform in front of it (architecture, "The hosted product"; the guides host worlds for a team and self-host the platform).

volter-host serve

@volter/world-host serves worlds under one URL by <org>/<world>, and provisions, rotates and removes them through its admin endpoints (HTTP API, "The hosting product"). It prints the admin token and, when @volter/world-console is installed beside it, the dashboard's URL. A user never needs it: a served world is the same thing for one team.

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. It prints its address, the provider, whether it bills, and the operator token (<dir>/admin).

Its environment:

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.