narumiruna/python-typer

Python CLI with Typer

Overview

Use Typer for ergonomic CLI construction. Core principle: keep command wiring thin, explicit, and testable while moving business logic into regular Python functions.

Use When

• Building a Python CLI with Typer.
• Adding commands, arguments, options, prompts, or confirmations.
• Wiring a module entry point or console script.
• Testing CLI behavior separately from business logic.

Install

uv add typer

Quick Reference

| Task | Pattern | | --- | --- | | Single command | @app.command() | | Options | function args with defaults | | Multiple commands | multiple @app.command() | | Module run | uv run python -m <package>.cli --help | | Script run | uv run python cli.py --help | | CLI tests | CliRunner().invoke(app, [...]) |

Workflow

• Define a typer.Typer() app in cli.py.
• Keep command functions small; move business logic into separate modules.
• Wire either if __name__ == "__main__": app() for script/module execution or a project console script in pyproject.toml.
• Run CLI via uv run python -m <module> or uv run python cli.py.
• Test command parsing and exit behavior with typer.testing.CliRunner.
• Test business logic directly with normal function tests.

Example

import typer

app = typer.Typer()

@app.command()
def greet(name: str, count: int = 1) -> None:
    for _ in range(count):
        typer.echo(f"Hello, {name}!")

if __name__ == "__main__":
    app()

Usage:

uv run python cli.py --help
uv run python cli.py Alice
uv run python cli.py Alice --count 3

Module entry point:

uv run python -m my_package.cli --help

Multiple commands:

import typer

app = typer.Typer()


@app.command()
def create(name: str) -> None:
    """Create a new item."""
    typer.echo(f"Creating {name}...")


@app.command()
def delete(name: str, force: bool = False) -> None:
    """Delete an item."""
    if not force:
        if not typer.confirm(f"Delete {name}?"):
            raise typer.Abort()
    typer.echo(f"Deleted {name}")


if __name__ == "__main__":
    app()

CLI test:

from typer.testing import CliRunner

from my_package.cli import app

runner = CliRunner()


def test_greet() -> None:
    result = runner.invoke(app, ["Alice", "--count", "2"])

    assert result.exit_code == 0
    assert "Hello, Alice!" in result.stdout

Common Mistakes

• Putting heavy business logic inside CLI functions.
• Forgetting to wire if __name__ == "__main__" for script entry.
• Testing only the underlying functions and missing CLI parsing or exit-code behavior.
• Adding shell parsing manually instead of using Typer arguments and options.

Red Flags

• CLI guidance that ignores Typer when Typer is the chosen framework.
• CLI commands that cannot be run through uv run.