gcx is a command-line tool that lets people and AI coding agents manage and inspect Grafana Cloud, Enterprise, and open-source instances. It provides access to dashboards, alerts, SLOs, metrics, logs, and traces, with workflows for alert investigation, dashboard management, GitOps, and observability setup. Its catalogue entries provide agent instructions and extensions for using gcx.
Getting it into your agent
It runs from inside its repository, so the clone comes first — what it calls does not travel with the file alone.
git clone --depth 1 https://github.com/grafana/gcxnpx agentmods add skills/grafana/gcx/setup-gcxWrote this? Show the measurements
A badge with what this costs and how it scanned, read live from this page, so it follows the numbers instead of freezing them. Markdown for a README, HTML for a documentation site or a project page.
[](https://agentmods.dev/skills/grafana/gcx/setup-gcx)<a href="https://agentmods.dev/skills/grafana/gcx/setup-gcx"><img src="https://agentmods.dev/badge/skills/grafana/gcx/setup-gcx/github.svg" alt="Measured on agentmods" height="20"></a>Or the 80×15 button, for a site that already has a row of RSS and ATOM ones. Only the verdict fits; the numbers stay here.
<a href="https://agentmods.dev/skills/grafana/gcx/setup-gcx"><img src="https://agentmods.dev/badge/skills/grafana/gcx/setup-gcx.svg" alt="Reviewed on agentmods" width="80" height="20"></a>- NVIDIA SkillSpector warn
SkillSpector: 2 findings, up to high
These are SkillSpector’s own severities. On a checked sample its high-severity flags on skills were ~96% false positives — a documented command, a public API, a “never do X” rule — so we show them as a caution to read, not a verdict. Why →
- high Tool Misuse · line 32 Tool calls are chained to bypass individual safety checks or escalate capabilities beyond what any single tool call would allow.Fix: Limit tool chaining depth and validate the output of each tool before passing it to the next. Require explicit user approval for multi-step chains.
- high Privilege Escalation · line 44 Code accesses credential files (SSH keys, AWS credentials, etc.). This could indicate credential theft attempts.Fix: Remove references to credential paths. Use environment variables or secrets managers. For docs, use placeholder paths (e.g., /path/to/config). Never load .env or token files in production code paths.
What it costs to keep this loaded
Counted locally with the o200k_base tokenizer, which is exact for GPT models; Claude uses its own tokenizer and its counts differ. Treat this as one consistent yardstick across the catalogue rather than a bill. Prices are per million input tokens.
| Model | Per session | Once invoked |
|---|---|---|
| Fable 5.1 | $0.00067 | $0.03858 |
| Opus 5.5 | $0.00027 | $0.01543 |
| Sonnet 5.5 | $0.00013 | $0.00772 |
| Haiku 4.5 | $0.00007 | $0.00386 |
Grade C, and why
setup-gcx scanned grade C with 2 findings against 26 rules in 11 categories — prompt injection, anti-refusal, data exfiltration, privilege escalation, supply chain, agent snooping, system-prompt leakage, SSRF and excessive agency — measured 14d ago.
A static scan of the body, not an audit. Every finding is printed with the line that produced it so you can judge whether it matters here. A mod is markdown that instructs an agent; that is exactly why what it instructs is worth reading.
Recursive force deletehighDestructive command
rm -rf with a variable or a broad path is one typo away from removing the wrong tree.
tmp=$(mktemp -d) && git clone --depth 1 https://github.com/grafana/gcx.git "$tmp" && (cd "$tmp" && go install ./cmd/gcx) && rm -rf "$tmp" Makes network callslowCapability
Not a fault in itself. Listed so you know the mod talks to something, and to what.
curl -I https://grafana.example.com/api/health How it starts
The opening of the file, as written. The whole thing — 486 lines — stays where its author put it; the contents beside it link to each section on GitHub.
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.
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 and a recent Go 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>.
What ships with it
1 file beside SKILL.md in the same directory: the scripts, references and assets a skill reads on demand. Not counted in the per-session cost; read them before you install if any of them is executable.
What this file has done since we first saw it
Hashed on every crawl. A supply-chain change to an agent config is a question of when, not whether, so the history is kept rather than the latest state alone.
- 14d ago Changed · -3 lines · -27 tokens per session ce9d92273174
- 29d ago Changed · +21 lines c29e009b52a8
- 1mo ago Changed · +5 lines 457f955ee6ac
- 2mo ago First seen · 463 lines · 94 tokens per session scan C 777cc75938ec
setup-gcx is a skill published in the GitHub repository grafana/gcx (817 stars, last pushed today), licensed Apache-2.0. It adds 67 tokens to every session and 3,858 once invoked, about $0.0003 per session on Opus 5.5. A static security scan graded it C with 2 findings (recursive force delete, makes network calls). No closer match exists in the catalogue, so it is treated as the original; first seen 2026-08-30.
setup-gcx compared with skills from other repositories
| Mod | Type | Stars | Last push | Licence | Scan | Tokens | Works with |
|---|---|---|---|---|---|---|---|
| setup-gcxgrafana/gcx | Skill | 817 | today | Apache-2.0 | C | 67 | Claude Code |
| gke-compute-classesgoogle/skills | Skill | 22k | yesterday | Apache-2.0 | A | 83 | Claude Code, Codex |
| gke-workload-securitygoogle/skills | Skill | 22k | yesterday | Apache-2.0 | A | 171 | Claude Code, Codex |
| gke-reliabilitygoogle/skills | Skill | 22k | yesterday | Apache-2.0 | A | 85 | Claude Code, Codex |
| cloud-architectJeffallan/claude-skills | Skill | 12k | 7d ago | MIT | A | 71 | Claude Code |
| nemo-automodel-launcher-configNVIDIA/skills | Skill | 3.9k | yesterday | Apache-2.0 | A | 30 | Claude Code |
| azure-mgmt-botservice-dotnetmicrosoft/skills | Skill | 3.2k | yesterday | MIT | A | 78 | Claude Code |