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
vitalsruns 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.
- 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>. - 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."). Answeryto "Approve … checks?". - 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
- 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…". - Approve it in your browser as in Sign in on the desktop app or vitals.
vitalssays "Signed in. … runs checks for …". vitals linknow matches the folder to your project by its GitHub remote; name it with--projectif it doesn't. If this machine runs checks for several workspaces, choose one with--workspace <name>.vitals runqueues the approved checks for this machine and runs them, so the results are in ShipVitals: its last line links to the run (Details: …).vitals gateprints the release verdict;vitals gate --waitwaits 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:
- 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. - 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-runnerkeeps 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;
--savewrites 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
0only 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_*.mdfor qa-repair: here with your own OpenRouter key, or--cloudwith 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
| 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 and Walk the guides in the cloud | |||
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 approveasks. 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-changedskips a check that names the paths it covers when nothing under them changed since it last passed: "Skipped: nothing it covers changed".--no-uploadkeeps the results on this machine.--accept-uploadaccepts 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-lingercommand, unless you pass--linger. vitals agent stopandvitals agent startstop and start it.vitals agent logsprints the last 200 lines of its log.-fkeeps following it until you press Ctrl-C.vitals statussays "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, andvitals statussays "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:
- Run
vitals relayto see the connections it relays, with the id of each. - 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." - Relays run in the agent. Run
vitals relay runto 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, withexitCodein it. - Exit codes:
0passed,1failed,2couldn't run or unproven,3usage. vitals uploadwarns and exits0when reporting fails, so it never breaks a build; with--strictit exits1. An unknown--formator--surfaceis a warning, and the results go up without it; with--strictit exits3. 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
vitalssays- "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.
vitalssays- "Code expired. Get a new one: run vitals login again."
- What to do
- Run
vitals loginagain.
vitalssays- "Sign-in was cancelled in the browser."
- What to do
- Run
vitals loginagain, and approve it.
vitalssays- "ShipVitals can't be reached. These results stay on this machine."
- What to do
- Check your connection; results send later.
vitalssays- "That token wasn't accepted. Issue a new one in Settings → Runners."
- What to do
- Issue a new token, then
vitals login --token -.
vitalssays- "Your plan's machines are all paired. …"
- What to do
- Replace one in Settings → Runners, then sign in again.
vitalssays- "Nothing is linked here yet. Run vitals link in a project's folder."
- What to do
- Run
vitals link.
vitalssays- "Sign in first: run vitals login."
- What to do
- Run
vitals login.
vitalssays- "The keychain is locked. …"
- What to do
- Unlock it (
security unlock-keychainon a Mac), then try again.
vitalssays- "Another ShipVitals engine is already running on this machine."
- What to do
- The app or the agent is starting. Try again in a moment.
vitalssays- "The agent isn't installed. Run vitals agent install."
- What to do
- Run
vitals agent install.
vitalssays- "Relays run in the agent on an always-on machine. …"
- What to do
- Run
vitals agent install, thenvitals relay run.
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. |