manage-dashboards

name

manage-dashboards

description

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.

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

1. Preflight — gcx config check, then fetch current state with gcx dashboards get <name> -o json
2. Edit — write the modified YAML locally
3. Validate and push — gcx resources validate -p <path> -o json, gcx resources push -p <path> --dry-run, gcx resources push -p <path>
4. 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>

<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.