Waitcher user guide
Waitcher runs your checks against your own sites on a schedule and alerts you when they fail. You write the checks next to your product: HTTP and certificate checks as JSON, API and browser journeys as end-to-end tests with the e2e framework. The waitcher CLI deploys them as monitors, and every run keeps evidence you can read later. The guide is written for people and for the coding agents that work in their repositories.
| Page | Covers |
|---|---|
| Access | Signing in, access tokens, project reach |
| Monitors | Monitor types and personal-account limits |
| Repository workflow | waitcher.json, validate, plan, apply, rollback, adoption, secrets |
| CI | GitHub Actions with waitcher ci init |
| Coding agents | The agent skill, doctor and explain |
| Results and evidence | Run status, diagnosis, artifacts, local evidence |
| Alerts | Channels, routing, cooldowns, maintenance windows |
| Account and data | Capabilities, retention, export, deletion, CLI updates |
| Troubleshooting | Exit codes and issue codes |
For agents. Every page is also plain Markdown at its path plus .md (for example https://waitcher.dev/docs/repository-workflow.md; this page is /docs/index.md). https://waitcher.dev/llms.txt indexes the pages, and https://waitcher.dev/llms-full.txt is the whole guide in one file. With the CLI installed, the agent skill and waitcher help TOPIC are the better sources (Coding agents).
Install the CLI
The CLI needs Node 24.15 or later:
npm install --global @waitcher/cli
waitcher --version
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.
Every command prints JSON. Help works offline: waitcher help deploy (or waitcher deploy --help) prints only the matching section.
Quickstart
In the repository of the site you want to watch:
waitcher auth login
waitcher config init --project-name "My Site" --target https://example.com
waitcher config validate
waitcher deploy plan --env production
waitcher deploy apply --env production --based-on none
config init writes a waitcher.json with two monitors: home (HTTP 200 on /) and tls (certificate expiry). The plan shows what would change and changes nothing. The first apply uses --based-on none; later applies use the basedOn value from the plan, which the plan's next prints for you. The apply result lists each monitor's ID.
New monitors start paused. Run one once on the server, then resume it when you want it on a schedule:
waitcher run start --id MONITOR_ID --wait
waitcher monitor resume --id MONITOR_ID
To add a browser journey, see Repository workflow.
Try a check without an account
Local runs need no account and may target localhost:
waitcher monitor init --file website.monitor.json --target https://example.com/
waitcher run local --file website.monitor.json
A local pass shows the check works on your machine. It is not uploaded and does not prove the hosted check is allowed or healthy.