Trevin Chow distills 10 CLI design principles into two tiers: 5 defensive basics agents require, plus 5 compounding behaviors that make CLIs better the more agents use them.
Key Takeaways
Tier 1 covers non-interactive defaults, structured JSON output, enumerated errors, idempotent retries, and bounded responses – gaps here cost tokens and cause silent failures.
Cloudflare rebuilt Wrangler around a TypeScript schema generating the CLI, SDKs, Terraform provider, and MCP server from one source; their Code Mode MCP serves ~3,000 operations in under 1,000 tokens.
Vocabulary consistency is mechanically enforced at the schema layer: always get not info, always --force not --skip-confirmations, always --json – “manually enforcing consistency through reviews is Swiss cheese.”
A three-layer introspection model adds a machine-readable agent-context endpoint (versioned JSON schema) on top of standard --help text, so agents can self-orient without burning tokens on help parsing.
Async job workflows need idempotency across the full submit-poll-collect arc, not just at submission – a persistent job ledger lets a retried agent find an in-flight job instead of spawning a duplicate.
