Skip to content

SYSTEM Cited by 1 source

gcx (Grafana Cloud CLI)

gcx is Grafana Labs' open-source command-line tool (github.com/grafana/gcx) that exposes Grafana Cloud's full observability lifecycle — instrumentation, alerts, SLOs, synthetic checks, frontend + application + Kubernetes monitoring, dashboards-as-code — as a single CLI surface explicitly designed with AI agents as the primary caller. Launched in April 2026 and positioned in the company's framing as "git or kubectl for observability" — the agent runs the command, reads the output, moves on; no wrapper, no shim.

Why it shows up on this wiki

gcx is the first observability-vendor CLI on the wiki that explicitly states the agent-primary design stance and ships the full agent-ergonomic commitment list in one tool. It sits in the same design lineage as Cloudflare's unified CLI (systems/cf-cli) and Fly.io's flyctl (systems/fly-flyctl), but specialises the agent-ergonomic-CLI pattern to the observability altitude — CI-reachable instrumentation validation, SLO-as-code, synthetic-check lifecycle, and "read the state of the running system" as the new baseline for agent-driven troubleshooting.

Surface area

The launch post enumerates four named lifecycle axes that gcx covers (exact command shapes not yet disclosed in the post; the github.com/grafana/gcx README is the authoritative surface):

Axis Scope
Instrumentation Wire OpenTelemetry into a codebase; validate that metrics/logs/traces are flowing; confirm data is landing in the right backends
Alerting, SLOs, synthetics Generate alert rules from emitted signals; define an SLO against a real latency or availability indicator; stand up synthetic probes
Frontend / Application / K8s Observability Onboard Faro-instrumented frontends + manage sourcemaps; onboard backend services and K8s infrastructure via Instrumentation Hub
Everything as code Pull dashboards, alerts, SLOs, and synthetic checks as local files; edit them locally with the agent; push them back

Agent-ergonomic design commitments

The post names seven commitments that make gcx an agent-first CLI. Each is a canonical wiki instance of a pre-existing agent-ergonomic-CLI principle (Cloudflare / Fly.io canonical), now shipped by an observability vendor:

1. Stable structured output — concepts/json-output-stability

Every command emits JSON or YAML via --output, "with field names that stay stable across versions." The "stable across versions" clause is the load-bearing commitment — prevents silent parser drift in agent sessions that run against the same tool weeks apart.

2. Documented, consistent exit codes — concepts/exit-code-semantics

"Exit codes and error shapes are documented and consistent, so an agent can branch on failure and recover on its own instead of guessing from a stderr string." Agent error handling becomes a switch on $? rather than an LLM-prompt-to-reparse-stderr.

3. Machine-readable command catalog — concepts/machine-readable-command-catalog

"It ships a machine-readable catalog of its own commands and flags, so agents can discover capabilities at runtime instead of guessing from stale training data." Distinct from --help text (human-oriented); the catalog is a first-class parseable inventory of the tool's entire surface, including which commands are destructive (see #5).

4. Agent-harness auto-detection — patterns/auto-detect-agent-context

"It auto-detects when it's being driven by Claude Code, Cursor, or similar, and it drops spinners, truncation, and other human-friendly noise (or force it with GCX_AGENT_MODE=true)." Humans get the polished default; agents get the machine-parseable default, automatically — without each agent needing to know the right env var.

5. Destructive-operation confirmation — patterns/destructive-operation-confirmation-as-agent-guardrail

"It will find commands that result in destructive operations, which require explicit confirmation to reduce agent mistakes." The catalog surface tags destructive commands; running them without the confirmation flag fails. Zero-cost guardrail on top of structured output — the tool knows which verbs mutate, not the agent's prompt.

6. Named contexts for multi-stack — concepts/named-contexts-for-multi-stack

"kubectl-style named contexts let an agent juggle several stacks in one session without mutating global state." The stack target is a per-command parameter, not a global ~/.config toggle — so switching stacks (staging → prod) doesn't leak into commands already in flight.

The CLI can emit deep links into Grafana Cloud — "the moment a human needs to look." Agent does the work in the terminal; when human review is needed, hand off to the UI via a precise URL instead of "go navigate to the dashboard."

Agent skills bundle

gcx ships a bundle of portable agent skills covering observability setup, alert investigation, SLO management / investigations, and synthetic-check investigations. The post's portability claim: "They work in any harness that follows the .agents skill convention, including Claude Code, and they can be installed with one command."

This is a concrete deployment of the agent-skills primitive: skills are shipped alongside the tool (vendor-authored, curated) rather than per-project authored. Installing gcx installs both the tool and a library of battle-tested observability workflows for agents that already support the .agents skill convention.

Design-stance contrast

Alternative gcx posture Rationale
Direct-exec (gcx … like git, kubectl) Primary "Agents already know how to run git, kubectl, and go test. gcx fits in the same slot."
MCP server wrapping gcx Not in launch post The patterns/wrap-cli-as-mcp-server pattern remains available for shell-less harnesses but isn't the primary mode
Bespoke per-agent integration layer Rejected Verbatim: "No wrapper, no shim, no bespoke integration layer."
GUI-driven automation Counter-example "CLI-driven agents also tend to be cheaper per task and more reliable than equivalent GUI-driven setups."

Canonical conversation shapes

The post lists five agent-driven workflow examples that gcx unlocks:

  1. "Why did this endpoint get slower this week?" — agent pulls traces and latency histograms, not just the diff.
  2. "Is my new query efficient?" — agent runs the PromQL against the actual metrics backend and iterates.
  3. "Are we meeting the SLO for checkout?" — agent reads the SLO definition and current burn rate before writing a line.
  4. "This alert is noisy, fix it." — agent inspects the rule, the firing history, and related dashboards, proposes a tuned threshold.
  5. Ticket-scale onboarding: "What used to be a multi-day ticket becomes a one-agent session."

All five are instances of concepts/agentic-troubleshooting-loop specialised to Grafana Cloud primitives.

Operational numbers

  • None disclosed in the launch post — no adoption metrics, no catalog size, no per-command latency numbers.
  • Open-source repository: github.com/grafana/gcx.

Caveats

  • Launch-post level of detail. Exact command shapes, the field-stability enforcement mechanism, and the agent-harness detection mechanism aren't disclosed in the post. The principles are — the architecture isn't.
  • Grafana Cloud–targeted. gcx is a Grafana Cloud CLI; the "everything as code" surface maps to Grafana Cloud dashboards/alerts/SLOs/synthetics. Not a general-purpose cross-vendor observability CLI.
  • Agent-skill .agents convention referenced but not respecified. The post asserts portability across any harness following the .agents skill convention; the convention itself isn't re-specified here (see concepts/agent-skills-discovery).
  • Confirmation mechanism shape is conceptual, not specified. "Explicit confirmation" — the flag name, whether it's a --yes / --force / --i-really-mean-it shape, isn't published in the post.

Seen in

Last updated · 433 distilled / 1,256 read