Skip to main content
The standalone vers binary talks directly to the HTTPS control plane. It does not maintain a local project, HEAD, checkout, alias database, or implicit target. Anonymous command telemetry is a separate, optional product signal; use an environment opt-out when an invocation must leave no telemetry state. COMPUTER accepts a full computer UUID, its exact remote name, or an unambiguous UUID prefix of at least eight characters. The standalone binary and ssh try.vers.sh gateway have different root command sets. This page describes only the locally installed binary. The gateway generates mutation recovery identities automatically. Buffered mutations omit them from normal success output; pending or ambiguous results include the identity and an exact retry command. Gateway run instead sends its recovery identities on stderr before initiating image import or computer creation. Advanced callers may supply --idempotency-key UUID for create, run, and delete, or --commit-id UUID for commit, when they need to retain the identity independently of the SSH response. Gateway account-key revocation also requires explicit confirmation with ssh-key revoke FINGERPRINT --yes.

​
SSH gateway and shell access

The SSH gateway is a separate command surface. Connect without a command for trial onboarding or an interactive command shell:
An unrecognized SSH key creates or resumes a trial. With a terminal, the gateway opens the trial shell; without one, it prints the trial help and exits. A valid one-shot command that needs an identity can create or resume the trial and continue on the same connection. Identity-free commands such as help do not allocate a trial. A known key can also run a one-shot gateway command:
ssh try.vers.sh ssh COMPUTER opens an interactive SSH session to that computer. The gateway supports help, whoami, list, get, create, run, delete, commit, resize, write, ssh, ssh-key, env, org, upgrade, and interactive exit. Gateway run accepts a public OCI reference or existing Vers image UUID. Local image selection with --local and copying a local environment value with bare -e KEY remain standalone-only; pass gateway environment overrides as -e KEY=VALUE. The gateway does not expose durable operation inspection, portable checkpoint/restore, retained logs, cat, workload exec, or telemetry preferences. The ordinary gateway create path needs neither an image UUID nor a recovery UUID:
Non-streaming one-shot gateway mutations buffer their response. If surviving a complete SSH channel loss is required, supply an advanced recovery identity before running one; otherwise a disconnect can hide the automatically generated value. Foreground gateway run streams workload output and sends its create operation identity, plus a derived image-import identity when needed, on stderr before the corresponding remote effects. Detached run prints the computer ID and returns after admission. Losing the SSH channel detaches the observer without cancelling admitted durable work; Ctrl-C does the same in the interactive gateway shell.

​
Local help

These commands do not read control-plane configuration or contact the control plane:
Add --json to vers help when a program needs structured help metadata. Use this explicit help command for subcommands; vers COMMAND --help is not accepted by the standalone parser. Root help and version are not captured by telemetry. Targeted vers help commands are ordinary parsed commands and may emit the documented anonymous telemetry event. Unknown commands, misspelled options, missing confirmation flags, and invalid values are usage errors. The interactive SSH gateway prompt supports Up/Down history, cursor movement, Ctrl-A/Ctrl-E, Ctrl-U, and Tab completion. Ctrl-C clears the current line; at an already-empty prompt, pressing Ctrl-C twice in a row disconnects. Ctrl-D also disconnects from an empty prompt and otherwise deletes at the cursor. Commands that can contain secret values (env, run, and write) are not saved in the in-session history.

​
Authentication and endpoint

Configuration precedence is:
  1. VERS_API_KEY and VERS_ORCHESTRATOR_URL
  2. ~/.versrc
  3. the default endpoint, https://api.vers.sh
~/.versrc is JSON:
The API key is required for control-plane commands. Local help, version, upgrade, and telemetry preference commands do not require it. There is no login, logout, signup, or command-line API-key option. A custom control-plane URL must use HTTPS; HTTP is accepted only for localhost or a numeric loopback development endpoint. It must be a bare origin: credentials, a non-root path, query parameters, and fragments are rejected.

​
Anonymous telemetry

Anonymous CLI telemetry is enabled by default and sent directly to PostHog on a best-effort basis. It records cli_command_invoked for a parsed command and cli_command_failed for a nonzero completed result. Properties are limited to:
  • a random installation ID;
  • the typed command name, never its arguments;
  • CLI version and operating system/version and architecture;
  • failure exit status and elapsed duration.
Person profiles and GeoIP enrichment are disabled. The CLI never sends paths, command output, environment values, API credentials, or error messages. Telemetry delivery cannot change command output or exit status. Root help, version, parse failures, and telemetry-management commands are not captured. The persistent preference and random ID live in ~/.vers/telemetry.json. Inspect or change them locally:
disable removes the installation ID. For an environment-only opt-out that does not create telemetry state, set either variable:

​
Updating

vers upgrade checks the stable latest.json release manifest, selects the exact binary for the current operating system and architecture, and installs it beside the running executable. --check-only reports the current and latest stable versions without changing the binary. There are no automatic or background update checks. Before replacement, the updater enforces the manifest’s byte count and SHA-256 digest, runs the staged binary’s --version, and then atomically renames it over the current executable. The executable’s directory must be writable. The checksum detects corruption relative to the HTTPS manifest; it is not an independent signature or publisher-authentication mechanism.

​
Computers

Structured computer commands support --json unless noted otherwise. vers get resolves names and UUID prefixes through the computer inventory, then uses the v2 observation resource for the selected immutable ID. Its displayed state, identity, labels, owner, and creation time come from v2. The reserved IP, CPU, memory, and lineage JSON fields remain null, and their human-readable lines are omitted.

​
exec

exec sends the argv after -- exactly as separate arguments. It does not insert a shell and never falls back to SSH for platform-init computers. The executable must exist in the computer’s OCI image; use an absolute path when the image’s PATH is uncertain. Environment overrides use repeated --env options, and duplicate keys are rejected. The timeout range is 1–3600 seconds; the server default is 300 seconds. Exec admission is not idempotent: exec_id correlates the response but does not deduplicate starts. If the HTTP request times out, the connection is lost, or the terminal response cannot be validated, the command may already have started. The CLI says so explicitly; do not blindly retry such an ambiguous request. A structured exec_unavailable response is also ambiguous because the bridge could have lost the terminal reply after starting the process. A structured command_timeout response is different: it is the guest’s definite terminal result for the requested execution. Human mode copies guest stdout to stdout and guest stderr to stderr, then exits with the guest status. JSON mode writes one object containing computer_id, exec_id, exit_code, stdout, and stderr to stdout and does not duplicate guest stderr onto the diagnostic channel. Portable process statuses are 0–255. The guest protocol uses -1 for signal termination; JSON retains that exact value, while a status outside 0–255 maps the local CLI process status to 1 instead of being silently truncated by the operating system. This exec bridge is synchronous and string-based. It does not support stdin, streaming, attach/resume, or binary-safe output; invalid UTF-8 returned by the guest is replaced by the server’s UTF-8 conversion. Use vers session for an interactive PTY-backed process.

​
session

The first form starts a platform-init computer’s single interactive session, passing the argv after -- exactly and using the local terminal’s current rows and columns for its PTY. The second reattaches to that same PTY after a disconnect and applies the current terminal size. Later window changes are forwarded while attached. Press Ctrl-] to detach without terminating the guest process; Ctrl-C is sent to the guest normally. Use --stop if a wedged or abandoned session must be terminated. The MVP permits one session and one attachment per computer. Session state lives in the running guest agent, so it does not survive a guest or computer restart. It has no named sessions, session listing, durable scrollback, or automatic reconnection.

​
create

Defaults are 2 vCPUs, 4096 MiB memory, a 120-second wait, and the platform’s managed default image. Pass --oci-image IMAGE_ID to select an immutable image previously published with vers image import. --disk is in GiB unless --mib is present. Use run to acquire and start an OCI workload in one command; create is the lower-level detached-computer command. --no-wait returns the admitted pending outcome with status 4 rather than claiming the computer is ready. The create operation UUID is written and flushed to stderr before the first control-plane request, including with --json, so an interrupted client keeps the recovery handle without contaminating stdout.

​
delete

The CLI writes and flushes a durable operation identity to stderr before deleting the computer. COMPUTER_ID must be an immutable UUID obtained from vers get COMPUTER or vers list --json; names are intentionally rejected so a lost-response retry cannot be redirected after the original computer disappears or a name is reused. If the result is still pending, human output also includes the exact retry command. Reuse that identity; do not mint a new one for the same retry.

​
checkpoint and restore

checkpoint captures CPU, memory, device, workload, and root-volume state. A successful result is published only after it is portable across Vers nodes. restore resumes that state into a new computer; labels describe the new control-plane resource and do not rewrite the hostname already running inside the guest. Restored computers remain awake by default, matching vers create; --allow-auto-sleep opts into inactivity sleeping. checkpoint waits up to 1800 seconds by default for portable publication; restore uses the same 120-second startup default as create. --no-wait returns exit status 4 while the validated operation remains pending; a terminal operation returned during admission keeps its normal terminal exit status. The CLI writes and flushes the operation UUID to stderr before admission. Transient admission responses are replayed automatically with that exact identity inside the command deadline. After an uncertain final response, rerun the exact invocation with the printed --idempotency-key; the same key and arguments converge on the original operation and result.

​
Legacy commit and resize

The CLI chooses a commit ID before sending the request and flushes it to stderr before that effect. COMPUTER_ID must be an immutable UUID obtained from vers get COMPUTER or vers list --json; names are rejected so retries cannot follow a later name binding. After an ambiguous response, rerun the exact same command with the same --commit-id; changing the computer ID, name, description, or wait policy conflicts with that identity instead of creating a different snapshot. commit retains the legacy v1 snapshot contract for compatibility. Its result is not a v2 portable checkpoint and is not accepted by vers restore. New checkpoint-and-resume workflows should use checkpoint and restore together. Disk sizes default to GiB. Resizing only grows the root disk and requires the immutable computer UUID so a reused name cannot redirect a retry.

​
Workloads

​
run

Public OCI references are the default. --local exports the image selected by Docker, OrbStack, or Podman on the client machine. An image UUID returned by vers image import is also accepted. run chooses the computer-create identity before any image effect and derives the image-import and local-upload identities from it. It writes and flushes the create and image-import identities to stderr before image resolution, export, or upload begins. If preparation or startup is uncertain, rerun the exact same invocation with the printed --idempotency-key. Changing verified image content, the public reference or source mode, the image name, or the computer request conflicts instead of creating a second interpretation of that identity. Supplying an existing image UUID performs only a catalog read before computer creation. Use -- before a workload command, especially when it has options:
Foreground mode passes workload stdout to local stdout, workload stderr to local stderr, and returns the workload’s exit status. It does not support --json, stdin forwarding, or signal forwarding. Ctrl-C cancels local CLI work, kills and reaps any container-engine process group, waits for archive verification to stop, and exits 130. It does not signal or delete the remote computer: foreground run detaches, and server-owned --rm cleanup continues.

​
Logs

logs reads retained command-execution entries. workload-logs reads the primary OCI workload. With both --follow and --json, each streamed event is one newline-delimited JSON value.

​
Files and SSH material

Human cat output is the file’s bytes. Its JSON form contains base64. write reads piped stdin when --content is absent and accepts at most 16 MiB. It refuses to read implicitly from a terminal, so an interactive invocation must pass --content. File modes are octal (0644, 755, or 0o600) and may not exceed 7777. write requires the immutable computer UUID; cat continues to accept any COMPUTER reference. ssh-key returns private connection material for one computer. Treat its stdout as a secret. Account SSH-key management is a gateway capability and is not part of the standalone parser.

​
Environment variables

These account-level values are applied to future computers:
Keys must be shell identifiers: a letter or underscore followed by letters, digits, or underscores. A mutation accepts at most 100 pairs; keys are limited to 256 UTF-8 bytes and values to 8192 UTF-8 bytes. An account retains at most 256 variables. replace replaces the entire set. Deletion requires --yes.
Human env list output includes values. Treat it as secret-bearing output and avoid copying it into logs.

​
Images

Without --local, SOURCE is a public registry reference. With --local, the CLI uses the selected local engine and keeps private-registry credentials on the client. The CLI writes and flushes the import operation ID to stderr before resolution or local engine work. Vers runs Linux/AMD64 images. Public multi-platform references select that variant; a local source must export it. On another host architecture, pull or build with --platform linux/amd64 before retrying. A local exported archive may be at most 5,000,000,000 bytes and contain at most 17 GiB of total uncompressed layer data. Imports are durable after admission. If a wait deadline expires after the CLI has received a validated pending snapshot, it renders that snapshot on stdout and returns status 4. A deadline can instead expire during preparation, the initial operation read, or admission before any snapshot exists; those paths do not promise recovery output on stdout. Resume admitted work with image status or operation wait. --idempotency-key recovers an uncertain import admission. Retry the exact same invocation with the same key. For a local source, Vers always inspects, exports, verifies, and hashes the current archive again before resending the durable request. The key is bound to the public source reference or local verified content, optional name, image identity, archive size, digest, and format; changed semantic input fails with a conflict instead of being mistaken for the original import. Local source spelling and the engine that produced byte-identical verified content are acquisition details, not different remote effects. Transient admission failures and a reservation that is too close to expiry are retried with the same identities inside the command’s one timeout budget. Local archive reads and seeks observe that deadline and Ctrl-C cooperatively before later hashing or upload can begin. Image JSON is a CLI-owned contract rather than a pass-through of control-plane responses. Import and inspect return one image object; list returns one bounded array page of those objects. --limit defaults to 50 and cannot exceed 100; --offset selects the next page without making the CLI aggregate an unbounded catalog in memory. A pending import or status wait returns the same recovery shape as a non-waiting status: import_id, status, cursor, stage, image_id, failure, and its three timestamps. Delete returns { "deleted": false, "image_id": "<UUID>" } on an already-absent replay and the same shape with deleted set to true on the first deletion. Image deletion accepts only the immutable UUID printed by image list or image inspect; names are intentionally rejected because they can be reused. Repeating deletion of the same UUID succeeds and reports that the image is already absent. An image referenced by a live computer or lifecycle resource still fails with a conflict.

​
Durable operations

get reads one snapshot. wait follows the durable event stream and resumes across reconnects until the operation becomes terminal or the deadline expires. The default wait deadline is 1800 seconds. After wait obtains a validated snapshot, a later timeout renders the last pending snapshot on stdout before returning status 4. If the initial read itself reaches the deadline, no snapshot is available to render.

​
JSON and output channels

--json exists only on commands that advertise it above. Structured commands render one CLI-owned result in either human or JSON form. Progress and recovery diagnostics go to stderr, leaving stdout available for results and pipelines. Foreground run and interactive session are different: they preserve the guest process’s output and status instead of wrapping them in JSON.

​
Exit status

Foreground run and interactive session may return any guest process exit status. If the process terminates by signal, the CLI returns 128 + signal. Anonymous CLI telemetry follows the documented default-on, explicit-opt-out contract above.