Typer

Typer is a Python library for building command-line interface applications that are easy to write and pleasant to use. Instead of a separate declarative API for arguments and options, Typer reads your function’s regular Python type hints and derives the CLI surface from them: parameter names become option flags, type annotations drive parsing and validation, and default values become defaults. Adding a CLI to an existing script is typically a two-line change — one import and one function call.

Built by the same author as FastAPI and following the same design philosophy, Typer is often described as “the FastAPI of CLIs.” It layers on top of Click’s proven command-parsing model but ships its own maintained internal fork of it (typer._click) rather than depending on the external click package, giving the project full control over its parsing internals. Typer also includes a standalone typer command that can run any Python script as a CLI — even scripts that don’t import Typer at all — by inspecting function signatures directly.

Beyond the basics, Typer supports arbitrarily nested command trees (subcommands and groups of subcommands), rich-formatted help and tracebacks via the rich library, automatic shell completion for Bash/Zsh/Fish/PowerShell, and a dedicated typer.testing module for exercising CLI apps in test suites without spawning subprocesses.

What You Get

• Automatic CLI generation from function signatures and type hints, with no separate parser declarations to maintain
• Rich-formatted help screens, error messages, and tracebacks powered by the rich library, enabled by default
• Automatic shell completion for Bash, Zsh, Fish, and PowerShell, installable with a single flag
• Support for arbitrarily deep command trees — subcommands and groups of subcommands — for growing a CLI as complexity increases
• A standalone typer command that can run any Python script as a CLI, even one that doesn’t import Typer
• A typer.testing module (CliRunner) for invoking commands and asserting on output/exit codes directly in test suites

Common Use Cases

• Turning an internal automation script into a proper CLI tool with help text and validated arguments in a couple of lines
• Building the command-line entry point for a Python package that also ships a library API
• Creating multi-command developer tools (database migrations, deployment scripts, data pipelines) with nested subcommand groups
• Adding shell autocompletion to an existing tool so users get tab-completion for commands, options, and choices
• Prototyping CLIs quickly during development using the typer run command before wiring a formal entry point

Under The Hood

Architecture Typer’s core is a translation layer between plain Python function signatures and a command-parsing engine: typer.main.Typer (typer/main.py, ~2,000 lines) collects registered callbacks via @app.command()/@app.callback(), inspects each function’s parameters with inspect and get_type_hints, and converts them into TyperArgument/TyperOption/TyperCommand/TyperGroup objects defined in typer/core.py. Rather than depending on the external click package, Typer vendors and maintains its own internal fork under typer/_click/ (parser, formatting, shell completion, terminal UI) — so all output parsing, argument dispatch, and help rendering flow through code the project owns outright. typer/models.py and typer/params.py define the intermediate representations (ArgumentInfo, OptionInfo, ParameterInfo) that bridge a function’s type hints to the underlying command objects, and typer/completion.py handles shell-completion wiring. This is a layered design: user-facing decorators → signature inspection → internal parameter model → vendored parsing engine.

Tech Stack Typer targets Python 3.10+ and declares only three runtime dependencies in pyproject.toml: shellingham (shell detection for completion), rich (formatted help/tracebacks/errors, on by default), and annotated-doc (for Annotated[...] metadata support), plus colorama on Windows. It builds with pdm-backend and is fully typed (py.typed marker, mypy --strict, and the newer ty type checker both run in CI). The project uses ruff for linting, pytest with pytest-xdist/pytest-cov for testing, and uv as the recommended installer/dev workflow. Documentation is built with mkdocs/zensical and deployed via GitHub Actions, with a large docs_src/ directory (300+ example scripts) that doubles as both documentation source and test fixtures.

Code Quality The repository ships an extensive test suite (roughly 200+ test functions across tests/, covering arguments, options, subcommands, completion, testing utilities, and edge cases like ambiguous parameters), run under pytest --strict-config --strict-markers with warnings promoted to errors. mypy --strict and ty both gate the codebase in CI, and ruff enforces a fairly wide lint rule set (pycodestyle, pyflakes, isort, bugbear, comprehensions, pyupgrade). GitHub Actions workflows cover testing across CPython versions (including nightly), pre-commit checks, dependency guarding, and a security-focused zizmor workflow for the CI config itself — indicating an unusually mature CI/quality posture for a library of this size.

What Makes It Unique Typer’s core idea — deriving a full CLI (arguments, options, validation, help, completion) purely from a function’s existing type hints — sets it apart from parser-declaration libraries like argparse or raw Click, where the CLI surface is described separately from the function it wires up. Its most distinctive engineering decision is vendoring its own internal fork of Click (typer._click) instead of depending on the external package, decoupling Typer’s release cadence and behavior guarantees from upstream Click changes while still reusing its proven parsing model. The standalone typer runner command — which can execute arbitrary undecorated scripts as CLIs by inspecting their signatures — is also unusual among CLI frameworks, most of which require explicit framework integration before a script becomes runnable as a CLI.