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