gcx: the Grafana CLI built for terminals and coding agents

gcx puts a Grafana instance behind shell commands

gcx is a Go command line client for Grafana, and its pitch is that one binary covers three deployments: Grafana Cloud, Grafana Enterprise and Grafana OSS on version 12 and later. The README says core features (resources, alerting, signal queries) work on any Grafana 12+, while Grafana Cloud adds product specific commands on top. What the tool exposes is structured access to what an instance already holds: dashboards, alerts, SLOs, metrics, logs and traces. That framing serves two audiences. A human in a terminal wants the same answers the web UI gives without clicking through panels. An AI coding agent wants a command it can parse and feed into a next step. The repository description calls gcx optimized for agentic usage, and the README says it ships with a suite of agent skills for common workflows, including alert investigation, dashboard creation and GitOps, SLO management and observability setup. The project is licensed under Apache-2.0 and is written in Go.

Signal queries and dashboard snapshots read the same data the browser does

The signal side is the part that makes gcx useful in a script rather than a chat window. A query takes a PromQL style expression and a time window, and the same binary handles dashboard listing, search and rendering. The README gives this example for checking how busy the API routes are, and it works against any Grafana:

gcx metrics query 'sum by (handler)(rate(grafana_http_request_duration_seconds_count[5m]))' --since 1h

Dashboards can then be listed, searched by title text, or rendered to a snapshot with an explicit timeout:

gcx dashboards list
gcx dashboards search "node exporter"
gcx dashboards snapshot my-dashboard --timeout 3m

The Cloud usage query is a separate shape, with a datasource named grafanacloud-usage and its own step interval:

gcx metrics query -d grafanacloud-usage 'grafanacloud_org_metrics_billable_series'  --since 24h  --step 1h

That last command is marked Grafana Cloud only, a distinction that carries through the rest of the tool.

Agent mode keys off Codex and Gemini CLI signals

Agent mode uses known identity signals, including Codex and Gemini CLI, so gcx can tell whether a tool or a person is driving it. For agents without a native signal, the README points to an environment variable, GCX_AGENT_NAME, set to a supported label, with the details in docs/design/environment-variables.md. The fallback is a variable you set yourself, which means a CI step or a wrapper script has to carry it. The repository also ships agent-facing skills, including a contribute skill that asks a coding agent to consult it before choosing a command, provider or datasource path. Those skill definitions live in the source tree under .agents/skills, next to claude-plugin and .claude directories, so they travel with the project rather than being fetched from a separate service at runtime. Detection is a label on the environment, not a different binary.

One login command handles Cloud and self-hosted instances

gcx login creates or re-authenticates a context. It auto-detects whether the server is Grafana Cloud, matching a *.grafana.net address, or on-premises, and adjusts the prompt accordingly, so one subcommand covers both. The Cloud path takes a named context and a server URL:

gcx login prod --server https://<your-cloud-instance>.grafana.net  # select oauth, then press Enter to skip cloud token selection

The self-hosted path passes a token directly on the command line:

gcx login local --server http://localhost:3000 --token <token>

Contexts are named, which is what makes a multi environment setup workable: a laptop can hold prod and local at once, and a pipeline step can select one by name instead of rewriting a URL on every run. For people without a Grafana Cloud account there is a signup command that opens the Cloud sign up page in the browser and returns to gcx once the first stack exists and the connection is approved.

Three install paths with different upgrade costs

The quick install for Linux and macOS pipes a script into a shell. The README says it downloads the latest release, verifies a SHA-256 checksum and installs to ~/.local/bin, and the destination can be changed with GCX_INSTALL_DIR:

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

Upgrading means running the same command again and then checking gcx --version, because an older gcx sitting earlier in your PATH keeps serving the old binary. Homebrew installs the gcx formula from homebrew-core with a prebuilt bottle, so the install takes seconds and needs no tap:

brew install gcx

The Grafana tap carries gcx as well, and that variant compiles the binary on your machine using Homebrew's go build dependency. A Go install works too:

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

Prebuilt archives for Linux, macOS and Windows are also published on the releases page.

The local stack enables kubernetesDashboards for gcx

The docker-compose.yml in the repository states plainly what gcx expects from a server. It pins mysql:9.7 and grafana/grafana:13.2 by image digest, and it turns on a Kubernetes dashboards feature toggle with a comment saying the toggle is required for gcx. It also disables analytics through GF_ANALYTICS_REPORTING_ENABLED and GF_ANALYTICS_CHECK_FOR_UPDATES:

  grafana:
    image: grafana/grafana:13.2@sha256:f772d434e8fab0049deb2b1b30abd43342bcfca1537614aa8d36080232cf4283
    environment:
      # Enable Kubernetes dashboards feature (required for gcx)
      GF_FEATURE_TOGGLES_ENABLE: kubernetesDashboards

The Dockerfile is not a development build recipe. Its own header says GoReleaser copies the release binaries in rather than building there, and the base image is distroless static-debian13 running as a nonroot user with no shell:

FROM gcr.io/distroless/static-debian13:nonroot@sha256:e2e927ec666bae08560abb3c55d0659eceabb657f56b6782ab500a9fc7f555e3 # static-debian13:nonroot
COPY $TARGETPLATFORM/gcx /usr/local/bin/gcx
ENTRYPOINT ["/usr/local/bin/gcx"]

That shape suits a container you run a command in, not one you open a shell inside to debug.

gcx and Grafana MCP split on interface, not on features

The README keeps a section on choosing between gcx and Grafana MCP, and it draws the line along the interface rather than the feature set. gcx reaches Grafana through shell commands, which the README recommends for terminal work, scripts and CI/CD pipelines, against OSS, Enterprise and Cloud. Grafana MCP reaches Grafana through Model Context Protocol tools, and the README says to pick it when a specific tool or its connection model fits better, or when the client has no shell access at all. Two MCP shapes are described. Grafana Cloud MCP is hosted by Grafana and authorized through the browser with OAuth. The open source Grafana MCP server is one you run and configure yourself, pointing at Grafana Cloud or your own instance. The README's guidance for a client that supports both is to start with gcx for these workflows. gcx also manages Cloud only products such as SLOs, Synthetic Monitoring, k6 and Fleet through dedicated commands.

A 12 version floor, tokens on the command line, and a recent release record

Several limits are visible without running anything. Core features need Grafana 12 or newer, so an older instance gets little value from the tool. The billable series query is labelled Grafana Cloud only and will not resolve on a self-hosted server. A token passed as a login argument, as the local example does, lands in shell history and in process listings on a shared machine. A manually downloaded macOS binary can be refused by Gatekeeper with a verification warning or killed: 9, and the README points to a one-time workaround while noting the curl installer handles it automatically. Maintenance signals are recent: the last push was on 2026-10-22, and three tagged releases sit in the preceding weeks, v1.4.0 on 2026-10-02, v1.5.0 on 2026-10-05 and v1.6.0 on 2026-10-13. The go.mod file requires go 1.26.5 and pulls in cobra, prometheus/prometheus, an Open Policy Agent library, Kubernetes client packages, a MySQL driver and a Grafana MCP doc server, which explains both the binary size and the compile time of a source build. The Apache-2.0 licence permits internal use, modification and redistribution if the notice is kept; read the LICENSE file for the exact terms.

Editorial conclusion

gcx fits engineers and coding agents that need Grafana facts without a browser, and it fits CI jobs that want dashboards, alerts and metrics as command output. It does not fit clients without shell access, and Cloud-only commands such as Synthetic Monitoring and k6 will not resolve against a self-hosted instance. Before adopting, run gcx login against your own instance, confirm gcx --version matches the release you expected, and check that your Grafana version is 12 or later.

Frequently asked questions

Official sources

1. grafana/gcx on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases