Grafana CLI for coding agents

When a coding agent needs to inspect or prepare Grafana dashboards or other resources Grafana uses to monitor systems, gcx provides a command-line interface (CLI). The agent uses this program to run Grafana commands from a shell. gcx supports Grafana OSS, Enterprise, and Cloud. The agent can use it to find resources and validate files. It can also preview pushes and produce output that scripts can process. For example, an agent can check local dashboard files before someone sends changes to Grafana.

gcx is separate from the Grafana server CLI, grafana cli, which comes bundled with Grafana server and has plugin and admin commands. The Grafana server CLI documentation covers that tool. For gcx, the gcx repository has the install guide and the full command reference. Its README lists Grafana 13 or later as fully supported for self-hosted setups. On Grafana 12, most features still work, but that version only gets security patches.

Install and sign in

On macOS or Linux, Homebrew can install gcx. Then sign in:

brew install gcx
gcx login

The installation page also documents an install script and the Windows steps. gcx login asks for your Grafana server URL and saves the credentials in a context, which is gcx’s name for a saved connection to one Grafana instance. For Grafana Cloud, it can sign you in through the browser. Sign in yourself before you hand the shell to an agent.

Start with local command discovery

Before asking an agent to run a command on Grafana resources, inspect what gcx supports. help-tree prints a compact text tree of the available commands with their flags. commands prints a catalog in JSON that programs can read. The catalog describes each command and its flags. It also lists the resource types gcx knows. Both are described in the gcx command reference.

gcx help-tree
gcx commands

These commands show which subcommands (commands nested under gcx) and flags (command options) the CLI supports. They inspect gcx locally; they do not ask Grafana to list or change resources. Only gcx commands --validate compares the catalog with a live Grafana instance. Check the output before proceeding, because it shows which resource commands are available.

A realistic prompt for this first pass is:

Run gcx help-tree and gcx commands. Identify the commands related to dashboards and validation, and report their flags. Do not contact Grafana or change any resources.

Validate local Grafana work before pushing

gcx has three kinds of checks for dashboard files, and they differ in what they touch. gcx dev lint run checks local files against built-in rules written in Rego, the policy language of Open Policy Agent. gcx resources validate sends the files to your Grafana instance for server-side validation, so it needs a working login. gcx resources push with --dry-run simulates a push without creating or updating any resources.

gcx dev lint run ./resources
gcx resources validate -p ./resources
gcx resources push -p ./resources --dry-run

./resources is the default path for validate and push, and -p sets another one. dev lint run takes the path as an argument. The gcx README shows these commands in its examples for managing resources. A prompt for this step could say:

Run gcx dev lint run ./resources and gcx resources validate -p ./resources against the dashboard files in this repository. Summarize the results per file. Do not run gcx resources push without --dry-run.

This keeps the agent to local checks and a validation request to Grafana. A real push remains a separate action. Ask the agent to show you the exact push command before it runs, and run it only after you have read the dry-run result.

Configure access outside the prompt

A command that reads or changes Grafana resources needs access to the right Grafana instance and permission to perform the requested action. The gcx authentication guide recommends a service account token for CI and other non-interactive use. gcx also reads the server and token from the GRAFANA_SERVER and GRAFANA_TOKEN environment variables, so a command works without a prior gcx login. Give the token the smallest role the task needs. Grafana says Viewer is enough for queries and for reading dashboards or folders, and Editor covers pushing and editing them.

Keep credentials in the shell environment or an approved secret store, not in the agent’s prompt or generated code. Before a service operation, verify which Grafana instance the CLI will contact and whether the configured identity has the required permission. gcx config check checks the configuration.

Know what errors tell the agent

gcx documents a fixed set of exit codes, the numbers a command returns to report its result. Code 3 means authentication or authorization failed. Code 4 means a partial failure. Some resources in the batch succeeded and others failed. The agent should report which items succeeded and which returned errors. It should not treat every nonzero result as a total failure or retry without checking the result.

gcx turns on agent mode when it detects a known coding agent. In agent mode, a failed command writes one JSON error document to standard output. It has a summary and the exit code, and it can include suggestions for recovery. A partial failure returns the successful items and the error in the same document.

gcx also reports limited usage statistics to Grafana Labs. Set GCX_TELEMETRY=disabled to turn this off, as the usage statistics page explains.

For broader directory browsing, see Awesome CLI.