cli-design
CLI design
A command-line interface is a contract with everyone who calls it: people at a terminal, scripts, CI jobs and agents. Every command name, flag, output shape, exit code and environment variable is part of that contract, and a script somewhere will depend on it the day it ships. A good CLI is predictable: someone who has learned one command can guess the next one, and the help alone is enough to use it.
Produce and present the design through the delivery framework in every session, whether you are designing, explaining, auditing or redesigning, so the user always finds the same things in the same places. The user chooses what the session is for; the framework sets how you lay out the answer. Stop once the user agrees to the design, since building it is done later.
The recurring failure is drift: each command added on its own terms, until the same verb means three things, the same idea has three names, and the help, the docs and the code each list something different. Prevent it by deciding the rules once, for the nouns, the verbs, the flag names and the output and error conventions, and deriving every command and every list a reader sees from them.
To design the code behind the commands, at the level of its modules, classes and folders, use /low-level-design. For a networked API, use /system-design.
Steps
- Restate the session's purpose in one line, read from the request and its context, so a misreading costs one reply: designing a new CLI or new commands, explaining or auditing an existing one, redesigning it, or deciding one question.
- Invoked inside a project with a CLI and no instructions: explain and audit that CLI.
- When the purpose is unclear: ask whether the user wants a new design, an audit of the existing CLI, or a change to it. Check yourself whether the CLI exists.
- Work through the delivery framework below, stage by stage. Read conventions.md when a stage reaches flags, exit codes, environment variables, configuration or the layout of the help.
- Present every stage and revise it with the user until they agree.
- Keep the design where the user wants it.