ccloud CLI: The “Agent-Ready” Database CLI

This post is part of the CRDB is Agent Ready launch series. See also: CockroachDB MCP Server|Agent Skills

Production database operations for AI agents, with enterprise security built in. Here's how CockroachDB’s ccloud CLI enables AI-driven database operations and automation, from alert triage to full lifecycle cluster management.

AI Agent Alert Triage: 12 Alerts Across 4 Clusters in Minutes

Imagine this: You wake up to 12 PagerDuty alerts across four clusters. This may be a typical Tuesday morning for a platform team managing dozens of CockroachDB clusters. The old workflow – open PagerDuty, click into each alert, cross-reference maintenance schedules, check backups, ping the on-call in Slack – could easily take an hour before the first fix is enacted.

With an agent:

The AI agent reads the PagerDuty alert channel in Slack, groups alerts by cluster, then uses ccloud to check maintenance windows, backup status, audit logs, and replication health across all four clusters. It correlates the signals and, a few minutes later, produces a prioritized triage:

9 of 12 alerts - resolved, no action needed. Three clusters in us-east-1 had rolling restarts during Tuesday's maintenance window. All are healthy now, backups completed successfully, and replication lag is under five seconds.

3 alerts on cluster-gamma - needs attention. The CPU spike was caused by a concurrent schema change on the user_events table during the maintenance window. The agent recommends moving gamma's maintenance window to avoid the overlap, and setting a blackout window around the next planned schema migration.

With AI agents, what had previously taken an hour of dashboard-hopping and cross-team Slack threads becomes a few minutes of structured analysis. This agent read signals from Slack and PagerDuty, acted through ccloud, and produced a prioritized summary with concrete next steps – all auditable through the CLI.

Notice what the agent didn't do: it didn't trigger a failover, delete a cluster, or modify replication topology. It couldn't, because the service account it authenticates with only has read access to cluster state and write access to maintenance windows. The guardrails aren't in the agent's prompt. They're in the permission model.

So how does this work? It starts with the CLI. In practice, this makes the CLI the foundation for database automation. Because agents operate through shell commands, a database CLI provides a consistent, scriptable interface for managing infrastructure, running diagnostics, and coordinating workflows across environments. Instead of relying on dashboards or manual steps, teams can use CLI-driven workflows to automate database operations end-to-end.

Why a database CLI outperforms MCP for AI-driven operations

The MCP vs CLI debate is heating up in the agent community – and the answer isn't either/or. Both are interfaces to the same database capabilities. For production operations, however, the CLI has structural advantages that MCP can't match. These include: 

AI agents - Claude Code, Codex, Gemini CLI, Cursor, or your own all operate through shell commands. They don't click UIs or browse dashboards, Instead they execute commands and parse output. MCP gives agents structured tool-calling with auto-discovery, which is powerful for conversational exploration. But when an agent needs to operate infrastructure, not just query it, the CLI wins on several dimensions.

Zero context overhead. Loading a typical MCP server's tool schema adds thousands of tokens to every agent request. A CLI command adds zero – the agent just runs it. For an agent managing 20 clusters, that token overhead compounds fast.

Universal. Major coding agents like Claude Code, Codex, and Gemini CLI all support MCP - but agent frameworks like AutoGen and LangGraph don't natively, and CI/CD environments like GitHub Actions, Jenkins, and ArgoCD have no MCP integration at all. Every one of them can run shell commands. CLI is the common denominator that works everywhere, from an engineer's terminal to a deployment pipeline to a custom agent built on raw LLM APIs.

Composable. Agents can pipe ccloud output into jq, chain commands with &&, combine with psql, curl, kubectl, or any other CLI tool. MCP tools are isolated; CLI tools are part of the Unix ecosystem.

Scriptable. Agents can generate shell scripts that combine multiple ccloud commands into repeatable runbooks, then commit those scripts to version control. What starts as an ad hoc agent conversation becomes a checked-in operational procedure. MCP tool calls live and die in the agent session, with no infrastructure required and no server to deploy, configure, or keep running. The CLI is a single binary, whereas MCP servers need to be hosted, maintained, and kept available.

Familiar patterns. Agents trained on code corpora have strong priors for noun-verb CLI patterns like git commit, docker run, kubectl apply. The ccloud pattern like ccloud cluster create, ccloud folder list, etc. fits the same mental model. Agents can reason about available commands from --help output alone.

CI/CD native. The CLI fits directly into existing automation pipelines (like GitHub Actions, Jenkins, ArgoCD) without requiring protocol integration in your CI system.

The bottom line: MCP is ideal for enterprise-ready, multiplayer applications like internal BI tools, company-wide schema explorers, federated access editors;  where many users authenticate into a shared service. CLI is ideal for single-player, developer-first workflows like scripting a deploy pipeline, triaging alerts from your terminal, building repeatable runbooks; where a human is in the loop. In practice, agents use both. The question is which tool fits which job.

What AI agents can do with a database CLI

The triage scenario above works because CockroachDB’s ccloud isn't just a query tool, it's a full lifecycle control plane. It didn't happen by accident: We deliberately redesigned ccloud with AI agents as a first-class consumer.

What "CockroachDB is AI-ready" means in practice:

• Consistent noun-verb patterns across every command – ccloud cluster create, ccloud folder list, ccloud replication create. Agents don't need a manual; they can infer available operations from --help output the same way they reason about git, docker, or kubectl.

• JSON output on every command – every ccloud command supports -o json as a global flag. Agents get structured, parseable responses – no screen-scraping or fragile text parsing. An agent can pipe ccloud cluster list -o json into jq and reason over cluster state programmatically.

• Predictable error codes -- not just human-readable messages but machine-parseable status codes. An agent can distinguish "permission denied" from "resource not found" from "rate limited" and react accordingly.

• Complete API coverage – the CLI now covers the full CockroachDB Cloud API surface. No gaps where an agent has to fall back to raw HTTP calls or a different tool.

Here's the full scope of what agents can manage from the terminal:

That's the full surface area: provision through production, all from the terminal. It doesn't mean every agent should have access to every operation, however, which brings us to the most important part.

Enterprise security for AI-driven database operations

This is what separates CockroachDB’s ccloud from generic database CLIs and dev-tier tools. Most database CLIs were designed for developer workflows, not production operations. When an agent operates your database in production, enterprises need answers to four questions about: Identity, Authorization, Network, and Auditability.

Who is the agent? (Identity)

Agents shouldn't use personal credentials or shared admin accounts. Our ccloud supports multiple approaches for establishing agent identity, depending on the type of agent.

Interactive agents like Claude Code or Cursor authenticate through the browser, using your organization's existing auth method - SSO via OIDC or SAMLv2, social login, or username/password. SCIM 2.0 support means agent user provisioning and deprovisioning can be managed through your identity provider (Okta, Azure AD, Google Workspace) just like any other user.

For agents running on headless or remote machines:

Automated agents running in CI/CD or background pipelines use service accounts with API keys that authenticate directly to the CockroachDB Cloud API. This agent uses the API key as a bearer token for Cloud API operations.

Every agent gets a distinct, traceable identity. No shared tokens. No anonymous access. The auth method stays consistent with how your organization already authenticates.

What can the agent do? (Authorization)

This is where the real guardrails live - not in the agent's prompt, but in the permission model.

CockroachDB Cloud service accounts support granular role assignments that control exactly what each agent can do. You don't give a triage agent the same permissions as a provisioning agent.

A triage agent gets the Cluster Operator role. It can read cluster summaries, view backups, check maintenance windows, and export logs and metrics but it cannot modify cluster configuration or manage roles. If it tries to create a cluster or modify networking, the API returns a clean 403:

The agent literally cannot provision infrastructure or modify security settings, no matter what its prompt says.

An admin agent gets the Cluster Admin role scoped to specific clusters. It inherits all Cluster Operator capabilities and can additionally configure maintenance windows, manage backups, and update cluster settings, but only for the clusters it's assigned to. It can't provision new infrastructure or touch clusters outside its scope.

The key insight: the blast radius of an agent mistake is bounded by its service account permissions, not by the quality of its prompt. An agent that hallucinates and tries to delete a production cluster will get an authorization error. This is the same separation-of-duties model that enterprises already use for human operators, applied to agents.

How does the agent connect? (Network)

Agents operating production databases shouldn't connect over the public internet. ccloud gives you full control over network boundaries: private endpoints, egress rules, IP allowlists, trusted cloud accounts, and mTLS via client CA certificates. Your agent connects through the same private network paths your application traffic uses. No special exceptions. See the networking documentation for setup details.

How do you verify what happened? (Auditability)

Every action an agent takes through ccloud is logged: Who did it, when, and what changed. Because each agent has its own service account, audit logs show exactly which agent performed which action. No ambiguity.

Logs and metrics can be exported to your existing observability stack like CloudWatch, Datadog, or your own monitoring;  so agent activity shows up in the same dashboards your team already watches. CMEK ensures the data itself is encrypted with keys you control. See the observability documentation for setup details.

CockroachDB ccloud answers the four questions enterprises always ask, all from the command line: 

• “Who is this agent?” 

• ”What can it do?” 

• “How does it connect?” 

• “How do I verify what the agent did?”

How CLI, MCP, and Agent Skills enable database automation

This article focuses on the CLI, but it's just one of three ways agents can interact with CockroachDB. Each serves a different purpose and in practice, agents use all three in a single workflow. They are:

The CockroachDB MCP Server (docs) provides native LLM tool-calling integration. The agent auto-discovers available tools at runtime and gets structured, typed responses without parsing CLI output. This makes it the natural fit when agents need to explore schema metadata, run ad hoc queries, and reason over results in a multi-turn conversation without the user writing a single command.

Agent Skills (docs) encode domain knowledge. Not just "run this command" but "here's how to investigate a performance regression step by step." Skills provide guardrails and reasoning templates that neither CLI nor MCP alone offer.

The ccloud CLI (docs) provides direct infrastructure control: provisioning, security configuration, backup/restore, networking; with zero protocol overhead, universal agent compatibility, and enterprise security built in.

Here's how these three CockroachDB agent AI capabilities work together in the alert triage scenario from the opening:

1. Skill provides the reasoning framework – "When triaging alerts, check maintenance windows first, then backups, then replication health."

2. MCP provides the data exploration – "Show me the top queries by CPU on cluster-gamma during the spike."

3. CLI executes the infrastructure changes – ccloud cluster maintenance update cluster-gamma, ccloud cluster blackout-window create cluster-gamma

It’s the same database with three complementary interfaces, each doing what it does best.

Get Started: Connect Your AI Agent to CockroachDB Today!

Biplav Saraf is a Staff Product Manager at Cockroach Labs. He works across product security and developer experience, delivering built-in trust to unlock enterprise adoption in regulated industries, while creating an intuitive developer platform that lowers barriers to innovation.