/gcx

name: gcx
description: >
  Manages Grafana Cloud resources via the gcx CLI. Trigger when the user wants to
  inspect, create, update, delete, query, or automate any Grafana resource -
  dashboards, datasources, alerts, SLOs, synthetic checks, oncall, incidents,
  fleet, k6, knowledge graph, or adaptive telemetry.
user-invocable: true
disable-model-invocation: false
allowed-tools: Bash, Read, Write, Edit, Glob, Grep, Agent, AskUserQuestion

gcx — Grafana Cloud CLI

gcx is a unified CLI for Grafana Cloud, organized like kubectl: named contexts, structured output, and a consistent verb model across all resource types.

Discover Before You Act

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.

Intent-to-Group Quick Reference

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.

Avoid Raw API Passthrough

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

Verify Context First

Before any operation, confirm which environment is targeted:

• `gcx config check` — validates the active context and tests connectivity
• `gcx config view` — shows full config (secrets redacted; use `--raw` to reveal)
• `gcx config current-context` — shows just the active context name
• `gcx config use-context <name>` — switch contexts
• `--context <name>` flag on any command — target a specific context without switching

Output Control

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

Safe Mutation Workflow

Follow this sequence for any change. Skip steps only when the user explicitly asks for speed.

1. **Verify context** — confirm which environment is targeted 2. **Read current state** — list or get the resource first 3. **Build from template** — use list-types/list-examples output, not hand-crafted payloads 4. **Preview** — use `--dry-run` where available before applying 5. **Apply** — create, update, or delete 6. **Verify** — re-read the resource to confirm the change landed

Key Flags for Operations

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

Resource Operations

The `gcx resources` group handles CRUD for Grafana's K8s-tier resources:

• `get` — list or fetch resources
• `push` — create or update from local files
• `pull` — export resources to local files
• `delete` — remove resources
• `edit` — edit resources interactively
• `validate` — validate local files against a live instance
• `list-types` — discover available resource types and their schemas
• `list-examples` — list example manifests for resource types

All resource commands accept selectors: `gcx resources get dashboards`, `gcx resources get dashboards/my-dash`, `gcx resources get dashboards folders`.

Datasource Queries

The `gcx datasources` group provides typed query interfaces:

• `list`