/manage-dashboards

name: manage-dashboards
description: >-
  Manages existing Grafana dashboards via gcx: list, search, get, audit panels,
  queries, datasources, and variables; apply a finished manifest; delete;
  versions and restore; pull/push/validate files; folders; PNG snapshots. Not
  for new dashboards, panels, or variables (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>` | | 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, r