Manage Dashboards
Use gcx dedicated commands first. Only use gcx api when a dedicated command
cannot perform the requested operation.
Routing
| User intent |
Use |
| Build a new dashboard from an idea, service, SLO, incident, or set of metrics |
create-dashboard |
| Redesign layout, choose panels/queries, or visually iterate dashboard quality |
create-dashboard |
| Generate a Go builder skeleton only |
generate-resource-stubs |
| Convert an existing live dashboard to Go code |
import-dashboards |
| List, search, inspect, delete, restore, pull, push, validate, promote, or snapshot existing dashboards |
this skill |
| Configure gcx/auth first |
setup-gcx |
Preflight for Mutations
Before any create/update/delete/push/restore operation:
gcx config current-context
gcx config check
Use --context <name> when the user named a target environment. Do not switch
the global context unless the user asked for it.
For writes, read current state first and preserve folder/manager intent:
gcx dashboards get <dashboard-name> -o json
gcx resources get folders -o json
Manager boundary: gcx protects resources managed by another tool. If a push
fails because of grafana.app/managed-by, stop and ask/confirm before using
--include-managed.
Typical Update Workflow
- Preflight —
gcx config check, then fetch current state with gcx dashboards get <name> -o json
- Edit — write the modified YAML locally
- Validate and push —
gcx resources validate -p <path> -o json, gcx resources push -p <path> --dry-run, gcx resources push -p <path>
- Verify —
gcx dashboards get <name> -o json
Operation Reference
Use JSON/YAML for programmatic work and table/wide output for human summaries.
| Operation |
Command pattern |
| List datasources |
gcx datasources list -o json |
| Prometheus metric names |
gcx datasources prometheus labels -d <uid> --label __name__ |
| Prometheus label values |
gcx datasources prometheus labels -d <uid> --label <label> |
| Prometheus metric metadata |
gcx datasources prometheus metadata -d <uid> |
| Loki label names |
gcx datasources loki labels -d <uid> |
| Loki label values |
gcx datasources loki labels -d <uid> --label <label> |
| Tempo attribute names |
gcx datasources tempo labels -d <uid> |
| Tempo attribute values |
gcx datasources tempo labels -d <uid> -l resource.service.name --llm -o json |
| Pyroscope profile types |
gcx datasources pyroscope list-profile-types -d <uid> |
| Pyroscope label values |
gcx datasources pyroscope labels -d <uid> --label service_name |
| Other datasource types |
Check gcx datasources <type> --help for dedicated subcommands before using gcx api |
| List dashboards |
gcx dashboards list -o wide |
| Search by text/tag/folder |
gcx dashboards search "<query>" --tag <tag> --folder <folder-name> -o json |
| Get one dashboard |
gcx dashboards get <dashboard-name> -o json |
| Create from finished file |
gcx dashboards create -f <dashboard.yaml> |
| Update from finished file |
gcx dashboards update <dashboard-name> -f <dashboard.yaml> |
| Delete with confirmation |
gcx dashboards delete <dashboard-name> |
| Delete non-interactively |
gcx dashboards delete <dashboard-name> --force |
| Version history |
gcx dashboards list-versions <dashboard-name> |
| Restore version |
gcx dashboards versions restore <dashboard-name> <version> --message "<why>" |
| Pull dashboards/folders |
gcx resources pull dashboards folders -p <dir> -o yaml |
| Pull one dashboard |
gcx resources pull dashboards/<dashboard-name> -p <dir> -o yaml |
| Validate local files |
gcx resources validate -p <path> -o json |
| Preview push |
gcx resources push -p <path> --dry-run |
| Push local files |
gcx resources push -p <path> |
| Delete by selector |
gcx resources delete dashboards/<dashboard-name> |
Edit in $EDITOR |
gcx resources edit dashboards/<dashboard-name> -o yaml |
| List resource kinds |
gcx resources list-types |
<dashboard-name> is the dashboard resource name (metadata.name), which is
also the value accepted by gcx dashboards snapshot.
Pull/Push Notes
- Pull output directories may include API version/group in their path. Use the
paths printed by gcx; do not assume a fixed
dashboards/ directory shape.
- When a directory contains folders and dashboards, gcx pushes folders first.
- Use
--on-error abort when later resources depend on earlier ones and partial
progress would be confusing.
- Dry-run before writing to production unless the user explicitly opts out.
Snapshots
GCX_AGENT_MODE=true gcx dashboards snapshot <dashboard-name> --output-dir ./snapshots --since 6h
# With variables:
GCX_AGENT_MODE=true gcx dashboards snapshot <dashboard-name> --output-dir ./snapshots --since 6h --var cluster=prod
Read the returned file_path PNG and summarize what you see; do not just report the path.
Troubleshooting: plugin not found/renderer 500 = image renderer unavailable; wrong data = inspect
template variables and rerun with --var; auth errors = check gcx config check.
Version Restore Safety
Restore performs a read of historical content and writes a new current revision.
Always include a message and verify afterwards:
gcx dashboards list-versions <dashboard-name> --limit 10
gcx dashboards versions restore <dashboard-name> <version> \
--message "Restore known-good dashboard after <reason>"
gcx dashboards get <dashboard-name> -o json
A conflict or 409 means someone changed the dashboard concurrently. Re-fetch,
review the newest version, and retry only if the restore is still correct.
Common Failure Handling
| Symptom |
Action |
gcx config check fails |
Use setup-gcx before dashboard operations |
gcx resources get datasources selector error |
Use gcx datasources list instead — datasource.grafana.app is not registered on all instances |
| Dashboard not found |
Search first; confirm metadata.name, not just title |
| Folder filter does not work with list |
Use gcx dashboards search --folder <folder-name> |
| Push blocked by manager metadata |
Ask before --include-managed |
| Validation fails |
Fix local file; do not push invalid resources |
| Snapshot returns wrong variables |
Inspect templating and pass --var name=value |
| Snapshot unavailable |
Report renderer/auth blocker; do not claim visual review |
References
- For full flag sets, selector syntax,
--on-error policy, and the
gcx dev serve live-reload workflow, read
references/resource-operations.md.
- For resource structure, manager metadata, push ordering, and lifecycle
behavior, read references/resource-model.md.
1---2name: manage-dashboards3description: Manages and inspects existing Grafana dashboards via gcx: list, get, search, audit what a saved dashboard actually contains (its panels and their types, the queries and expressions as saved, which datasource each panel uses, variables and what they are wired to), create or update from an already-authored manifest, delete, inspect and restore versions, pull/push/validate/promote dashboard resource files, manage dashboard folders, or render PNG snapshots. Trigger on "what's on dashboard X", "what is each panel querying", "audit this dashboard", "which datasource does each panel use", "does the dashboard have a service dropdown". Do NOT use when the task involves adding new panels, variables, or annotations - those require discovering real metrics or log schema, so use create-dashboard instead. For designing or creating a new dashboard, or for material visual/dashboard UX changes, also use create-dashboard.4---56# Manage Dashboards78Use `gcx` dedicated commands first. Only use `gcx api` when a dedicated command9cannot perform the requested operation.1011## Routing1213| User intent | Use |14|-------------|-----|15| Build a new dashboard from an idea, service, SLO, incident, or set of metrics | `create-dashboard` |16| Redesign layout, choose panels/queries, or visually iterate dashboard quality | `create-dashboard` |17| Generate a Go builder skeleton only | `generate-resource-stubs` |18| Convert an existing live dashboard to Go code | `import-dashboards` |19| List, search, inspect, delete, restore, pull, push, validate, promote, or snapshot existing dashboards | this skill |20| Configure gcx/auth first | `setup-gcx` |2122## Preflight for Mutations2324Before any create/update/delete/push/restore operation:2526```bash27gcx config current-context28gcx config check29```3031Use `--context <name>` when the user named a target environment. Do not switch32the global context unless the user asked for it.3334For writes, read current state first and preserve folder/manager intent:3536```bash37gcx dashboards get <dashboard-name> -o json38gcx resources get folders -o json39```4041Manager boundary: gcx protects resources managed by another tool. If a push42fails because of `grafana.app/managed-by`, stop and ask/confirm before using43`--include-managed`.4445## Typical Update Workflow46471. Preflight — `gcx config check`, then fetch current state with `gcx dashboards get <name> -o json`482. Edit — write the modified YAML locally493. Validate and push — `gcx resources validate -p <path> -o json`, `gcx resources push -p <path> --dry-run`, `gcx resources push -p <path>`504. Verify — `gcx dashboards get <name> -o json`5152## Operation Reference5354Use JSON/YAML for programmatic work and table/wide output for human summaries.5556| Operation | Command pattern |57|-----------|-----------------|58| List datasources | `gcx datasources list -o json` |59| Prometheus metric names | `gcx datasources prometheus labels -d <uid> --label __name__` |60| Prometheus label values | `gcx datasources prometheus labels -d <uid> --label <label>` |61| Prometheus metric metadata | `gcx datasources prometheus metadata -d <uid>` |62| Loki label names | `gcx datasources loki labels -d <uid>` |63| Loki label values | `gcx datasources loki labels -d <uid> --label <label>` |64| Tempo attribute names | `gcx datasources tempo labels -d <uid>` |65| Tempo attribute values | `gcx datasources tempo labels -d <uid> -l resource.service.name --llm -o json` |66| Pyroscope profile types | `gcx datasources pyroscope list-profile-types -d <uid>` |67| Pyroscope label values | `gcx datasources pyroscope labels -d <uid> --label service_name` |68| Other datasource types | Check `gcx datasources <type> --help` for dedicated subcommands before using `gcx api` |69| List dashboards | `gcx dashboards list -o wide` |70| Search by text/tag/folder | `gcx dashboards search "<query>" --tag <tag> --folder <folder-name> -o json` |71| Get one dashboard | `gcx dashboards get <dashboard-name> -o json` |72| Create from finished file | `gcx dashboards create -f <dashboard.yaml>` |73| Update from finished file | `gcx dashboards update <dashboard-name> -f <dashboard.yaml>` |74| Delete with confirmation | `gcx dashboards delete <dashboard-name>` |75| Delete non-interactively | `gcx dashboards delete <dashboard-name> --force` |76| Version history | `gcx dashboards list-versions <dashboard-name>` |77| Restore version | `gcx dashboards versions restore <dashboard-name> <version> --message "<why>"` |78| Pull dashboards/folders | `gcx resources pull dashboards folders -p <dir> -o yaml` |79| Pull one dashboard | `gcx resources pull dashboards/<dashboard-name> -p <dir> -o yaml` |80| Validate local files | `gcx resources validate -p <path> -o json` |81| Preview push | `gcx resources push -p <path> --dry-run` |82| Push local files | `gcx resources push -p <path>` |83| Delete by selector | `gcx resources delete dashboards/<dashboard-name>` |84| Edit in `$EDITOR` | `gcx resources edit dashboards/<dashboard-name> -o yaml` |85| List resource kinds | `gcx resources list-types` |8687`<dashboard-name>` is the dashboard resource name (`metadata.name`), which is88also the value accepted by `gcx dashboards snapshot`.8990## Pull/Push Notes9192- Pull output directories may include API version/group in their path. Use the93 paths printed by gcx; do not assume a fixed `dashboards/` directory shape.94- When a directory contains folders and dashboards, gcx pushes folders first.95- Use `--on-error abort` when later resources depend on earlier ones and partial96 progress would be confusing.97- Dry-run before writing to production unless the user explicitly opts out.9899## Snapshots100101```bash102GCX_AGENT_MODE=true gcx dashboards snapshot <dashboard-name> --output-dir ./snapshots --since 6h103# With variables:104GCX_AGENT_MODE=true gcx dashboards snapshot <dashboard-name> --output-dir ./snapshots --since 6h --var cluster=prod105```106107Read the returned `file_path` PNG and summarize what you see; do not just report the path.108109Troubleshooting: `plugin not found`/renderer 500 = image renderer unavailable; wrong data = inspect110template variables and rerun with `--var`; auth errors = check `gcx config check`.111112## Version Restore Safety113114Restore performs a read of historical content and writes a new current revision.115Always include a message and verify afterwards:116117```bash118gcx dashboards list-versions <dashboard-name> --limit 10119gcx dashboards versions restore <dashboard-name> <version> \120 --message "Restore known-good dashboard after <reason>"121gcx dashboards get <dashboard-name> -o json122```123124A conflict or 409 means someone changed the dashboard concurrently. Re-fetch,125review the newest version, and retry only if the restore is still correct.126127## Common Failure Handling128129| Symptom | Action |130|---------|--------|131| `gcx config check` fails | Use `setup-gcx` before dashboard operations |132| `gcx resources get datasources` selector error | Use `gcx datasources list` instead — `datasource.grafana.app` is not registered on all instances |133| Dashboard not found | Search first; confirm `metadata.name`, not just title |134| Folder filter does not work with list | Use `gcx dashboards search --folder <folder-name>` |135| Push blocked by manager metadata | Ask before `--include-managed` |136| Validation fails | Fix local file; do not push invalid resources |137| Snapshot returns wrong variables | Inspect templating and pass `--var name=value` |138| Snapshot unavailable | Report renderer/auth blocker; do not claim visual review |139140## References141142- For full flag sets, selector syntax, `--on-error` policy, and the143 `gcx dev serve` live-reload workflow, read144 [references/resource-operations.md](references/resource-operations.md).145- For resource structure, manager metadata, push ordering, and lifecycle146 behavior, read [references/resource-model.md](references/resource-model.md).
grafana