gcx

gcx — Grafana Cloud CLI

Grafana Cloud and the Grafana Assistant — in your terminal and your agentic coding environment.

Query production. Investigate alerts. Let the Assistant root-cause issues. Ship fixes with observability built in. Without leaving your editor.

"Don't guess. Check the actual production data."

Why gcx

Agentic coding tools like Claude Code and Cursor have changed how developers build software.

But we face a critical architectural gap: Our development environments are operating in a Context Vacuum.

gcx closes that gap. It connects your editor to your entire Grafana Cloud production stack — including the Grafana Assistant — making observability a development signal, not an afterthought. When something breaks, the Assistant's investigation is already waiting: mitigations planned, context assembled, so you can act immediately.

• Grafana Assistant integration — automated root-cause analysis, investigation summaries, and remediation suggestions powered by the Assistant
• Production-aware development — query live metrics, logs, and traces without leaving your editor
• AI agent native — JSON/YAML output, structured errors, predictable exit codes. Agent mode auto-detected for Claude Code, Copilot, Cursor, and others
• Full Grafana Cloud access — dashboards, alerting, SLOs, Synthetic Monitoring, OnCall, K6, Fleet Management, Incidents, and more from a single CLI
• GitOps & CI/CD — pull resources to files, version in git, push back with full round-trip fidelity
• Observability as code — scaffold projects, import dashboards, lint with Rego rules, live-reload dev server
• Multi-environment — named contexts to switch between dev, staging, and production

[!NOTE] gcx requires Grafana 12 or above. Older Grafana versions are not supported.

Maturity

[!WARNING] This project is currently in public preview, which means that it is still under active development. Bugs and issues are handled solely by Engineering teams. On-call support or SLAs are not available.

See Release life cycle for Grafana Labs.

The Agentic Workflow

Here's what it looks like when your coding agent has access to production:

1. An alert fires — P95 latency on the checkout service crosses the SLO threshold.

2. The Assistant investigates — Your coding agent calls the Grafana Assistant through gcx. The Assistant has already started its investigation — it traces the issue to a missing index on customer_id causing full table scans under load.

3. It fixes the issue — Drafts the migration, adds the index.

4. It prevents recurrence — Instruments the service with OpenTelemetry spans, sets up a Synthetic Monitoring check on the checkout flow, and creates an alert rule on query duration.

5. It ships — Opens a PR, tests pass, deploys to production. The alert resolves.

Investigation, fix, instrumentation, monitoring — without the developer ever leaving their editor. The Grafana Assistant provides the intelligence; gcx provides the interface. And because it all builds on everything you've already configured in Grafana Cloud — your dashboards, your alerts, your datasources — no other tool can give you this depth out of the box.

Install

Pre-built binary (Linux/macOS/Windows):

Download the latest archive for your OS and architecture from the releases page, extract it, and move the binary to your PATH:

tar xzf gcx_*.tar.gz
chmod +x gcx && sudo mv gcx /usr/local/bin/

Go install:

go install github.com/grafana/gcx/cmd/gcx@latest

Shell completion:

gcx completion zsh > "${fpath[1]}/_gcx"   # zsh
gcx completion bash > /etc/bash_completion.d/gcx  # bash

Verify: gcx --version

AI Agent Plugin

A Claude Code plugin is included with skills for managing dashboards, exploring datasources, investigating alerts with the Grafana Assistant, and debugging with live observability data. Install it alongside gcx to give your agent deep Grafana knowledge.

Quick Start

1. Authenticate

Grafana API access (service account token, recommended):

gcx config set contexts.my-grafana.grafana.server https://your-instance.grafana.net
gcx config set contexts.my-grafana.grafana.token your-service-account-token
gcx config use-context my-grafana