Get Started with openstatus CLI

In this tutorial, you’ll learn how to use the openstatus CLI to manage your monitors as code. This enables you to version control your monitoring configuration, automate deployments, and implement GitOps workflows.

• An openstatus account
• Command line experience
• API token from your openstatus workspace (Settings → API)

By the end of this tutorial, you’ll have:

• openstatus CLI installed on your system
• Monitors exported to a YAML configuration file
• Understanding of monitoring as code workflows
• Ability to manage monitors programmatically

Install the openstatus CLI to manage your monitors directly from code.

Using Homebrew (recommended):

brew install openstatusHQ/cli/openstatus --cask

Or using the install script:

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

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

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

Run the following command to confirm the CLI is installed:

openstatus --version

You should see output like:

openstatus version x.x.x

Create an API key in your workspace settings (Settings → API), then set it as an environment variable:

# macOS / Linux
export OPENSTATUS_API_TOKEN=<your-api-token>

# Windows PowerShell
$env:OPENSTATUS_API_TOKEN="<your-api-token>"

Start by importing your existing monitors from your workspace to a YAML file:

openstatus monitors import

You should see output confirming the import:

Successfully imported X monitors to openstatus.yaml

This creates an openstatus.yaml file containing all your current monitors. This file becomes your single source of truth for monitoring configuration.

Checkpoint: Open the openstatus.yaml file and verify it contains your monitors. You should see entries with your monitor names and URLs.

Now you can add, remove, or update monitors in the YAML file and apply your changes:

openstatus monitors apply

The CLI will show you a diff of changes before applying them, ensuring you’re aware of what will be modified.

Excellent work! You’ve successfully:

• ✅ Installed the openstatus CLI
• ✅ Configured API authentication
• ✅ Imported monitors to a YAML file
• ✅ Learned the monitoring as code workflow

Cause: The CLI binary is not in your PATH.

Fix (macOS/Homebrew):

brew reinstall openstatusHQ/cli/openstatus --cask

Fix (install script): Ensure ~/.local/bin is in your PATH:

export PATH="$HOME/.local/bin:$PATH"

Cause: Your API token is missing or incorrect.

Fix:

1. Verify the token is set: echo $OPENSTATUS_API_TOKEN
2. Regenerate the token in your workspace settings (Settings → API)
3. Make sure there are no extra spaces or newlines in the token value

Cause: Your workspace has no monitors, or the token belongs to a different workspace.

Fix: Create at least one monitor in the dashboard first, then retry the import.

Now that you have the CLI set up, you can:

• Monitor Your MCP Server - Example of CLI-based monitor configuration
• CLI Reference - Complete command documentation
• Set up CI/CD - Automate monitoring in your pipeline

With the CLI, you can:

• Version control your monitoring configuration with Git
• Review monitoring changes in pull requests
• Automate monitor creation for new services
• Sync monitors across multiple environments
• Implement GitOps for infrastructure monitoring

• Monitoring as Code Concept - Why manage monitors as code
• CLI Reference - All available commands
• YAML Configuration Examples - Sample configurations