Designing Agent-Native CLIs: 10 Principles for the AI Era

For decades, the Command Line Interface (CLI) has been designed with a human at the terminal as the primary user. We optimized for visual alignment, ANSI colors, and interactive prompts—elements that are intuitive for people but often act as blockers for AI agents. As agents increasingly become the primary consumers of our APIs, the design philosophy must shift.

Trevin Chow recently proposed a framework of "Agent-Native CLIs," drawing from his own work and the implementations of companies like Cloudflare and HeyGen. The core thesis is simple: when you design for agents first, humans actually benefit from the resulting rigor and consistency.

Tier 1: Don't Break the Agent

The first tier of principles focuses on defensive design. These are the baseline requirements to ensure an agent doesn't hang, loop infinitely, or fail silently.

1. Non-interactive by Default

Agents cannot answer a "Are you sure? [y/N]" prompt. If a command hangs waiting for input, the agent simply stops.

• The Standard: Every command that might prompt must have a --no-input or --yes flag.
• Optimization: Cloudflare standardizes on --force for destructive bypass and explicitly bans --skip-confirmations to maintain a predictable vocabulary.

2. Structured, Parseable Output

While humans love tables, agents need data they can reliably extract.

• The Standard: Provide a --json flag on every data-returning command.
• Optimization: Maintain strict consistency. Avoid mixing --format=json and --output json. Use stdout for data and stderr for diagnostics.

3. Errors that Teach and Enumerate

An error like "invalid visibility" is a dead end for an agent. An error that says "--visibility must be one of: public, private, unlisted" allows the agent to self-correct in a single retry.

• The Standard: When rejecting input against an enum or schema, surface the valid set of values directly in the error message.

4. Safe Retries and Explicit Mutation Boundaries

Agents retry frequently. Without idempotency, a retried "create" command results in duplicate resources.

• The Standard: Use idempotency tokens or natural keys.
• Optimization: Implement --dry-run for consequential operations and ensure that destructive actions require an explicit, non-default flag.

5. Bounded Responses

Unbounded output wastes tokens and can blow out an agent's context window.

• The Standard: Implement pagination, limits, and filtering on all list-style commands.
• Optimization: Provide truncation messages that explicitly teach the agent how to narrow the next query (e.g., "add --limit=N to see more").

Tier 2: Empower the Agent

Once the CLI is stable, the next goal is to make it more useful as it is used more frequently. This layer is often best implemented via codegen or schemas rather than manual coding.

6. Cross-CLI Vocabulary Consistency

Agents build a generalized model of how CLIs work. If most tools use get but yours uses info, the agent will spend tokens and retries figuring that out.

• The Standard: Adhere to community conventions (e.g., get, list, create, update, delete).
• Optimization: Enforce this mechanically at the schema layer to prevent "Swiss cheese" consistency created by human reviews.

7. Three-Layer Introspection

Progressive help discovery is not enough for agents. They need a machine-readable map of the tool's capabilities.

• Layer 1: Standard --help for humans.
• Layer 2: agent-context—a versioned, machine-readable JSON describing the full shape of the CLI.
• Layer 3: Skill manifests (e.g., SKILL.md)—long-form prose teaching the agent how to compose operations into complex workflows.

8. Async-Aware Execution

Forcing an agent to write its own polling loop for async jobs is token-intensive and error-prone.

• The Standard: Provide a --wait flag that blocks until completion.
• Optimization: Maintain a local job ledger (e.g., ~/.cli/jobs.jsonl) so that if an agent is disconnected mid-poll, the next invocation can recover the in-flight job rather than starting a new one.

9. Persistent Identity through Profiles

Stateless CLIs force agents to re-specify the same configuration flags every time.

• The Standard: Implement a profile system (profile save, profile use) to bundle configuration.
• Optimization: Surface available profiles in the agent-context so the agent can discover existing identities without parsing config files.

10. Two-Way I/O

Agents often need to move artifacts (like generated videos or logs) to specific destinations.

• The Standard: Implement a --deliver flag supporting stdout, file:<path>, and webhook:<url>.
• Optimization: Include a feedback command that allows agents to report friction (e.g., "this flag is documented but rejected") directly to the maintainers.

The Debate: Agent-Native vs. Unix-Native

Not all developers agree with the "agent-native" label. Some argue that these principles are simply "good CLI design" that should have been followed all along.

"If you've ever met jq, you don't need anyone to tell you that --json is a very valuable thing to have... This is just taking command-line interfaces seriously as interfaces. It has pretty much nothing to do with AI except at the edges."

Others warn against over-engineering for agents at the expense of human usability, suggesting that agents are capable enough to handle messy CLIs if given a good enough "manpage for LLMs."

Regardless of the philosophical divide, the practical outcome is the same: a CLI that is predictable, structured, and consistent is superior for every user, whether they are made of carbon or silicon.