Do not dump the full manual up front. Let the top-level command list subcommands and make the AI agentAn AI system that doesn't just answer once but works toward a goal in a loop — taking actions, reading the results, and deciding what to do next.Full definition → drill into the one it picked, so it spends no context windowThe maximum amount of text a model can consider at once — its working memory for the current conversation or task.Full definition → reading about commands it will never run.
Examples do most of the work in a help page. An agent pattern-matches off a full sample invocation faster than it reads a prose description of each flag.
Pick one naming pattern — resource then verb — and apply it everywhere. An agent that learns one command can then guess the ones it has never seen instead of hunting through help output.
Return usable data on success, like the deploy ID and the URL. Agents chain commands, so the output of one is the input of the next. Emoji and celebration text are noise in that pipeline.
Terms in this piece · Glossary
AI agent — An AI system that doesn't just answer once but works toward a goal in a loop — taking actions, reading the results, and deciding what to do next.
context window — The maximum amount of text a model can consider at once — its working memory for the current conversation or task.
Why it matters
Design patterns for CLIs that agents can actually drive — non-interactive, predictable, machine-readable output. Essential if you are exposing tools to agents and wondering why they keep getting stuck on your prompts.
Key quotes
“Most CLIs were built assuming a human is at the keyboard.”
“An agent pattern-matches off mycli deploy --env staging --tag v1.2.3 faster than it reads a description.”
“Most of the work is just making explicit what humans figured out implicitly!”
