# 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](access.md) | Signing in, access tokens, project reach |
| [Monitors](monitors.md) | Monitor types and personal-account limits |
| [Repository workflow](repository-workflow.md) | `waitcher.json`, validate, plan, apply, rollback, adoption, secrets |
| [CI](ci.md) | GitHub Actions with `waitcher ci init` |
| [Coding agents](agents.md) | The agent skill, `doctor` and `explain` |
| [Results and evidence](results.md) | Run status, diagnosis, artifacts, local evidence |
| [Alerts](alerts.md) | Channels, routing, cooldowns, maintenance windows |
| [Account and data](account.md) | Capabilities, retention, export, deletion, CLI updates |
| [Troubleshooting](troubleshooting.md) | 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](agents.md#skill-help-and-docs)).

## Install the CLI

The CLI needs Node 24.15 or later:

```sh
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:

```sh
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:

```sh
waitcher run start --id MONITOR_ID --wait
waitcher monitor resume --id MONITOR_ID
```

To add a browser journey, see [Repository workflow](repository-workflow.md#write-tests).

## Try a check without an account

Local runs need no account and may target localhost:

```sh
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.