| name | manage-dashboards |
| description | Manages existing Grafana dashboards operationally via gcx: list, get, search, 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. 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.
|
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 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 versions list <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 schemas |
<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
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 versions list <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
