Agent-Friendly CLI Design

10 principles for building CLIs that AI agents can actually use, from a Cursor dev. Plus the missing piece: WHEN and WHEN NOT to use each command.

CLIs are making a comeback as the interface du jour for AI agents. They’ve obviously been around for years, but writing effective CLIs for agents requires different design principles than for humans. A lot of these would still be effective with humans too.

Cursor dev Eric Zakariasson had a nice post about the principles to apply when writing these:

  1. Make it non-interactive. Every input should be passable as a flag.
  2. Don’t dump all your docs upfront. Let agents discover via --help on subcommands.
  3. Make --help actually useful. Every subcommand gets examples.
  4. Accept flags and stdin for everything. Agents think in pipelines.
  5. Fail fast with actionable errors. Show the correct invocation.
  6. Make commands idempotent. Agents retry constantly.
  7. Add --dry-run for destructive actions. Let agents preview before committing.
  8. --yes / --force to skip confirmations. Safe default for humans, bypassable for agents.
  9. Predictable command structure. resource + verb pattern everywhere.
  10. Return data on success. IDs, URLs, durations. Not just emoji checkmarks.

I agree with pretty much all of them and have built some Claude Code skills (.claude/skills/) that apply them automatically to any CLIs I design.

Probably the most effective to me is the context management of help commands. This is documentation on the fly, progressive disclosure in action. Most help text focuses on what a command does, which is fine for humans. You read it once, reason about how to use it, and remember it. Agents don’t remember it. They re-read --help every time. So the help text needs to go further: when to use this and why, when not to use it and why. Throw in some breadcrumb scent too: “if you use this command, consider using X next.” That kind of upsell makes agents work noticeably better with CLI tools.

Read the full post →