/setup-gcx

name: setup-gcx
description: >
  Sets up gcx: installation, context creation, authentication, and connection
  to a Grafana instance. Covers Grafana Cloud and on-premise deployments,
  environment variable overrides for CI/CD, default datasource configuration,
  and troubleshooting connection and authentication problems. Use when
  installing gcx, connecting gcx to a Grafana instance for the first time, or
  when gcx commands fail with auth or connectivity 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`).

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 this path when connecting to a self-hosted Grafana instance.

Step 1: Create a stack and context

gcx config set stacks.onprem.grafana.server https://grafana.example.com
gcx config set contexts.onprem.stack onprem

Replace `onprem` with a name that identifies this environment (e.g., `production`, `staging`, `local`).

Step 2: Set authentication

**Option B-1: API token (recommended)**

gcx config set stacks.onprem.grafana.token glsa_XXXXXXXXXXXXXXXX

**Option B-2: Username and password**

gcx config set stacks.onprem.grafana.user admin
gcx config set stacks.onprem.grafana.password mysecretpassword

Use Option B-1 when service accounts are available. Use Option B-2 for development or when service accounts are not configured.

Step 3: Set the org ID

On-premise Grafana uses an org ID to identify the namespace for API calls. Set it to the numeric ID of the organization (default org is 1):

gcx config set stacks.onpr