Skip to content

CONCEPT Cited by 5 sources

Agent-ergonomic CLI

An agent-ergonomic CLI is a command-line interface explicitly designed for AI agents as the primary caller, with human usability as a correlated-but-secondary concern. In Cloudflare's framing:

"Increasingly, agents are the primary customer of our APIs."

(Source: sources/2026-04-13-cloudflare-building-a-cli-for-all-of-cloudflare.)

What agents need from a CLI

  1. Consistency across resources — verbs, flags, noun forms identical across every product, because the agent's plan generalizes from one product to another. See concepts/cli-convention-enforcement.
  2. Structured output — --json everywhere, reliably parseable, same shape every time.
  3. Discoverability — --help output that is itself parseable, and machine-readable manifests (OpenAPI, MCP tool lists) that describe the full surface.
  4. Low context cost — tools should fit in an agent's context window; MCP "Code Mode" is the extreme version, fitting ~3,000 Cloudflare operations in <1,000 tokens.
  5. Explicit side-effect signaling — dry-run support; flags like --force; output that says which environment (local / remote, production / staging) the command hit. See concepts/local-remote-parity.
  6. Predictable error shape — actionable errors the agent can turn into a next action, not opaque stack traces. See patterns/actionable-error-messages.
  7. Idempotency where reasonable — retrying a command should be safe under network error, which an agent will definitely do.

How this differs from human-first CLI

Human CLIs prioritize:

  • Pretty-printed tables, colored output, prompts for confirmation, interactive mode.
  • Short aliases (g for get).
  • Free-form arguments.

Agent-first CLIs prioritize:

  • Machine-readable --json by default for agent sessions.
  • Full verb / flag names (aliases introduce ambiguity).
  • Rigid schemas; any ambiguity is a failure mode.
  • No interactive confirmation prompts on non-TTY contexts.

Cloudflare's target is a CLI that is "ergonomic for both agents and humans" — not either-or. The convention- enforcement rules (get over info, --json everywhere) satisfy both, because consistency helps humans too.

Why it matters now

Agents are starting to build and deploy real systems. If the CLI they use to provision infrastructure is fundamentally inconsistent across products, the agents either fail or require costly post-hoc patching. Cloudflare is betting that getting the CLI right for agents now is the durable investment; humans inherit the benefits.

Interfaces that must be equally agent-ergonomic

  • CLI commands (this concept).
  • SDK surfaces.
  • MCP servers (explicit agent-first by design).
  • Workers bindings RPC (the internal API agents call from inside Workers).
  • Configuration files (wrangler.jsonc).

The unifying move is to generate all of them from one unified interface schema so they share the same ergonomic properties.

Seen in

Last updated · 542 distilled / 1,571 read