Dashboards CLI reference

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

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

List dashboards

hb dashboards list --project-id 12345

Required flags:

• --project-id — Project ID

Optional flags:

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

Get dashboard details

hb dashboards get --project-id 12345 --id abc123

The default text output summarizes the dashboard and lists its widgets. Use --output json to get the full widget definitions — that’s the form hb dashboards update --cli-input-json expects.

Required flags:

• --project-id — Project ID
• --id — Dashboard ID

Optional flags:

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

Create a dashboard

hb dashboards create --project-id 12345 --cli-input-json '{
  "dashboard": {
    "title": "Request Health",
    "default_ts": "P1D",
    "widgets": [
      {
        "type": "insights_vis",
        "grid": { "x": 0, "y": 0, "w": 6, "h": 4 },
        "presentation": { "title": "Errors Over Time" },
        "config": {
          "streams": ["default"],
          "query": "filter event_type::str == \"notice\" | stats count() as count by bin(1h)",
          "vis": { "view": "line" }
        }
      }
    ]
  }
}'

Or from a file:

hb dashboards create --project-id 12345 --cli-input-json file://dashboard.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:

• title — Dashboard title
• default_ts — Default time range for the dashboard (e.g., P1D for one day)
• widgets — List of widget definitions

Widget fields:

• type — Widget type: insights_vis, alarms, errors, deployments, checkins, or uptime
• grid — Position and size on a 12-column grid: x, y, w, h. Widgets must not overlap.
• presentation — Display options, including the widget title
• config — Widget configuration. The fields it accepts depend on the widget type.
• id — Widget ID. Omit it on create and the server assigns one.

An insights_vis widget — the primary building block, which renders a BadgerQL query as a chart or table — takes these config fields:

• streams — Streams to query: default, internal, or both (defaults to ["default"])
• query — The BadgerQL query producing the widget’s data
• vis — How to render the result: {"view": ..., "chart_config": {...}}

The other widget types take their own fields, mostly a limit plus type-specific options. See the dashboards API reference for more on widget structure.

Dashboard structure is validated on save, and unknown keys anywhere in the dashboard, widget, or config objects are rejected.

The payload is accepted either wrapped in a {"dashboard": {...}} envelope or as a bare dashboard object, so output from hb dashboards get --output json can be edited and passed straight back.

Update a dashboard

Update replaces the dashboard rather than patching it, so send the complete widget list — any widget you omit is dropped. Both title and widgets are required; a payload carrying only one of them is refused rather than sent.

The reliable workflow is to fetch the current state, edit it, and send it back:

hb dashboards get --project-id 12345 --id abc123 --output json > dashboard.json
# edit dashboard.json
hb dashboards update --project-id 12345 --id abc123 --cli-input-json file://dashboard.json

Keep each existing widget’s id in the payload so it’s updated in place instead of being replaced by a newly assigned one. To remove every widget, pass "widgets": [] explicitly.

Required flags:

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

Delete a dashboard

hb dashboards delete --project-id 12345 --id abc123

This action cannot be undone.

Required flags:

• --project-id — Project ID
• --id — Dashboard ID