gcx CLI on Grafana Labs

Introduction to gcx

Thu, 30 Jul 2026 16:41:53 +0000

Overview of the `gcx` CLI

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.

gcx is under continuous development. Contact Grafana for support or to report any issues you encounter and help us improve this feature.

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.

Costs

Note
gcx itself is free, but some commands operate Grafana Cloud products that are billed based on usage.

For example:

Grafana Assistant is charged per token consumed, including requests made through gcx.
Synthetic Monitoring is billed per test execution.
Performance Testing (k6) is charged per Virtual User Hour.
IRM is billed per monthly active user.

For details, refer to the Cost Management and Billing documentation and Grafana Cloud pricing.

Compatibility

The following applies:

gcx is available for Grafana Cloud and Grafana OSS/Enterprise v12 or later. Older Grafana versions are not supported.
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, 14 Aug 2026 09:32:53 +0000

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.

Upgrade

To upgrade, run the same command again. The script always installs the latest release.

Check the result:

gcx --version

If the version does not change, refer to The version does not change after an upgrade.

Installer configuration options

Use these environment variables to customize the install script:

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

The script also accepts INSTALL_DIR and VERSION. The GCX_ names take precedence. Prefer the GCX_ names, because INSTALL_DIR and VERSION are common names, and curl | sh inherits every variable that your shell exports.

Examples

Install a specific version:

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

Install to /usr/local/bin:

curl -fsSL https://raw.githubusercontent.com/grafana/gcx/main/scripts/install.sh | GCX_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 gcx

This command installs the gcx formula from homebrew-core. Homebrew has a prebuilt bottle for macOS and Linux, so the install takes seconds. You do not need to add a tap.

To upgrade an existing installation:

brew upgrade gcx

Install from the Grafana tap

The Grafana tap also carries gcx. Use the tap if you want Homebrew to compile the binary on your machine:

brew install grafana/grafana/gcx

Homebrew installs go as a build dependency for this formula. The first install usually takes 30 to 60 seconds, and later upgrades reuse the Homebrew download cache.

Install gcx from one source only. Two Homebrew formulas with the same name conflict with each other.

Homebrew and macOS Gatekeeper

Both Homebrew methods avoid the macOS Gatekeeper problem. Homebrew does not set the quarantine attribute on the files that it installs, so you do not 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

The version does not change after an upgrade

This page lists several install methods, and they write gcx to different directories. If you use two methods, you get two copies. Your shell runs the copy in the directory that comes first in PATH, and an upgrade of the other copy changes nothing that you can see.

List every copy:

which -a gcx

The first line is the copy that your shell runs. Remove the copies that you do not want:

Path	Install method	Command that removes it
`~/.local/bin/gcx`	Install script	`rm ~/.local/bin/gcx`
`/usr/local/bin/gcx`	Prebuilt binary, or the script with `GCX_INSTALL_DIR`	`sudo rm /usr/local/bin/gcx`
`/opt/homebrew/bin/gcx`, `/home/linuxbrew/.../gcx`	Homebrew	`brew uninstall gcx`
`~/go/bin/gcx`	`go install`	`rm ~/go/bin/gcx`

After you remove a copy, your shell can still hold the old path in its command hash table. Open a new terminal, or run:

hash -r

The install script reports this problem for you. It names both paths and both versions, and it gives the removal command.

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. Homebrew does not set the xattr on the files that it installs.

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, 14 Aug 2026 15:24:45 +0000

Configure `gcx`

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

A configuration file stores named stacks, named Grafana Cloud credentials, and contexts that bind them. gcx can layer system, user, and repository files. Check the configuration file reference documentation for all options. If you have a file from an older gcx version, refer to Migrate your gcx configuration.
Environment variables override the selected context in memory, so they work best in CI environments and are never persisted implicitly. Refer to Configure gcx with environment variables for more information.

Choose an authentication method

gcx supports four ways to authenticate to a Grafana instance:

OAuth (Grafana Cloud only): Browser-based sign-in with gcx login. Recommended for interactive use. The tokens are user-scoped: every request runs with your own identity and RBAC permissions, so you can’t access anything through gcx that you can’t already access in the Grafana UI. Refer to Required role for OAuth sign-in for the permission this flow needs.
Service account token: Works for Grafana Cloud and on-premises instances, and is the recommended method for CI and other non-interactive environments. Refer to Grafana service accounts for how to create one.
Basic authentication: Username and password. Use this only when service accounts aren’t available.
mTLS: A client certificate and key for instances behind an identity-aware proxy. Configure the grafana.tls fields or corresponding TLS environment variables.

Grafana Cloud platform APIs use a separate credential stored in a named Cloud entry. A Cloud Access Policy token has full command compatibility and is recommended for automation. Direct Cloud OAuth is available through gcx cloud login or the interactive Cloud step of gcx login, but remains experimental and is not yet accepted by every Cloud product command. OAuth entries retain expiry, granted scopes, and a coherent OAuth/API endpoint pair.

To authorize a gcx CLI connection with OAuth, your Grafana user needs the grafana-assistant-app.tokens.gcx:access permission. The gcx User role, registered by the Grafana Assistant application, grants this permission and is assigned automatically to users with the basic role Viewer or higher.

This permission only lets you create gcx tokens for your own user. It doesn’t grant access to other users’ tokens and it doesn’t extend your existing Grafana permissions.

Note
If gcx login fails with a Permission Required error naming the gcx User role, ask your Grafana administrator to assign you the gcx User role, or a custom role that includes the grafana-assistant-app.tokens.gcx:access permission. If the role doesn’t exist on your instance, the Grafana Assistant application needs to be updated to a version that includes it.

Understand the `gcx` configuration file in use

Run gcx config path to display the configuration files currently in use.

gcx stores configuration in YAML. --config <path> or GCX_CONFIG=<path> selects one explicit file and bypasses layering. Otherwise, gcx loads every existing source in this order, with later sources taking precedence:

System: the platform system config directory (for example, $XDG_CONFIG_DIRS/gcx/config.yaml).
User: $HOME/.config/gcx/config.yaml, falling back to the platform user config directory such as $XDG_CONFIG_HOME/gcx/config.yaml.
Repository: .gcx.yaml in the current working directory.

Named stacks and cloud entries are atomic across sources: a higher-priority same-named entry replaces the lower entry completely. This keeps a credential and its server or Cloud endpoint in the same trust source. Context references and datasource defaults may merge field-by-field.

Credentials in the OS credential store (Keychain on macOS, Credential Manager on Windows, Secret Service on Linux) are tied to the canonical config file, exact owner kind and name, exact secret field, and normalized destination. Copying a config file does not make its stored credentials portable; authenticate the copied file separately.

An automatically discovered repository .gcx.yaml cannot attach tokens, passwords, or client-certificate files from your environment, login flags, or prompts to destinations the file supplies. It also cannot implicitly combine a Cloud credential with a direct provider endpoint or write derived provider credentials and caches. A provider endpoint supplied at runtime is accepted only with its matching runtime credential, and neither value authorizes TLS or proxy settings from an auto-discovered repository stack. To trust the repository config for those operations, select it explicitly:

gcx login --config .gcx.yaml
# or
GCX_CONFIG=.gcx.yaml gcx login

Credentials already owned by that exact file remain usable while their bound destination is unchanged.

Literal edits to a named stack or Cloud entry affect every context that references it. If an edit changes a credential destination - such as a Grafana server, Synthetic Monitoring URL, or Cloud API/OAuth endpoint - gcx clears the old credential in the same write. Supply a fresh credential before using the new destination. Normalization-equivalent endpoint edits preserve it.

Define contexts

gcx supports multiple contexts so you can switch between instances. A context references a named stack entry, which holds the Grafana connection details. By default, gcx uses the default context.

A stack entry holds one credential alongside its server. To use two identities against the same stack - for example a personal token and a CI token, or read-only and admin - define two stack entries and a context for each.

To configure the default context:

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

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

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

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

To create another context, use the same pattern:

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

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

Useful commands

Use these commands to check the configuration:

gcx config check

Without --context, the check covers every configured context before returning. It exits non-zero when the current context is invalid or any checked context fails configuration, authentication setup, connectivity, or Grafana version checks, so it is safe to use as a deployment gate.

To check only one context without validating unrelated entries, pass --context:

gcx config check --context staging

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.

Migrate your gcx configuration

Fri, 14 Aug 2026 15:24:45 +0000

Migrate your `gcx` configuration files to v1 format

gcx is adjusting its configuration file format to make it easier to reuse credentials across contexts. This applies for gcx versions v0.6.0 and later. The v1 format splits the file into three sections: stacks for Grafana connections, cloud for Grafana Cloud credentials that multiple contexts can reference, and contexts that reference both by name.

How migration works

gcx attempts to migrate any legacy configuration file automatically the first time it loads it. If gcx prints a warning or error that linked here, your migration paused or stopped for one of a small set of reasons. Find the message you saw in Why a migration paused or stopped and follow the steps.

Refer to the table of field mappings at the end of this document to see how to convert a config file manually.

Migration doesn’t delete any information

Whatever state your migration is in, nothing has been lost:

A paused or stopped migration changes nothing: no file, no backup, no credential store entry. gcx keeps working from an in-memory conversion where it safely can.
A completed migration replaces the file only after checking the converted result means the same as the original, and keeps the original next to it as <file>.legacy.bak. gcx never overwrites or deletes that backup.
Credentials in the OS credential store (Keychain on macOS, Credential Manager on Windows, Secret Service on Linux) are copied into new entries; the old entries stay, so the backup remains fully usable.

Roll back a completed migration

To roll back a completed migration, copy the backup over the configuration file:

cp ~/.config/gcx/config.yaml.legacy.bak ~/.config/gcx/config.yaml

Caution
If your legacy file contained plaintext credentials, they remain in <file>.legacy.bak even after migration moves them into the OS credential store. Remove the backup yourself once you’re sure you won’t roll back.

Why a migration paused or stopped

Here are the reasons the config migration might have aborted, with an explanation of how to fix it:

“layered configuration migration is incomplete”: your configuration is spread across several files (system, user, or a repository .gcx.yaml). gcx converts them in memory so commands keep working, but never rewrites several files for you, to avoid a state where some config files were migrated, but others were not. To remedy this, follow How to migrate layered files.

“cannot safely auto-migrate layered legacy configuration” or “the overlapping entries require manual consolidation”: two of your files define overlapping pieces of the same entry, which the v1 merge rules would combine differently than the legacy rules did. To remedy this, follow How to consolidate overlapping layers.

“running with in-memory config migration … reason: a legacy credential could not be read from the credential store”: the credential store was locked, an unlock prompt was dismissed, or gcx ran in a session without credential store access (SSH, CI). Persisting the migration then could strand references to credentials it couldn’t re-store, so gcx waits. Unlock your credential store (or run from a desktop session) and run any gcx command; the migration completes on its own.

“running with in-memory config migration” with a permission-related reason: the configuration file or its directory isn’t writable. Read-only config commands keep working from the in-memory config, but anything that writes configuration or credentials fails until the file is writable or replaced with a v1 file. To remedy this, either fix the permissions and run any gcx command, or for CI type environments, update the config file to use the v1 format. (see the field mapping).

“existing legacy config backup does not match the current source”: a previous migration left a .legacy.bak and the file has since been rewritten in the legacy format (for example by an older gcx version). gcx won’t overwrite the earlier backup. To fix this, compare the two files, keep the one you trust and run any gcx command.

“unsupported config version”: the file isn’t in the legacy format, and gcx doesn’t recognize it. Upgrade gcx to support a more modern format (this is more for futureproofing - there is only v1 at the moment).

“config migration self-check failed”: gcx converted the file, checked the result against the original, and found a difference, so it left the file untouched. This indicates a bug, report it with the error text, and migrate by hand in the meantime.

How to migrate layered files

The migration warning lists each remaining legacy file that needs migrating. Migrate the config files one at a time - each command rewrites just that file in the v1 format and leaves a .legacy.bak backup next to it. For example:

gcx config set --file user version 1
gcx config set --file local version 1

After each step, gcx re-prints the commands for whatever legacy files still need migrating, and refuses any per-file conversion that could replace a complete entry with a partial one. When it can’t offer a safe command it tells you to edit the file instead. To inspect any file without loading it, run gcx config edit <system|user|local>.

Be aware that editing the system config file edits the config for all users on your system.

When all files are migrated, the warning will disappear. To confirm everything is ok, refer to Verify the result.

How to consolidate overlapping layers

Legacy gcx merged contexts with the same name, but from different files, field by field. v1 doesn’t: a stack or Cloud entry in a higher-priority file completely replaces a same-named entry in a lower one. This is so one file can never mix its server with another file’s credentials. Files that relied on partial overrides need consolidating once, manually:

The error will name the entries that overlap. Open each file with gcx config edit <system|user|local>.
Move the overriding fields into the file that owns the complete entry, or rename the overriding entry (for example, give a repository-specific context its own stack name) so nothing overlaps.
Run any gcx command. The preflight re-checks; once nothing overlaps you are directed to Migrate layered files.

Map a legacy configuration to version 1

To convert a file by hand: copy the original somewhere safe, move each field to its new home using the table, add version: 1 at the top, and verify. Here is a map from the old field locations to the new ones:

Legacy (per context)	Version 1
`contexts.<name>.grafana.*`	`stacks.<name>.grafana.*`, plus `contexts.<name>.stack: <name>`
`contexts.<name>.cloud.token`	`cloud.<entry>.token`, plus `contexts.<name>.cloud: <entry>`
`contexts.<name>.cloud.api-url`	`cloud.<entry>.api-url`
`contexts.<name>.cloud.oauth-url`	`cloud.<entry>.oauth-url`
`contexts.<name>.cloud.stack`	`stacks.<name>.slug`
`contexts.<name>.providers.*`	`stacks.<name>.providers.*`
`contexts.<name>.resources.*`	`stacks.<name>.resources.*`, or top-level `resources:` to apply to all stacks
`contexts.<name>.default-prometheus-datasource`	`contexts.<name>.datasources.prometheus`
`contexts.<name>.default-loki-datasource`	`contexts.<name>.datasources.loki`
`contexts.<name>.default-tempo-datasource`	`contexts.<name>.datasources.tempo`
`contexts.<name>.default-pyroscope-datasource`	`contexts.<name>.datasources.pyroscope`
`contexts.<name>.datasources.*`	unchanged
`current-context`, `diagnostics`	unchanged

You can name the cloud entries whatever you like, since contexts refer to them by name. You can reuse cloud configs in multiple contexts.

If your legacy cloud.token came from the experimental OAuth sign-in rather than an access policy, it still migrates into token - the legacy format can’t tell the two apart. The next gcx cloud login stores it in the entry’s oauth-token field.

Example of a legacy configuration update

A legacy configuration:

contexts:
  prod:
    grafana:
      server: https://myorg.grafana.net
      token: "<service account token>"
    cloud:
      token: "<cloud access policy token>"
      stack: myorg
    default-prometheus-datasource: my-prom
  dev:
    grafana:
      server: https://myorg-dev.grafana.net
      token: "<service account token>"
    cloud:
      token: "<cloud access policy token>"   # same token as prod
current-context: prod

becomes:

version: 1
stacks:
  prod:
    slug: myorg
    grafana:
      server: https://myorg.grafana.net
      token: "<service account token>"
  dev:
    grafana:
      server: https://myorg-dev.grafana.net
      token: "<service account token>"
cloud:
  grafana-com:
    token: "<cloud access policy token>"     # shared by both contexts
contexts:
  prod:
    stack: prod
    cloud: grafana-com
    datasources:
      prometheus: my-prom
  dev:
    stack: dev
    cloud: grafana-com
current-context: prod

Credential references

If your legacy file contains values like keychain:gcx:prod:cloud-token, they are references to secrets in the OS credential store. Let the migration move them rather than copying the strings yourself.

gcx only resolves legacy credential references from files you chose and own, such as your standard user config file (a symlinked home or XDG path still counts), or one you selected explicitly with --config or GCX_CONFIG, and only when the file is writable by you alone. A reference must also sit where it claims to belong: the context and field named inside it have to match its location in the file. Files discovered from repositories or system directories are never trusted.

If a repository config contains credential references, select it explicitly with --config (only if you trust it), or replace the references with fresh credentials before migrating. Copying a legacy reference into a version 1 file never grants access to the secret.

Version 1 credential references are tied to the config file’s path, the exact stack or Cloud entry and field they belong to, and the credential’s destination. Copying a version 1 config to a different path copies its structure but not access to its credentials - run gcx login or gcx cloud login for the copied file instead of copying reference strings by hand.

Verify the result

After migrating, confirm the configuration parses and every context connects:

gcx config view
gcx config check

Where:

gcx config view shows the effective configuration with secrets redacted.
gcx config check validates every context, including connectivity, and exits non-zero if any check fails. Pass --context <name> to validate only that context.

Usage statistics

Thu, 30 Jul 2026 16:41:53 +0000

Understand gcx usage statistics

gcx reports limited usage statistics about itself to Grafana Labs. This data is used to understand which commands and flags are used most, where commands fail, and which commands people try that don’t exist, so we can make the product better.

The statistics describe only the shape of usage, including command path, and flag names. Positional argument values and flag values are never sent. Some server-side enrichment is also performed on the usage statistics exported - see Server-side enrichment for details.

Note
Usage statistics reporting is enabled by default. See the Opt out section below for guidance on how to turn off usage reporting.

Telemetry data and identifiers

The only identifier is a device_id field: a randomly generated UUID created on first use and stored at $XDG_STATE_HOME/gcx/device-id. It identifies an installation of gcx, not a person. It’s random, not derived from your hardware or account.

Understand which data is collected

Each gcx event contains the following properties:

Field	Description	Example
`service`	Always `gcx`, identifying the reporting product.	`gcx`
`version`	The version of `gcx`.	`0.4.1`
`os`	Operating system.	`linux`, `darwin`, `windows`
`arch`	CPU architecture.	`amd64`, `arm64`
`device_id`	The random per-installation ID described in Telemetry data and identifiers.	UUID
`device_id_persisted`	Whether the device ID was read from or saved to disk. `false` means a throwaway ID was used for this invocation.	`true`
`command`	The resolved command path only, no arguments are sent.	`dashboards push`
`flags`	The names of the flags you set, sorted. No flag values are sent.	`dry-run,folder`
`provider`	The resource provider the command belongs to.	`dashboards`
`outcome`	How the invocation ended: `ok`, `runtime_error`, `parse_error`, or `help`.	`ok`
`exit_code`	The process exit code.	`0`
`error_kind`	A coarse error category when the command failed: `usage_error`, `auth_failure`, `partial_failure`, `version_incompatible`, or `error`. Never an error message.	`auth_failure`
`duration_ms`	Total invocation duration in milliseconds.	`1234`
`is_tty`	Whether `gcx` ran attached to an interactive terminal.	`false`
`is_ci`	Whether a CI environment was detected.	`true`
`ci_provider`	Which CI system was detected, from a fixed list of known names. `gcx` reads well-known CI environment variables to detect the provider but never sends their values.	`github_actions`
`is_agent`	Whether an AI coding agent drove the invocation.	`true`
`agent`	The name of the agent harness, if one was detected.	`claude-code`
`target_kind`	Whether the target Grafana is `cloud` or `self-hosted`. Empty when no effective Grafana target could be resolved. Deliberately coarse — never the URL, hostname, or stack slug.	`cloud`
`output_format`	The output format the command used.	`table`, `json`

When the invocation fails to parse, these additional fields are set. They capture what was attempted so the team can understand the differences between what users expect and what exists:

Field	Description	Example
`parse_error_kind`	The kind of parse failure: `unknown_command`, `unknown_flag`, or `invalid_args`.	`unknown_command`
`parse_error_parent`	The deepest valid command reached before the failure.	`dashboards`
`parse_error_token`	The first unknown toke. It’s only sent if it looks like a command name (short, lowercase, no digits, not a URL, IP address, or UUID); otherwise it’s replaced with `<redacted>`.	`serch`
`attempted_command`	The parent command plus the unknown token, truncated at the unknown token so no later arguments are included.	`dashboards serch`
`parse_error_flags`	The names of unknown flags. No flag values are sent.	`verbsoe`
`parse_error_nearest`	The nearest real command or flag name, if one is close.	`search`
`parse_error_distance`	The edit distance to the nearest real name, or `-1` if there is no near match.	`2`

Invocations that report nothing

Some invocations never emit an event:

Shell completion — the completion machinery runs on every tab-press and carries no usage signal.
gcx version
Cancelled invocations — pressing Ctrl-C emits nothing.

Server-side enrichment

Reports are received by Grafana’s usage-stats service, the same service that receives usage reports from Grafana, Loki, Tempo, and Mimir. On receipt, the service adds two pieces of information derived from the connection:

A coarse geographic region (for example, a country or subdivision), taken from headers added by the CDN edge.
The network organization name from a whois lookup of the connecting IP address. For CLI traffic this typically resolves to your ISP or employer’s network.

The connecting IP address is not stored in the usage event.

Inspect what would be sent

To see exactly what gcx would report for an invocation, set GCX_TELEMETRY=log. The event is printed to stderr and nothing is sent:

GCX_TELEMETRY=log gcx dashboards list

Opt out

You can control usage statistics reporting three ways:

GCX_TELEMETRY environment variable: Set to enabled, disabled, or log. Takes precedence over everything else:

export GCX_TELEMETRY=disabled

DO_NOT_TRACK environment variable: Set to 1 or true to disable reporting, following the cross-tool DO_NOT_TRACK convention. Overridden by GCX_TELEMETRY.
Configuration file: Add a top-level diagnostics block to your gcx configuration file, with telemetry set to enabled, disabled, or log:

diagnostics:
  telemetry: disabled

Opting out disables reporting entirely. No event is constructed and nothing is sent.

gcx CLI on Grafana Labs

Introduction to gcx

Overview of the gcx CLI

Benefits of gcx

Costs

Compatibility

Migrate from grafanactl

Learn more

Install gcx

Install gcx

Quick install using the script

Upgrade

Installer configuration options

Examples

Uninstall

Install gcx with Homebrew (macOS and Linux)

Install from the Grafana tap

Homebrew and macOS Gatekeeper

Install a prebuilt binary

Install gcx from source

The version does not change after an upgrade

macOS Gatekeeper and killed 9

Bypass the macOS gatekeeper

Configure gcx

Configure gcx

Choose an authentication method

Required role for OAuth sign-in

Understand the gcx configuration file in use

Define contexts

Useful commands

Configure gcx with environment variables

Migrate your gcx configuration

Migrate your gcx configuration files to v1 format

How migration works

Migration doesn’t delete any information

Roll back a completed migration

Why a migration paused or stopped

How to migrate layered files

How to consolidate overlapping layers

Map a legacy configuration to version 1

Example of a legacy configuration update

Credential references

Verify the result

Usage statistics

Understand gcx usage statistics

Telemetry data and identifiers

Understand which data is collected

Invocations that report nothing

Server-side enrichment

Inspect what would be sent

Opt out

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

Migrate your `gcx` configuration files to v1 format