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

# Manage Platform-Owned Datadog Monitors

> Create, update, and delete Datadog monitors managed by the Tolmo platform. All monitors are tagged managed-by:tolmo and use server-side org credentials.

The `tolmo monitor` command manages Datadog monitors that the Tolmo platform owns on behalf of your organization. Datadog credentials are resolved server-side and never exposed to the CLI. Every monitor created this way is stamped with the `managed-by:tolmo` tag, making it easy to distinguish platform-owned monitors from anything you manage outside Tolmo.

## List managed monitors

Retrieve the monitors Tolmo currently manages with `tolmo monitor list`. Use the `--tag` flag to filter to platform-owned monitors, and add `--json` for machine-readable output:

```bash theme={null}
tolmo monitor list --tag managed-by:tolmo --json
```

To inspect a single monitor by its Datadog ID, use `monitor get`:

```bash theme={null}
tolmo monitor get 12345 --json
```

## Create a monitor

Provide a JSON spec file that matches the [Datadog monitor API format](https://docs.datadoghq.com/api/latest/monitors/). The backend always appends `managed-by:tolmo` to the tags array before forwarding the request to Datadog — you do not need to include it yourself.

You can supply the spec as a file path or pipe it from stdin:

```bash theme={null}
tolmo monitor create -f /tmp/cpu-spec.json
cat spec.json | tolmo monitor create -f -
```

## Update a monitor

Pass the monitor's Datadog ID and a JSON patch file to update any fields:

```bash theme={null}
tolmo monitor update 12345 -f /tmp/patch.json
```

<Warning>
  `tolmo monitor update` and `tolmo monitor delete` refuse with **HTTP 403** on any monitor that does not carry the `managed-by:tolmo` tag. This safeguard prevents you from accidentally modifying or deleting monitors you manage outside of Tolmo.
</Warning>

## Delete a monitor

Remove a platform-managed monitor by its Datadog ID:

```bash theme={null}
tolmo monitor delete 12345
```

The command fails with HTTP 403 if the target monitor does not carry the `managed-by:tolmo` tag (see the warning above).

## Multiple Datadog integrations

When your organization has more than one Datadog account connected, use `--integration <integration-id>` to target the correct one. Run `tolmo query list` to find integration IDs:

```bash theme={null}
tolmo monitor list --integration <integration-id>
```

## Example monitor spec

Use the following minimal spec as a starting point for a CPU alert monitor. Adapt the `query`, `message`, and threshold values to match your environment, then pass the file to `tolmo monitor create`:

```json cpu-monitor.json theme={null}
{
  "name": "High CPU on production hosts",
  "type": "metric alert",
  "query": "avg(last_5m):avg:system.cpu.user{env:prod} > 80",
  "message": "CPU is over 80% on {{host.name}}. @pagerduty",
  "tags": ["env:prod"],
  "options": {
    "thresholds": {
      "critical": 80,
      "warning": 70
    }
  }
}
```

The backend automatically adds `managed-by:tolmo` to the `tags` array, so you don't need to include it in your spec file.