CLI commands
dev, check, db, incident and maintenance — every command, flag and exit code.
The heyo-status binary ships with @heyo-sh/heyo-status and operates on the
project's configuration file directly — no running server, no API token.
Every command accepts --config, defaulting to HEYO_STATUS_CONFIG or
./heyo-status.config.ts. The configuration must export the heyoStatus()
result as statusPage or as the default export.
It loads a TypeScript configuration module directly. Bun 1.4.3+ is required even when the project is installed with npm, pnpm or Yarn.
dev
Starts the local cron scheduler and, optionally, a framework dev server.
- Everything after
--is spawned as a child process with inherited stdio; the scheduler stops when it exits. - Without a command, the CLI serves the API itself on
--port(orPORT, default3000) plus a small index page at/. This path requires Bun. - One check runs immediately, so a fresh database is never empty.
- Then
checks.interval,checks.summaryCronandchecks.cleanupCrondrive the schedule. SIGINTandSIGTERMstop both the server and the scheduler.
The scheduler evaluates once per second but runs each job at most once per
minute, and the minute of the initial check is marked consumed so
* * * * * does not fire twice at startup.
check run
Runs every monitor once, stores the results, reconciles automatic incidents and dispatches notifications.
| Exit code | Meaning |
|---|---|
0 | Every check passed, or no monitors. |
1 | At least one check failed. |
The non-zero exit makes it usable as a post-deploy smoke test.
db migrate
Calls migrate() when the adapter exposes it — PostgreSQL and D1 — and
otherwise reports that embedded migrations are applied automatically, which
is the SQLite case. Run it per environment before the first deploy and after
upgrading the package.
db seed
Fabricates deterministic history so a new page has something to draw.
| Flag | Required | Notes |
|---|---|---|
--uptime | yes | 0–100. |
--days | yes | Positive integer. |
It writes 100 evenly distributed checks per monitor per day, with failures spread to match the requested uptime exactly, then compacts everything before today into daily summaries:
Seed a development or demo database only. There is no "unseed"; clearing it means deleting the rows yourself or starting from a fresh database.
incident
| Command | Required flags | Optional |
|---|---|---|
create | --title, --severity, --monitors, --message | --status (not resolved) |
update | positional <id> | --status, --severity, --message |
resolve | positional <id>, --message | — |
list | — | --status, --severity |
--monitors is a comma-separated list, trimmed and de-duplicated. Records
are printed as formatted JSON, so the output pipes into jq.
update --status resolved is equivalent to resolve. Omitting --message
on update uses "Incident details updated.".
maintenance
--start and --end are ISO-8601; --end must be after --start.
list prints upcoming and in-progress windows, with their status refreshed
against the current time.
Option parsing
--name valueand--name=valueare both accepted.- An unknown option is an error — flags are never silently ignored.
- Repeating an option is an error.
- An option whose value is missing or starts with
--is an error. - Unexpected positional arguments are rejected, except where documented.
Failures print heyo-status failed: <message> and exit 1.
CLI versus HTTP
| Task | CLI | HTTP |
|---|---|---|
| Run checks | check run | POST /admin/checks/run |
| Compact history | dev scheduler | — (cron only) |
| Delete old history | dev scheduler | — (cron only) |
| Create an incident | incident create | POST /admin/incidents |
| Migrate | db migrate | — |
| Seed | db seed | — |
The CLI talks to the database directly, so it needs database access but no admin token. The HTTP API needs a token but no database access. Use the CLI locally and in CI; use the API from a deployed environment.