Skip to content
Guides

The vitals command line

vitals runs your project's own checks (tests, a Docker smoke, a signing verification) on your machine, and says whether the project can ship. It's the same engine as the desktop app, with the same words and approvals. It works without an account for local results; signed in, each run it starts is a run in ShipVitals.

Install

vitals needs Node 24 or newer. On an older Node it says so in one line and stops.

  • From npm: npm install -g @nannertech/shipvitals.
  • From the desktop app: on a Mac, choose ShipVitals → Install Command Line Tool…. There's no desktop app for Linux: there, install from npm. The dialog asks Install the vitals command?; press Install. It says "Installed vitals at …", or, when that folder isn't on your PATH, which folder to add. This vitals runs the copy inside the app, with the same engine and approvals.

Run vitals --version to see the version, and vitals --help for the commands.

Run checks on this machine only

You don't need an account for this.

  1. In a project's folder, run vitals link. It finds the checks the project already has (Makefile targets, package scripts, .shipvitals/checks.yml) and shows each with why it was found. Nothing that deploys, publishes or pushes is proposed. In a terminal it asks "Link … with … checks? [y/N]". Without an account the project is named after the folder; name it yourself with --project <name>.
  2. Run vitals checks approve. Read each command: approving one means this machine may run it, on this branch ("This command, on this branch. It runs the code on that branch."). Answer y to "Approve … checks?".
  3. Run vitals run. Each check gets a row with its time and result, such as "412 passed", "3 of 88 failed", "Couldn't run: Docker isn't running" or "Skipped: …", then one line for the project. The first time, it says Sign in to keep these results.

Run vitals alone in a linked folder to see its project and each check's last result.

Sign in

  1. Run vitals login. It prints Sign in to ShipVitals, an address and a code like WDJB-MJHT (and, in a terminal, a QR code for your phone), then "Waiting for you to approve it…".
  2. Approve it in your browser as in Sign in on the desktop app or vitals. vitals says "Signed in. … runs checks for …".
  3. vitals link now matches the folder to your project by its GitHub remote; name it with --project if it doesn't. If this machine runs checks for several workspaces, choose one with --workspace <name>.
  4. vitals run queues the approved checks for this machine and runs them, so the results are in ShipVitals: its last line links to the run (Details: …).
  5. vitals gate prints the release verdict; vitals gate --wait waits for this commit's proof.

On a machine with no browser

For a Mac mini over SSH, or an image, issue a token in Settings → Runners → Issue a token (see Pair a runner), then on the machine:

  1. Run vitals login --token -. It asks for Runner token: without showing what you type. In a script, pipe it in instead: vitals login --token - < token.txt.
  2. It says "… runs checks for …", then "This machine runs what the web sends it. A run started here stays here until someone signs in with vitals login."

Don't type the token after --token: it would stay in your shell history, and vitals warns you if you do.

Sign out

vitals logout signs this machine out and removes the runners paired from it: "Signed out. Local results stay on this machine." On an always-on machine that should keep running checks for others, use vitals logout --keep-runner.

Commands

  • Command
    vitals
    Does
    This folder's project and its checks' last results; elsewhere, the help
  • Command
    vitals login
    Does
    Signs in through your browser and pairs this machine
  • Command
    vitals login --token -
    Does
    Pairs with a runner token, read from stdin
  • Command
    vitals logout [--keep-runner]
    Does
    Signs out; --keep-runner keeps this machine running checks
  • Command
    vitals doctor
    Does
    What this machine can run, and what's missing, with the command to install it
  • Command
    vitals link [path] [--project <name>] [--workspace <name>] [--yes]
    Does
    Links a folder to a project and proposes its checks; approves nothing
  • Command
    vitals checks [project] [--save]
    Does
    Lists checks and whether each is Approved, Not approved or Changed here; --save writes them to .shipvitals/checks.yml, uncommitted
  • Command
    vitals checks approve [project] [--check <id>] [--yes]
    Does
    Reviews and approves checks
  • Command
    vitals run [project] [--check <id>] [--only-changed] [--no-upload] [--accept-upload]
    Does
    Runs checks
  • Command
    vitals gate [project] [--wait]
    Does
    The release verdict; exits 0 only when Shippable
  • Command
    vitals walk [project] [--set-key] [--install-browser] [--cloud] [--guide <slug>]… [--persona <name>] [--target <address>] [--limit <n>] [--model <id>] [--without-reset] [--docs <url>] [--no-save]
    Does
    Walks the how-to guides in a browser and saves QA_REPORT_*.md for qa-repair: here with your own OpenRouter key, or --cloud with the workspace's AI credits. See Walk the guides and Walk the guides in the cloud
  • Command
    vitals status
    Does
    The engine, the agent, what's paired and the last run
  • Command
    `vitals agent install [--linger] \
    Does
    start \
    stop \
    logs`
    The background service
  • Command
    vitals relay
    Does
    Connections this machine relays
  • Command
    vitals relay add <id> --url <address> --user <name>
    Does
    Stores a relay's sign-in here; the password from stdin
  • Command
    `vitals relay remove <id> \
    Does
    --all`
    Removes a relay's sign-in, or every one
  • Command
    vitals relay run
    Does
    Runs every relay now, in the agent
  • Command
    vitals upload <report>...
    Does
    Sends a test report from CI or a laptop

--help (or -h) after any command prints the same help.

Approving checks

  • In a terminal, vitals checks approve asks. In a script, it needs --yes; without it: "Nothing was approved: approving needs a person here. Run it in a terminal, or pass --yes."
  • --check <id> approves only that check. You can give it more than once.
  • A check whose command changed since you approved it shows "… check changed. It won't run until someone here reviews it." and its diff. It's approved on its own, never in bulk: with --yes, name it with --check.

Running checks

  • --check <id> runs only that check; give it more than once for several.
  • --only-changed skips a check that names the paths it covers when nothing under them changed since it last passed: "Skipped: nothing it covers changed".
  • --no-upload keeps the results on this machine.
  • --accept-upload accepts a project's first upload without asking (see below).

What goes on a first upload

The first results of each project wait until you've seen what goes. In a terminal, after the run, vitals prints "Before …'s first upload, this is what goes to ShipVitals:", the rows (Result, Commit, Counts, Test names, First error, Files or Stays here), then "Error messages can contain what your app showed." and asks "Upload these results? It won't ask again for this project. [y/N]".

  • y: "…: uploaded. Its uploads go without asking from now on."
  • Anything else: "…: nothing was uploaded, and these results stay on this machine. The next upload asks again."

In a script, vitals run won't start a project's first upload unseen. Add --accept-upload to send what it prints, or --no-upload to keep the run here. vitals status lists first uploads still waiting. See What leaves your machine.

The release gate

vitals gate prints each linked project's verdict (Shippable, Not yet or Unproven, with the reason) and each requirement under it. It needs you signed in. With --wait, it checks every 15 seconds until the verdict is about this folder's commit and no longer waiting for proof, for up to 30 minutes (SHIPVITALS_GATE_WAIT_S sets the seconds). See The release gate.

Keep a machine running checks

vitals agent install starts the engine as a background service (launchd on a Mac, a systemd user unit on Linux), so the machine runs what the web sends it. It says "The agent is running. vitals talks to it from now on."

  • On Linux, a user service stops when you log out unless linger is on. In a terminal, install asks "Keep the agent running after you log out? …"; elsewhere it prints the loginctl enable-linger command, unless you pass --linger.
  • vitals agent stop and vitals agent start stop and start it.
  • vitals agent logs prints the last 200 lines of its log. -f keeps following it until you press Ctrl-C.
  • vitals status says "The ShipVitals agent is running on this machine." or "The ShipVitals agent isn't running." While the desktop app is open, it runs the checks instead, and vitals status says "The ShipVitals app is running checks on this machine."

Windows runs checks with vitals run, but not the agent yet: "vitals agent isn't available on Windows yet. Checks still run with vitals run."

Relay a self-hosted service

An always-on machine on your network can read a self-hosted service, such as Umami, for ShipVitals. Start in ShipVitals: in Connections, connect the service and choose Run through … with this machine's name. Then on the machine:

  1. Run vitals relay to see the connections it relays, with the id of each.
  2. Run vitals relay add <id> --url <address> --user <name>, and type the password when it asks (or pipe it in). It's tested from this machine first: "… works from this machine (… found). Its sign-in is in this machine's keychain and never leaves it."
  3. Relays run in the agent. Run vitals relay run to sync them now.

vitals relay remove <id> removes one sign-in, and vitals relay remove --all every one.

For scripts

  • Every command takes --json: standard output is then one JSON document, with exitCode in it.
  • Exit codes: 0 passed, 1 failed, 2 couldn't run or unproven, 3 usage.
  • vitals upload warns and exits 0 when reporting fails, so it never breaks a build; with --strict it exits 1. An unknown --format or --surface is a warning, and the results go up without it; with --strict it exits 3. See Send test results and your own metrics.
  • Colour follows NO_COLOR (any value turns it off). Output that isn't a terminal has no colour and no live line.

When it doesn't work

  • vitals says
    "vitals needs Node 24 or newer, and this is Node …"
    What to do
    Install Node 24 (nodejs.org, or nvm install 24) and run it again.
  • vitals says
    "Code expired. Get a new one: run vitals login again."
    What to do
    Run vitals login again.
  • vitals says
    "Sign-in was cancelled in the browser."
    What to do
    Run vitals login again, and approve it.
  • vitals says
    "ShipVitals can't be reached. These results stay on this machine."
    What to do
    Check your connection; results send later.
  • vitals says
    "That token wasn't accepted. Issue a new one in Settings → Runners."
    What to do
    Issue a new token, then vitals login --token -.
  • vitals says
    "Your plan's machines are all paired. …"
    What to do
    Replace one in Settings → Runners, then sign in again.
  • vitals says
    "Nothing is linked here yet. Run vitals link in a project's folder."
    What to do
    Run vitals link.
  • vitals says
    "Sign in first: run vitals login."
    What to do
    Run vitals login.
  • vitals says
    "The keychain is locked. …"
    What to do
    Unlock it (security unlock-keychain on a Mac), then try again.
  • vitals says
    "Another ShipVitals engine is already running on this machine."
    What to do
    The app or the agent is starting. Try again in a moment.
  • vitals says
    "The agent isn't installed. Run vitals agent install."
    What to do
    Run vitals agent install.
  • vitals says
    "Relays run in the agent on an always-on machine. …"
    What to do
    Run vitals agent install, then vitals relay run.