Alarms CLI reference

The alarms command lets you view and manage Insights alarms for your projects.

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

List alarms

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

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

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\"",
    "evaluation_period": "5m",
    "lookback_lag": "1m",
    "trigger_config": {
      "type": "alert_result_count",
      "config": { "operator": "gt", "value": 10 }
    }
  }
}'

Or from a file:

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 query whose results are evaluated
• stream_ids — Optional list of stream IDs to query. Omit it and the alarm queries every stream on the project. See Scoping an alarm to specific streams below.
• 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:

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

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

Scoping an alarm to specific streams

An alarm queries every stream on the project unless you pass stream_ids. To narrow it, get the IDs first:

hb streams list --project-id 12345

Then pass them in the payload:

{ "stream_ids": ["pEFgoATf7kNq"] }

Use the opaque IDs from the ID column — not the slugs (default, internal) shown under SLUG. Unrecognized IDs are dropped without complaint, so a wrong one silently leaves the alarm watching fewer streams than you intended. If every ID you pass is unrecognized, nothing survives and the API rejects the alarm with a 422.

That rejection means the IDs weren’t recognized, not that the field is mandatory — passing a slug like "default" is the usual cause. Omitting stream_ids entirely is always valid.

Update an alarm

hb alarms update --project-id 12345 --id abc123 --cli-input-json '{
  "alarm": {
    "name": "Updated Alarm Name",
    "query": "filter event_type::str == \"notice\"",
    "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

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.

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)