openstatus-cli

# OpenStatus CLI Manage uptime monitors, incident 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 | | Create incident report | `status-report create` | Something is broken, notify users | | Add update to incident | `status-report add-update <ID>` | Post a progress update on an ongoing incident | | List incidents | `status-report list` | See active/recent incidents | | Get incident details | `status-report info <ID>` | View full incident timeline | | Update incident metadata | `status-report update <ID>` | Change title or components | | Delete incident | `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`, `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. ### Incident lifecycle Use status reports for **unplanned** outages and incidents. 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 '...' ``` **`create` flags:** | Flag | Required | Description | |------|----------|-------------| | `--title` | yes | Incident title | | `--status` | yes | `investigating`, `identified`, `monitoring`, or `resolved` | | `--message` | yes | Initial message describing the incident | | `--page-id` | yes | Status page ID (get it from `status-page list`) | | `--impact` | no | Per-component impact, repeatable: `--impact <component_id>=<level>`. Level is one of `operational`, `degraded`, `partial_outage`, `major_outage`. Mutually exclusive with `--component-ids`. | | `--component-ids` | no | **Legacy.** Comma-separated component IDs in a single string: `"id1,id2"` — marks them all affected without a specific impact level. Prefer `--impact`. Mutually exclusive with `--impact`. | | `--notify` | no | Send notification to status page subscribers | | `--date` | no | RFC 3339 timestamp (e.g. `2026-03-25T10:00:00Z`), defaults to now (UTC) | The four impact levels are `operational`, `degraded`, `partial_outage`, `major_outage` (`degraded_performance` is also accepted as an alias for `degraded`). Pass `--impact` once per component, e.g. `--impact comp-1=major_outage --impact comp-2=degraded`. > **Interactive vs. scripted:** if any required flag (`--title`, `--status`, `--message`, `--page-id`) is missing, the CLI launches an interactive wizard on a terminal. In non-interactive contexts (when `--json` is set or stdin isn't a TTY — i.e. how Claude runs it), it instead errors with `missing required flags: …` and exits 1. Always pass every required flag. **3. Post updates as you learn more:** ```bash openstatus status-report add-update 456 \ --status identified \ --message "Root cause identified: database connection pool exhaustion" \ --notify ``` **`add-update` flags:** | Flag | Required | Description | |------|----------|-------------| | `--status` | yes | New status value | | `--message` | yes | Update message | | `--impact` | no | Per-component impact, repeatable: `--impact <component_id>=<level>` (`operational`, `degraded`, `partial_outage`, `major_outage`). Can also add newly affected components to the report. | | `--notify` | no | Notify subscribers | | `--date` | no | RFC 3339 timestamp, defaults to now (UTC) | **4. Resolve:** ```bash openstatus status-report add-update 456 \ --status resolved \ --message "Connection pool limits increased, monitoring confirms recovery" \ --notify ``` When status is set to `resolved`, the CLI confirms: `Report resolved.` **5. Update metadata (title or components) without changing status:** ```bash openstatus status-report update 456 \ --title "API Degradation - Resolved" \ --component-ids "comp-1,comp-3" ``` At least one of `--title` or `--component-ids` must be provided. Note: `--component-ids` **replaces** the entire list — it's not additive. **6. Track incident progress:** ```bash openstatus status-report info 456 ``` Shows full metadata plus the **update timeline** — each update displayed as `<date> [status] <message>`. **7. List and filter incidents:** ```bash openstatus status-report list # all reports openstatus status-report list --status investigating # only active investigations openstatus status-report list --limit 10 # last 10 reports ``` **8. Delete an incident:** ```bash openstatus status-report delete 456 # prompts for confirmation openstatus status-report delete 456 -y # skip confirmation ``` ### Scheduling maintenance Use maintenance for **planned** downtime windows. **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 a maintenance window:** ```bash openstatus maintenance create \ --title "Database Migration" \ --message "Scheduled database migration to improve performance" \ --from "2026-04-05T02:00:00Z" \ --to "2026-04-05T04:00:00Z" \ --page-id 123 \ --component-ids "comp-1,comp-2" \ --notify ``` On success, the CLI prints the maintenance ID and suggests the next command: ``` Maintenance created successfully (ID: 789) Run 'openstatus maintenance info 789' to see details ``` **`create` flags:** | Flag | Required | Description | |------|----------|-------------| | `--title` | yes | Maintenance title | | `--message` | yes | Description of the maintenance | | `--from` | yes | Start time in RFC 3339 format (e.g. `2026-04-05T02:00:00Z`) | | `--to` | yes | End time in RFC 3339 format | | `--page-id` | yes | Status page ID (get it from `status-page list`) | | `--component-ids` | no | Comma-separated component IDs in a single string: `"id1,id2"` | | `--notify` | no | Notify status page subscribers |