Terminal
Terminal/Skill
Lists, inspects, audits, updates, and restores existing Grafana dashboards, and renders PNG snapshots, using the gcx CLI.
By Grafana Labs
Works with
npx skills add grafana/gcx --skill manage-dashboardsUse gcx dedicated commands first. Only use gcx api when a dedicated command
cannot perform the requested operation.
| 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 |
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.
gcx config check, then fetch current state with gcx dashboards get <name> -o jsongcx resources validate -p <path> -o json, gcx resources push -p <path> --dry-run, gcx resources push -p <path>gcx dashboards get <name> -o jsonUse 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.
dashboards/ directory shape.--on-error abort when later resources depend on earlier ones and partial
progress would be confusing.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.
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.
| 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 |
--on-error policy, and the
gcx dev serve live-reload workflow, read
references/resource-operations.md.