Something went wrong. Try again.
[READ-ONLY] Mirror of https://github.com/openstatusHQ/openstatus. 🫖 Status page with uptime monitoring & API monitoring as code 🫖 openstatus.dev
bun drizzle-orm monitoring monitoring-as-code nextjs observability on-call open-source shadcn-ui status-page statuspage synthetic-monitoring tinybird turso uptime uptime-checker uptime-monitor
Something went wrong. Try again.
5.4 kB · 168 lines
MDX
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169---category: Tutorialstitle: Get Started with openstatus CLIdescription: "Step-by-step tutorial to install the openstatus CLI and export your workspace to Terraform"---
| | ||---|---|| **Time** | ~10 minutes || **Level** | Intermediate || **Prerequisites** | openstatus account, command-line experience, API key from your workspace (Settings > General > API Keys) |
In this tutorial, you'll install the openstatus CLI and use it to export your existing workspace into Terraform configuration. That gives you a version-controlled, reviewable definition of your monitoring you can then manage with the standard `plan` / `apply` workflow.
By the end you'll have the openstatus CLI installed and authenticated, and your monitors, status pages, and notification channels written out as `.tf` files.
<Image src="/docs/tutorial/get-started-with-openstatus-cli/CLI.png" alt="openstatus CLI in action showing monitor management"/>
## Installation
Install the openstatus CLI to manage your monitors directly from code.
### macOS
Using Homebrew (recommended):```bashbrew install openstatusHQ/cli/openstatus --cask```
Or using the install script:```bashcurl -fsSL https://raw.githubusercontent.com/openstatusHQ/cli/refs/heads/main/install.sh | bash```
### Linux
```bashcurl -fsSL https://raw.githubusercontent.com/openstatusHQ/cli/refs/heads/main/install.sh | bash```
### Windows
```powershelliwr https://raw.githubusercontent.com/openstatusHQ/cli/refs/heads/main/install.ps1 | iex```
### Verify installation
Run the following command to confirm the CLI is installed:
```bashopenstatus --version```
You should see output like:
```openstatus version x.x.x```
## Configure API authentication
1. In your openstatus dashboard, go to **Settings > General** and find the **API Keys** card.2. Click **Create** and copy the value — you won't see it again after closing the dialog.3. Make it available to the CLI as an environment variable:
```bash# macOS / Linuxexport OPENSTATUS_API_TOKEN=<your-api-token>```
```powershell# Windows PowerShell$env:OPENSTATUS_API_TOKEN="<your-api-token>"```
<Aside>Add the export to your shell profile (`~/.bashrc`, `~/.zshrc`, or `~/.config/fish/config.fish`) to persist across sessions. You can also pass the token per-command with `-t <your-api-token>` instead.</Aside>
<Aside type="note">The CLI reads `OPENSTATUS_API_TOKEN`. The openstatus SDKs (Node.js, Python, PHP) read the same API key value from `OPENSTATUS_API_KEY` instead — you can set both to the same value if you use both tools.</Aside>
## Export your workspace to Terraform
The CLI can write your existing workspace out as ready-to-use Terraform configuration, so youdon't have to translate your monitors by hand:
```bashopenstatus terraform generate```
Files are written to `./openstatus-terraform/` by default; pass `--output-dir` to choose anotherdirectory, and `--force` to overwrite an existing one. The export covers monitors, status pages,component groups, notification channels, and private locations.
**Checkpoint:** open the generated `.tf` files and confirm your monitors are there, with the namesand URLs you expect.
## Manage it with Terraform
From the output directory, the standard Terraform workflow takes over:
```bashterraform init # download the openstatus providerterraform plan # preview what will changeterraform apply # apply the changes```
To adopt resources that already exist rather than recreate them, import them into state first:
```bashterraform import openstatus_http_monitor.website <monitor_id>```
From here on, edit the `.tf` files, open a pull request, and let `terraform plan` show the diffbefore anything reaches your workspace.
## What you've accomplished
- Installed the openstatus CLI- Configured API authentication- Exported your workspace to Terraform configuration- Learned the monitoring-as-code workflow
## Troubleshooting
### "command not found: openstatus"
**Cause:** The CLI binary is not in your PATH.
**Fix (macOS/Homebrew):**```bashbrew reinstall openstatusHQ/cli/openstatus --cask```
**Fix (install script):** Ensure `~/.local/bin` is in your PATH:```bashexport PATH="$HOME/.local/bin:$PATH"```
### "unauthorized" or "invalid token" error
**Cause:** Your API token is missing or incorrect.
**Fix:**1. Verify the token is set: `echo $OPENSTATUS_API_TOKEN`2. Regenerate the key in your workspace settings (Settings > General > API Keys)3. Make sure there are no extra spaces or newlines in the token value
### The export is empty
**Cause:** Your workspace has no resources yet, or the token belongs to a different workspace.
**Fix:** Confirm which workspace the token belongs to with `openstatus whoami`, create at least onemonitor in the dashboard, then re-run the export.
## What's next
- **[Manage openstatus with Terraform](/docs/guides/how-to-manage-openstatus-with-terraform)** — the end-to-end Terraform workflow.- **[Monitor your MCP server](/docs/guides/how-to-monitor-mcp-server)** — a worked monitor definition.
### Learn more
- **[Monitoring-as-code concept](/docs/concept/uptime-monitoring-as-code)** — why manage monitors as code.- **[CLI reference](/docs/reference/cli-reference)** — all available commands.- **[Terraform provider reference](/docs/reference/terraform)** — every resource, argument, and block.