Designing a Python command-line tool: argparse, main() and exit codes

Goal

Build a command-line tool that shell scripts, CI jobs and agents can drive: predictable arguments, help text that is the documentation, structured exit codes and clean streams.

Prerequisites

A package with a pyproject.toml (see the packaging article) whose logic lives in importable functions, separate from argument handling.

Steps

1. Write def main(argv: list[str] | None = None) -> int that builds the parser, parses argv (falling back to sys.argv[1:]) and returns an exit code. Register it as [project.scripts] tool = "pkg.cli:main" and add if __name__ == "__main__": sys.exit(main()). Tests then call main(["--flag", "x"]) and assert on the return value and captured output.
2. Build the parser with prog, description and an epilog of examples. Use type= converters (int, pathlib.Path, or a function raising ArgumentTypeError) so that bad values are reported as usage errors, choices= for closed sets, and add_subparsers(dest="command", required=True) for multi-command tools.
3. Follow the convention the sys.exit documentation describes: Unix programs generally use 2 for command-line syntax errors and 1 for all other errors, and 0 is success. argparse already exits with status 2 on invalid arguments. Adopt further codes from sysexits.h (EX_USAGE 64, EX_NOINPUT 66, EX_UNAVAILABLE 69, EX_TEMPFAIL 75) only if --help documents them.
4. Write results to stdout and diagnostics to stderr. Offer --json when other programs consume the output, and --verbose/--quiet that set the logging level rather than sprinkling print.
5. Catch expected failures (FileNotFoundError, connection errors, domain exceptions) in main, print one line to stderr and return the documented code; let unexpected exceptions propagate so the traceback and exit code 1 are preserved.
6. Handle KeyboardInterrupt by cleaning up and returning 130, matching the shell convention of 128 plus the signal number, and swallow BrokenPipeError on stdout so tool | head ends quietly.
7. Keep help honest: metavar for readable placeholders, ArgumentDefaultsHelpFormatter so defaults appear, and a test that --help exits 0.

Expected result

tool --help documents the whole interface; tool --bad; echo $? prints 2; an input problem prints one stderr line and a documented code; a caller can branch on the code without parsing text.

Limits and test basis

The sys.exit documentation notes that most systems require exit codes in the range 0 to 127; values above collide with the shell's signal encoding. exit_on_error=False makes the parser raise ArgumentError instead of exiting, which suits embedding but needs its own error handling. Conventions follow the cited documentation; no usability measurement is claimed.

Exiting after Ctrl-C

A shell decides whether an interrupt should also stop the enclosing script by checking whether the child died from SIGINT, not by reading the exit code. A tool that catches KeyboardInterrupt and returns 130 therefore looks like a normal exit, and for f in *; do tool "$f"; done continues with the next file after every Ctrl-C. Do the cleanup, then end the process the way an unhandled interrupt would (Python has done this by itself since 3.8):

except KeyboardInterrupt:
    cleanup()
    signal.signal(signal.SIGINT, signal.SIG_DFL)
    os.kill(os.getpid(), signal.SIGINT)

$? still reads 130, and a parent that waits on the process sees a signal death. Reserve return 130 for callers known to read codes only.