Install the CLI

vio builds, deploys and operates Viorant agents from a terminal. It turns a folder into a Space, validates a .vio file, stands the agent up on Viorant Cloud and hands you a URL — the same deploy pipeline as the Hub, without opening it.

These pages describe vio 1.0.0 or later. Running without installing, the one-line coding-agent setup, connecting before you deploy, vio run and vio logs --run need 1.0.4 or later. vio update --check and the npm-global update message need 1.0.6 or later. Check with vio --version, and run vio update if you are behind.

vio ships as one self-contained JavaScript file. It needs Node 22 or 24:

node --version   # v22.x or v24.x

You can also run it without installing anything. npx fetches the current release from npm and runs it, so any vio command works with npx -y @viorant/cli in front of it:

npx -y @viorant/cli --version

To put vio on your PATH with npm instead:

npm i -g @viorant/cli

The signed installer below stays the verified path: it checks a signature on the release (How releases are verified) and is what vio update keeps current.

macOS and Linux

curl -fsSL https://dl.viorant.ai/cli/install.sh | sh

The installer puts vio in ~/.viorant/bin/vio without sudo, then adds that folder to your PATH in your shell’s startup file:

Shell	File it adds the `PATH` line to
zsh	`~/.zshenv` (or `$ZDOTDIR/.zshenv`)
bash	`~/.bashrc`, and your login file (`~/.bash_profile`, `~/.bash_login` or `~/.profile`)
fish	`~/.config/fish/conf.d/vio.fish`
anything else	`~/.profile`

It prints each file it changed. The block it adds is marked # added by vio installer, and it is never added twice: a file that already mentions .viorant/bin is left alone. Open a new shell, then check:

vio --version

Keep your startup files untouched

To install without the installer editing any file, set VIO_NO_MODIFY_PATH:

curl -fsSL https://dl.viorant.ai/cli/install.sh | VIO_NO_MODIFY_PATH=1 sh

It writes nothing outside ~/.viorant/bin. If that folder isn’t on your PATH yet, it prints the line to add yourself:

export PATH="$HOME/.viorant/bin:$PATH"

If a startup file can’t be written — for example one managed read-only by Nix home-manager — the install still succeeds, and the installer warns with the exact line to add by hand:

vio install: could not write /Users/you/.zshenv; add this line yourself: export PATH="$HOME/.viorant/bin:$PATH"

Windows

There is no installer script for Windows yet. Paste this whole block into Windows PowerShell (5.1 or later). It makes the same two checks as the macOS and Linux installer, in order: the sha256 checksum, then the Cloud KMS signature, verified with Node’s crypto.verify against the pinned release key. If either check fails, the block stops with “Nothing was installed.” and does not run vio.js, even when it is pasted line by line:

& {
$ErrorActionPreference = 'Stop'
$v = (Invoke-RestMethod https://dl.viorant.ai/cli/latest.json).version
Invoke-WebRequest "https://dl.viorant.ai/cli/vio-$v.js" -OutFile vio.js
Invoke-WebRequest "https://dl.viorant.ai/cli/vio-$v.js.sha256" -OutFile vio.js.sha256
Invoke-WebRequest "https://dl.viorant.ai/cli/vio-$v.js.sig" -OutFile vio.js.sig
$expected = ((Get-Content vio.js.sha256 -Raw) -split '\s+')[0].ToLower()
$actual = (Get-FileHash vio.js -Algorithm SHA256).Hash.ToLower()
if ($expected -ne $actual) { throw "checksum mismatch. Nothing was installed." }
# BEGIN vio-release-pubkey (synced from scripts/vio-release-pubkey.pem by `npm run sync:pubkey`)
$pubkey = @'
-----BEGIN PUBLIC KEY-----
MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEqBMZIAQMlHrrVAxBjTYqcBljyNHz
0MRgxuGlzvBUdnGYu83jGTZSkS6Nw8OeMQNb32vKXaVjclnjXWVpT6OdoA==
-----END PUBLIC KEY-----
'@
# END vio-release-pubkey
$env:VIO_INSTALL_SIGNING_PUBKEY = $pubkey
$verify = @'
const { verify } = require('node:crypto');
const { readFileSync } = require('node:fs');
const [dataPath, sigPath] = process.argv.slice(1);
try {
  const data = readFileSync(dataPath);
  const sig = readFileSync(sigPath);
  const pubkey = process.env.VIO_INSTALL_SIGNING_PUBKEY;
  if (!verify('sha256', data, pubkey, sig)) {
    console.error('signature verification FAILED');
    process.exit(1);
  }
  console.log('signature verified');
} catch (error) {
  console.error(error instanceof Error ? error.message : String(error));
  process.exit(2);
}
'@
node -e $verify vio.js vio.js.sig
if ($LASTEXITCODE -ne 0) { throw "signature verification FAILED. Nothing was installed." }
node vio.js --version
}

Keep the block as one paste. The & { … } wrapper and $ErrorActionPreference = 'Stop' are what make it stop at the first failure. Run commands as node vio.js <command>. To update on Windows, repeat these steps, or run node vio.js update: with no install.sh to run, it downloads the release, checks the sha256 checksum and the signature, and replaces vio.js only if both pass.

Update

vio update

vio update installs the current release in place. On macOS and Linux it runs the same installer as above, so the same checksum and signature checks apply. When you are already current it says so and changes nothing. It is subcommand-only — there is no /update in the shell. To install a specific version, including an older one:

vio update --version 1.0.0

To check without installing, add --check:

vio update --check
vio update --check --json

It reports the installed version and the latest release, and installs nothing. With --json it prints one object on stdout: {current, latest, channel, updateAvailable, install, command}. install is how this copy was installed (installer, npm-global or npx), and command is the command that would update it. A coding agent runs this before it starts work. If it can’t reach the release server, it exits 1 with the reason on stderr. Installed with npm i -g? Then npm owns that copy, so vio update does not run the installer or touch it. It prints npm i -g @viorant/cli@latest for you to run instead. Running the install command again does the same thing, and VIO_VERSION pins a version there:

curl -fsSL https://dl.viorant.ai/cli/install.sh | VIO_VERSION=1.0.0 sh

Under npx, there is nothing installed for vio update to replace, so it explains instead of updating: it prints npx -y @viorant/cli@<version> <command> to pin a version, and the installer line above for a permanent install. Pin a version yourself by adding it after the package name, for example npx -y @viorant/cli@1.0.4 --version. The next release, while it is still being tested, is published under the beta dist-tag:

npx -y @viorant/cli@beta --version

About once a day vio checks for a newer release and, if there is one, prints a one-line notice to stderr naming vio update. The notice never installs anything, never touches stdout, and is skipped entirely on a --json run, so it cannot break a script. If your build is too old for Viorant Cloud, commands that talk to it refuse with a message that says to run vio update.

vio update updates the app. vio upgrade is your Viorant plan, not the CLI — see Your plan.

How releases are verified

On macOS and Linux the installer checks every release twice, with no extra tool to install and no way to opt out:

The sha256 checksum, before anything is written. It must match the checksum published beside the file.
A Cloud KMS signature. Viorant’s release workflow signs each release with a Cloud KMS key. The installer verifies that signature with Node’s own crypto.verify, against a public key pinned inside the installer script.

A bad or missing signature installs nothing, exactly as a bad checksum does: the installer stops with “Nothing was installed.” A checksum proves the file arrived intact. The signature proves it came from Viorant’s release workflow, which a checksum served from the same place as the file cannot. To confirm the key pinned in the installer is the one you expect, compare its fingerprint (the SHA-256 of the DER-encoded public key):

e9743c18617112150e1222332c9d37cfc34d3908af1928e4d5ddd727e75290a3

Every release is also signed with keyless Sigstore signing, from the release workflow’s GitHub identity, and recorded in the public Rekor transparency log. The installer does not run this check. It is an optional, independent second check you can run by hand with cosign:

cosign verify-blob --bundle vio-<version>.js.sigstore.json \
  --certificate-identity https://github.com/viorant/viorant-cli/.github/workflows/release.yml@refs/tags/v<version> \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com \
  vio-<version>.js

Windows makes the same two checks. The PowerShell block above and vio update on Windows both verify the sha256 checksum and then the signature, against the same pinned key, and install nothing if either fails.

Then

vio            # the interactive shell
vio --help     # every subcommand

Running vio with no arguments opens the interactive shell. In a script or a CI job, use the subcommands — they are the automation surface.

Turn a folder into a Space

Scaffold an agent you can edit and deploy.

Sign in

Connect vio to your Viorant account.

Get started

Concepts

Spaces

The Masters

Connectors & tools

Providers & models

Run an agent

Deploy

CLI

Evals

Help

Install the CLI

macOS and Linux

Keep your startup files untouched

Windows

Update

How releases are verified

Then

Turn a folder into a Space

Sign in

​macOS and Linux

​Keep your startup files untouched

​Windows

​Update

​How releases are verified

​Then

Turn a folder into a Space

Sign in

macOS and Linux

Keep your startup files untouched

Windows

Update

How releases are verified

Then