# CronPup

> CronPup alerts people when scheduled jobs (cron jobs, backups, workers, CI schedules, timers) stop running or fail,
> and before TLS certificates expire. Each job gets a ping URL; if the ping is late (schedule + grace) or reports a
> failure, CronPup sends an email, ntfy push, Slack/Discord or webhook alert. Free for 10 monitors.

This file is for AI agents. If a person gave you a prompt like "https://cronpup.com/ onboard <something>", follow the
steps below. Never ask the person for their CronPup account API key: use the approval link flow, which gives you a key
that only works for the monitors they approve.

## Onboard a job in 5 steps

### 1. Find the job and pick the monitor type
Look at how the thing runs and choose:
- **Runs on a cron schedule** (crontab line, systemd OnCalendar, Kubernetes CronJob `schedule`, GitHub Actions
  `on.schedule.cron`, Celery beat crontab, Cloud Scheduler): a **cron monitor**: `"cron": "<5-field expression>"` and
  `"tz": "<IANA zone the schedule uses>"` (crontabs use the server's zone unless `CRON_TZ` is set; GitHub Actions uses
  UTC). Copy the expression exactly.
- **Runs every N seconds/minutes/hours** (a loop, a worker heartbeat, `OnUnitActiveSec`, `@hourly`-style intervals, a
  queue consumer): a **period monitor**: `"period": <seconds>` (20 s or more).
- **A TLS certificate to watch** (a domain, not a job): `"kind": "tls", "host": "<hostname>", "port": 443`.
- **Grace** (`"grace": <seconds>`, 10 s or more): how late a run may be before alerting. Use the job's usual run time
  plus a margin, e.g. 300 for a quick nightly job, 1800-3600 for a long backup, 15-60 for a fast loop.
- **Name**: what a person would recognise in an alert, e.g. "web1: nightly pg_dump".
One monitor per job. If one script runs several important jobs, propose one monitor per job (up to 5 per request).

### 2. Ask for approval (no account key needed)
```
POST https://cronpup.com/api/v1/agent/requests
Content-Type: application/json

{"client": "<your name, e.g. Claude Code on web1>",
 "monitors": [{"name": "web1: nightly pg_dump", "cron": "30 2 * * *", "tz": "Europe/Berlin", "grace": 1800}]}
```
The response (201) has `approve_url`, `poll_url` and `poll_token`. If it is 400, the `error` says which field to fix.
**Show `approve_url` to the person** and ask them to open it. They log in or create a free account there, see exactly
what you proposed, and click Approve. Requests expire after 1 hour.

### 3. Wait for approval
Poll every 5-10 seconds:
```
GET <poll_url>
Authorization: Bearer <poll_token>
```
`"status": "pending"` means keep waiting; `"denied"` means stop; `"approved"` returns `monitors` (each with its
`ping_url`) and `key`, a key scoped to these monitors only (starts with `cpm_`, shown once: keep it if you need it later).

### 4. Wire the ping into the job
Report success at the end of each run and, where possible, the exit code, so failures alert at once:
- crontab: `30 2 * * *  /path/job.sh; curl -fsS -m 10 --retry 3 <ping_url>/$?`
- or the CLI (start signal, exit code and output tail):
  `curl -fsSL https://cronpup.com/install.sh | sh` then `30 2 * * *  cronpup run <monitor uuid> -- /path/job.sh`
- systemd (Type=oneshot): `ExecStartPost=-/usr/bin/curl -fsS -m 10 <ping_url>`
- Kubernetes CronJob: append `; curl -fsS -m 10 --retry 3 <ping_url>/$?` to the container command
- GitHub Actions: last step `if: always()`, `run: curl -fsS -m 10 --retry 3 <ping_url>/${{ job.status == 'success' && '0' || 'fail' }}`
- Python: `urllib.request.urlopen("<ping_url>", timeout=10)` after the work; `<ping_url>/fail` on an exception
- Long jobs: request `<ping_url>/start` when they begin, so a hung run alerts too.
Never let a failed ping fail the job (`curl ... || true`, try/except). Keep the user's existing schedule and command
unchanged apart from the added ping.

### 5. Verify
Run the job once if that is safe, or send a single ping to `<ping_url>`, then check:
```
GET https://cronpup.com/api/v1/agent/monitors
Authorization: Bearer <key>
```
Done when the monitor shows `"status": "up"` and a recent `last_ping`. Tell the person the dashboard link from the
response and when the next run is expected. With the same key you can `POST /api/v1/agent/monitors/<id>/pause` or
`/resume` (e.g. around maintenance).

## Reference
- Human docs: https://cronpup.com/docs (markdown: https://cronpup.com/docs.md)
- Ping URL signals: `<ping_url>` success, `/start`, `/fail`, `/<exit code>` (0 = success), `POST` a body up to 10 KB to
  attach output. `POST <ping_url>/pause` and `/resume` pause and resume the monitor (`?expect=1` on resume: expect a
  ping within period + grace).
- Full account API (for people who choose to use their own key): https://cronpup.com/docs#manage
- Cron expression checker: https://cronpup.com/tools/cron
- Support: support@cronpup.com