cli-development

# CLI Development Build CLIs that stay actionable in both success and failure paths. ## Core Principles 1. Avoid dead ends. - Print next steps when a reasonable next action exists. - On terminal completion, state that no further action is required. 2. Make failures diagnosable. - Print known state, failed operation, and likely cause. - Include recovery commands and focused help text. - Include usage text for argument or syntax errors. 3. Keep output minimal and context-efficient. - Use short defaults. - Show detail only when requested by flags or when needed to recover from failure. 4. Scope help to subcommands. - Keep root help high-level. - Put detailed flags, examples, and edge cases in subcommand help. ## Command Contract 1. Keep output deterministic. - Use stable wording and field names. - Avoid random ordering in lists. 2. Use conventional stream behavior. - Write primary result data to stdout. - Write diagnostics, warnings, and human-oriented guidance to stderr. - In machine mode (`--json`), print a complete structured success or error object to stdout. - Document that automation should capture both stdout and stderr for full logs. 3. Return meaningful exit codes. - `0` for success. - Non-zero codes map to clear failure classes. 4. Support automation. - Add machine-readable output mode such as `--json`. - Keep human-readable output as the default. 5. Support safe execution. - Add `--dry-run` for mutating ...