Skip to main content

​
Requirements

The initial release supports Linux and macOS on x86-64 and ARM64. Windows is not yet a release target. The installer requires curl plus either sha256sum or shasum on your PATH.

​
Install the CLI

The current source version is 0.2.0, but it has not been published. Do not promote this installer until immutable v0.2.0 artifacts and the stable release manifest are live.
The installer selects the binary for your platform, verifies its SHA-256 checksum, validates its version, and installs it atomically in /usr/local/bin/vers. If /usr/local/bin is not writable, install to a directory you own:
Make sure that directory is on your PATH, then verify the binary:
The default installer follows only the latest stable release. Prereleases do not change that channel; after an exact version is published, pin it explicitly:
Public release versions may be stable or use a -prerelease suffix. SemVer build metadata (+...) is intentionally not a public release identity.

​
Manual download

Immutable versioned artifacts live at https://releases.vers.sh/cli/v<version>/: Download the matching binary and adjacent .sha256 file, verify the checksum, make the binary executable, and move it onto your PATH. The adjacent checksum detects download corruption; it is not an independent signature.

​
Authentication

Get a key from the Vers dashboard. The CLI supports two local configuration channels.

​
Environment variable

Set VERS_API_KEY through your shell’s secret manager, CI secret store, or process environment. Avoid putting the literal key in a committed file or a command that will remain in shell history.

​
Configuration file

Alternatively, create ~/.versrc as JSON and restrict its permissions:
Edit the file directly; do not print it to verify authentication. Environment variables override values from ~/.versrc. The optional VERS_ORCHESTRATOR_URL environment variable overrides the default https://api.vers.sh; orchestratorUrl in ~/.versrc is the lower-precedence equivalent. Remote control-plane URLs must use HTTPS. Plain HTTP is accepted only for localhost or a numeric loopback address during local development, because the CLI sends its bearer credential to this origin. The URL must be a bare origin: credentials, a non-root path, query parameters, and fragments are rejected. Help and version commands are local and do not require configuration:

​
Anonymous telemetry

Anonymous command telemetry is enabled by default. Inspect the exact data and effective setting with:
Disable it persistently and delete the random installation ID:
For CI, air-gapped use, or an invocation that must not create telemetry state, use an environment-only opt-out:
Telemetry contains only a random installation ID, the typed command name, CLI version, operating system/version and architecture, and coarse failure status and duration. It never contains arguments, paths, command output, environment values, API credentials, or error messages. Delivery is best-effort and cannot change a command’s result or exit status. See the CLI reference telemetry contract.

​
Updating

Check for or install the latest stable release explicitly:
The updater selects this platform’s entry from the stable release manifest, streams the binary with a hard size limit, verifies its declared byte count and SHA-256 digest, runs its --version check, and atomically replaces the current executable. It never checks for updates in the background. The executable’s directory must be writable; otherwise, rerun the installer with the required permissions. The checksum detects corruption relative to the HTTPS release manifest. It is not an independent signature or proof of publisher identity.

​
Troubleshooting

​
Command not found

Check which binary your shell resolves:
If you used a user-owned install, add it to your shell startup file:

​
Authentication failed

Create or rotate the key in the dashboard, update one supported configuration channel, and run vers whoami. There is no vers login or vers logout state to repair.