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\"",
    "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:

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. Defaults to all streams on the project. IDs that don’t belong to the project are ignored, so use hb streams list 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:

{
  "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

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

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)