# OpenStatus CLI

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

## Installation

### Homebrew

```bash
brew install openstatusHQ/cli/openstatus --cask
```

### macOS / Linux

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

### Windows

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

## Quick Start

```bash
# 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.

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

```bash
# 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:

```bash
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`):

```bash
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):

```bash
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

```bash
go test -race ./...
```

### Generate Documentation

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