gcx
Grafana Cloud CLI optimized for agentic usage
TLDR
SYNOPSIS
gcx command [subcommand] [options] [args]
DESCRIPTION
gcx is the official command-line interface for Grafana Cloud, with first-class support for querying signals (metrics, logs, traces, profiles), managing alert rules and SLOs, and performing observability-as-code workflows against dashboards and folders. It is designed to be usable both by humans and by agentic coding assistants that need structured access to production observability data.Each Grafana product has its own top-level command (metrics, logs, traces, profiles, alert, slo, synth, irm, k6, fleet, assistant, and so on), and resources can be exported to local YAML or JSON with gcx resources pull and pushed back with gcx resources push, enabling GitOps-style management of Grafana objects.
PARAMETERS
auth login --server URL
Start browser-based OAuth login against a Grafana instance.config set key value
Set a configuration value (e.g. contexts.my-grafana.grafana.token).config use-context name
Switch the active configuration context.config check
Verify the active authentication and connectivity.metrics query PROMQL
Execute a PromQL query against Prometheus / Mimir.logs query LOGQL
Execute a LogQL query against Loki.traces query QUERY
Query trace data from Tempo.profiles query QUERY
Query profiling data from Pyroscope.alert rules list [--state STATE]
Display alert rules and their state, health, and pause status.alert groups list
Show alert groups.resources pull [-p DIR] [-o FORMAT]
Export dashboards, folders, and other resources to local files.resources push [-p DIR] [--dry-run] [--on-error MODE]
Deploy local resources back to Grafana.resources delete, edit, validate, get
Manage resources: remove, interactively modify, check, or list them.slo definitions list, slo reports list
Manage Service Level Objectives.synth checks list, synth probes list
Synthetic monitoring checks and probes.irm oncall schedules list, irm incidents list
Incident response and on-call management.k6 load-tests list, k6 runs list
Load testing with k6.fleet pipelines list, fleet collectors list
Fleet management.kg status, kg search, kg entities show
Grafana knowledge graph.assistant investigations list, assistant prompt TEXT
Drive the Grafana Assistant AI.frontend apps list
Frontend observability.aio11y conversations list, aio11y agents list
AI observability.dev scaffold, dev import, dev serve, dev lint
Observability-as-code workflow: scaffold, import, live-reload, and lint.api PATH
Raw passthrough to the Grafana HTTP API.skills list, skills install
Show and deploy agent skill bundles.completion SHELL
Generate shell completions for bash, zsh, or fish.--since DURATION
Time window for queries (e.g. 1h, 24h).-o, --output FORMAT
Output format: json or yaml.--dry-run
Preview changes without applying them.--on-error MODE
Error-handling strategy: abort, fail, or ignore.-p PATH
Resource directory used by resources commands.-f FILE
Input file for resources commands.
CONFIGURATION
Configuration is stored in contexts that point at a Grafana server and an authentication token:
gcx config set contexts.my-grafana.grafana.token [your-service-account-token]
gcx config use-context [my-grafana]
CAVEATS
gcx supports Grafana Cloud, Grafana Enterprise, and Grafana OSS 12+. Cloud-specific products (slo, synth, irm, parts of fleet and kg) require Grafana Cloud; feature availability varies by deployment type. Use service-account tokens rather than personal tokens for automation.
HISTORY
gcx is published by Grafana Labs and is explicitly positioned as "optimized for agentic usage", closing the gap between AI coding tools that see only source code and production systems where the code actually runs.
SEE ALSO
grafana-cli(1), promtool(1), logcli(1), k6(1)
