cli-development

# CLI Development ## Purpose Build command-line tools that behave the way the shell expects: composable, scriptable, quiet by default, and honest about failure. ## When to Use - Building a developer tool, deployment script, or internal utility with a CLI. - Designing the argument surface of an existing tool. - Making a tool safe to use inside pipelines and CI. ## Capabilities - Argument and subcommand design. - Correct use of stdout, stderr, and exit codes. - Configuration precedence: flags, environment, config file, defaults. - Human output versus machine output (`--json`, TTY detection). - Progress, colour, and interactivity that degrade correctly when piped. ## Inputs - The tasks the tool must perform and who runs it (humans, CI, both). - Whether it will be composed with other tools. - Whether it performs destructive operations. ## Outputs - A command surface that is predictable and discoverable. - Machine-readable output behind a flag. - Exit codes that scripts can branch on. - Help text that answers the question without a web search. ## Workflow 1. **Design the verbs** — Subcommands are verbs on nouns: `tool deploy service`, not `tool --deploy --service`. Group related operations. 2. **Separate the streams** — Results go to stdout. Everything else — progress, warnings, logs — goes to stderr. This is what makes `tool list | grep x` work. 3. **Define the exit codes** — 0 for success, 1 for a general failure, 2 for a usage error. Document any others. 4. **Set th...