Waitcher
Docs
Open Waitcher
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:
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
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.
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; waitcher explain CODE explains any issue or error code offline.
Help
Help works offline and always matches the installed version:
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 |
config, runtime, deploy, secret | waitcher.json: validate, plan, apply, roll back, environment secrets | Repository workflow |
monitor | One monitor without waitcher.json; list, pause, resume, delete | Monitors |
run, artifact, report, incident | Start runs, read status, traces and evidence, diagnose failures, run locally | Results and evidence |
alert | Channels, routing policies, maintenance windows, deliveries | Alerts |
ci | GitHub Actions workflow | CI |
connection | Model connections for agent checks | Agent checks |
skill, doctor, explain | Agent skill, setup check, code meanings | Coding agents |
account, system | Plan, billing, export, deletion, capabilities | Account and data |
project, environment | Projects, environments and their limits | waitcher help project |
heartbeat | Heartbeat credentials and events | Monitors |
waitcher --help lists the rest, including groups that need a capability your account may not have.
Update
npm install --global @waitcher/cli@latest
Then, in each repository:
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.