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 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 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.
  • sources/2026-03-10-flyio-unfortunately-sprites-now-speak-mcp — Ptacek's canonical "CLI > MCP for shell-capable agents" statement. "In 2026, MCP is the wrong way to extend the capabilities of an agent. The emerging Right Way to do this is command line tools and discoverable APIs." Flips the default: agent-ergonomic CLI is not just "one surface agents consume" — it is the preferred surface for any agent that can run shell commands. Two new cost axes added to the agent-ergonomic-CLI case: progressive capability disclosure (CLI subcommand trees reveal capabilities incrementally, avoiding up-front context cost) and context as importance signal (tool descriptions in context direct model attention, not just capability awareness). The MCP server Fly ships in the same post (sprites.dev/mcp) is explicitly positioned as a fallback for shell-less agents — see patterns/mcp-as-centralized-integration-proxy. "In claude, gemini, or codex, you should just show your agent the sprite CLI and let it impress you."
  • sources/2026-04-29-grafana-get-observability-in-the-terminal-for-you-and-your-agents-with-the-gcx-cli-tool — first observability-vendor commitment to the agent-primary CLI stance with a full shipping list. Grafana's gcx launch restates the Cloudflare framing from the observability altitude ("agents are the primary customer of our APIs" → "two things matter most when an LLM (instead of a human at a keyboard) is the caller") and ships the seven commitments as one tool: stable JSON/YAML via --output with field names stable across versions, documented + consistent exit codes + error shapes, machine-readable command catalog with destructive-command tagging, auto-detected agent mode (Claude Code, Cursor; GCX_AGENT_MODE=true override), destructive-op confirmation as a zero-cost guardrail, kubectl-style named contexts for multi-stack sessions, and deep links back into the Grafana UI for human handoff. Canonical wiki instance of the pattern applied to the observability domain and the first to ship the full commitment list simultaneously.
Last updated · 766 distilled / 2,225 read