OpenStatus CLI

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

Installation

Homebrew

brew install openstatusHQ/cli/openstatus --cask

macOS / Linux

curl -fsSL https://github.com/raw/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

# Report an incident
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
status-report	sr	Create and manage incident 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.3.2 (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