How do you expose a CLI command from a Python package?

Short answer

Define a console script in [project.scripts] inside pyproject.toml pointing to a main function, and installing creates an executable with that name in the environment's bin.

Explanation

The entry point separates the command name from the internal code path, and works on every operating system without writing a shebang or .bat files. Make main return an exit code and use argparse or a library such as Typer or Click, and do not run any logic at import time. You can also support python -m my_tool by adding __main__.py.

Code example

# pyproject.toml
[project.scripts]
invoice = "billing.cli:main"

# src/billing/cli.py
import argparse

def main() -> int:
    parser = argparse.ArgumentParser(prog="invoice")
    parser.add_argument("order_id", type=int)
    args = parser.parse_args()
    print(f"creating invoice for {args.order_id}")
    return 0

Common mistakes

• Running CLI logic at the top level of the module, so it runs on any import.
• Asking users to run python path/to/script.py instead of defining an entry point.

Follow-up questions

• Why do we use if __name__ == "__main__"?
• What is the role of the pyproject.toml file?

Sources

• Python Packaging User Guide — Creating command line tools