Design and implement command-line interfaces with subcommand-scoped help, actionable success output, and debuggable failure output. Use when creating or modifying CLI commands, argument parsing, help and usage text, exit codes, or command UX for humans and agents.
Build CLIs that stay actionable in both success and failure paths.
--json), print a complete structured success or error object to stdout.0 for success.--json.--dry-run for mutating commands.Use this pattern for each subcommand:
When returning an error, format output in this order:
Success with next step:
Created release r123.
Next: mycli release publish r123
Success without next step:
Published release r123.
No further action required.
Failure with recovery:
Error: failed to publish release r123 (artifact missing).
Known state: release exists, build step did not produce dist/app.tar.gz.
Try: mycli release build r123
Then: mycli release publish r123
Help: mycli help release publish