gcx

gcx — Grafana CLI

gcx is Grafana in your terminal and your agentic coding environment.

With gcx you don't guess, but check the actual data. You can query production, investigate alerts, let the Assistant root-cause issues, or ship fixes with Observability built in, without ever leaving your editor.

What is gcx?

gcx is a CLI for Grafana Cloud, Enterprise, and OSS alike. It gives you and your AI coding agent structured access to your Grafana deployment's dashboards, alerts, SLOs, metrics, logs, traces, and more. Core features (resources, alerting, signal queries) work on Grafana 12 or higher, while Grafana Cloud adds product-specific commands on top. Refer to the compatibility matrix for details on supported features.

gcx works with any agentic coding tool. It ships with a suite of agent skills for common workflows like alert investigation, dashboard creation and GitOps, SLO management, and observability setup. Refer to Use with your AI agent for further details.

AI tools: Choose between gcx, Grafana MCP, and Grafana Assistant

Grafana offers you a few AI tools to work with.

gcx gives you and your coding agents access to Grafana through shell commands. Grafana MCP gives AI clients access through Model Context Protocol tools. Grafana Assistant is the Grafana AI agent, built into Grafana. Use gcx for terminal work, scripts, GitOps, and CI/CD pipelines. It supports Grafana OSS, Enterprise, and Cloud and has dedicated commands for Grafana Cloud products.

The Grafana MCP is a Model Context Protocol server that gives AI assistants and LLM clients access to your Grafana instance, including clients without shell access. Choose between the Grafana Cloud MCP(Grafana hosts the server) or the Grafana OSS MCP(You run and configure the server).

Finally, Grafana Assistant brings a purpose-built LLM into Grafana. Use it to troubleshoot issues, manage dashboards, and answer product questions in plain language. Some advanced features require the full Grafana Cloud feature set. In self-managed Grafana the Assistant app runs in your own deployment but connects to a Grafana Cloud Assistant backend, with a reduced feature set. Refer to the Grafana Assistant documentation for an overview.

If your coding agent supports both shell commands and MCP, start with gcx for these workflows. Choose MCP when a specific tool or its connection model better meets your needs.

Compatibility and availability

Grafana version support

gcx supports the current Grafana major version (currently 13.x), plus the previous major version for 3 months after the new one ships.

Grafana	Support level
Grafana Cloud	Full support. Everything in this README, including Cloud-only products (SLO, Synthetic Monitoring, IRM, k6, Fleet, Adaptive Telemetry, Assistant).
Grafana 13+ (OSS / Enterprise)	Full support of self-hosted features. All app-platform API groups gcx relies on are enabled by default.
Grafana 12.x (OSS / Enterprise)	Not actively supported. Most features will still work, but there'll only be patches with security updates. Features built on app-platform API groups that are not yet enabled by default need an explicit feature toggle.
Grafana < 12	Not supported. gcx detects the server version and exits with code 6 (version incompatible).

Feature availability by deployment

Feature availability depends on your Grafana deployment:

Feature	Commands	OSS	Enterprise	Cloud	BYOC
Resource management (dashboards, folders)	resources	✓	✓	✓	✓
Alert rules	alert	✓ (1)	✓ (1)	✓	✓
Raw API passthrough	api	✓	✓	✓	✓
Observability as Code	dev	✓	✓	✓	✓
Signal queries (metrics, logs, traces, profiles)	metrics, logs, traces, profiles	✓ (2)	✓ (2)	✓	✓
SLO, Synthetic Monitoring, IRM, k6, Fleet, etc.	slo, synthetic-monitoring, irm, k6, fleet	✗	✗	✓	(3)
Adaptive Metrics / Logs / Traces	metrics adaptive, logs adaptive, traces adaptive	✗	✗	✓	(3)
Grafana Assistant	assistant	✗	✗	✓	✗

(1) Alert rules (gcx alert rules, gcx alert groups) and ruler writes (gcx alert ruler) managed by data sources work on Grafana 12 or higher. To write Grafana-managed rules via the resources tier (gcx resources pull/push alertrules) you need Grafana 13 or higher. If you're using Grafana 12, refer to Grafana 12 feature toggles.

(2) Self-hosted signal queries (gcx metrics query, gcx logs query, gcx traces query, and gcx profiles query) work against self-hosted data sources (Prometheus, Loki, Tempo, Pyroscope), but you need to manually configure data source endpoints. In Grafana Cloud, your stack will auto-discover endpoints.

(3) Bring Your Own Cloud runs the Grafana stack on your own infrastructure while connecting to the Grafana Cloud control plane. Core Grafana features (dashboards, alerts, signal queries) work in full. Cloud product availability (SLO, Synthetic Monitoring, IRM, etc.) depends on which plugins you've installed and configured in your BYOC stack.

Grafana 12 feature toggles

Grafana is progressively migrating APIs to app-platform (Kubernetes-style) API groups. Each group flips to enabled-by-default in a different release. When a command needs an API group your stack doesn't serve, upgrade or enable the corresponding feature toggle.

• Track declaration of these requirements (min version, feature toggles) for each command in #989.
• Read more abut the new API model.

For example, writing Grafana-managed rules via the resources tier (gcx resources pull/push alertrules) requires Grafana 13 or higher, where the rules.alerting.grafana.app API is enabled by default. On Grafana 12 you must enable it explicitly with the kubernetesAlertingRules feature toggle:

[feature_toggles]
kubernetesAlertingRules = true

This toggle is experimental in 12.x, requires a restart, and Unified Alerting must be enabled.

Supported Grafana Cloud products

gcx provides dedicated commands for each Grafana Cloud product:

Product	Command	Examples
SLOs	gcx slo	slo definitions list, slo reports list
Synthetic Monitoring	gcx synthetic-monitoring	synthetic-monitoring checks list, synthetic-monitoring probes list, synthetic-monitoring probes deploy
IRM	gcx irm	irm oncall schedules list, irm oncall integrations list, irm incidents list, irm incidents create -f incident.yaml
Alerting	gcx alert	alert rules list, alert groups list
k6 Cloud	gcx k6	k6 load-tests list, k6 runs list
Fleet Management	gcx fleet	fleet pipelines list, fleet collectors list
Knowledge Graph	gcx kg	kg status, kg entities list, kg entities inspect, kg graph query
Frontend Observability	gcx frontend	frontend apps list, frontend apps get
App Observability	gcx appo11y	appo11y overrides get, appo11y settings get
Agent Observability	gcx agento11y	agento11y conversations list, agento11y experiments pull, agento11y rules list
Assistant	gcx assistant	assistant prompt, assistant investigations list, assistant mcp-servers list
Adaptive Metrics	gcx metrics adaptive	metrics adaptive recommendations list, metrics adaptive rules list
Adaptive Logs	gcx logs adaptive	logs adaptive patterns list, logs adaptive drop-rules list
Adaptive Traces	gcx traces adaptive	traces adaptive recommendations list, traces adaptive policies list
Profiles (Pyroscope)	gcx profiles	profiles query, profiles labels
Traces (Tempo)	gcx traces	traces query, traces get, traces labels

Keep in mind Grafana Cloud costs. gcx itself is free, but some of these products are billed based on usage: Grafana Assistant is charged per token consumed (including requests made through gcx), Synthetic Monitoring per test execution, k6 per Virtual User Hour, and IRM per monthly active user. Queries and resource push/pull are not billed. Refer to Costs and billing and the Grafana Cloud Cost Management and Billing documentation for more details.

New to gcx or Grafana? Start here!

Install gcx

For other installation options such as the binary or Go install, refer to the main Installation doc.

The quickest way to install gcx in Linux or macOS is with the script, which downloads the latest release, verifies the SHA-256 checksum, and installs to ~/.local/bin.

curl -fsSL https://raw.githubusercontent.com/grafana/gcx/main/scripts/install.sh | sh

You can override the location with GCX_INSTALL_DIR:

curl -fsSL https://raw.githubusercontent.com/grafana/gcx/main/scripts/install.sh | GCX_INSTALL_DIR=/usr/local/bin sh

To upgrade, run the same command again, then check gcx --version.

Windows

Run this command in PowerShell 7 or Windows PowerShell 5.1:

irm https://raw.githubusercontent.com/grafana/gcx/main/scripts/install.ps1 | iex
gcx --version

The installer checks the SHA-256 checksum. It installs gcx.exe in $env:LOCALAPPDATA\gcx\bin and adds that directory to your user PATH. Run the command again to upgrade. Use GCX_VERSION or GCX_INSTALL_DIR to select a version or directory. See the Windows install guide for manual ZIP installation and uninstall steps. For WSL, use the Linux installer inside WSL.

Homebrew

To install gcx using Homebrew in Linux or macOS run:

brew install gcx

This installs the gcx formula from homebrew-core. Homebrew has a prebuilt bottle for macOS and Linux, so the install takes seconds and needs no tap.

To update to the latest version:

brew update && brew upgrade gcx

The Grafana tap also carries gcx. Use it if you want Homebrew to compile the binary on your machine, run:

brew install grafana/grafana/gcx

Access Grafana

If you're new to Grafana Cloud, use gcx to create a free account and connect to its first stack when you approve:

gcx signup

Next, log into your account from your terminal or agent:

gcx login

login creates or re-authenticates a context. It auto-detects whether the server is Grafana Cloud (*.grafana.net) or on-premise and adjusts the prompt accordingly.

Refer to Authentication for the available paths and options to authenticate.

Use with your AI agent