gcx#

This page is for operators who want Grafana from a terminal, and for anyone wiring Grafana into a script or an AI agent. gcx is Grafana Labs’ command-line tool, and it supports Grafana 13 and later. It reaches dashboards, data sources, and alerting through Grafana’s API, so it needs a Grafana login and no Kubernetes access.

Connect to your Grafana#

gcx keeps each Grafana it talks to as a named context.

To connect a context to the bundled Grafana, follow these steps:

1. In Grafana, create a service account with the Viewer role, and add a token to it. For how, see Service accounts. Give it Editor instead only if you’re going to change dashboards with it.

2. Log in, and name the context:

   gcx login mzmon --server GRAFANA_ADDRESS --token SERVICE_ACCOUNT_TOKEN

3. Set the chart’s data sources as the context’s defaults, so queries don’t need a -d flag:

   gcx config set contexts.mzmon.datasources.prometheus mzmon-thanos
   gcx config set contexts.mzmon.datasources.loki mzmon-loki

Replace the following:

• GRAFANA_ADDRESS: the URL your Grafana serves. For an unexposed Grafana, port-forward it first, as Grafana in a browser shows, and use http://localhost:3000.
• SERVICE_ACCOUNT_TOKEN: the token from the first step.

Query metrics and logs#

gcx metrics query runs PromQL against a Prometheus-type data source, and gcx logs query runs LogQL against a Loki one:

gcx --context mzmon metrics query 'up{namespace="materialize-environment"}' --since 1h

gcx --context mzmon logs query '{namespace="materialize-environment", app="environmentd"} |= "error"' --since 1h

Add --share-link to print the same query as a Grafana Explore URL, which you can hand to someone working in a browser. For queries worth running, see Common queries.

Read dashboards#

The shipped dashboards are v2 dashboards, and gcx dashboards reads and writes them through Grafana’s resource API:

gcx --context mzmon dashboards search "Materialize"

gcx --context mzmon dashboards get mz-mon-env-top -o yaml

A dashboard’s resource name is its UID. To import a dashboard with gcx, see Importing dashboards.

gcx dashboards snapshot renders a dashboard to PNG through the Grafana Image Renderer. The chart leaves the renderer off, and it should stay off in production, so snapshots fail against the bundled Grafana.

Use gcx from an AI agent#

gcx detects common AI agents, such as Claude Code and Cursor, and switches to JSON output when one runs it. It also bundles agent skills, which teach an agent its commands. The following command installs the skills for setting up gcx, investigating with it, and reading dashboards into ~/.agents/skills:

gcx agent skills install setup-gcx debug-with-grafana manage-dashboards

gcx agent skills list lists the rest.

An agent with a shell needs nothing else to use gcx. For an agent without one, use the Grafana MCP server instead.