gcx CLI

gcx is a unified CLI designed for both human users and AI coding agents to interact with Grafana and Grafana Cloud products. It provides structured access to Grafana resources (dashboards, folders, alert rules, data sources) and Grafana Cloud-specific services like Synthetic Monitoring, k6, Fleet Management, Incidents, and Adaptive Telemetry.

Key capabilities include:

• GitOps: Full round-trip fidelity for pulling resources to files and pushing them back.
• Observability as Code: Scaffolding Go projects, importing dashboards, linting with Rego, and live-reloading.
• Multi-environment management: Using named contexts to switch between environments (e.g., dev, staging, prod).
• AI Agent Integration: Native support for agentic workflows with auto-detection for tools like Claude Code, Copilot, and Cursor.

The gcx datasources command group provides a declarative, manifest-based interface for managing the full lifecycle of Grafana datasources. Instead of using imperative flags, you interact with datasources using Kubernetes-style manifests (YAML/JSON) supplied via files or stdin. This approach supports a 'fetch → edit → apply' workflow, making it ideal for both human operators and AI agents.

Key capabilities include:

• CRUD Operations: create, get, list, update, and delete.
• Health Checks: Verify the status of specific datasources or all datasources of a certain type.
• Schema Discovery: Inspect the configuration schema of installed datasource plugins to author valid manifests.
• Safe Secret Handling: Use the fromEnv keyword in manifests to reference environment variables, ensuring plaintext secrets never appear in command logs or outputs.

The gcx CLI is a unified control plane for managing Grafana resources, including dashboards, datasources, alerting, and various Grafana Cloud product APIs (such as SLO, IRM, Synthetic Monitoring, Fleet, and k6).

To see a list of bundled Agent Skills along with task-specific guidance, run:

gcx agent skills list

The gcx CLI is organized into a hierarchical command tree. It provides high-level commands for interacting with Grafana resources (like dashboards, metrics, logs, and traces), low-level API access via api, configuration management via config, and developer tooling via dev.

Common persistent flags available at the root include:

• --no-color: Disable color output.
• --no-truncate: Disable table column truncation.
• --agent: Enable agent mode.
• --verbose / -v: Increase verbosity (can be used multiple times).

gcx --verbose --no-color [command]
# Example: list dashboards
gcx dashboards list

The gcx instrumentation surface is designed for two primary user roles:

1. Onboarding Operators (Primary)

Goal: End-to-end instrumentation of new clusters. Workflow: Uses setup commands, action verbs, and wait commands to monitor state-machine transitions until instrumentation is complete.

2. Investigators/SREs (Secondary)

Goal: Troubleshooting telemetry gaps (e.g., "Why isn't this app producing data?"). Workflow: Uses status commands, services list --status=ERROR, and granular per-workload reads to see what the collectors (like Beyla) are actually observing.

Agent Observability allows you to inspect and manage LLM-powered application production data. It tracks generations (individual LLM API calls), groups them into conversations (user sessions), and uses evaluators (scoring functions) to assess quality. Rules bind these evaluators to production traffic by selecting specific generations and controlling sampling rates.

All management commands are prefixed with gcx agento11y.

To avoid manual marshal/unmarshal boilerplate, use TypedCRUD[T] to implement a ResourceAdapter. This requires your domain type T to implement the ResourceNamer interface (GetResourceName() string).

The ResourceIdentity Contract: If your resource uses composite names (e.g., name-ID like grafana-instance-health-5594), your type must implement the ResourceIdentity interface to ensure round-trip support:

• GetResourceName() string: Extracts the identity for metadata.name.
• SetResourceName(name string): Crucial. Must parse and restore internal state (like numeric IDs) from the name string. If this fails, Update or Delete operations may fail because the ID is lost during the K8s round-trip.