code-review-cli

CLI Application Code Review Patterns

Stack-specific rules loaded by dh:code-reviewer when CLI entrypoints are detected (argparse, click, typer, commander.js, or similar argument parsing libraries).

Load /dh:review-principles before applying these checks. Establish the command's supported platforms and human/machine output contracts before prescribing an exact flag or exit code.

Exit Codes

• Verify exit status distinguishes success from failure under the documented command contract, including partial-success or best-effort modes where supported.
• Report success status after a required operation failed when callers cannot detect that failure; distinguish an overall failure from a documented recoverable warning.
• Common conventions: 1 for general errors, 2 for usage/argument errors, 3+ for application-specific codes documented in --help
• Verify fatal paths reach a non-zero exit through the framework or explicit exit handling; printing to stderr alone is not a failure signal for a caller that checks exit status.

# WRONG: exits 0 even on error
def main():
    try:
        run()
    except Exception as e:
        print(f"Error: {e}", file=sys.stderr)
    # implicit exit 0


# RIGHT: non-zero on error
def main():
    try:
        run()
    except Exception as e:
        print(f"Error: {e}", file=sys.stderr)
        sys.exit(1)

Help and Version Flags

• Check that supported help/version interfaces are discoverable and usable by their intended callers; use --help and --version as conventions for new human-facing commands.
• Verify help describes the actual options and examples, and version output agrees with the installed/distributed package's version source.
• Help text must be consistent with actual behavior — stale help text is a blocking finding
• Supported help and version requests must report success when they complete successfully.

stdin / stdout / stderr Separation

• Progress indicators, status messages, and diagnostic output go to stderr
• Data output (results to be piped or redirected) goes to stdout
• Mixing diagnostic messages into stdout breaks pipe usage — this is a blocking finding for tools that produce structured output
• Error messages go to stderr with a non-zero exit code