How to Achieve Terminal-Based Observability for You and Your AI Agents Using the gcx CLI

By ● min read

Introduction

Modern development is increasingly command-line-driven, with AI agents like Cursor and Claude Code handling many day-to-day coding tasks. While these agents accelerate code generation, they create a new visibility gap: they see your source files but remain blind to your production environment. They don't detect latency spikes, SLO violations, or real user issues—they write code based on assumptions instead of actual system behavior. To bridge this gap, Grafana Cloud's gcx CLI brings observability directly into your terminal and your agent's workflow. This How-To guide walks you through setting up full observability for your services and enabling your AI agents to make informed, data-driven decisions—reducing incident response from hours to minutes.

What You Need

• gcx CLI – installed and authenticated (public preview)
• Grafana Cloud account – with an active stack
• AI agent tool – e.g., Cursor, Claude Code, or any CLI-integrated agent
• A service to observe – backend, frontend, or Kubernetes workload
• Basic familiarity with terminal and YAML/JSON editing

Step-by-Step Guide

Step 1: Install and Authenticate gcx

Download the latest gcx CLI binary from the Grafana Cloud documentation. After installation, run gcx auth login to authenticate with your Grafana Cloud account. This connects the CLI to your stack, enabling all subsequent operations.

Step 2: Point Your Agent at an Uninstrumented Service

Choose a service that currently has no observability instrumentation, alerts, or SLOs. Use your agent (e.g., in Cursor or Claude Code) to identify the service directory. Simply ask your agent: "Bring this service up to standard using gcx." The agent will use gcx commands to proceed.

Step 3: Instrument the Code with OpenTelemetry

Run gcx instrumentation add to automatically wire OpenTelemetry into your codebase. This command injects the necessary libraries and configuration for metrics, logs, and traces. Your agent can execute this as a terminal step, eliminating manual setup.

Step 4: Validate Data Flow

After instrumentation, use gcx check telemetry to confirm that telemetry data is flowing into the correct backends. The CLI verifies that metrics, logs, and traces are landing in your Grafana Cloud stack. If not, the output pinpoints misconfigurations.

Step 5: Set Up Alerting Rules and SLOs

Generate alert rules dynamically based on the signals your service emits. Use gcx alerts generate to create rules for latency, error rates, or custom metrics. Then define an SLO with gcx slo create—for example, an availability SLO based on 99.9% uptime over 30 days. Push it live with gcx slo push.

Step 6: Create Synthetic Checks

Stand up synthetic monitoring probes so users aren't the first to report an outage. Run gcx synthetics create to define HTTP or scripted checks from your terminal. These probes run from multiple locations and alert your team before customers notice.

Step 7: Onboard Frontend, Backend, or Kubernetes

• Frontend: Use gcx frontend onboard to add Faro instrumentation, create the app in Grafana Cloud, and manage sourcemaps for readable stack traces.
• Backend: With gcx backend onboard, you can apply standard instrumentation via the Instrumentation Hub.
• Kubernetes: Use gcx k8s onboard to monitor your cluster and workloads with preconfigured dashboards.

Step 8: Manage Everything as Code

Pull your existing dashboards, alerts, SLOs, and synthetic checks as local files using gcx pull. Edit them with your agent—no manual clicking. Push changes back with gcx push. Everything stays version-controlled and reproducible.

Step 9: Use Deep Links for Human Investigation

When an alert fires or you need deeper context, generate a deep link directly to Grafana Cloud from the terminal. Use gcx link --resource="dashboard/dashboard-uid" to open the exact view. This saves context switching and keeps your agent in the loop.

Tips for Maximum Impact

• Start simple: Focus on one critical service first. Once your agent can observe it, scale out.
• Leverage agentic workflows: Let your AI agent run the gcx commands. It can iterate faster than manual execution.
• Close the visibility gap: Agents without production context pattern-match blindly. With gcx, they read real system state and make smarter code changes.
• Reduce ticket time: What used to be a multi-day ticket becomes a single agent session. Encourage your team to use gcx as the first line of investigation.
• Combine with version control: Keep your observability-as-code files in Git. Your agent can suggest changes and even open pull requests.
• Remember the preview nature: gcx is in public preview—provide feedback to Grafana Labs to shape future features.

By following these steps, you turn your terminal into a full observability command center—for you and your AI agents. No more context-switching. No more blind agents. Just faster, data-driven development.