# Openstatus CLI

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

- Skill: `openstatushq/openstatus-cli` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add openstatushq/openstatus-cli`
- Raw SKILL.md: https://api.skillmd.com/api/skills/openstatushq/openstatus-cli/raw
- Safety review: pending (external: skill-scanner PASS, skillspector CAUTION)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: openstatushq (https://skillmd.com/u/openstatushq)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/openstatushq/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 |

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:**
```bash
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:**
```bash
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:**
```bash
openstatus maintenance info <ID>
```

**6. Delete:**
```bash
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:**
```bash
openstatus monitors trigger <MONITOR_ID>
```

**Run a batch of monitors via config:**
1. Create `config.openstatus.yaml`:
   ```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:**
```bash
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):**
```bash
openstatus monitors list --all
```

**Monitor response logs (debug failures):**
```bash
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:**
```bash
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:**
```bash
openstatus status-report info <ID>
```

**Maintenance details:**
```bash
openstatus maintenance info <ID>
```

**Status page components and config:**
```bash
openstatus status-page info <ID>
```

**Notification channels:**
```bash
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.

```bash
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:**
```bash
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:**
```bash
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, `apply` can't diff properly.
- **Use `-y` in scripts** — skip interactive confirmations with `--auto-accept` / `-y` for CI/CD pipelines.