Building CLIs for agents
If you've ever watched an agent try to use a CLI, you've seen it get stuck on an interactive prompt it can't answer, or parse a help page with no examples. Most CLIs were built assuming a human is at the keyboard. Here are some things I've found that make them work better for agents:
Make it non-interactive. If your CLI drops into a prompt mid-execution, an agent is stuck. It can't press arrow keys or type "y" at the right moment. Every input should be passable as a flag. Keep interactive mode as a fallback when flags are missing, not the primary path.
Don't dump all your docs upfront. An agent runs mycli, sees subcommands, picks one, runs mycli deploy --help, gets what it needs. No wasted context on commands it won't use. Let it discover things as it goes.
Make --help actually useful. Every subcommand gets a --help, and every --help includes examples. The examples do most of the work. An agent pattern-matches off mycli deploy --env staging --tag v1.2.3 faster than it reads a description.
Accept flags and stdin for everything. Agents think in pipelines. They want to chain commands and pipe output between tools. Don't require positional args in weird orders or fall back to interactive prompts for missing values.
Fail fast with actionable errors. If a required flag is missing, don't hang. Error immediately and show the correct invocation. Agents are good at self-correcting when you give them something to work with.
Make commands idempotent. Agents retry constantly. Network timeouts, context getting lost mid-task. Running the same deploy twice should return "already deployed, no-op", not create a duplicate.
Add --dry-run for destructive actions. Agents should be able to preview what a deploy or deletion would do before committing. Let them validate the plan, then run it for real.
--yes / --force to skip confirmations. Humans get "are you sure?" and agents pass --yes to bypass it. Make the safe path the default but allow bypassing.
Predictable command structure. If an agent learns `mycli service list`, it should be able to guess `mycli deploy list` and `mycli config list`. Pick a pattern (resource + verb) and use it everywhere.
Return data on success. Show the deploy ID and the URL. Emojis are cute, but not really needed.
If you're building CLIs that agents will use, these patterns save a lot of debugging time. Most of the work is just making explicit what humans figured out implicitly!
I bet there are many more things that I've forgotten, let me know!