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

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

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:

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

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:

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:

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:

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

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
• private_locations.tf — private locations with their monitor assignments
• 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:

Flag	Effect
--json	Machine-readable JSON output
--no-color	Disable colored output
--quiet / -q	Suppress non-error output
--debug	Enable debug output

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, can't diff properly.