OpenStatus CLI #

Manage status pages, monitors, and incidents from the terminal.

Installation #

Homebrew #

brew install openstatusHQ/cli/openstatus --cask

macOS / Linux #

curl -fsSL https://raw.githubusercontent.com/openstatusHQ/cli/refs/heads/main/install.sh | bash

Windows #

iwr https://raw.githubusercontent.com/openstatusHQ/cli/refs/heads/main/install.ps1 | iex

Quick Start #

# Run a one-shot HTTP check against a URL from 28 global regions (no auth)
openstatus check https://openstat.us

# Authenticate with your API token
openstatus login

# List your monitors
openstatus monitors list

# Get detailed info on a monitor (live status + latency percentiles)
openstatus monitors info 123

# Trigger an on-demand check
openstatus monitors trigger 123

# Declare an incident, then publish a linked public status report
ID=$(openstatus incident declare --title "Checkout API returns 502" --severity major -q)
openstatus status-report create --title "Checkout issues" --status investigating \
  --message "We are investigating failed payments" --page-id 1 --incident-id "$ID"

# Run the incident: notes, status changes, postmortem
openstatus inc note "$ID" --message "Rolled back the deploy"
openstatus inc resolve "$ID" --note "Error rate back to normal"
openstatus inc postmortem edit "$ID" --file postmortem.md
openstatus inc postmortem approve "$ID" --close -y

# Post a public status update
openstatus status-report create --title "API degradation" --status investigating --page-id 1

# Report an incident with per-component impact
openstatus sr create --title "API down" --status investigating --message "Investigating" \
  --page-id 1 --impact comp_api=major_outage --impact comp_db=degraded

# Update an incident and change impact
openstatus sr add-update sr_42 --status monitoring --message "Recovering" \
  --impact comp_api=degraded,comp_db=operational

# Run synthetic tests from config
openstatus run

Global Speed Check #

openstatus check <URL> runs a one-shot HTTP check from 28 global probe regions via the public OpenStatus speed checker. No API token required.

openstatus check https://openstat.us
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            # adds DNS/Connection/TLS/TTFB/Transfer columns
openstatus check https://openstat.us --json | jq '.summary'

Rate limit: 3 requests per 60 seconds.

Commands #

Command	Alias	Description
check	c	Run an HTTP check against a URL from 28 global regions (no auth)
login / logout		Authenticate with the OpenStatus API
whoami	w	Show current workspace info
monitors	m	List, inspect, trigger, import, and apply monitors
incident	inc, incidents	Declare and run incidents (lifecycle, notes, status report link, postmortem)
status-report	sr	Post and manage public status reports
maintenance	mt	Schedule and manage maintenance windows
status-page	sp	View status pages and components
notification	n	View notification channels
run	r	Run synthetic tests across global regions
terraform generate	tf gen	Export workspace resources to Terraform HCL

Global Flags #

Flag	Description
--json	Machine-readable JSON output
--quiet, -q	Suppress non-error output
--debug	Print HTTP request details to stderr
--no-color	Disable colored output
--access-token, -t	Override API token

Monitors as Code #

Define monitors declaratively in YAML and sync them with apply:

# Export existing monitors to openstatus.yaml + openstatus.lock
openstatus monitors import

# Preview changes
openstatus monitors apply --dry-run

# Apply changes
openstatus monitors apply

Terraform Export #

Generate Terraform HCL for your entire workspace:

openstatus terraform generate --output-dir ./terraform

This creates provider.tf, monitors.tf, notifications.tf, status_pages.tf, private_locations.tf, and imports.tf ready for terraform plan.

Authentication #

The CLI resolves your API token in this order:

1. --access-token / -t flag
2. OPENSTATUS_API_TOKEN environment variable
3. Saved token at ~/.config/openstatus/token (written by openstatus login)

Self-Hosted #

Point the CLI at your own API server with OPENSTATUS_API_URL (default https://api.openstatus.dev):

export OPENSTATUS_API_URL=https://api.openstatus.example.com
openstatus whoami

openstatus terraform generate then writes the matching base_url into provider.tf. The check command always uses the public speed checker.

Usage Data #

Requests to the API carry a User-Agent with the CLI version and platform, plus the command being run (x-openstatus-cli-command, e.g. monitors list) and a random per-run ID (x-openstatus-cli-invocation). We use them to understand which commands are used. No arguments, flag values or file contents are sent.

To stop sending the command and run ID, set either variable (0, false, no and off leave it enabled):

export DO_NOT_TRACK=1
# or
export OPENSTATUS_NO_TELEMETRY=1

Opting out does not remove the User-Agent: like any HTTP client, the CLI still identifies itself with its version and platform (e.g. openstatus-cli/v1.4.0 (darwin; arm64)).

When OPENSTATUS_API_URL points at a self-hosted instance, the command and run ID only go to that instance; check does not send them to openstatus.dev.

Development #

Run Tests #

go test -race ./...

Generate Documentation #

go run cmd/docs/docs.go
cd docs
pandoc -s -t man openstatus-docs.md -o openstatus.1