openstatus-cli

# OpenStatus CLI Manage uptime monitors, incidents, public status reports, status pages, notifications, and maintenance windows from the terminal. The CLI supports monitors-as-code via YAML config files. Run `openstatus --help` or `openstatus <command> --help` for full option details. ## Prerequisites Most commands require authentication. Verify with: ```bash openstatus whoami ``` This shows your workspace name, slug, and plan. If not authenticated, run `openstatus login` and paste your API token from the OpenStatus dashboard. Run `openstatus logout` to remove the saved token. Token resolution order: 1. `--access-token` / `-t` flag 2. `OPENSTATUS_API_TOKEN` environment variable 3. Saved token at `~/.config/openstatus/token` **Exception:** `openstatus check <URL>` is **unauthenticated** — it uses the public global speed checker. Reach for it when the user wants an ad-hoc multi-region check without setting up a saved monitor. ## Command Overview | Task | Command | When to use | |------|---------|-------------| | Ad-hoc global speed check (no auth) | `check <URL>` | One-shot HTTP check from 28 regions — no saved monitor needed | | Sync monitors from config | `monitors apply` | You have an `openstatus.yaml` and want to create/update/delete monitors | | List all monitors | `monitors list` | See what monitors exist in the workspace | | Get monitor details + metrics | `monitors info <ID>` | Check latency, status, and config for a specific monitor | | List monitor response logs | `monitors logs <ID>` | See recent HTTP responses (14-day retention) to debug failures | | Get a single log's full detail | `monitors log-info <ID> <LogID>` | Inspect timing phases, response headers, and assertion results for one request | | Trigger a monitor now | `monitors trigger <ID>` | Run an on-demand check across all regions | | Delete a monitor | `monitors delete <ID>` | Remove a monitor | | Export monitors to YAML | `monitors import` | Pull existing monitors into an `openstatus.yaml` + lock file | | Declare an incident | `incident declare` | Something is broken — start the internal response first | | List incidents | `incident list` | See open/recent incidents (`--active`, `--closed`, `--status`) | | Get incident details + timeline | `incident info <ID>` | Severity, commander, allowed transitions, timeline | | Edit an incident | `incident update <ID>` | Change title, severity, summary, commander or start time | | Change incident status | `incident mitigate/resolve/reopen/cancel <ID>` or `incident set-status <ID> --status …` | Move through the lifecycle, optionally with `--note` | | Add a timeline note | `incident note <ID> --message …` | Record what happened or what was tried | | Link a status report | `incident link-report <ID> <ReportID>` / `unlink-report <ID>` | Connect the public report to the incident | | Close an incident | `incident close <ID>` | After it is resolved and the postmortem is approved (or `--skip-postmortem`) | | Delete an incident | `incident delete <ID>` | Only for incidents declared by mistake (still open, never mitigated) | | Read/write/approve the postmortem | `incident postmortem show/edit/approve <ID>` | After the incident is resolved | | Create public status report | `status-report create` | Users are affected — publish on the status page (link with `--incident-id`) | | Add update to status report | `status-report add-update <ID>` | Post a public progress update | | List status reports | `status-report list` | See active/recent public reports | | Get status report details | `status-report info <ID>` | View the public update timeline | | Update status report metadata | `status-report update <ID>` | Change title or components | | Delete status report | `status-report delete <ID>` | Remove a status report | | List status pages | `status-page list` | See all your status pages | | Get status page details | `status-page info <ID>` | View page config, components, theme | | List notifications | `notification list` | See all notification channels in the workspace | | Get notification details | `notification info <ID>` | View provider config, linked monitors | | Create a maintenance window | `maintenance create` | Plan a maintenance window for a status page | | List maintenance windows | `maintenance list` | See scheduled/active/completed maintenance | | Get maintenance details | `maintenance info <ID>` | View full details of a maintenance window | | Update a maintenance window | `maintenance update <ID>` | Change title, message, or time window | | Delete a maintenance window | `maintenance delete <ID>` | Remove a maintenance window | | Run synthetic tests | `run` | Execute on-demand tests for specific monitors | | Generate Terraform config | `terraform generate` | Export workspace resources to Terraform HCL files | | Check workspace | `whoami` | Verify auth and workspace info | | Save API token | `login` | Authenticate — paste your token from the dashboard | | Remove saved token | `logout` | Sign out (deletes the saved token) | Command aliases: `check` = `c`, `monitors` = `m`, `incident` = `inc` / `incidents` (and `incident declare` = `create`, `incident postmortem` = `pm`), `status-report` = `sr`, `status-page` = `sp`, `notification` = `n`, `maintenance` = `mt`, `terraform` = `tf` (and `terraform generate` = `gen`), `run` = `r`, `whoami` = `w`. `login` and `logout` have no aliases. ## Workflows ### Ad-hoc global speed check (no auth) When the user wants to test how an HTTP endpoint performs from around the world without setting up a saved monitor, reach for `check`. It hits the public OpenStatus speed checker and streams per-region latency live. ```bash openstatus check https://openstat.us # GET, no auth, 28 regions openstatus check https://openstat.us -X POST -H 'Authorization: Bearer …' -d '{"ping":true}' openstatus check https://openstat.us -d @payload.json openstatus check https://openstat.us --timing # DNS / Conn / TLS / TTFB / Transfer openstatus check https://openstat.us --json | jq '.summary' ``` **Flags:** | Flag | Description | |------|-------------| | `--method` / `-X` | HTTP method (default `GET`; not auto-promoted to POST when `-d` is set — explicit) | | `--header` / `-H` | Header in `"Key: Value"` form (repeatable, curl-style) | | `--body` / `-d` | Inline string, `@/path/to/file`, or `@-` for stdin | | `--timing` | Show DNS/Connection/TLS/TTFB/Transfer phase columns | **Output behavior:** - Human mode streams one row per region as it arrives (no client-side sort), then prints a summary (fastest, slowest, mean latency, success rate) and a `View:` shareable link. - `--json` buffers and emits a single object with `url`, `check_id`, `share_url`, `results[]`, and `summary{}`. - `--quiet` silences stdout (errors still print on stderr). - Failure rows show `—` for missing latency/status and the server's `message` (e.g. `url not reachable`) in the State column. **Rate limit:** 3 requests per 60 seconds. On 429 the CLI prints `Rate limited. Retry after Xs. (3 requests per 60s allowed.)` and exits 1 — do not auto-retry in scripts; loop in shell if needed. **When NOT to use `check`:** - Recurring uptime monitoring → use `monitors apply` with an `openstatus.yaml`. - Tests that need to run from monitor-configured regions (or with saved assertions) → use `monitors trigger <ID>` or `run`. ### Setting up monitors (monitors-as-code) This is the primary way to manage monitors. Write a YAML config, then let the CLI sync it. **Starting from scratch:** 1. Create an `openstatus.yaml` file — see [references/monitor-config.md](references/monitor-config.md) for the full schema 2. Preview changes: `openstatus monitors apply --dry-run` 3. Apply: `openstatus monitors apply` 4. The CLI creates a `openstatus.lock` file to track state — commit this alongside your config **Starting from existing monitors:** 1. Export: `openstatus monitors import` (creates `openstatus.yaml` + `openstatus.lock`) 2. Edit the YAML as needed 3. Apply changes: `openstatus monitors apply` **The apply workflow** compares your `openstatus.yaml` against the lock file and the API, then creates, updates, or deletes monitors to match. Use `--dry-run` to preview, `-y` to skip the confirmation prompt. ### Running an incident **Incident vs. status report:** an **incident** is the internal response — severity, commander, lifecycle, timeline notes and the postmortem. A **status report** is the public communication on a status page. When something is broken ("our API is down", "we have an incident"), **declare an incident first**; then, if users are affected, publish a status report linked to it with `--incident-id`. Changing the incident status never updates the public report — post public updates with `status-report add-update`. Severities: `critical`, `major`, `minor`. Statuses: `open` -> `mitigated` -> `resolved`, or `canceled`. | From | Allowed transitions | |------|---------------------| | `open` | `mitigated`, `resolved`, `canceled` | | `mitigated` | `resolved`, `open`, `canceled` | | `resolved` | `open` | `canceled` is terminal and closes the incident. "Closed" is not a status: a closed incident keeps its last status, has a `closed_at` timestamp, and is read-only except for its postmortem. `incident info <ID>` lists the allowed transitions from the current state. **1. Declare:** ```bash openstatus incident declare \ --title "Checkout API returns 502" \ --severity major \ --summary "Payments failing for EU customers" \ --commander jane@example.com ``` Prints `Incident declared (ID: 42)` and the next step. Use `-q` to print only the ID: `ID=$(openstatus inc declare --title "…" --severity major -q)`. **`declare` flags:** | Flag | Required | Description | |------|----------|-------------| | `--title` | yes | 1-256 characters | | `--severity` | yes | `critical`, `major` or `minor` | | `--summary` | no | Short human summary | | `--commander` | no | Email of the workspace member leading the response (emailed when assigned) | | `--started-at` | no | RFC 3339 start of impact, defaults to now; can be in the past | | `--status-report-id` | no | Link an existing status report | | `--slack` | no | Open a dedicated Slack channel when Slack is connected | > **Interactive vs. scripted:** without `--title` or `--severity`, `declare` prompts on a terminal; with `--json` or a non-TTY stdin it fails with `missing required flags: …`. Always pass both when scripting. **2. Publish the public status report, linked to the incident** (only if users are affected — see [Public status reports](#public-status-reports)): ```bash openstatus status-report create --title "Checkout issues" --status investigating \ --message "We are investigating failed payments" --page-id 123 --incident-id 42 ``` Or link an existing report: `openstatus incident link-report 42 456` (`unlink-report 42` removes it). **3. Record what happens and move the status:** ```bash openstatus incident note 42 --message "Rolled back deploy 2026-10-16.3" echo "multi-line markdown" | openstatus incident note 42 --message - openstatus incident mitigate 42 --note "Traffic shifted to the healthy region" openstatus incident resolve 42 --note "Error rate back to baseline" openstatus incident reopen 42 --note "Errors are back" openstatus incident set-status 42 --status resolved # generic form, for scripts openstatus incident cancel 42 -y # declared in error but already mitigated: closes it ``` Edit metadata with `incident update 42 [--title …] [--severity …] [--summary … | --clear-summary] [--commander … | --clear-commander] [--started-at …]`. **4. Postmortem (after it is resolved), then close:** ```bash openstatus incident postmortem edit 42 --file postmortem.md # or --file - (stdin), or --content "…" openstatus incident postmortem show 42 # piped: raw markdown only openstatus incident postmortem approve 42 --close -y # approve and close in one step openstatus incident close 42 --skip-postmortem -y # close without a postmortem ``` `postmortem show 42 > pm.md`, edit, then `postmortem edit 42 --file pm.md` round-trips the body. **5. Inspect and list:** ```bash openstatus incident info 42 # details + timeline, newest first openstatus incident list # everything, newest declared first openstatus incident list --active # not closed openstatus incident list --status open,mitigated --limit 10 --offset 10 ``` **Rules agents must know:** - `cancel` (and `set-status --status canceled`), `close`, `delete` and `postmortem approve --close` ask for confirmation; pass `-y` when not on a terminal. - `delete` only works while the incident is open and was never mitigated; otherwise `cancel` it. - `close` needs a resolved incident and an approved postmortem, or `--skip-postmortem`. - `close`, `delete` and `postmortem approve` act as the API key's creator: they need a workspace owner/admin (or the incident commander for close/approve). API keys without a creator get `permission denied`. - Every command that changes an incident prints the incident as JSON with `--json`, and only its ID with `-q`. - A refused change (wrong transition, closed incident, report already linked) prints the server's reason plus a hint. ### Public status reports Use status reports to communicate **unplanned** outages publicly on a status page. When there is an incident, link the report to it with `--incident-id`. Status reports follow a progression: `investigating` -> `identified` -> `monitoring` -> `resolved`. These are the only valid status values — the CLI rejects anything else. **1. Find your status page ID and component IDs first:** ```bash openstatus status-page list openstatus status-page info <PAGE_ID> # shows components grouped by section ``` **2. Create the incident:** ```bash openstatus status-report create \ --title "API Degradation" \ --status investigating \ --message "We are investigating increased error rates on the API" \ --page-id 123 \ --impact comp-1=major_outage --impact comp-2=degraded \ --notify ``` (Or use the legacy `--component-ids "comp-1,comp-2"` instead of `--impact` to mark components affected without a per-component level — the two are mutually exclusive.) On success, the CLI prints the report ID and suggests the next command: ``` Status report created successfully (ID: 456) To add updates, run: openstatus status-report add-update 456 --status identified --message '...' ```