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

Exit Codes

• Exit code 0 must be returned only on success — any error condition must produce a non-zero exit code
• Returning exit code 0 after printing an error message is a blocking finding — tools in pipelines cannot detect the failure
• Common conventions: 1 for general errors, 2 for usage/argument errors, 3+ for application-specific codes documented in --help
• sys.exit(1) or process.exit(1) must be called on fatal errors, not just printing to stderr

# 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

• --help must be present and print usage information, option descriptions, and examples — the auto-generated help from argparse/click/typer is acceptable as a minimum
• --version must be present and print the version string matching pyproject.toml or package.json
• Help text must be consistent with actual behavior — stale help text is a blocking finding
• --help must exit 0; --version must exit 0

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

Non-Interactive Operation

• Every interactive prompt (input(), readline, inquirer) must have a corresponding flag alternative (--flag value) for use in CI and scripts
• Interactive prompts that block in non-TTY environments (piped input, CI) are a blocking finding
• Detect TTY with sys.stdin.isatty() or equivalent and skip interactive prompts in non-TTY mode