---
title: Alarms CLI reference
description: Manage Honeybadger Insights alarms and view their trigger history from the command line.
url: https://docs.honeybadger.io/resources/cli/alarms/
---

The `alarms` command lets you view and manage [Insights alarms](https://docs.honeybadger.io/guides/insights/alarms/) for your projects.

All alarms commands require `--project-id` (or `HONEYBADGER_PROJECT_ID`).

## List alarms

```shell
hb alarms list --project-id 12345
```

**Required flags:**

* `--project-id` — Project ID

**Optional flags:**

* `-o, --output` — Output format: `table` or `json` (default: `table`)

## Get alarm details

```shell
hb alarms get --project-id 12345 --id abc123
```

**Required flags:**

* `--project-id` — Project ID
* `--id` — Alarm ID

**Optional flags:**

* `-o, --output` — Output format: `text` or `json` (default: `text`)

## Create an alarm

```shell
hb alarms create --project-id 12345 --cli-input-json '{
  "alarm": {
    "name": "High Error Rate",
    "description": "Alert when errors spike",
    "query": "filter event_type::str == \"notice\"",
    "stream_ids": ["<stream-id>"],
    "evaluation_period": "5m",
    "lookback_lag": "1m",
    "trigger_config": {
      "type": "alert_result_count",
      "config": { "operator": "gt", "value": 10 }
    }
  }
}'
```

Or from a file:

```shell
hb alarms create --project-id 12345 --cli-input-json file://alarm.json
```

**Required flags:**

* `--project-id` — Project ID
* `--cli-input-json` — JSON payload (inline string or `file://path`)

**Optional flags:**

* `-o, --output` — Output format: `text` or `json` (default: `text`)

**JSON fields:**

* `name` — Alarm name
* `description` — Optional description, included in alarm notifications
* `query` — [BadgerQL](https://docs.honeybadger.io/guides/insights/badgerql/) query whose results are evaluated
* `stream_ids` — Optional list of [stream IDs](https://docs.honeybadger.io/api/streams/) to query. Defaults to all streams on the project. IDs that don’t belong to the project are ignored, so use [`hb streams list`](https://docs.honeybadger.io/resources/cli/streams/) to get real IDs rather than guessing.
* `evaluation_period` — How often the alarm is evaluated, and the window it looks back over (e.g., `5m`, `1h`, `1d`)
* `lookback_lag` — Delay before each evaluation, so late-arriving data is counted (e.g., `1m`)
* `trigger_config` — When the alarm triggers

**Trigger config:**

The only trigger type is `alert_result_count`, which compares the number of results the query returns against a threshold:

```json
{
  "type": "alert_result_count",
  "config": { "operator": "gt", "value": 10 }
}
```

Operators are `gt` (greater than), `gte`, `lt` (less than), `lte`, `eq`, and `neq`.

## Update an alarm

```shell
hb alarms update --project-id 12345 --id abc123 --cli-input-json '{
  "alarm": {
    "name": "Updated Alarm Name",
    "query": "filter event_type::str == \"notice\"",
    "stream_ids": ["<stream-id>"],
    "evaluation_period": "10m",
    "lookback_lag": "1m",
    "trigger_config": {
      "type": "alert_result_count",
      "config": { "operator": "gt", "value": 25 }
    }
  }
}'
```

**Required flags:**

* `--project-id` — Project ID
* `--id` — Alarm ID
* `--cli-input-json` — JSON payload (inline string or `file://path`)

## Delete an alarm

```shell
hb alarms delete --project-id 12345 --id abc123
```

This action cannot be undone.

**Required flags:**

* `--project-id` — Project ID
* `--id` — Alarm ID

## View trigger history

List the times an alarm has changed state.

```shell
hb alarms history --project-id 12345 --id abc123
```

**Required flags:**

* `--project-id` — Project ID
* `--id` — Alarm ID

**Optional flags:**

* `--page` — Page number for pagination
* `-o, --output` — Output format: `table` or `json` (default: `table`)

---

## Try Honeybadger for FREE

Intelligent logging, error tracking, and Just Enough APM™ in one dev-friendly platform. Find and fix problems before users notice.

[Start free trial](https://app.honeybadger.io/users/sign_up)

[See plans and pricing](https://www.honeybadger.io/plans/)