# [[GCX]] ![[GCX.svg]] **GCX** (lowercase `gcx`) is the **Grafana Cloud CLI** — a single command-line tool for managing [[Grafana]] and [[Grafana Cloud]] resources, designed from the ground up for **agentic** usage inside AI-assisted coding environments like [[Claude Code]], [[Cursor]], and [[GitHub Copilot]]. It was announced on **21 April 2026** at **[[GrafanaCON]] 2026** in Barcelona, alongside AI Observability in Grafana Cloud, expanded [[Grafana Assistant]] capabilities, and `o11y-bench`. It is the evolution of `grafanactl`, and it is currently in **public preview**. ## Why it's important Grafana's framing is that modern dev workflows have an **"AI blind spot"** / **"context vacuum"**: agents write code in the editor, but have no line of sight into what's happening in production. GCX closes that gap by giving your coding agent a structured, machine-friendly way to talk to your entire Grafana Cloud stack — dashboards, alerts, logs, metrics, traces, SLOs, synthetics, k6, OnCall, Incidents — *and* to invoke the [[Grafana Assistant]] without ever leaving the editor. The agent can query live telemetry, correlate alerts with recent repo changes, propose fixes, and ship them — closing the loop between **code → production → code**. This is Grafana's bet on what "observability as a development signal" looks like once the agent becomes the primary interface. ## Links - **Announcement (press release)**: [Grafana Labs Targets the "AI Blind Spot" with New Observability Tools Announced at GrafanaCON 2026](https://www.morningstar.com/news/business-wire/20260421657088/grafana-labs-targets-the-ai-blind-spot-with-new-observability-tools-announced-at-grafanacon-2026) - **Analyst write-up**: [SiliconANGLE — Grafana is trying to close the AI observability gap before enterprise agents reign supreme](https://siliconangle.com/2026/04/21/grafana-trying-close-ai-observability-gap-enterprise-agents-reign-supreme/) - **Conference context**: [GrafanaCON 2026 agenda](https://grafana.com/blog/grafanacon-2026-agenda/) · [GrafanaCON event page](https://grafana.com/events/grafanacon/) - **GitHub repo**: [grafana/gcx](https://github.com/grafana/gcx) (Apache-2.0, Go) - **Official docs**: [gcx CLI | Grafana documentation](https://grafana.com/docs/grafana/latest/as-code/observability-as-code/grafana-cli/gcx/) · [Introduction to the Grafana CLI](https://grafana.com/docs/grafana/latest/as-code/observability-as-code/grafana-cli/) - **Deep-dive docs in repo**: [Configuration](https://github.com/grafana/gcx/blob/main/docs/configuration.md) · [Dashboards as Code guide](https://github.com/grafana/gcx/blob/main/docs/guides/dashboards-as-code.md) · [Claude Code plugin README](https://github.com/grafana/gcx/blob/main/claude-plugin/README.md) - **Related video**: [Agentic AI for Observability: Grafana Assistant & Investigations](https://www.youtube.com/watch?v=mYgexXCMXeg) (Assistant + Investigations demo — the intelligence layer GCX exposes) ## Features / what you can do with it - **Agent-native interface** — JSON/YAML output, structured errors, predictable exit codes, non-interactive by default. Agent mode is auto-detected for [[Claude Code]], Copilot, and Cursor. - **Bundled [[Claude Code]] plugin** — ships with ~18 skills (e.g. `explore-datasources`) that give your agent deep Grafana knowledge out of the box. - **Grafana Assistant integration** — your agent can delegate to the Assistant for automated root-cause analysis, investigation summaries, and remediation suggestions. - **Live production queries from the terminal** — PromQL against Mimir/Prometheus, LogQL against Loki, plus Tempo (traces) and Pyroscope (profiles). - **Unified resource management** — get / push / pull / edit / delete / validate dashboards, folders, alert rules, and more, with a single CLI. - **Observability-as-code workflow** — scaffold projects with the `grafana-foundation-sdk`, import existing dashboards as Go builder code, run a live-reload dev server, and lint with built-in or custom Rego rules. - **GitOps round-trip** — pull resources to files, commit, push back; idempotent, with dependency-aware ordering (folders before dashboards). - **CI/CD friendly** — `--dry-run`, `--on-error abort|fail|ignore`, machine-readable output — drop straight into GitHub Actions. - **Multi-environment contexts** — named contexts for dev/staging/prod, plus env-var auth (`GRAFANA_SERVER`, `GRAFANA_TOKEN`, `GRAFANA_CLOUD_TOKEN`) for pipelines and agents. - **Raw API passthrough** — `gcx api …` for anything not yet wrapped by a dedicated command. - **Auth** — service account tokens, Cloud Access Policy tokens, and an experimental browser-based OAuth login (`gcx auth login`). Requirement: **Grafana 12 or later**. ## Which Grafana products work with it GCX reaches across most of the Grafana Cloud surface area. From the repo's product table: | Product | Command | What you get | | --- | --- | --- | | [[Grafana]] core (dashboards, folders, datasources, alert rules) | `gcx resources`, `gcx alert` | Full CRUD, pull/push, dashboards-as-code | | [[Grafana Alerting]] | `gcx alert` | `rules list`, `groups list` | | [[SLOs\|Grafana SLO]] | `gcx slo` | `definitions list`, `reports list` | | [[Synthetic Monitoring]] | `gcx synthetic-monitoring` | `synthetic-monitoring checks list`, `synthetic-monitoring probes list` | | [[IRM]] (incidents + on-call) | `gcx irm` | `irm oncall schedules list`, `irm oncall integrations list`, `irm incidents list`, `irm incidents create -f incident.yaml` | | [[k6\|Grafana Cloud k6]] | `gcx k6` | `load-tests list`, `runs list` | | [[Fleet Management]] | `gcx fleet` | `pipelines list`, `collectors list` | | [[Grafana Assistant]] | `gcx assistant` | `assistant prompt`, `assistant investigations list`, `assistant investigations report` | | Knowledge Graph | `gcx kg` | `status`, `search`, `entities show` | | [[Adaptive Telemetry]] (metrics + logs + traces) | `gcx metrics adaptive`, `gcx logs adaptive`, `gcx traces adaptive` | recommendations, patterns, drop-rules, policies | | Frontend Observability | `gcx frontend` | `frontend apps list`, `frontend apps get` | | App Observability | `gcx appo11y` | `appo11y overrides get`, `appo11y settings get` | | AI Observability (Sigil) | `gcx aio11y` | `aio11y conversations list`, `aio11y agents list`, `aio11y rules list` | | Mimir / Prometheus | `gcx metrics` | PromQL queries, labels, metadata | | [[Loki]] | `gcx logs` | LogQL queries, labels, series | | [[Tempo]] | `gcx traces` | Query traces | | [[Pyroscope]] | `gcx profiles` | Query profiles | (Corrected 2026-08-18 against the `grafana/gcx` README — the previous version of this table had `gcx synth` and separate OnCall/Incidents rows, which don't match the actual command namespace.) ## Compatibility - Resource management, alerting, raw API passthrough, and Observability-as-Code work identically on **OSS, Enterprise, Cloud, and BYOC** (Grafana 12+). - Signal queries (metrics/logs/traces/profiles) work against **self-hosted** datasources too — you configure the datasource endpoint manually; Grafana Cloud auto-discovers it. - **Cloud-only**: SLO, Synthetic Monitoring, IRM, k6, Fleet Management, Adaptive Metrics/Logs/Traces, and [[Grafana Assistant]]. BYOC gets partial support depending on which plugins are installed. ## What [[Grafana Assistant]] has to do with it — and what it doesn't **GCX does not require [[Grafana Assistant]] to function — not even a subscription.** Verified directly with Grafana staff (Gregor Zeitlinger, #o11y-sdks-dev, 2026-08-18), in response to a question about whether gcx needs an active GC subscription for its AI features: *"no gcx doesn't need a subscription — that would have been a non-starter... gcx is great to use for your agent — that's the angle."* Core commands — `gcx metrics query`, `gcx logs query`, `gcx resources`, `gcx alert`, etc. — run on nothing but a Grafana service account token, and the reasoning happens in **your own coding agent** (Claude Code, Cursor, Copilot), not Assistant. Same "bring your own brain" model as [[Grafana MCP]]. Assistant only enters the picture in two optional places: - The **OAuth login shortcut** (`gcx login` with browser auth) proxies through Assistant's backend for that one auth flow — skip it with a service account token instead. - Calling **`gcx assistant`** directly (prompts, investigations) invokes Grafana's own hosted reasoning — and its usage-based token billing (see [[Grafana Assistant]] pricing). Where Assistant *is* genuinely useful: it already does the hard observability reasoning — investigations, root-cause analysis, remediation suggestions, drafting alert rules — inside Grafana Cloud. GCX's `gcx assistant` commands let your coding agent call into that reasoning from wherever it lives (Claude Code, Cursor, Copilot, a CI job), so conclusions show up in your editor instead of a browser tab. It's an optional power-up, not a dependency. The canonical agentic workflow Grafana describes, for when you *do* reach for `gcx assistant`: 1. An alert fires (e.g. P95 latency on checkout crosses SLO). 2. Your coding agent calls the Grafana Assistant **through gcx**. The Assistant investigates and traces it to, say, a missing index causing full table scans. 3. The agent drafts the migration and adds the index. 4. It prevents recurrence — instruments with OpenTelemetry spans, adds a Synthetic Monitoring check, creates an alert rule on query duration. 5. It opens a PR, tests pass, the alert resolves. All of it without the developer leaving the editor. That's the loop GCX is built to close. ## Pricing **`gcx` itself is free** — open-source CLI, no license cost, no Grafana Cloud subscription required (see verification above). You only pay for the **Grafana Cloud products it invokes**, at their normal usage-based rates: - [[Grafana Assistant]] — billed per token via the Assistant plan (see [[Grafana Assistant]]'s pricing section); `gcx metrics` / `gcx logs` / `gcx resources` etc. consume zero Assistant tokens since the reasoning stays in your own agent. - Synthetic Monitoring — per test execution. - k6 — per Virtual User Hour. - IRM — per monthly active user. - Signal queries (metrics/logs/traces/profiles) against **self-hosted** datasources are free either way — only Grafana Cloud product usage is metered. ## See also - [[Grafana Assistant]] - [[Grafana Cloud]] - [[GrafanaCON]] - [[Claude Code]] - [[Observability as code]] %% # Excalidraw Data ## Text Elements ## Drawing ```compressed-json N4KAkARALgngDgUwgLgAQQQDwMYEMA2AlgCYBOuA7hADTgQBuCpAzoQPYB2KqATLZMzYBXUtiRoIACyhQ4zZAHoFAc0JRJQgEYA6bGwC2CgF7N6hbEcK4OCtptbErHALRY8RMpWdx8Q1TdIEfARcZgRmBShcZQUebR44gAYaOiCEfQQOKGZuAG0AXX4IXDg4AGUoqHFUUDBIdXTqiCJlaRS6hkIECgAhXGwAa2VSYQ5iAGE2fDZSbggAYgAzZZX2 yGwRQKyASSr9CpGBhEnp2Yl5gEYEK6u1iA3SLahd9L7B4dGJqZm5qHIOZhwXBPO4PJ4vfQAMUI+HwFRgwTmgg8oM2mWeewObCOAHUSOpuHxwOs0TtMX9sQh4YiJMiSKjHuiIQAlYStDjhHJoC78EmMsnpADyQOwahg3AuiUSvPupIx6UhnCgkNw+hh4rQAFYZWCmXtFVkyoQjNUeNLibL+fL9AAVLBQACCLS4EmCiygDPB5OBjsebAokhCxG4HCE sJ1cohAFExg6/QGg3NgSMqBGrRC4ymbfAmiMhGNPXqFeQMqyaahQ+GLcxsCNYQANbgAZgALHEeC3EgBOLsAdibFxbLc1A5lNbr+AAmtwAGxdxLaAAcTZnbc1vcXFx42otRjYBm4tQ69AIQmqF2JAF80170qz88QOcwueg8wWZcMSEaTYTzR1P8QFQIHA3A7v+pAkAAsmwxAIDGuCaMEwZoIsBBhB+EFfKch7EpAPRTMhr7KJouAABQ8BcvbULwlH URRVGoAumoAJRrJAzIIMoYbAnMpDEWRPBNtKvBCXRomMdoLEQFeN7oliRzClA7AAiGYb4DKiwlggHFjEwhAcMoOF1JAmQIUh3B/GevLrEQIFoJZCDWRAHCqtUDlOcIUBEByFmkFZuEQPowJHKQAByrm+f5xmBcFTDwYhCCEQ5MkWnYABWCDYNkZQuXA0GwfF5koWhjkWv0SmMDa+74EZHSwIgSJpFlylsbKzBQAY2YNWglbqQF0yDIl3Cofg6EBZ pBhlE1SmcMNJVOfgoSOs1lXVapsIpR0jjMGZxxKvakGZEIc2jaVHSaPpjgGQACoEixMJkYhzKZCXBjKhDMD0l36cohVDfZflnZAH2QSQcBsPpUA5SUcA/X9SWAzKmhsJgU3BM1nD5U0ehZLg+nSWA150IsMLhIel4gJeQA== ``` %%