cli-architecture

CLI Architecture for Python Packages

Not every package needs a CLI, but when it does, the structure and framework choice have long-term consequences for maintenance, discoverability, and user experience. The Python ecosystem has converged on clear patterns -- 7 out of 13 surveyed top packages (httpx, Black, Hatch, Flask, cookiecutter, rich-cli, Typer itself) use Click directly. Typer wraps Click and is gaining adoption for simpler CLIs. argparse remains the choice when zero external dependencies is a hard requirement.

Framework Selection

Choose the CLI framework based on your constraints and complexity:

Your CLI	Use This Framework	Why
Zero dependencies required	argparse (stdlib)	No external deps; used by pytest, pre-commit, Django
Simple-to-moderate, modern Python (3.10+)	Typer	Less boilerplate, leverages type hints, Click underneath
Complex with subcommand groups, plugins, custom types	Click	Battle-tested, explicit decorators, deep customization
Performance-critical tool	Clap (Rust) + maturin	Used by ruff, uv; not a Python CLI at all

What top packages use:

Package	Framework	Reason
Flask, Hatch, Black, httpx, cookiecutter	Click	Complex CLIs, plugin systems, mature ecosystem
fastapi-cli	Typer	Same author, type-hint-driven API
pytest, pre-commit	argparse	Zero-dependency policy
ruff, uv	Clap (Rust)	Performance-critical, not Python CLIs

Click has ~530M monthly downloads; Typer has ~100M and growing. Typer IS Click underneath -- choosing Typer means you are using Click with a type-hint-based API surface. The Python Packaging User Guide now demonstrates Typer as its primary CLI example.

CLI Module Layout

Two patterns, chosen by CLI complexity:

Single cli.py file (small-to-medium CLIs, used by Flask, httpx, pre-commit, fastapi-cli):

src/my_package/
    __init__.py
    __main__.py          # delegates to cli.main()
    cli.py               # all CLI logic here

cli/ directory with subcommand modules (large CLIs, used by Hatch, pip, poetry):

src/my_package/
    __init__.py
    __main__.py          # delegates to cli.main()
    cli/
        __init__.py      # main group, imports subcommands
        build.py         # 'build' subcommand
        publish.py       # 'publish' subcommand
        env/
            __init__.py  # 'env' subcommand group
            create.py
            remove.py

Start with cli.py. Migrate to cli/ when subcommands exceed 3-4 or when individual subcommands are complex enough to warrant their own modules.

__main__.py for python -m Support

Every package with a CLI should provide __main__.py so users can run python -m my_package. The file purely delegates -- it never contains CLI logic.

"""Allow running as: python -m my_package"""

from my_package.cli import main

raise SystemExit(main())

Key conventions:

• Use raise SystemExit(main()) instead of sys.exit(main()) -- avoids importing sys and works the same way
• The main() function must return an integer exit code (0 = success, 1 = error, 2 = usage error)
• [project.scripts] and __main__.py must call the same function -- users expect identical behavior from my-cli and python -m my_package

Entry Point Registration

Register the CLI via [project.scripts] in pyproject.toml (see pyproject-toml skill for the full entry points section):

[project.scripts]
my-cli = "my_package.cli:main"

The entry point and __main__.py point to the same main() function:

Invocation	Mechanism	Calls
my-cli	[project.scripts] entry point	my_package.cli:main()
python -m my_package	__main__.py	my_package.cli:main()

Exit Code Handling

Click-based packages: Click handles exit codes automatically in standalone_mode=True (the default). ctx.exit(code) or raising click.exceptions.Exit(code) propagates to sys.exit(). Exit code 0 = success, 2 = usage error (bad arguments).

Typer-based packages: Uses raise typer.Exit(code=N) which delegates to Click's exit mechanism underneath.

argparse-based packages: Return an integer from main(), and __main__.py calls raise SystemExit(main()).

All frameworks follow the same convention:

Exit Code	Meaning	When
0	Success	Command completed normally
1	Error	Runtime failure (network error, file not found, validation failure)
2	Usage error	Bad arguments, missing required options

Anti-Patterns

Anti-Pattern	Consequence
CLI logic in __main__.py	Cannot be imported or tested independently
sys.exit() scattered throughout CLI code	Hard to test, bypasses cleanup
[project.scripts] and __main__.py calling different functions	Users get different behavior depending on invocation
Missing __main__.py	python -m package does not work
Mixing Click and argparse in the same package	Inconsistent argument parsing, confusing error messages

Review Checklist

When reviewing a Python package CLI:

• CLI framework chosen appropriately (argparse for zero-deps, Typer for simple, Click for complex)
• CLI logic lives in cli.py or cli/ directory, not in __init__.py or __main__.py
• __main__.py exists and purely delegates to cli.main()
• [project.scripts] and __main__.py call the same function
• main() returns an integer exit code
• __main__.py uses raise SystemExit(main()), not sys.exit(main())
• Subcommands organized in separate modules when CLI grows beyond 3-4 commands