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.

1. 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.

1. Keep output minimal and context-efficient.

• Use short defaults.
• Show detail only when requested by flags or when needed to recover from failure.

1. 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.

1. 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.

1. Return meaningful exit codes.

• 0 for success.
• Non-zero codes map to clear failure classes.

1. Support automation.

• Add machine-readable output mode such as --json.
• Keep human-readable output as the default.

1. Support safe execution.

• Add --dry-run for mutating commands.
• Make retry behavior explicit.

Help and Error Pattern

Use this pattern for each subcommand:

1. One-line purpose.
2. Usage line.
3. Required arguments.
4. Optional flags.
5. Examples, including one failure-recovery example.

When returning an error, format output in this order:

1. Error summary.
2. Known state.
3. Recovery options.
4. Exact next command.
5. Relevant subcommand help hint.

Output Templates

Success with next step:

text
Created release r123.
Next: mycli release publish r123

Success without next step:

text
Published release r123.
No further action required.

Failure with recovery:

text
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

Implementation Checklist

• Define root command and subcommand boundaries.
• Write subcommand help before command logic.
• Implement parser and validate required arguments.
• Implement success and failure output contracts.
• Verify stream contract: parseable payloads on stdout, diagnostics on stderr.
• Add tests for success, parser errors, and runtime failures.
• Verify each failure path includes state and next steps.