openstatus-cli

name: openstatus-cli description: | OpenStatus CLI for managing uptime monitors, incident reports, status pages, notifications, maintenance windows, synthetic tests, monitor response logs, and ad-hoc global HTTP checks. Use this skill whenever the user wants to monitor a website or API, set up uptime checks, create or manage monitors, inspect monitor response logs or debug why a check failed, report an incident, update a status page, view notifications, schedule maintenance, run synthetic tests, check latency or availability from around the world, run an ad-hoc speed check, define monitors as code, generate Terraform configuration, export to Terraform, log in or out, or use the openstatus command. Also trigger when the user says "is my site up", "check my endpoint", "speed check", "global latency", "latency from regions", "ad-hoc check", "test from multiple regions", "show monitor logs", "response logs", "why did my monitor fail", "see the failed requests", "create a status report", "set component impact", "monitor this URL", "run uptime tests", "set up monitoring", "our API is down", "schedule maintenance", "maintenance window", "planned downtime", "terraform", "generate terraform", "export to terraform", "infrastructure as code", "list notifications", "notification channels", "log in to openstatus", "save my api token", or mentions openstatus in any context. This skill knows the full CLI — commands, flags, config format, and workflows — so Claude can act without guessing. allowed-tools: - Bash(openstatus *)

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:

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

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.

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:

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

openstatus status-page list
openstatus status-page info <PAGE_ID>   # shows components grouped by section

2. Create the incident:

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:

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:

openstatus status-report add-update 456 \
  --status identified \
  --message "Root cause identified: database connection pool exhaustion" \
  --notify

add-update flags:

4. Resolve:

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:

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:

openstatus status-report info 456

Shows full metadata plus the update timeline — each update displayed as <date> [status] <message>.

7. List and filter incidents:

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:

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:

openstatus status-page list
openstatus status-page info <PAGE_ID>   # shows components grouped by section

2. Create a maintenance window:

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:

Status is computed automatically: scheduled (before --from), in_progress (between --from and --to), completed (after --to). There is no --status flag.

Interactive vs. scripted: like status-report create, if any required flag (--title, --message, --from, --to, --page-id) is missing, the CLI launches an interactive wizard on a terminal but errors with missing required flags: … and exits 1 in non-interactive contexts (--json set or stdin not a TTY). Pass every required flag when scripting.

3. Update a maintenance window:

openstatus maintenance update <ID> \
  --title "Extended Maintenance" \
  --to "2026-04-05T06:00:00Z"

Only provided flags are updated. At least one of --title, --message, --from, --to, or --component-ids must be set. --component-ids replaces the entire list.

4. List and filter:

openstatus maintenance list                        # all maintenance windows
openstatus maintenance list --page-id 123          # filter by page
openstatus maintenance list --limit 10             # limit results

5. View details:

openstatus maintenance info <ID>

6. Delete:

openstatus maintenance delete <ID>       # prompts for confirmation
openstatus maintenance delete <ID> -y    # skip confirmation

On-demand testing

Run specific monitors immediately across all their configured regions.

Trigger a single monitor:

openstatus monitors trigger <MONITOR_ID>

Run a batch of monitors via config:

1. Create config.openstatus.yaml:

   tests:
     ids:
       - monitor-id-1
       - monitor-id-2
   

2. Run: openstatus run

Both approaches run tests in parallel and show latency + status per region.

Inspecting state

Monitor details with metrics:

openstatus monitors info <ID>
openstatus monitors info <ID> --time-range 7d

Shows config, live status per region, and summary metrics (P50/P75/P95/P99 latency). --time-range accepts 1d (default), 7d, or 14d.

List monitors (including inactive):

openstatus monitors list --all

Monitor response logs (debug failures):

openstatus monitors logs <ID>                                         # recent HTTP responses
openstatus monitors logs <ID> --limit 10                              # cap results (1-100)
openstatus monitors logs <ID> --limit 5 --offset 5                    # paginate
openstatus monitors logs <ID> --from 2026-05-06T00:00:00Z --to 2026-05-07T00:00:00Z   # time window

Lists HTTP response logs from the 14-day retention window — status code, latency, region, and timestamp per request. Use this to investigate why a monitor failed. --limit, --offset, --from, and --to (RFC 3339) are all optional.

Single log full detail:

openstatus monitors log-info <ID> <LogID>

Fetches one HTTP response log with full detail: timing phases (DNS/Connection/TLS/TTFB/Transfer), response headers, and assertion results. Get the <LogID> from monitors logs <ID>.

Incident timeline:

openstatus status-report info <ID>

Maintenance details:

openstatus maintenance info <ID>

Status page components and config:

openstatus status-page info <ID>

Notification channels:

openstatus notification list                    # all notification channels
openstatus notification list --limit 10         # limit results
openstatus notification info <ID>               # provider config, linked monitors

Supported providers: discord, email, google_chat, grafana_oncall, ntfy, pagerduty, opsgenie, slack, sms, telegram, webhook, whatsapp.

Terraform export

Generate Terraform HCL configuration from all workspace resources. This creates ready-to-use .tf files with import blocks for adopting Terraform on an existing OpenStatus setup.

openstatus terraform generate

This creates an openstatus-terraform/ directory with:

• provider.tf — Terraform provider configuration
• monitors.tf — all HTTP, TCP, and DNS monitors
• notifications.tf — all notification channels with provider-specific blocks
• status_pages.tf — status pages, components, and component groups
• imports.tf — Terraform 1.5+ import blocks for all resources

Custom output directory:

openstatus terraform generate --output-dir ./infra/openstatus/

By default generate refuses to overwrite any of the .tf files it would create if they already exist (it errors with refusing to overwrite existing file …; pass --force to replace). Pass --force / -f to overwrite them. The generate subcommand also has the alias gen.

After generating:

cd openstatus-terraform
terraform init
terraform plan

Sensitive values (passwords, API keys) are emitted as "REPLACE_ME" with a TODO comment — update them before running terraform apply.

Global Flags

Every command supports these:

Use --json when you need to parse output programmatically or pipe it to jq.

Best Practices

• Reach for check for one-off probes — if the user just wants to know "how fast is this URL from around the world?", openstatus check <URL> is the right tool. No auth, no setup, 28 regions, done in 2–5s. Don't create a throwaway monitor for this.
• Use apply, not create — monitors apply is the declarative, idempotent way to manage monitors. monitors create exists but apply handles creates, updates, and deletes in one command.
• Always --dry-run first — preview what apply will change before committing.
• Get the page ID before creating reports — status-report create requires --page-id. Run status-page list first. Then use status-page info <ID> to find component IDs if you need --component-ids.
• Prefer --impact over --component-ids for status reports — --impact comp-1=major_outage records a specific per-component impact level; --component-ids is the legacy flag that only marks components affected without a level. They're mutually exclusive. --component-ids is still a single comma-separated string ("id1,id2,id3", not multiple flags), and on status-report update it replaces the full list.
• Provide all required flags when scripting — status-report create, status-report add-update, and maintenance create fall back to an interactive wizard when required flags are missing, but in non-interactive/JSON contexts they error with missing required flags: …. Always pass them explicitly.
• Status values are strict — only investigating, identified, monitoring, resolved. The CLI rejects anything else.
• Use --notify deliberately — it emails all subscribers. Useful for create and resolved, but you may want to skip it for intermediate updates.
• Commit your lock file — openstatus.lock tracks the mapping between your YAML and the API. Without it, apply can't diff properly.
• Use -y in scripts — skip interactive confirmations with --auto-accept / -y for CI/CD pipelines.