Pages

Topics

Tools

↑↓navigate↵openescclose
All guides

Python Typer CLI: Commands, Arguments, and Options

Learn how to build a Python Typer CLI with commands, arguments, and options. This guide covers Typer's default-value rule, arguments, options, type conversion, validation, error handling, and app structure.

~4 min readPython
#Python#Typer#CLI Development#Type Hints
Editorial illustration of a terminal window with abstract command, argument, and option blocks representing a Python Typer CLI.

Typer builds a command-line interface directly from a Python function signature. You declare parameters with type hints, and Typer generates the parsing, help text, and validation for you. This guide explains how Typer maps function parameters to CLI commands, arguments, and options, and how to keep that mapping maintainable as a CLI grows.

Building a Minimal Typer CLI

Install Typer with pip:

bash
pip install typer

The smallest useful CLI is a single function passed to typer.run():

python
import typer def main(name: str) -> None: typer.echo(f"Hello {name}") if __name__ == "__main__": typer.run(main)

typer.run() inspects main and maps its parameters to CLI input. The name parameter has no default value, so it becomes a required positional argument. The str type hint tells Typer to accept any text and reject missing input with a clear error. typer.echo() prints to stdout and handles terminal encoding consistently.

A parameter with a default value behaves differently: it becomes an option unless you explicitly declare it with typer.Argument. That default/no-default distinction is the foundation for how Typer separates arguments from options.

Defining Multiple Commands

For more than one operation, create a typer.Typer() instance and decorate each function with @app.command():

python
import typer app = typer.Typer() @app.command() def add(a: int, b: int) -> None: typer.echo(a + b) @app.command() def greet(name: str, formal: bool = False) -> None: if formal: typer.echo(f"Good day, {name}.") else: typer.echo(f"Hi {name}!") if __name__ == "__main__": app()

Each decorated function becomes a subcommand. If the file is saved as cli.py, you invoke it as python cli.py add 2 3 or python cli.py greet Ada. Typer converts function names to kebab-case by default, so a function named send_email becomes the command send-email. The formal parameter defaults to False, so it becomes a --formal / --no-formal flag rather than a positional value.

app() at the bottom runs the CLI, parses sys.argv, and dispatches to the matching command. Typer also generates --help output for the app and for each command automatically.

Working with Arguments

Arguments are positional values that appear after the command name. A parameter without a default is required; a parameter with a default is optional and must be declared after required parameters.

python
import typer def main( source: str, destination: str = typer.Argument(help="Output path"), ) -> None: typer.echo(f"Copy from {source} to {destination}")

Both source and destination are required here. typer.Argument(help=...) adds help text without changing requiredness, because no default value was supplied. If you want an optional argument with a fallback, pass the default explicitly:

python
def main( source: str, destination: str = typer.Argument("out.txt", help="Output path"), ) -> None: typer.echo(f"Copy from {source} to {destination}")

Now destination can be omitted and defaults to out.txt. The Python interpreter requires a parameter with a default value to be declared after any parameter without one, so Typer inherits that constraint.

Configuring Options

Options are named flags and values that start with one or two dashes. In Typer, any parameter with a default value becomes an option unless you explicitly declare it with typer.Argument.

python
import typer def main( name: str, greeting: str = typer.Option("Hello", help="Greeting to use"), uppercase: bool = False, ) -> None: message = f"{greeting}, {name}" if uppercase: message = message.upper() typer.echo(message)

greeting becomes --greeting with a default of Hello. uppercase is a bool, so Typer generates both --uppercase and --no-uppercase flags. This is the standard way to implement boolean switches without requiring a value.

To change the option name or add a short alias:

python
def main( name: str, count: int = typer.Option(1, "--count", "-c", min=1, max=10), ) -> None: typer.echo(f"{name} repeated {count} times")

The first string after the default is the long name, and additional strings are aliases. min and max are validation constraints that Typer applies during parsing, so invalid values fail before your function runs.

Type Conversion and Validation

Type hints control how Typer converts raw strings into Python values. Integers, floats, booleans, and pathlib.Path work directly. For a fixed set of choices, use an Enum:

python
import typer from enum import Enum class LogLevel(str, Enum): debug = "debug" info = "info" warning = "warning" error = "error" def main(level: LogLevel = LogLevel.info) -> None: typer.echo(f"Log level: {level.value}")

Typer builds a choice list from the Enum members and rejects anything outside it. Because LogLevel inherits from str, the values serialize cleanly and compare naturally with strings.

To accept repeated values for one option, annotate it with List[str] and declare it with typer.Option:

python
import typer from typing import List def main(items: List[str] = typer.Option(...)) -> None: for item in items: typer.echo(item)

The option can be repeated, and Typer collects the values into a list. The same pattern works with List[int] or List[Path], and each element is converted according to the inner type.

String and numeric constraints are declared directly on the parameter:

python
def main( port: int = typer.Option(8080, min=1, max=65535), name: str = typer.Option(..., min_length=2, max_length=50), ) -> None: typer.echo(f"Starting on {port} for {name}")

typer.Option(...) with an explicit ellipsis means the option is required even though it is an option. min_length and max_length apply to strings; min and max apply to numbers. Keeping validation in the signature means the function body never sees invalid input.

Error Handling and Exit Codes

Typer does not force a particular error style. You can print to stderr and set the process exit code explicitly:

python
import typer app = typer.Typer() @app.command() def process(path: str) -> None: if not path.endswith(".csv"): typer.echo("File must be a CSV", err=True) raise typer.Exit(code=1) typer.echo(f"Processing {path}") if __name__ == "__main__": app()

typer.echo(..., err=True) writes to stderr instead of stdout, which keeps normal output and diagnostics separate in shell pipelines. typer.Exit(code=1) stops execution immediately and sets the process exit code. For a simpler abort that prints Aborted and exits with code 1, raise typer.Abort().

Validation failures raised by Typer itself also produce non-zero exit codes and readable messages, so you do not need to wrap every parameter in a try/except.

Structuring a Larger CLI for Maintainability

As a CLI grows, keep command groups in separate modules and attach them to a shared app with add_typer:

python
# cli.py import typer from commands import users, reports app = typer.Typer() app.add_typer(users.app, name="users") app.add_typer(reports.app, name="reports") if __name__ == "__main__": app()
python
# commands/users.py import typer app = typer.Typer() @app.command() def list() -> None: typer.echo("user list")

The nested app becomes a command group, so the invocation is python cli.py users list. Each module owns its commands, its validation constraints, and its help text, which keeps the type-hint signatures readable and testable. Because Typer is built on Click, you can also mix in Click decorators and callbacks for behavior that type hints do not express directly, such as an option callback that validates a value before the command runs.

The main maintainability tradeoff is that the type-hint signature is the source of truth for the interface. Keep parsing and validation in the signature rather than inside the function body, and keep side effects in the command functions. That separation makes each command predictable, easy to test by calling the function directly, and easy to extend when a new argument or option is added.

Try matching browser tools

All tools

Small utilities that fit Python work — they run entirely in this browser tab, so nothing you paste leaves your device.

All Python guides

More in Python

All Python guides

The guides filed next to this one in Python, in library order.