Dashboard & Widget CLI Commands

[betegon]

Overview

New sentry dashboard and sentry dashboard widget commands for managing Sentry dashboards from the CLI. Dashboards are org-scoped — the org is auto-detected from project context or specified explicitly.

Tasks

• sentry dashboard — list, view, create, delete
• sentry dashboard widget — add, edit, delete

---

sentry dashboard commands

sentry dashboard list

List dashboards in a Sentry organization.

sentry dashboard list [<org/>]

Flag	Alias	Description
--web	-w	Open dashboards list in browser
--json		Output as JSON
--fields		Filter JSON output fields

Table output columns: ID, TITLE, WIDGETS (count)

Examples:

sentry dashboard list                # auto-detect org
sentry dashboard list my-org/        # explicit org
sentry dashboard list --json         # JSON output
sentry dashboard list --web          # open in browser

Shorthand: sentry dashboards is an alias for sentry dashboard list.

---

sentry dashboard view

View details of a specific dashboard, including its widgets.

sentry dashboard view [<org/>] <dashboard-id-or-title>

Flag	Alias	Description
--web	-w	Open dashboard in browser
--json		Output as JSON
--fields		Filter JSON output fields

The dashboard can be specified by numeric ID or title (case-insensitive match). When a title is given, the CLI lists all dashboards in the org and finds the match.

Human output: Key-value table (Title, ID, Created, URL) followed by a widget table (TITLE, DISPLAY, TYPE, LAYOUT).

Examples:

sentry dashboard view 12345
sentry dashboard view 'My Dashboard'
sentry dashboard view my-org/ 12345
sentry dashboard view 12345 --json
sentry dashboard view 12345 --web

---

sentry dashboard create

Create a new dashboard, optionally with an inline widget.

sentry dashboard create [<org/project>] <title> [--widget-title <t> --widget-display <type> ...]

Flag	Description
--widget-title	Inline widget title
--widget-display	Inline widget display type (line, bar, table, big_number, ...)
--widget-dataset	Inline widget dataset (default: spans)
--widget-query	Inline widget aggregate (repeatable, e.g. count, p95:span.duration)
--widget-where	Inline widget search conditions filter
--widget-group-by	Inline widget group-by column (repeatable)
--widget-sort	Inline widget order by (prefix - for desc)
--widget-limit	Inline widget result limit
--json	Output as JSON
--fields	Filter JSON output fields

When <org/project> is provided, the dashboard is scoped to that project (by numeric project ID). Without it, the org is auto-detected and the dashboard has no project filter.

Examples:

sentry dashboard create 'My Dashboard'
sentry dashboard create my-org/ 'My Dashboard'
sentry dashboard create my-org/my-project 'My Dashboard'
sentry dashboard create 'My Dashboard' \
  --widget-title "Error Count" --widget-display big_number --widget-query count

---

sentry dashboard delete

Delete a dashboard.

sentry dashboard delete [<org/>] <dashboard-id-or-title>

Flag	Description
--json	Output as JSON
--fields	Filter JSON output fields

The dashboard can be specified by numeric ID or title (case-insensitive match).

Examples:

sentry dashboard delete 12345
sentry dashboard delete 'My Dashboard'
sentry dashboard delete my-org/ 12345

---

sentry dashboard widget commands

sentry dashboard widget add

Add a widget to an existing dashboard using inline flags.

sentry dashboard widget add [<org/>] <dashboard-id-or-title> <widget-title> --display <type> [flags]

Flag	Alias	Description
--display	-d	(required) Display type (line, bar, table, big_number, ...)
--dataset		Widget dataset (default: spans)
--query	-q	Aggregate expression (repeatable, e.g. count, p95:span.duration)
--where	-w	Search conditions filter (e.g. is:unresolved)
--group-by	-g	Group-by column (repeatable)
--sort	-s	Order by (prefix - for desc, e.g. -count)
--limit	-n	Result limit
--json		Output as JSON
--fields		Filter JSON output fields

The new widget is auto-laid out in the dashboard's 6-column grid, placed in the first available position.

Query shorthand (no shell quoting needed for common values):

• count → count() (bare name = no-arg aggregate)
• p95:span.duration → p95(span.duration) (colon = function with arg)
• count() → count() (parens passthrough)

Sort shorthand:

• count → count() (ascending)
• -count → -count() (descending)

Examples:

# Simple big_number widget
sentry dashboard widget add 'My Dashboard' "Error Count" \
  --display big_number --query count --where is:unresolved

# Line chart with group-by
sentry dashboard widget add 'My Dashboard' "Errors by Browser" \
  --display line --query count --group-by browser.name

# Table with multiple aggregates
sentry dashboard widget add 'My Dashboard' "Top Endpoints" \
  --display table --query count --query p95:span.duration \
  --group-by transaction --sort -count --limit 10

# With explicit org
sentry dashboard widget add my-org/ 12345 "My Widget" --display line --query count

---

sentry dashboard widget edit

Edit a widget in an existing dashboard. Only provided flags are changed — omitted values are preserved from the existing widget.

sentry dashboard widget edit [<org/>] <dashboard-id-or-title> (--index <n> | --title <name>) [flags]

Flag	Alias	Description
--index	-i	Widget index (0-based)
--title	-t	Widget title to match (exact)
--new-title		New widget title
--display	-d	Display type
--dataset		Widget dataset
--query	-q	Aggregate expression (repeatable)
--where	-w	Search conditions filter
--group-by	-g	Group-by column (repeatable)
--sort	-s	Order by
--limit	-n	Result limit
--json		Output as JSON
--fields		Filter JSON output fields

One of --index or --title is required. The existing widget's layout is always preserved.

Examples:

sentry dashboard widget edit 12345 --title 'Error Rate' --display bar
sentry dashboard widget edit 'My Dashboard' --index 0 --query p95:span.duration
sentry dashboard widget edit 12345 --title 'Old Name' --new-title 'New Name'

---

sentry dashboard widget delete

Remove a widget from an existing dashboard.

sentry dashboard widget delete [<org/>] <dashboard-id-or-title> (--index <n> | --title <name>)

Flag	Alias	Description
--index	-i	Widget index (0-based)
--title	-t	Widget title to match (exact)
--json		Output as JSON
--fields		Filter JSON output fields

One of --index or --title is required.

Examples:

sentry dashboard widget delete 12345 --index 0
sentry dashboard widget delete 'My Dashboard' --title 'Error Rate'

---

Cross-cutting behaviors

Auto-detection

All commands auto-detect the org from local project context (.sentryclirc, git remotes, cached defaults) when no explicit <org/> target is given.

Title-based dashboard lookup

view, delete, and all widget subcommands accept a dashboard title instead of a numeric ID. The CLI lists dashboards in the org and performs a case-insensitive match. If no match is found, the error message shows up to 5 available dashboards.

--json and --fields

All commands support --json for machine-readable output and --fields to select specific fields. These are injected by the shared buildCommand() framework.

--web / -w

dashboard list and dashboard view support --web to open the resource in the default browser instead of printing output.

Project scoping

dashboard create supports <org/project> to scope the new dashboard to a specific project. Other commands only need the org slug.

Query preparation

The CLI automatically computes fields (= columns + aggregates) and defaults conditions to "" before sending to the Sentry API. Users never need to provide these.

Limit enforcement

Table and bar widgets enforce a maximum limit of 10.

---

Branch: feat/dashboard-commands (PR #401)