> ## 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.
# monitors
> DevHelm CLI monitors commands — list, get, create, update, delete, pause, resume, and test monitors
Manage monitors from the command line. Create, update, delete, pause, resume, and run on-demand checks.
Monitor IDs are **UUIDs** (e.g. `6e09775a-1b2c-4d5e-9f0a-1b2c3d4e5f6a`). The CLI validates the format locally and rejects non-UUID values before calling the API. Get IDs from `devhelm monitors list`.
## Commands
| Command | Description |
| ---------------------------------------------- | --------------------------------------- |
| `devhelm monitors list` | List all monitors |
| `devhelm monitors get ` | Get monitor details |
| `devhelm monitors create` | Create a monitor |
| `devhelm monitors update ` | Update a monitor |
| `devhelm monitors delete ` | Delete a monitor |
| `devhelm monitors pause ` | Pause a monitor |
| `devhelm monitors resume ` | Resume a paused monitor |
| `devhelm monitors test ` | Run an on-demand check |
| `devhelm monitors set-channels ` | Replace a monitor's alert channel links |
| `devhelm monitors results ` | Show recent check results |
| `devhelm monitors versions list ` | List monitor config versions |
| `devhelm monitors versions get ` | Get a specific config version |
## monitors list
List all monitors in your organization.
```bash theme={null}
devhelm monitors list
```
| Flag | Type | Default | Description |
| ------------- | ------- | ------- | --------------------------------------- |
| `--page-size` | integer | `200` | Number of items per API request (1–200) |
## monitors get
Get detailed information about a single monitor.
```bash theme={null}
devhelm monitors get
```
```bash theme={null}
devhelm monitors get -o json
```
## monitors create
Create a new monitor.
```bash theme={null}
devhelm monitors create \
--name "API Health" \
--type HTTP \
--url https://api.example.com/health \
--frequency 60 \
--regions us-east,eu-west
```
| Flag | Type | Required | Description |
| ------------------ | ------ | -------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `--name` | string | Yes | Human-readable name for this monitor |
| `--type` | string | Yes | Monitor type: `HTTP`, `DNS`, `TCP`, `ICMP`, `HEARTBEAT`, `MCP_SERVER` |
| `--url` | string | — | Target URL or host |
| `--frequency` | string | — | Check frequency in seconds (default: `60`) |
| `--method` | string | — | HTTP method: `GET`, `POST`, `PUT`, `PATCH`, `DELETE`, `HEAD` (default: `GET`) |
| `--port` | string | — | TCP port to connect to (default: `443` for TCP monitors) |
| `--regions` | string | — | Comma-separated probe regions |
| `--assertion` | string | — | Assertion to attach (repeatable). DSL like `status_code=200`, `response_time<5000`, or a JSON object. Attach failures roll back the monitor. |
| `--alert-channels` | string | — | Comma-separated alert channel IDs to attach after create. Attach failures roll back the monitor. |
Probe-driven types (`HTTP`, `TCP`, `DNS`, `ICMP`) require at least one region. If you omit `--regions`, the CLI defaults to `us-east` and prints a note to stderr.
### Examples by type
```bash HTTP theme={null}
devhelm monitors create \
--name "API Health" \
--type HTTP \
--url https://api.example.com/health \
--method GET \
--frequency 60 \
--regions us-east,eu-west
```
```bash TCP theme={null}
devhelm monitors create \
--name "Database Port" \
--type TCP \
--url db.example.com \
--port 5432 \
--frequency 120
```
```bash DNS theme={null}
devhelm monitors create \
--name "DNS Resolution" \
--type DNS \
--url example.com \
--frequency 300
```
```bash With assertions theme={null}
devhelm monitors create \
--name "Checkout API" \
--type HTTP \
--url https://api.example.com/checkout \
--assertion "status_code=200" \
--assertion "response_time<2000"
```
### Heartbeat monitors
`monitors create --type HEARTBEAT` creates a heartbeat with a fixed default config (`expectedInterval: 60`, `gracePeriod: 60` seconds) — the CLI flags don't expose these fields yet. To control the expected ping interval and grace period, define the monitor in YAML and deploy it:
```yaml Config-as-code theme={null}
monitors:
- name: Nightly Backup
type: HEARTBEAT
config:
expectedInterval: 86400
gracePeriod: 3600
```
```bash theme={null}
devhelm deploy -f devhelm.yml --yes
```
## monitors update
Update an existing monitor's configuration.
```bash theme={null}
devhelm monitors update \
--name "API Health (v2)" \
--frequency 30
```
| Flag | Type | Description |
| ------------------ | ------ | ----------------------------------------------------------------------------- |
| `--name` | string | New monitor name |
| `--url` | string | New target URL or host |
| `--frequency` | string | New check frequency in seconds |
| `--method` | string | New HTTP method |
| `--port` | string | New TCP port |
| `--alert-channels` | string | Comma-separated alert channel IDs (replaces current list; pass `""` to clear) |
## monitors delete
Delete a monitor. This also removes all associated check results. Prompts for confirmation; pass `--yes` (`-y`) in scripts and CI — non-interactive runs without it are refused.
```bash theme={null}
devhelm monitors delete
```
## monitors pause
Temporarily stop a monitor from running checks. The monitor retains its configuration and can be resumed at any time.
```bash theme={null}
devhelm monitors pause
```
## monitors resume
Resume a paused monitor.
```bash theme={null}
devhelm monitors resume
```
## monitors test
Run an on-demand check immediately, without waiting for the next scheduled interval.
```bash theme={null}
devhelm monitors test
```
The result is printed to stdout. Use `-o json` for structured output:
```bash theme={null}
devhelm monitors test -o json
```
You can also validate and dry-run a **proposed** monitor config (YAML or JSON `CreateMonitorRequest` payload) without persisting anything — pass `--config` instead of an ID:
```bash theme={null}
devhelm monitors test --config monitor.yml
```
Pass either an ID or `--config`, not both.
## monitors set-channels
Replace the full set of alert channels linked to a monitor. Pass an empty string to clear all channels.
```bash theme={null}
devhelm monitors set-channels --channel-ids ,
```
```bash theme={null}
devhelm monitors set-channels --channel-ids ""
```
| Flag | Type | Required | Description |
| --------------- | ------ | -------- | -------------------------------------------------------------------------- |
| `--channel-ids` | string | Yes | Comma-separated alert channel IDs (replaces current list; `""` clears all) |
## monitors results
Show recent check results for a monitor.
```bash theme={null}
devhelm monitors results
```
| Flag | Type | Default | Description |
| --------- | ------- | ------- | ------------------------------------------ |
| `--limit` | integer | `20` | Maximum number of results to show (1–1000) |
```bash theme={null}
devhelm monitors results --limit 5 -o json
```
## monitors versions list
List configuration versions for a monitor. Each update to a monitor creates a new version.
```bash theme={null}
devhelm monitors versions list
```
| Flag | Type | Default | Description |
| --------- | ------- | ------- | ---------------------------------- |
| `--limit` | integer | `20` | Maximum number of versions to show |
## monitors versions get
Get a specific configuration version.
```bash theme={null}
devhelm monitors versions get 3
```
The first argument is the monitor ID, the second is the version number.
## Next steps
Understanding monitor types, regions, and assertions.
Deploy monitors from YAML configuration files.