---
title: Dashboards CLI reference
description: Manage Honeybadger Insights dashboards and their widgets from the command line.
url: https://docs.honeybadger.io/resources/cli/dashboards/
---

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

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

## List dashboards

```shell
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

```shell
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

```shell
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:

```shell
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](https://docs.honeybadger.io/guides/insights/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](https://docs.honeybadger.io/api/dashboards/) 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:

```shell
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

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

This action cannot be undone.

**Required flags:**

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

---

## 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/)