Introduction to the Grafana CLI on Grafana Labs

gcx CLI

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 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 and set up the grafanactl CLI

Tue, 28 Apr 2026 08:48:36 +0000

Install and set up the `grafanactl` CLI

Caution
grafanactl is being deprecated, and we’re bringing all our learning and experience into the new, improved CLI tool gcx. The grafanactl repository in GitHub will be archived on June 1, 2026.

To migrate from grafanactl to gcx, search-and-replace grafanactl with gcx. For grafanactl resources serve, use gcx dev serve instead.

The grafanactl command-line tool allows you to authenticate, manage multiple environments, and perform administrative tasks through the Grafana REST API, all from the terminal. It’s available for Grafana OSS, Enterprise, and Cloud.

Install the Grafana CLI `grafanactl`

You can install the project using one of the following supported methods:

1. Download a pre-built binary

Download the latest binary for your platform from the Releases page.

Prebuilt binaries are available for a variety of operating systems and architectures. Visit the latest release page, and scroll down to the Assets section.

To install the binary, follow the instructions below:

Download the archive for the desired operating system and architecture
Extract the archive
Move the executable to the desired directory
Ensure this directory is included in the PATH environment variable
Verify that you have execute permission on the file

2. Build from source

To build grafanactl from source you must:

Have git installed
Have go v1.24 (or greater) installed

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

Configure `grafanactl`

You can configure grafanactl in two ways: using environment variables or through a configuration file.

Environment variables are ideal for CI environments and support a single context. A full list of supported environment variables is available in the reference documentation.
Configuration files can manage multiple contexts, making it easier to switch between different Grafana instances.

Note
Configuration items may change depending on your set-up. For example, use org-id for self-managed Grafana, but use stack-id for Grafana Cloud.

Configure Grafana CLI with environment variables

Grafana CLI communicates with Grafana via the REST API, which requires authentication credentials.

At a minimum, set the URL of your Grafana instance and the organization ID:

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

Depending on your authentication method, you may also need to set:

A token for a Grafana service account (recommended)
A username and password for basic authentication

To persist your configuration, consider creating a context.

Use configuration contexts

Contexts allow you to easily switch between multiple Grafana instances.

By default, the CLI uses a context named default. To configure it use:

grafanactl config set contexts.default.grafana.server http://localhost:3000
grafanactl config set contexts.default.grafana.org-id 1

Authenticate with a service account token:

grafanactl config set contexts.default.grafana.token service-account-token

Or use basic authentication:

grafanactl config set contexts.default.grafana.user admin
grafanactl config set contexts.default.grafana.password admin

You can define additional contexts in the same way:

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

Note
In these examples, default and staging are the names of the contexts.

Configure Grafana CLI with configuration files

Grafana CLI stores its configuration in a YAML file. The CLI determines the configuration file location in the following order:

If the --config flag is provided, the specified file is used.
If $XDG_CONFIG_HOME is set: $XDG_CONFIG_HOME/grafanactl/config.yaml
If $HOME is set: $HOME/.config/grafanactl/config.yaml
If $XDG_CONFIG_DIRS is set: $XDG_CONFIG_DIRS/grafanactl/config.yaml

Note
Use grafanactl config check to display the configuration file currently in use.

Useful commands

Check the current configuration:

grafanactl config check

Note
This command is useful to troubleshoot your configuration.

List all available contexts:

grafanactl config list-contexts

Switch to a specific context:

grafanactl config use-context staging

View the full configuration:

grafanactl config view

Introduction to the Grafana CLI on Grafana Labs

gcx CLI

Overview of the gcx CLI

Benefits of gcx

Compatibility

Migrate from grafanactl

Learn more

Install and set up the grafanactl CLI

Install and set up the grafanactl CLI

Install the Grafana CLI grafanactl

1. Download a pre-built binary

2. Build from source

Configure grafanactl

Configure Grafana CLI with environment variables

Use configuration contexts

Configure Grafana CLI with configuration files

Useful commands

Overview of the `gcx` CLI

Benefits of `gcx`

Migrate from `grafanactl`

Install and set up the `grafanactl` CLI

Install the Grafana CLI `grafanactl`

Configure `grafanactl`