> ## Documentation Index
> Fetch the complete documentation index at: https://docs.devhelm.io/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI Overview

> The DevHelm CLI — install, authenticate, and manage your monitoring stack from the terminal

The `devhelm` CLI is a full-featured command-line tool for managing monitors, incidents, alert channels, and deploying config-as-code. Install it via npm and authenticate with an API token.

## Install

```bash theme={null}
npm install -g devhelm
```

Verify the installation:

```bash theme={null}
devhelm --version
```

## Authentication

The CLI resolves your API token from (in priority order):

1. `--api-token` flag on any command
2. `DEVHELM_API_TOKEN` environment variable
3. Saved context in `~/.devhelm/contexts.json`

```bash theme={null}
# Option A: environment variable (recommended for CI)
export DEVHELM_API_TOKEN=dh_live_xxxxxxxx

# Option B: interactive login (saves to contexts.json)
devhelm auth login
```

## Command reference

The CLI ships a wide command surface across resource topics, status pages, deploy/state, and auth. Every list/get command supports `--output json` for machine-readable output (deploy/validate use `text|json` instead — see those commands' references).

### Config as Code

| Command | Description |
| - | - |
| `devhelm validate <file>` | Validate config file syntax offline |
| `devhelm plan -f <file>` | Preview changes without applying |
| `devhelm deploy -f <file>` | Apply config changes |
| `devhelm deploy --dry-run -f <file>` | Simulate deploy without applying |
| `devhelm deploy force-unlock` | Release a stuck deploy lock |

### Monitors

| Command | Description |
| - | - |
| `devhelm monitors list` | List all monitors |
| `devhelm monitors get <id>` | Get monitor details |
| `devhelm monitors create` | Create a monitor |
| `devhelm monitors update <id>` | Update a monitor |
| `devhelm monitors delete <id>` | Delete a monitor |
| `devhelm monitors pause <id>` | Pause a monitor |
| `devhelm monitors resume <id>` | Resume a paused monitor |
| `devhelm monitors test <id>` | Run an on-demand check |
| `devhelm monitors results <id>` | Show recent check results |
| `devhelm monitors set-channels <id>` | Replace a monitor's alert channel links |
| `devhelm monitors versions list <id>` | List monitor config versions |

### Incidents

| Command | Description |
| - | - |
| `devhelm incidents list` | List incidents |
| `devhelm incidents get <id>` | Get incident details |
| `devhelm incidents create` | Create a manual incident |
| `devhelm incidents resolve <id>` | Resolve an incident |

### Alert channels

| Command | Description |
| - | - |
| `devhelm alert-channels list` | List alert channels |
| `devhelm alert-channels get <id>` | Get channel details |
| `devhelm alert-channels create` | Create an alert channel |
| `devhelm alert-channels update <id>` | Update a channel |
| `devhelm alert-channels delete <id>` | Delete a channel |
| `devhelm alert-channels test <id>` | Send a test notification |

### Other resources

| Topic | Commands |
| - | - |
| `notification-policies` | list, get, create, update, delete |
| `tags` | list, get, create, update, delete |
| `environments` | list, get, create, update, delete |
| `secrets` | list, create, update, delete |
| `webhooks` | list, get, create, update, delete, test |
| `resource-groups` | list, get, create, update, delete |
| `api-keys` | list, get, create, revoke, delete |
| `dependencies` | list, get, track, update, delete |
| `data services` | status, uptime |
| `maintenance-windows` | list, get, create, update, cancel |
| `forensics` | timeline, trace, snapshot, evaluations, transitions |

### Status pages

| Topic | Subcommands |
| - | - |
| `status-pages` (root) | list, get, create, update, delete |
| `status-pages components` | list, create, update, delete |
| `status-pages groups` | list, create, update, delete |
| `status-pages incidents` | list, get, create, update, delete, publish, dismiss, post-update |
| `status-pages maintenance` | list, get, create, update, delete, publish, dismiss, post-update |
| `status-pages subscribers` | list, add, remove |
| `status-pages domains` | list, add, verify, remove, set-primary |

Full reference: [`devhelm status-pages`](/cli/commands/status-pages).

### Status and auth

| Command | Description |
| - | - |
| `devhelm status` | Show current monitor status overview |
| `devhelm auth login` | Interactive login |
| `devhelm auth logout` | Clear saved credentials |
| `devhelm auth token` | Display the current token |
| `devhelm auth context` | Manage auth contexts |

## Global flags

| Flag | Description |
| - | - |
| `--api-token` | API token (overrides env var and saved context) |
| `--api-url` | API base URL (default: `https://api.devhelm.io`) |
| `--output`, `-o` | Output format: `table`, `json`, `yaml` (default: `table`) |
| `--verbose` | Enable debug logging |
| `--help` | Show help for any command |

See [Global flags](/cli/global-flags) for full details.

## Exit codes

| Code | Meaning |
| - | - |
| `0` | Success |
| `1` | General error |
| `2` | Usage error (unknown command/flag, missing required argument) |
| `4` | Validation (missing token, malformed config, schema-invalid request body) |
| `10` | Changes pending (with `--detailed-exitcode` on `plan` / `deploy --dry-run`) |
| `11` | API error (non-2xx response) |
| `12` | Transport error (network/DNS/TLS/timeout) |
| `13` | Partial deploy failure |

See [Exit codes](/cli/exit-codes) for the full taxonomy and CI patterns.

## Getting help

Every command supports `--help`:

```bash theme={null}
devhelm monitors create --help
devhelm deploy --help
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.