Grafana

Installs gcx (the Grafana CLI) and configures shell aliases and per-shell account selection.

What it does

• Auto-installs and updates gcx to the latest GitHub release (checksum-verified release tarball on Linux, Homebrew on macOS)
• Registers gcx in ~/.versions.d/ so versions reports its version
• Keeps Grafana account selection per-shell (GCX_CONFIG) so terminals never collide, see Per-shell isolation
• Installs bash completion generated by gcx completion bash, plus tab completion for the account functions
• Shell aliases for day-to-day checks: connectivity, dashboards, datasources, firing alert rules

gcx talks to Grafana Cloud and to self-hosted Grafana 12 or later (13 for full support); against an older Grafana it exits with code 6. It replaces grafanactl, which Grafana deprecated, and grafanactl commands carry over by swapping the binary name (grafanactl resources pull becomes gcx resources pull).

Variables

Variable	Default	Description
grafana_gcx_version	latest	Pin gcx to an exact version, or track the newest release
grafana_aliases	See defaults	Shell aliases to generate
grafana_functions	See defaults	Shell functions to generate
grafana_completions	See defaults	Completion wiring for the functions

grafana_gcx_version: "1.5.0" # latest

Aliases

Alias	Command	Description
grafana	gcx-account	Show / switch the Grafana account
grafana-check	gcx config check	Validate every context in the account: config, auth, connectivity, Grafana version
grafana-dashboards	gcx dashboards list	List dashboards
grafana-datasources	gcx datasources list	List datasources
grafana-firing	gcx alert rules list --state firing	List alert rules that are firing

Functions

Function	Description
gcx-authenticate	Create or select an account and run gcx login into it in one step
gcx-account	Show the current account, or switch to a named one

Authentication

The role installs the binary but leaves you signed out, so nothing writes credentials during an apply. gcx-authenticate <name> creates the account file, runs gcx login <name> against it, and passes any extra flags through:

gcx-authenticate company --server https://company.grafana.net                              # Grafana Cloud, browser OAuth
gcx-authenticate local --server http://localhost:3000 --token glsa_xxx                     # self-hosted, service account token
gcx-authenticate company --server https://company.grafana.net --cloud-token glc_xxx        # add Grafana Cloud product APIs (SLO, IRM, k6)

On a Grafana Cloud stack, gcx login offers browser OAuth, which acts with your own Grafana permissions. A service account token works on Cloud and self-hosted alike: give the service account Viewer to query and read dashboards, Editor to push dashboards and folders, and Admin to manage datasources.

For CI and other non-interactive hosts, skip the login and set the connection in the environment; gcx reads it on every command:

export GRAFANA_SERVER=https://company.grafana.net
export GRAFANA_TOKEN=glsa_xxx

Per-shell isolation

gcx keeps its contexts the way kubectl does: one shared config file with a current-context key. A gcx config use-context in one terminal moves every other terminal with it, and gcx reads no environment variable that picks a context. gcx-account <name> exports GCX_CONFIG=~/.config/gcx/accounts/<name>.yaml instead, so the selection belongs to the current shell. Picking an account in one terminal can't change which Grafana another terminal acts on, and that includes a coding agent like Claude Code running its own shell. Run gcx-account with no argument to show the current account, context, and server, and to list the accounts you have.

An account file can hold more than one context, for example a production and a staging stack under one login. gcx --context staging <command> targets one of them for a single command without touching the file.

The starship prompt reads the same GCX_CONFIG and shows the account ( <account>), so each shell visibly shows the Grafana it is on. This is the per-shell context isolation concept applied to Grafana.

Troubleshooting

Keychain unavailable on WSL and headless hosts

gcx stores tokens in the OS credential store (Secret Service on Linux) and never falls back to plaintext on its own. On WSL, in containers, and on headless hosts, gcx login stops with Error: Keychain unavailable. Allow plaintext storage before you authenticate, and keep the variable set in your own dotfiles, since a later login or OAuth token refresh writes the credential again:

export GCX_KEYCHAIN=off
gcx-authenticate local --server http://localhost:3000 --token glsa_xxx

The token then sits in the account file, which gcx writes with mode 0600. Setting credentials.keychain: off in ~/.config/gcx/config.yaml has no effect while an account is selected, because GCX_CONFIG makes gcx read the account file only.

A repository's .gcx.yaml is ignored

gcx normally layers a system config, ~/.config/gcx/config.yaml, and a .gcx.yaml in the working directory. GCX_CONFIG turns that layering off, so in a shell with an account selected gcx reads the account file alone. Point gcx at the repository file explicitly when you need it:

gcx --config .gcx.yaml resources push --path ./resources