Building Agent CLIs

Expert guidance for designing CLIs that AI agents can use safely and effectively.

Core Insight

Human DX optimizes for discoverability and forgiveness. Agent DX optimizes for predictability and defense-in-depth. These are different enough that retrofitting a human-first CLI for agents is often a losing bet.

The agent is not a trusted operator. You wouldn't build a web API that trusts user input without validation. Don't build a CLI that trusts agent input either.

Before Building

Gather this context (ask if not provided):

1. Current CLI state — Existing CLI to retrofit, or building from scratch?
2. Underlying system — REST API, database, filesystem, or something else?
3. Agent consumers — Which agents will call this? (Claude Code, Gemini, custom agents)
4. Risk profile — What's the blast radius of a wrong command? (read-only vs destructive)