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

### 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](release-gate.md).

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