/create-dashboard

name: create-dashboard
description: >-
  Designs and creates Grafana dashboards with gcx, with `gcx dashboards
  snapshot` as a visual feedback loop. Use to build a new dashboard, add panels,
  variables, or annotations, or redesign a dashboard. Not for inventory, audit,
  or pull/push of existing dashboards (use manage-dashboards).

Create Dashboard

Create dashboards as an iterative product workflow, not as a one-shot manifest write. The loop is:

understand goal → discover data → author dashboard → validate/push → snapshot → inspect → revise

A dashboard creation task is not complete after `push` succeeds. It is complete only after the dashboard has been visually checked, or after you report exactly why the snapshot step is blocked.

For pure operations on existing dashboards — list, search, pull, push, promote, restore, delete, or one-off snapshot — use `manage-dashboards` instead.

Hard Rules

• Do not create dashboards in an arbitrary/default folder. If the target

context or folder is ambiguous and the operation will write to Grafana, ask one concise question.

• If the user gives a context, folder, datasource, or dashboard title, proceed

with stated assumptions instead of running a long clarification round.

• Verify the active gcx context before writes.
• Verify datasources, metrics, labels, and log fields before adding panels. Do

not invent PromQL, LogQL, datasource UIDs, label names, or folder UIDs.

• Prefer existing project conventions. If the repo already has

grafana-foundation-sdk builders, generated manifests, or a dashboards registry, follow that pattern.

• Use `gcx dashboards snapshot` for visual feedback. After rendering a PNG,

inspect the image with the available image/read tool; do not only report the file path.

• Iterate at least once after the first snapshot when there are obvious visual

or data problems: login page, wrong variables, empty prime panels, title truncation, broken layout, unreadable legends, or poor top-screen triage.

• Prefer dedicated gcx commands over `gcx api`. Use raw API only when a needed

operation has no dedicated command.

Inputs to Establish

Collect only the missing inputs needed to start:

| Input | Needed for | Default if user is vague | |-------|------------|--------------------------| | Grafana context | Any read/write | Active gcx context after `gcx config current-context` | | Folder | Dashboard creation | Ask; do not default to General silently | | Audience | Dashboard shape | On-call/SRE triage audience | | Entity scope | Queries/variables | Service/team/namespace from the user request | | Datasource(s) | Panel queries | Infer from similar dashboards, then verify | | Time range | Snapshot and query tests | `--since 6h` for operational dashboards | | Storage path | Local files | Existing repo convention, else `./resources/dashboards/<name>.yaml` |

Workflow

1. Verify context and permissions

gcx config current-context
gcx config check
gcx config list-contexts

Use `--context <name>` on subsequent commands when the user named a context and you do not want to mutate global state.

Classify failures before continuing:

• config/connectivity failure → use `setup-gcx` first
• read 401/403 → missing dashboard/datasource read permissions
• write 403 → token lacks dashboard write permissions
• folder-specific write failure → wrong folder UID or folder permissions

2. Resolve folder and find local/live conventions

Find the target folder and similar dashboards before authoring.

# Folder/resource inventory. Use JSON for exact UIDs.
gcx resources get folders -o json

# Similar live dashboards are better than generic examples for variables,
# datasource UIDs, tags, units, and team conventions.
gcx dashboards search "<service-or-team-keyword>" -o json

# Pin the API version. Without --api-version the server returns its preferred
# version, which may use a different spec shape (elements/layout/variables
# instead of panels/templating) — the jq recipes below would then silently
# return nothing.
gcx dashboards get <similar-dashboard-uid> --api-version dashboard.grafana.app/v1beta1 -o json > /tmp/similar-dashboard.json

Extract useful patterns:

jq -r '.. | objects | select(.expr?) | .expr' /tmp/similar-dashboard.json | sort -u
jq '.spec.templating.list[]? | {name,type,query,current}' /tmp/similar-dashboard.json
jq '.spec.panels[]? | {id,title,type,gridPos}' /tmp/similar-dashboard.json

If local repository scans are appropriate under project rules, look for existing dashboard builders/manifests and follow their style instead of creating a new parallel convention.

3. Discover data before panels

Discover datasources and metrics directly when datasource choice or metric inventory is unclear. Minimum discovery for Prometheus/Loki dashboards:

gcx datasources list -o json

| Type | List names | Values for a specific name | |------|-----------|---------------------------| | Prometheus | `gcx datasources prometheus labels -d <uid> --label __name__` | `gcx datasources prometheus labels -d <uid> --label <label>` | | Loki | `gcx datasources loki labels -d <uid>` | `gcx datasources loki labels -d <uid> --label <label>` | | Tempo | `gcx datasources tempo labels -d <uid>` | `gcx datasources tempo labels -d <uid> -l <attr> --llm -o json [--scope span\|resource] [-q '<traceql>']` | | Pyroscope | `gcx datasources pyroscope list-profile-types -d <uid>` then `labels -d <uid>` | `gcx datasources pyroscope labels -d <uid> --label <label>` |

Prometheus also has `gcx datasources prometheus metadata -d <uid>` for metric type and help text. For Prometheus scoped label lookups, narrow with one `--match` selector or `--metric` (repeated `--match` selectors combine as a union): `gcx datasources prometheus labels -d <uid> --label <label> --match '{job="api"}'`. Other datasource types may have their own discovery subcommands — check `gcx datasources <type> --help` be