setup-gcx

Configure gcx CLI contexts, authentication, and connections to Grafana Cloud or on-premise instances.

1|Updated May 25, 2020
One-click install
npx skills add https://github.com/titaneric/dotfiles --skill setup-gcx-titaneric
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: setup-gcx
Source: https://github.com/titaneric/dotfiles/tree/main/dot_agents/skills/setup-gcx
Command: npx skills add https://github.com/titaneric/dotfiles --skill setup-gcx-titaneric

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve? Setting up the gcx CLI to talk to a Grafana instance involves context configuration, authentication choices, namespace resolution, and datasource defaults, and mistakes in any of these cause confusing connection or authorization errors. This Skill walks an agent through the complete first-time setup and diagnoses common failures. ## Core Features & Use Cases - Three Configuration Paths: Covers Grafana Cloud (browser OAuth or service account token), on-premise Grafana (token or basic auth with org ID and TLS options), and environment-variable overrides for CI/CD pipelines. - Context and Datasource Management: Creates and switches kubectl-style contexts, sets default Prometheus and Loki datasource UIDs, and verifies connectivity with gcx config check. - Troubleshooting Guidance: Resolves 401/403 errors, connection timeouts, TLS issues, and namespace resolution problems such as mismatched stack IDs. - Use Case: A platform engineer needs gcx working in a GitHub Actions pipeline against Grafana Cloud. The Skill provides the exact GRAFANA_SERVER/GRAFANA_TOKEN environment variable setup and a working workflow snippet. ## Quick Start Ask the agent to set up gcx for your Grafana instance by providing your server URL and whether it is Grafana Cloud or on-premise.

Frequently Asked Questions about setup-gcx

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I set up gcx for Grafana Cloud?

Set the context server to your .grafana.net URL, then either run gcx login with --oauth for browser-based auth or set a service account token with gcx config set. The stack ID namespace is auto-discovered from the /bootdata endpoint, and gcx config check verifies the connection.

How do I configure gcx for on-premise Grafana?

Create a context with your server URL, set a service account token or username and password, and set grafana.org-id to your numeric organization ID (usually 1). Switch to the context with gcx config use-context and verify with gcx config check.

Can I use gcx in CI/CD pipelines without a config file?

Yes, gcx supports environment variables such as GRAFANA_SERVER, GRAFANA_TOKEN, GRAFANA_USER, GRAFANA_PASSWORD, GRAFANA_ORG_ID, and GRAFANA_STACK_ID. These override the active context at runtime without modifying the config file on disk.

Why does gcx return a 401 Unauthorized error?

A 401 means the token or credentials are invalid or expired. Generate a fresh service account token in Grafana under Administration > Service accounts and update it with gcx config set contexts.<name>.grafana.token.

How do I fix a mismatched stack ID error in gcx?

This error occurs when a manually configured grafana.stack-id conflicts with the value auto-discovered from /bootdata. Remove the manual value with gcx config unset contexts.<name>.grafana.stack-id, or correct it to match the discovered ID.

How do I avoid passing a datasource UID on every gcx query?

List datasource UIDs with gcx datasources list -o json, then set defaults per context using gcx config set contexts.<name>.default-prometheus-datasource and default-loki-datasource. Query commands then use these UIDs automatically.