A Checklist for Every Tool You Ship
When you finish writing a CLI tool, run through this checklist before calling it production-ready. Each item corresponds to a practice covered in this lesson.
Interface Design
- [ ] Arguments are parsed with a library, not manually from sys.argv or $1.
- [ ] Both short (-v) and long (--verbose) flag forms are provided where appropriate.
- [ ] --help / -h prints usage and exits 0.
- [ ] --version prints the version and exits 0.
- [ ] The -- separator is supported (handled automatically by most parsing libraries).
Configuration
- [ ] Configuration follows the precedence hierarchy: defaults → config file → env vars → flags.
- [ ] Environment variables the tool respects are documented in --help output.
Output
- [ ] Data goes to stdout; errors, warnings, and progress go to stderr.
- [ ] A --json flag provides structured output for machine consumers.
- [ ] Color codes are only emitted when writing to a terminal (isatty() check).
Safety
- [ ] Destructive operations prompt for confirmation interactively.
- [ ] A --yes or --force flag skips confirmation for automation.
- [ ] A --dry-run flag shows what would happen without doing it.
Exit Codes
- [ ] Success exits 0.
- [ ] All failure paths exit non-zero.
- [ ] Specific exit codes are defined and documented for distinct failure modes.
- [ ] Errors are printed to stderr before exiting non-zero.
Signals
- [ ] SIGINT (Ctrl+C) is handled gracefully with cleanup.
- [ ] SIGTERM is handled for containerized environments.
- [ ] Ctrl+C exits with code 130.
A tool that passes this checklist is ready for production pipelines, team use, and the kind of operational scrutiny that comes with being on-call.