# CLI

The `waitcher` CLI is how you work with Waitcher from a repository: you deploy monitors from `waitcher.json`, start runs, read evidence, and set up alerts, tokens and secrets. The web app shows the same monitors and runs.

## Install

The CLI needs Node 24.15 or later:

```sh
npm install --global @waitcher/cli
waitcher --version
waitcher doctor
```

`doctor` checks your Node version, session, server and runtime, then prints the next step. CI that must match the server exactly can install the archive the server serves instead (`https://waitcher.dev/downloads/cli.json` names it with its SHA-256); `waitcher ci init` writes that step.

## Sign in

```sh
waitcher auth login
waitcher auth status
```

`auth login` opens a browser. Scripts and CI sign in with an automation token instead (`auth login --token-file FILE` or `--token-stdin`). The session is saved under `~/.config/waitcher/`; `WAITCHER_CONFIG_DIR` moves it, and `WAITCHER_SERVER` points the CLI at another instance. See [Access](access.md).

## Output and exit codes

Every command prints JSON on stdout, so scripts and agents can read it. Errors print `{"error":{"code","message"}}` on stderr with a non-zero exit code. `run diagnose` and `run scenarios` print a readable report unless you pass `--json`. The exit codes, and what to do about each, are in [Troubleshooting](troubleshooting.md#exit-codes); `waitcher explain CODE` explains any issue or error code offline.

## Help

Help works offline and always matches the installed version:

```sh
waitcher --help          # overview and topic list
waitcher help deploy     # one topic
waitcher deploy --help   # the same, by group
waitcher help all        # everything
```

## Commands

Commands follow `waitcher GROUP COMMAND [options]`. The groups you will use most:

| Group | Does | Guide |
| --- | --- | --- |
| `auth`, `token` | Sign in, automation and project tokens | [Access](access.md) |
| `config`, `runtime`, `deploy`, `secret` | `waitcher.json`: validate, plan, apply, roll back, environment secrets | [Repository workflow](repository-workflow.md) |
| `monitor` | One monitor without `waitcher.json`; list, pause, resume, delete | [Monitors](monitors.md#one-monitor-without-waitcherjson) |
| `run`, `artifact`, `report`, `incident` | Start runs, read status, traces and evidence, diagnose failures, run locally | [Results and evidence](results.md) |
| `alert` | Channels, routing policies, maintenance windows, deliveries | [Alerts](alerts.md) |
| `ci` | GitHub Actions workflow | [CI](ci.md) |
| `connection` | Model connections for agent checks | [Agent checks](agent-checks.md) |
| `skill`, `doctor`, `explain` | Agent skill, setup check, code meanings | [Coding agents](agents.md) |
| `account`, `system` | Plan, billing, export, deletion, capabilities | [Account and data](account.md) |
| `project`, `environment` | Projects, environments and their limits | `waitcher help project` |
| `heartbeat` | Heartbeat credentials and events | [Monitors](monitors.md#types) |

`waitcher --help` lists the rest, including groups that need a capability your account may not have.

## Update

```sh
npm install --global @waitcher/cli@latest
```

Then, in each repository:

```sh
waitcher skill install       # refresh the agent skill
waitcher runtime install     # lists runtime upgrades; rerun with --yes
waitcher doctor
```

After a CLI update the previous runtime still deploys for one release with a `RUNTIME_VERSION_OUTDATED` warning. `doctor` warns when your CLI and the server disagree on the runtime.