Skip to content

README.md

Latest commit

 

History

History
356 lines (251 loc) · 13.3 KB

README.md

File metadata and controls

356 lines (251 loc) · 13.3 KB

gcx — Grafana Cloud CLI

CI Go License Public Preview

Grafana Cloud and the Grafana Assistant — in your terminal and your agentic coding environment.

Query production. Investigate alerts. Let the Assistant root-cause issues. Ship fixes with observability built in. Without leaving your editor.

"Don't guess. Check the actual production data."

Why gcx

Agentic coding tools like Claude Code and Cursor have changed how developers build software.

But we face a critical architectural gap: Our development environments are operating in a Context Vacuum.

gcx closes that gap. It connects your editor to your entire Grafana Cloud production stack — including the Grafana Assistant — making observability a development signal, not an afterthought. When something breaks, the Assistant's investigation is already waiting: mitigations planned, context assembled, so you can act immediately.

  • Grafana Assistant integration — automated root-cause analysis, investigation summaries, and remediation suggestions powered by the Assistant
  • Production-aware development — query live metrics, logs, and traces without leaving your editor
  • AI agent native — JSON/YAML output, structured errors, predictable exit codes. Agent mode auto-detected for Claude Code, Copilot, Cursor, and others
  • Full Grafana Cloud access — dashboards, alerting, SLOs, Synthetic Monitoring, OnCall, K6, Fleet Management, Incidents, and more from a single CLI
  • GitOps & CI/CD — pull resources to files, version in git, push back with full round-trip fidelity
  • Observability as code — scaffold projects, import dashboards, lint with Rego rules, live-reload dev server
  • Multi-environment — named contexts to switch between dev, staging, and production

Note

gcx requires Grafana 12 or above. Older Grafana versions are not supported.

Maturity

Warning

This project is currently in public preview, which means that it is still under active development. Bugs and issues are handled solely by Engineering teams. On-call support or SLAs are not available.

See Release life cycle for Grafana Labs.

The Agentic Workflow

Here's what it looks like when your coding agent has access to production:

1. An alert fires — P95 latency on the checkout service crosses the SLO threshold.

2. The Assistant investigates — Your coding agent calls the Grafana Assistant through gcx. The Assistant has already started its investigation — it traces the issue to a missing index on customer_id causing full table scans under load.

3. It fixes the issue — Drafts the migration, adds the index.

4. It prevents recurrence — Instruments the service with OpenTelemetry spans, sets up a Synthetic Monitoring check on the checkout flow, and creates an alert rule on query duration.

5. It ships — Opens a PR, tests pass, deploys to production. The alert resolves.

Investigation, fix, instrumentation, monitoring — without the developer ever leaving their editor. The Grafana Assistant provides the intelligence; gcx provides the interface. And because it all builds on everything you've already configured in Grafana Cloud — your dashboards, your alerts, your datasources — no other tool can give you this depth out of the box.

Install

Quick install (Linux/macOS):

curl -fsSL https://raw.githubusercontent.com/grafana/gcx/main/scripts/install.sh | sh

Downloads the latest release, verifies the SHA-256 checksum, and installs to ~/.local/bin. Override the location with INSTALL_DIR:

curl -fsSL https://raw.githubusercontent.com/grafana/gcx/main/scripts/install.sh | INSTALL_DIR=/usr/local/bin sh

Pre-built binary (Linux/macOS/Windows):

Download the latest archive for your OS and architecture from the releases page, extract it, and move the binary to your PATH:

tar xzf gcx_*.tar.gz
chmod +x gcx && sudo mv gcx /usr/local/bin/

Go install:

go install github.com/grafana/gcx/cmd/gcx@latest

Shell completion:

gcx completion zsh > "${fpath[1]}/_gcx"   # zsh
gcx completion bash > /etc/bash_completion.d/gcx  # bash
gcx completion fish > ~/.config/fish/completions/gcx #fish

Verify: gcx --version

AI Agent Plugin

A Claude Code plugin is included with a portable Agent Skills bundle for gcx workflows: setup, dashboard GitOps, datasource exploration, alert investigation, structured debugging, SLO management, Synthetic Monitoring workflows, project scaffolding, resource generation and import, and end-to-end observability rollout. Install it alongside gcx to give your agent deep Grafana knowledge.

Quick Start

1. Authenticate

Grafana API access (service account token, recommended):

gcx config set contexts.my-grafana.grafana.server https://your-instance.grafana.net
gcx config set contexts.my-grafana.grafana.token your-service-account-token
gcx config use-context my-grafana

Use a Grafana service account token with Editor or Admin role.

Grafana Cloud product APIs (SLO, Synth, OnCall, etc.):

Grafana Cloud product commands require a Cloud Access Policy token:

gcx config set contexts.my-grafana.cloud.token your-cloud-access-policy-token

# Optional: set this only if gcx cannot derive the stack slug from grafana.server.
gcx config set contexts.my-grafana.cloud.stack your-stack-slug

You do not need to set cloud.api-url for grafana.com; gcx defaults to https://grafana.com. Set cloud.api-url only when you need a non-default Grafana Cloud API endpoint.

Environment variables (recommended for CI/CD and agents):

export GRAFANA_SERVER="https://your-instance.grafana.net"
export GRAFANA_TOKEN="your-service-account-token"
export GRAFANA_CLOUD_TOKEN="your-cloud-access-policy-token"

# Optional: only needed if gcx cannot derive the stack slug from GRAFANA_SERVER.
export GRAFANA_CLOUD_STACK="your-stack-slug"

Browser-based OAuth login (experimental):

gcx auth login --server https://byoc-grafana.com

This opens a browser and bootstraps the selected context without preconfiguring grafana.server. On success, gcx saves the server URL, OAuth access token, refresh token, and proxy endpoint to that context.

If you want to save the login to a specific context:

gcx auth login --context my-grafana --server https://byoc-grafana.com

Note

For automation, CI/CD, and other non-interactive usage, the token-based setup above remains the recommended approach.

Verify: gcx config check

2. Explore

# Grafana resources
gcx resources schemas                           # discover available resource types
gcx resources get dashboards                    # list all dashboards
gcx resources get folders                       # list all folders
gcx alert rules list                            # list alert rules

# Grafana Cloud products
gcx slo definitions list                        # list SLOs
gcx synth checks list                           # list synthetic monitoring checks
gcx oncall schedules list                       # list on-call schedules
gcx k6 load-tests list                          # list k6 load tests

# Query datasources
gcx metrics query 'rate(http_requests_total[5m])' --since 1h
gcx logs query '{app="nginx"} |= "error"' --since 1h

Grafana Cloud Products

gcx provides dedicated commands for each Grafana Cloud product:

Product Command Examples
SLOs gcx slo slo definitions list, slo reports list
Synthetic Monitoring gcx synth synth checks list, synth probes list
OnCall gcx oncall oncall schedules list, oncall integrations list
Alerting gcx alert alert rules list, alert groups list
K6 Cloud gcx k6 k6 load-tests list, k6 runs list
Fleet Management gcx fleet fleet pipelines list, fleet collectors list
IRM Incidents gcx incidents incidents list, incidents create -f incident.yaml
Knowledge Graph gcx kg kg status, kg search, kg entities show
Adaptive Metrics gcx metrics adaptive metrics adaptive recommendations show, metrics adaptive rules list
Adaptive Logs gcx logs adaptive logs adaptive patterns show, logs adaptive drop-rules list

Resource Management

Manage both Grafana-native resources (dashboards, folders) and Grafana Cloud resources from a single CLI:

# Pull dashboards and folders to local files
gcx resources pull dashboards -p ./resources -o yaml
gcx resources pull folders -p ./resources -o yaml

# Push local changes back to Grafana
gcx resources push -p ./resources

# Preview changes without applying
gcx resources push -p ./resources --dry-run

# Validate resources before pushing
gcx resources validate -p ./resources

# Edit a dashboard interactively (opens $EDITOR)
gcx resources edit dashboards/my-dashboard

# Delete a resource
gcx resources delete dashboards/my-dashboard

Alerting & Datasource Queries

Inspect alerting rules and query datasources directly:

# Alert rules
gcx alert rules list
gcx alert groups list

# PromQL queries
gcx metrics query 'rate(http_requests_total[5m])' --since 1h
gcx metrics labels
gcx metrics metadata

# LogQL queries
gcx logs query '{app="nginx"} |= "error"' --since 1h
gcx logs labels
gcx logs series --match '{app="nginx"}'

gcx also supports Pyroscope (profiling) and Tempo (traces) datasources.

Observability as Code

gcx includes tools for managing Grafana resources as Go code using the grafana-foundation-sdk:

# Scaffold a new project
gcx dev scaffold --project my-dashboards

# Import existing dashboards from Grafana as Go builder code
gcx dev import dashboards

# Live-reload dev server (preview dashboards in browser)
gcx dev serve ./resources

# Lint resources with built-in and custom Rego rules
gcx dev lint run -p ./resources
gcx dev lint rules                              # list available rules
gcx dev lint new --resource dashboard --name my-rule  # create custom rule

# Build and push
go run ./dashboards/... | gcx resources push -p -

Raw API Access

For anything not covered by built-in commands, use the API passthrough:

gcx api /api/health
gcx api /api/datasources -o yaml
gcx api /api/dashboards/db -d @dashboard.json
gcx api /api/dashboards/uid/my-dashboard -X DELETE

GitOps

Pull resources to files, version in git, push back:

# Pull all resources
gcx resources pull -p ./resources -o yaml

# Commit to git
git add ./resources && git commit -m "snapshot Grafana resources"

# Push changes from git to Grafana
gcx resources push -p ./resources

gcx push is idempotent — running it multiple times produces the same result. Folders are automatically pushed before dashboards to satisfy dependencies.

CI/CD

# .github/workflows/deploy-resources.yaml
name: Deploy Grafana Resources
on:
  push:
    branches: [main]
    paths: ['resources/**']

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install gcx
        run: |
          curl -fL "$(curl -s https://api.github.com/repos/grafana/gcx/releases/latest | grep browser_download_url | grep linux_amd64.tar.gz | cut -d '"' -f 4)" | tar xz gcx
          chmod +x gcx && sudo mv gcx /usr/local/bin/

      - name: Deploy resources
        env:
          GRAFANA_SERVER: ${{ secrets.GRAFANA_PROD_URL }}
          GRAFANA_TOKEN: ${{ secrets.GRAFANA_PROD_TOKEN }}
        run: |
          gcx resources validate -p ./resources
          gcx resources push -p ./resources --on-error abort
  • All commands except edit are non-interactive — safe for pipelines
  • --dry-run on push and delete to preview changes
  • --on-error abort|fail|ignore to control error behavior
  • -o json or -o yaml for machine-parseable output

Documentation

Topic Description
Installation Install gcx on macOS, Linux, and Windows
Configuration Contexts, authentication, environment variables
Managing Resources Get, push, pull, delete, edit, validate
Dashboards as Code Dashboard-as-code workflow with live dev server
Linting Resources Lint dashboards and alert rules with Rego policies
CLI Reference Full command reference (auto-generated)

Contributing

See our contributing guide.

License

Apache 2.0 — see LICENSE.