gcx CLI on Grafana Labs

Introduction to gcx

Tue, 02 Jun 2026 16:22:08 +0200

Overview of the `gcx` CLI

Caution
The Grafana CLI gcx is available in public preview for Grafana Cloud and Grafana OSS/Enterprise v12 or later. Older Grafana versions are not supported.

gcx is under development. Documentation and support is available based on the different tiers but might be limited to enablement, configuration, and some troubleshooting. No SLAs are provided.

Contact Grafana for support or to report any issues you encounter and help us improve this feature.

gcx is a single CLI that allows you and your AI coding agent structured access to both Grafana (dashboards, folders, alert rules, data sources) and Grafana Cloud products such as Synthetic Monitoring, K6, Fleet Management, Incidents, or Adaptive Telemetry.

gcx ships with a suite of agent skills for common workflows like alert investigation, root-cause analysis, dashboard creation and GitOps, SLO management, and observability setup. It natively supports agentic workflows and it’s integrated with Grafana Assistant, combining the previously fragmented user experience into one single tool.

Benefits of `gcx`

Among others, gcx provides the following benefits:

Manage Grafana OSS/Enterprise and Grafana Cloud: Use a single tool for dashboards, alerting, SLOs, on-call, synthetic checks, load testing, and more.
GitOps: Pull resources to files, version in Git, or push back with full round-trip fidelity.
SRE: Ensure system performance by monitoring telemetry and root-causing incidents.
Observability as code: gcx can scaffold Go projects, import existing dashboards, lint with Rego rules, or live-reload development servers.
Automation: gcx uses JSON/YAML output, structured errors, and predictable exit codes.
Multi-environment: Use named contexts to switch between development, staging, and production environments.
AI agent friendly: Agent mode auto-detected for Claude Code, Copilot, Cursor, and other.

Compatibility

gcx is compatible with any agentic coding tool.

gcx works across a wide range of Grafana product offerings. Feature availability depends on your Grafana deployment. For more information, refer to the Compatibility matrix.

Migrate from `grafanactl`

If you want to migrate from grafanctl to gcx, search-and-replace grafanactl with gcx. For grafanactl resources serve, use gcx dev serve instead.

Learn more

Refer to the gcx repository in GitHub for more information on:

Installation and configuration
How to manage resources, including dashboards-as-code
CLI command reference

Install gcx

Fri, 15 May 2026 16:15:40 +0100

Install `gcx`

Quick install using the script

The fastest way to install gcx on Linux or macOS is with the script:

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

The script:

Detects your operating system and architecture.
Downloads the latest release from GitHub
Verifies the SHA-256 checksum.
Installs the binary to ~/.local/bin.

Installer configuration options

Use these environment variables to customize the install script:

Environment variable	Default	Description
`INSTALL_DIR`	`$HOME/.local/bin`	Directory to install the binary into
`VERSION`	latest	Specific version to install (e.g., `0.2.4`)
`GITHUB_TOKEN`	unset	GitHub token for API requests (avoids rate limits)

Examples

Install a specific version:

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

Install to /usr/local/bin:

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

Uninstall

To remove gcx, delete the binary:

rm ~/.local/bin/gcx

Install `gcx` with Homebrew (macOS and Linux)

To install gcx with Homebrew run:

brew install grafana/grafana/gcx

To upgrade an existing installation:

brew upgrade grafana/grafana/gcx

Homebrew builds gcx from source on your machine, as it pulls go as a build dependency. The first install usually takes 30 to 60 seconds, and later upgrades reuse the Homebrew download cache.

This option avoids macOS Gatekeeper because it doesn’t download a prebuilt binary. You won’t need to work around notarisation.

Install a prebuilt binary

Prebuilt binaries are available for a variety of systems and architectures. Refer to the release versions on GitHub for more details.

To install a prebuilt binary:

Download the archive for the operating system and architecture you need.
Extract the archive.
Move the executable to the directory where you want to keep it.
Make sure that directory is in your PATH.
Make sure the file has execute permission.

If you use macOS, a manually downloaded binary might be blocked by Gatekeeper. For more information, refer to macOS Gatekeeper and killed: 9.

Install `gcx` from source

To install gcx with Go, you need:

git.
go 1.24 or later.

To install, run:

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

macOS Gatekeeper and killed 9

macOS quarantines any downloaded binary by default. Since gcx release binaries are not yet Apple-notarised, macOS may block it the first time you run it. If this happens, you’ll see one of these two symptoms:

Intel macOS: A dialog says, “Apple could not verify ‘gcx’ is free of malware…”, and the binary doesn’t run.
Apple Silicon (M-series) macOS: The binary exits immediately with killed: 9 and no visible dialog.

Homebrew users are not affected. Since it compiles gcx from source on your machine, no pre-built binary is downloaded and no xattr is set.

Bypass the macOS gatekeeper

In manual downloads, bypass this by clearing the xattr and ad-hoc sign the binary so Apple Silicon accepts it:

xattr -d com.apple.quarantine "$(command -v gcx)" 2>/dev/null || true
codesign --sign - --force "$(command -v gcx)"   # required on Apple Silicon

Next, run gcx --version again; subsequent invocations should succeed without the block.

Note that these steps will no longer be necessary once gcx release binaries are Apple-notarised.

Configure gcx

Fri, 15 May 2026 16:15:40 +0100

Configure `gcx`

You can configure gcx with a configuration file or using environment variables.

A configuration file can store multiple contexts, which makes it easier to switch between Grafana instances. Check the configuration file reference documentation for details on all available configuration options.
Environment variables describe a single context, so they work best in CI environments. Refer to Configure gcx with environment variables for more information.

Understand the `gcx` configuration file in use

Run gcx config check to display the configuration file currently in use.

gcx stores its configuration in a YAML file. Configuration is prioritized in this order:

If the --config flag is set, then that file will be loaded. No other location will be considered.
If the $XDG_CONFIG_HOME environment variable is set, then it will be used: $XDG_CONFIG_HOME/gcx/config.yaml
If the $HOME environment variable is set, then it will be used: $HOME/.config/gcx/config.yaml
If the $XDG_CONFIG_DIRS environment variable is set, then it will be used: $XDG_CONFIG_DIRS/gcx/config.yaml

Define contexts

gcx supports multiple contexts so you can switch between instances. By default, it uses the default context.

To configure the default context:

gcx config set contexts.default.grafana.server http://localhost:3000

# Set org-id when using OSS/Enterprise - skip when targeting Grafana Cloud
gcx config set contexts.default.grafana.org-id 1

# Authenticate with a service account token
gcx config set contexts.default.grafana.token service-account-token

# Or alternatively, use basic authentication
gcx config set contexts.default.grafana.user admin
gcx config set contexts.default.grafana.password admin

To create another context, use the same pattern:

gcx config set contexts.staging.grafana.server https://staging.grafana.example
gcx config set contexts.staging.grafana.org-id 1

Note that in these examples, default and staging are the context names.

Useful commands

Use these commands to check the configuration:

gcx config check

List existing contexts:

gcx config list-contexts

Switch to a different context:

gcx config use-context staging

See the entire configuration:

gcx config view

Configure `gcx` with environment variables

Every supported environment variable is listed in our reference documentation.

Since gcx connects to Grafana through the REST API, you must configure authentication credentials. At minimum, set the Grafana URL and organization ID:

GRAFANA_SERVER='http://localhost:3000' GRAFANA_ORG_ID='1' gcx config check

Depending on your authentication method, also set one of the following:

If you use a Grafana service account (recommended), set a token.
If you use basic authentication, set a username and a password.

After you configure authentication, you can start using gcx.

If you want to persist this configuration, create a context.

gcx CLI on Grafana Labs

Introduction to gcx

Overview of the gcx CLI

Benefits of gcx

Compatibility

Migrate from grafanactl

Learn more

Install gcx

Install gcx

Quick install using the script

Installer configuration options

Examples

Uninstall

Install gcx with Homebrew (macOS and Linux)

Install a prebuilt binary

Install gcx from source

macOS Gatekeeper and killed 9

Bypass the macOS gatekeeper

Configure gcx

Configure gcx

Understand the gcx configuration file in use

Define contexts

Useful commands

Configure gcx with environment variables

Overview of the `gcx` CLI

Benefits of `gcx`

Migrate from `grafanactl`

Install `gcx`

Install `gcx` with Homebrew (macOS and Linux)

Install `gcx` from source

Configure `gcx`

Understand the `gcx` configuration file in use

Configure `gcx` with environment variables