CLI Packaging & Distribution

The Pattern

Problem: You want a CLI tool that installs cleanly from a git URL with zero manual steps — no cloning, no virtual env, no PATH fiddling.

Approach: Combine pyproject.toml [project.scripts] with hatchling build backend, a __main__.py dual entry point, and argparse with a default-action subcommand design so mytool and mytool serve do the same thing.

Pattern proven in production across multiple Python CLI tools and web services.

When this skill is NOT the right answer

This skill assumes a pure Python CLI distributed via uv tool install. If your project does not fit that profile, use a different pattern:

If the project IS a pure Python CLI, the rest of this skill applies.

Key Design Decisions

1. Hatchling + [project.scripts] — Not setuptools

Use hatchling as the build backend. The entry point declaration is:

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

Why hatchling: simpler than setuptools, no setup.py, no MANIFEST.in. The [tool.hatch.build.targets.wheel] section lets you exclude test files from the published wheel:

[tool.hatch.build.targets.wheel]
packages = ["my_tool"]
exclude = ["my_tool/tests", "my_tool/frontend/tests"]

2. __main__.py dual entry — python -m always works

Include a minimal __main__.py so the tool works even when the script entry point isn't on PATH:

# my_tool/__main__.py
"""Allow running as: python -m my_tool"""
from my_tool.cli import main
main()

This matters because uv tool install creates a wrapper script, but during development or in edge cases, python -m my_tool is a reliable fallback. Service management code should use this as a fallback too:

def _resolve_tool_bin() -> str:
    which = shutil.which("my-tool")
    if which:
        return which
    return f"{sys.executable} -m my_tool"

3. Default action + subcommands — tool equals tool serve

Use argparse with shared flags on the root parser AND on the serve subcommand, so the bare command runs the server:

def main() -> None:
    parser = argparse.ArgumentParser(prog="my-tool", ...)
    _add_serve_flags(parser)              # flags on root parser
    sub = parser.add_subparsers(dest="command")
    serve_parser = sub.add_parser("serve", help="Start the server (default)")
    _add_serve_flags(serve_parser)        # same flags on 'serve' subcommand

The dispatch at the bottom falls through to serve() when no subcommand is given:

    else:
        serve(host=args.host, port=args.port, ...)

4. 3-tier config resolution: CLI > file > default

The serve() function resolves every setting with the same pattern — CLI flag wins, then settings file, then hardcoded default:

settings = load_settings()
host = host if host is not None else settings.get("host", "127.0.0.1")
port = port if port is not None else settings.get("port", 8088)
log_level = log_level if log_level is not None else settings.get("log_level", "info")

Using None as the argparse default (not a value like "127.0.0.1") is critical — it distinguishes "user didn't pass a flag" from "user explicitly set it."

5. uv tool install git+https://... compatibility

No special config needed — hatchling + [project.scripts] is all uv requires. The install command is:

uv tool install git+https://github.com/yourorg/your-tool

…