Skip to content

CONCEPT Cited by 4 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

  • sources/2026-04-13-cloudflare-building-a-cli-for-all-of-cloudflare — the concept is central to why Cloudflare rebuilt Wrangler as cf.
  • sources/2026-04-20-cloudflare-internal-ai-engineering-stack — sibling framing: internal agents at Cloudflare drive the same design posture for MCP servers (portal-level aggregation, <1,000 token Code Mode).
  • sources/2025-04-10-flyio-30-minutes-with-mcp-and-flyctl — cross-vendor confirmation. Fly.io's 2020 decision to give most flyctl commands --json mode — framed at the time as "for automation", not for LLMs — anticipates Cloudflare's 2026 explicit "agents are the primary customer of our APIs" framing. Five years later the --json investment is what makes systems/flymcp (a 90-LoC MCP wrapper, patterns/wrap-cli-as-mcp-server) trivially viable. The structured-output axis of agent-ergonomic CLI design predates and survives the LLM era; it is a general automation property that LLMs retroactively weaponise.
  • sources/2025-05-07-flyio-provisioning-machines-using-mcps — mutation-side framing of the same design pressure. Sam Ruby's post makes the agent-ergonomic CLI case against all three alternative provisioning surfaces — HTTP API ("would have required some effort"), CLI directly ("would have had to use the documentation and a bit of copy/pasting of arguments"), web dashboard ("isn't any way to sort the list or delete a volume") — landing on an LLM-through-MCP flow as the win. Canonical wiki datum for the NL- provisioning thesis as a direct consequence of the agent- ergonomic-CLI framing.
Last updated · 200 distilled / 1,178 read