/setup-gcx

name: setup-gcx
description: >-
  Installs and configures gcx: contexts, authentication, connection to Grafana
  Cloud or on-premise Grafana, env var overrides for CI/CD, default datasources.
  Use for first-time setup, or when gcx fails with auth or connection errors
  (401, 403, connection refused, missing namespace).

Setup gcx

Three configuration paths: Grafana Cloud (Path A), on-premise (Path B), and environment variables for CI/CD (Path C). For the complete config reference (all `config set` paths, TLS options, namespace resolution rules, multi-context patterns), see [configuration.md](references/configuration.md).

Step 0: Install gcx

First, check whether gcx is already installed:

gcx --version

If the command is not found, build it from source. Requires [git](https://git-scm.com/) and a recent [Go](https://go.dev/) toolchain:

tmp=$(mktemp -d) && git clone --depth 1 https://github.com/grafana/gcx.git "$tmp" && (cd "$tmp" && go install ./cmd/gcx) && rm -rf "$tmp"

After installing, verify the binary is on PATH:

gcx --version

Configuration Model

gcx uses a context-based configuration model inspired by kubectl's kubeconfig. One or more layered YAML files (with the user file at `~/.config/gcx/config.yaml` by default) store named `stacks` (Grafana destination, credentials, provider config), named `cloud` entries (Grafana Cloud platform credentials and endpoints), and thin `contexts` that reference a stack and optional Cloud entry. One context is selected at a time; all commands operate against it unless overridden. Single-source legacy configs are migrated automatically after a safe preflight. When several layers participate, gcx converts them in memory and asks the user to migrate each layer explicitly rather than partially persisting the result.

Use `gcx config view` to inspect the current configuration at any time. Use `gcx config check` to validate that the active context is correct and can reach the server.

---

Path A: Grafana Cloud

Use this path when connecting to a Grafana Cloud instance (URLs ending in `.grafana.net`).

**No Grafana Cloud account yet?** Skip Steps 1 to 4 and run:

gcx signup cloud

It opens the Grafana Cloud sign-up page (in agent mode it prints the URL for the user to open). The user creates the account, verifies their email, creates a first stack, and approves "Connect gcx"; gcx then saves the connection to the `cloud` context and makes it current. A browser already signed in to Grafana Cloud skips sign-up and asks for one of that account's stacks, or goes straight to "Connect gcx" with one organization and one stack; the user then approves as usual. To create a separate account instead, the user signs out of Grafana Cloud in that browser first. Signup asks no questions, and it only saves a new connection, so it refuses a context or stack entry that already exists: do not run Step 1 first. If it fails once the browser step has started, run the `gcx login` command the error shows, not `gcx signup` again, which could start a second account. It saves no Grafana Cloud management credentials; for Cloud product APIs (SLOs, Synthetic Monitoring, k6), add a Cloud Access Policy token afterwards with `gcx cloud login --context cloud --cloud-token <token>`.

Step 1: Create a stack and context

gcx config set stacks.cloud.grafana.server https://myorg.grafana.net
gcx config set contexts.cloud.stack cloud

Replace `cloud` with any name you prefer (e.g., `prod`, `myorg-cloud`). Replace the server URL with your Grafana Cloud URL. The first command creates the stack entry; the second creates a context pointing at it.

Step 2: Authenticate

**Option A-1: Browser OAuth (recommended for Grafana Cloud)**

gcx login cloud --server https://myorg.grafana.net --oauth

Opens a browser for the user to approve. This works non-interactively and in agent mode — the agent issues the command, the browser opens, and the user approves. No token to create or paste. `gcx login` also sets the context as current and verifies connectivity, so Steps 1, 3, and 4 are handled for you; skip them when using this option.

**Option A-2: Service account token**

gcx config set stacks.cloud.grafana.token glsa_XXXXXXXXXXXXXXXX

Obtain a service account token from **Administration > Service accounts** in your Grafana Cloud instance. The token must have sufficient permissions for the operations you intend to run (Viewer for read-only, Editor or Admin for write operations).

The `grafana.token` field takes precedence over `grafana.user`/`grafana.password` when both are present.

Grafana Cloud product APIs use a separate credential. A Cloud Access Policy token has the widest compatibility and can be supplied during unified login:

gcx login cloud --server https://myorg.grafana.net \
  --token glsa_XXXXXXXXXXXXXXXX --cloud-token glc_XXXXXXXXXXXXXXXX --yes

For interactive use, the Cloud step of `gcx login` can keep an existing CAP or unexpired OAuth credential, accept a CAP, run the experimental direct Cloud OAuth flow, or skip. `gcx cloud login --context cloud` runs direct Cloud OAuth separately. OAuth retains expiry, granted scopes, and its coherent OAuth/API endpoint pair, but not every Cloud product command supports it yet; use a CAP for full compatibility.

Step 3: Switch to the context

gcx config use-context cloud

Step 4: Verify the connection

gcx config check

A successful check prints the active context name and server URL without errors. For Grafana Cloud, the stack ID (namespace) is auto-discovered from the server's `/bootdata` endpoint -- you do not need to set `grafana.stack-id` manually unless auto-discovery fails.

If the discovered stack ID conflicts with a manually configured `grafana.stack-id`, gcx raises a validation error - see [Namespace resolution issues](#namespace-resolution-issues).

---

Path B: On-Premise Grafana

Use