Terminal
Terminal/Skill
Manages Grafana Cloud resources such as dashboards, alerts, SLOs and k6 tests through the gcx CLI.
By Grafana Labs
Works with
npx skills add grafana/gcx --skill gcxgcx is a unified CLI for Grafana Cloud, organized like kubectl: named contexts, structured output, and a consistent verb model across all resource types.
gcx has a built-in command catalog. Never guess a command — discover it first. Use progressive disclosure to minimize token cost:
Step 1 — Orient (30 lines, all top-level groups):
gcx help-tree --depth 1 -o text
Step 2 — Drill down (5-20 lines per group):
gcx help-tree <group> -o text # full subtree for one group
gcx <group> <subcommand> --help # exact flags and args
Build payloads:
gcx resources list-types <kind> # resource types + JSON schema for a type
gcx resources list-examples <kind> # example manifest
Only fall back to gcx commands --flat -o json when you need structured metadata
for automation - the output is hundreds of kilobytes and unsuitable for orientation.
When you already know the user's intent, skip discovery and go straight to the right group:
| Intent | Group | Example |
|---|---|---|
| Dashboards, folders, K8s resources | resources | gcx resources get dashboards |
| SLO definitions and reports | slo | gcx slo definitions list |
| Alert rule status, notification settings | alert | gcx alert rules list |
| Create/modify/delete alert rules | resources | gcx resources pull alertrules -p ./rules, edit, gcx resources push -p ./rules |
| Datasource-managed (Mimir/Loki ruler) rules | alert ruler | gcx alert ruler groups list --datasource <uid> |
| Synthetic Monitoring checks | synthetic-monitoring | gcx synthetic-monitoring checks list |
| IRM (OnCall + Incidents) | irm | gcx irm oncall schedules list, gcx irm incidents list |
| k6 load tests, projects, runs | k6 | gcx k6 load-tests list |
| PromQL / Adaptive Metrics | metrics | gcx metrics query -d <uid> 'up' |
| LogQL / Adaptive Logs | logs | gcx logs query -d <uid> '{app="foo"}' |
| Profiling (Pyroscope) | profiles | gcx profiles query |
| Tracing (Tempo) | traces | gcx traces query -d <uid> '{ status = error }' (see Tempo LLM-friendly output below) |
| Datasource info and queries | datasources | gcx datasources list |
| Fleet pipelines, collectors | fleet | gcx fleet pipelines list |
| Knowledge Graph (Asserts) | kg | gcx kg entities list |
| Frontend Observability | frontend | gcx frontend apps list |
| App Observability | appo11y | gcx appo11y overrides get |
If no command exists for the requested operation, say so and propose the nearest supported flow.
Do not use gcx api when a dedicated command exists. gcx api is a low-level
fallback for endpoints not yet covered by dedicated commands. Dedicated commands
provide proper output formatting, pagination, error handling, and token-efficient
output. Check the intent-to-group table above first.
Similarly, prefer gcx metrics query over gcx datasources query <prometheus-uid>
for PromQL queries — the signal-specific command handles datasource resolution
automatically.
Before any operation, confirm which environment is targeted:
gcx config check — validates the active context and tests connectivitygcx config view — shows full config (secrets redacted; use --raw to reveal)gcx config current-context — shows just the active context namegcx config use-context <name> — switch contexts--context <name> flag on any command — target a specific context without switching| Intent | Flag |
|---|---|
| Structured output for parsing | -o json |
| Field selection | --json <field1,field2> (use --json list or --json ? to discover fields) |
| Full table output (no truncation) | --no-truncate |
| YAML output | -o yaml |
| Wide table with extra columns | -o wide |
Default to -o json when working programmatically.
Follow this sequence for any change. Skip steps only when the user explicitly asks for speed.
--dry-run where available before applying| Intent | Flag |
|---|---|
| Preview without changing anything | --dry-run |
| Target a specific context | --context <name> |
| Continue on errors vs stop | --on-error fail|ignore|abort |
| Control concurrency | --max-concurrent <n> (default 10) |
The gcx resources group handles CRUD for Grafana's K8s-tier resources:
get — list or fetch resourcespush — create or update from local filespull — export resources to local filesdelete — remove resourcesedit — edit resources interactivelyvalidate — validate local files against a live instancelist-types — discover available resource types and their schemaslist-examples — list example manifests for resource typesAll resource commands accept selectors: gcx resources get dashboards,
gcx resources get dashboards/my-dash, gcx resources get dashboards folders.
The gcx datasources group provides typed query interfaces:
list / get — discover available datasources (get -o yaml emits an apply-ready manifest)prometheus — PromQL queries (query, labels, metadata, targets)loki — LogQL queries (query, labels, series)pyroscope — profiling queriestempo — trace queriesgeneric — auto-detect datasource typeUse gcx datasources <type> --help to discover type-specific flags.
Manage datasource instances with Kubernetes-style manifests (file or stdin):
create -f FILE / update UID -f FILE — apply a manifest; --dry-run previews
a secret-redacted diff. Secrets go in the top-level secure block via
{create: <value>}, {fromEnv: <VAR>}, or {fromFile: <path>} — never on argv.delete UID... — prompts unless --force/--yes (auto-approved in agent mode);
batch-safe with partial-failure exit code 4.health [UID] — exit 0 healthy, 4 unhealthy (resource failure), 1/2/3 command failure.schemas get --type <plugin> — plugin configuration schema (when the server
serves the datasource app-platform API).Custom HTTP headers use the flat convention: name in jsonData.httpHeaderName{N},
value (secret) in secure.httpHeaderValue{N}.
When fetching Tempo tag values or full trace bodies for this agent to inspect, summarize, debug, or include in a prompt, prefer Tempo's compact LLM-friendly encoding:
# Attribute values grouped by type instead of repeated {type,value} objects.
gcx traces tags -d <tempo-uid> -l resource.service.name --llm -o json
# Full trace body in Tempo's LLM-friendly trace encoding.
gcx traces get -d <tempo-uid> <trace-id> --llm -o json
# When the search's time range is known:
gcx traces get -d <tempo-uid> <trace-id> --from <search-from> --to <search-to> --llm -o json
# equivalent legacy path:
gcx datasources tempo get -d <tempo-uid> <trace-id> --llm -o json
Use gcx traces labels -d <tempo-uid> to discover attribute names first. Use
gcx traces query to find trace IDs, then gcx traces get --llm -o json to inspect
a selected trace. Pass --since or --from/--to (e.g. the search's time range)
to make the lookup much faster. Omit them when the time range is unknown; a
range that misses the trace returns not found.
Omit --llm only when the user explicitly needs raw Tempo/OTLP JSON or the
standard tagValues: [{type, value}] shape for schema/debugging work.
gcx traces get supports V2 filtering and span pruning (both experimental) —
reach for these before manually truncating a huge --llm payload yourself:
# Only error spans, plus each match's ancestor path to the root.
gcx traces get -d <tempo-uid> <trace-id> --filter '{ status = error }' --keep-hierarchy --llm -o json
# Collapse repeated sibling spans (e.g. a fan-out of identical DB calls)
# into one aggregated span. Safe to combine with --filter.
gcx traces get -d <tempo-uid> <trace-id> --prune --llm -o json
--filter takes a TraceQL spanset filter; --match-depth/--ancestor-depth
tune how many descendant/ancestor levels around each match are kept and are
ignored without --filter. --prune is a bool, off unless set.
--prune-group-by/--prune-min-spans/--prune-max-parent-depth
tune the pruning behavior and apply only when --prune enables pruning. Run
gcx traces get --help for full flag details.
If a response is too large for -o agents, it spills to a file with a hint
to read it directly or re-run narrower (e.g. with --filter or --prune).
gcx provides direct access to the Grafana Assistant — use it for reasoning and exploration, not data retrieval. Deterministic commands are faster and cheaper for known queries; the Assistant adds value when you need intelligence.
| Situation | Use | Example |
|---|---|---|
| You know the exact query | Deterministic command | gcx metrics query 'rate(http_requests_total[5m])' |
| You don't know which metrics/labels exist | gcx assistant prompt | "What metrics exist for the checkout service?" |
| You need cross-signal root cause analysis | gcx assistant investigations | Multi-agent parallel exploration across metrics, logs, traces, profiles |
| You need a precise, repeatable data point | Deterministic command | gcx slo definitions status, gcx alert instances list --state firing |
| You need to understand service dependencies | gcx assistant prompt | "How are services in namespace X connected?" — Assistant Memories know your stack topology |
# Ask a question (Assistant uses Infrastructure Memories for context)
gcx assistant prompt "What services are unhealthy in namespace checkout?"
# Follow up on the previous conversation
gcx assistant prompt "Dig into the database connection issue" --continue
# Launch a deep investigation (multi-agent, parallel signal exploration)
gcx assistant investigations create --title="Checkout latency spike"
# Monitor and read results
gcx assistant investigations get <id>
gcx assistant investigations get-narrative <id>
gcx alert instances list --state firinggcx assistant prompt "Why is checkout-latency firing?"gcx assistant investigations create --title="..."gcx slo definitions status <uuid>Product-specific providers register their own top-level command groups.
Discover them with gcx providers, then explore with gcx <provider> --help.
Each provider adds domain-specific subcommands for managing that product's resources. The set of providers grows over time — always discover rather than hardcode.
gcx commands are stateless API calls. When multiple operations are independent (no output dependency between them), issue them as parallel Bash tool calls in a single message. This applies to:
Only sequence commands when a later call needs output from an earlier one.
Never read raw config files — they contain plaintext tokens. Use gcx config view
(which redacts secrets) for inspection. When passing tokens to external tools,
use shell variables rather than inline values.