/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'` | | Metric names, labels, metadata | `metrics` | `gcx metrics list-names -d <uid> --contains <term> -o json` | | 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), service dependencies | `kg` | `gcx kg entities list`, `gcx kg graph query "<cypher>" --since 1h` | | Frontend Observability | `frontend` | `gcx frontend apps list` | | App Observability | `appo11y` | `gcx appo11y overrides get` |

Each signal group has its own discovery commands, for example `gcx metrics labels`, `gcx logs labels`, and `gcx traces labels`; `gcx help-tree <group> --depth 1 -o text` lists them. Some command areas also have a workflow skill: `gcx help-tree --depth 1 -o text` marks them with `# skill:`, `gcx <group> --help` lists them under Related skills, and `gcx agent skills get <name> -o text` prints one your harness hasn't loaded. Dashboard authoring uses `create-dashboard`.

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.

Target Context

When the target context is known, pass `--context <name>` directly; no separate configuration or connectivity check is needed. Inspect configuration only when the target is ambiguous or a request fails with a configuration, authentication, or connectivity error:

• `gcx config list-contexts` — list configured contexts and their servers
• `gcx config current-context` — show the active context name
• `gcx config check` — validate the active context and test connectivity
• `gcx config view` — inspect configuration with secrets redacted

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