Typer Python
Build a CLI as a stable user-facing protocol: command path, parameter spelling,
types, defaults, streams, exit codes, help, side effects, and tests are its
contract.
Boundary
Use this skill when the project imports Typer or the user explicitly requests a
Typer CLI. Keep domain operations in ordinary Python functions and let command
functions adapt terminal input/output to them. Do not introduce Typer for a
library API, a Click-only project, a one-off shell invocation, or Rich-only
rendering. Use Rich guidance separately when terminal presentation itself is
the job.
Know the runtime objects
| Object |
Meaning |
Responsibility |
typer.Typer |
Command registry and root/group configuration |
Own commands, callbacks, sub-apps, and help behavior. |
| Command function |
Type-annotated adapter called after parsing |
Validate command-level invariants, call domain code, emit output, map failures. |
Annotated[T, typer.Argument(...)] |
Positional CLI field |
Required ordered input whose position is natural and stable. |
Annotated[T, typer.Option(...)] |
Named CLI field |
Optional/configuration input, flags, secrets, repeatable values, or a required named field. |
typer.Context |
One invocation's Click/Typer state |
Shared object state, invoked subcommand, raw extra arguments only when explicitly allowed. |
CliRunner result |
Captured invocation outcome |
Assert exit code, stdout/stderr-visible output, exception, and side effects. |
Read the command object model before changing a
single-command app into groups, adding callbacks, or passing shared state.
Ordered workflow
- Recover the public command contract from documentation, entry points,
existing invocations, completion, and tests. Preserve names and exit behavior
unless the task explicitly changes them.
- Separate pure domain work from the command adapter. Do not unit-test domain
behavior only through terminal text.
- Choose command topology first: one command, several peer commands, or nested
sub-apps. Do not add a callback merely to make help look different.
- Classify every field as argument or option, then specify its Python type,
required/default state, aliases, validation, environment source, and
sensitivity.
- Map expected user errors to concise CLI errors and nonzero exits. Let
unexpected defects retain useful diagnostics; never print secrets or local
values in production tracebacks.
- Test help, success, invalid input, and one side-effect boundary with
CliRunner. Test the domain function directly as well.
- Run the real installed entry point, not only
python module.py, before
declaring completion.
Parameter decisions
| Condition |
Use |
A value is the primary ordered subject (FILE, NAME) |
Argument |
| A value configures behavior or should be self-describing |
Option |
| Omission means a meaningful default |
Option with an explicit default |
| The user must supply a named value |
Required option; do not encode a fake sentinel default |
| Exactly two states exist |
Boolean flag, with positive/negative spelling when both matter |
| Values come from a closed set |
Enum/Literal supported by the installed Typer version |
| A filesystem precondition is structural |
Path plus exists, file/dir, readable/writable constraints |
| Validation depends on another field or external state |
Validate in the command adapter/domain boundary, not an isolated parameter callback |
| Input is secret |
Hidden prompt or environment/config source; never echo it |
Prefer typing.Annotated metadata on Python 3.11+. Keep Python defaults as the
source of default/required semantics. Do not blindly copy legacy
name: str = typer.Option(...) syntax from a prompt; inspect the installed
version when editing older code.
Canonical anchor
from pathlib import Path
from typing import Annotated
import typer
app = typer.Typer(no_args_is_help=True)
@app.callback()
def main() -> None:
"""File export commands."""
@app.command()
def export(
source: Annotated[Path, typer.Argument(exists=True, dir_okay=False)],
output: Annotated[Path, typer.Option("--output", "-o")],
force: Annotated[bool, typer.Option("--force/--no-force")] = False,
) -> None:
if output.exists() and not force:
raise typer.BadParameter("output exists; pass --force", param_hint="--output")
export_file(source, output)
typer.echo(str(output))
if __name__ == "__main__":
app()
The callback keeps export as a named subcommand; without it, Typer can promote
a sole command function to the root invocation. typer.Exit(code=...)
represents an intentional termination, not a returned
process code. BadParameter is for actionable user input errors. Do not catch
Exception and convert programmer defects into a friendly success-looking
message.
Groups, callbacks, and state
- Use one root
Typer and add_typer for a coherent noun namespace such as
users create; do not nest a single command without a stable grouping need.
- A group callback runs before its subcommand. Keep it cheap and free of
irreversible side effects. If
invoke_without_command=True, branch on
ctx.invoked_subcommand is None when root-only behavior must not also run for
subcommands.
- Put shared invocation state in a typed object assigned to
ctx.obj; do not
use module globals for per-invocation configuration.
- Parameter callbacks also run during completion. They must not print, mutate
durable state, or perform expensive network work.
- Enable unknown/extra arguments only for an intentional pass-through command;
otherwise preserve parser rejection.
Read design and testing rules for composition,
error handling, entry points, and CliRunner assertions.
Verification
Inspect the installed version with importlib.metadata.version("typer") and
the installed signatures when
a parameter or help behavior may drift; read version grounding.
Completion requires: the packaged entry point resolves; --help and no-args
behavior are intentional; aliases, defaults, env sources, and secret handling
match the contract; invalid input exits nonzero without a traceback; success
uses the correct output stream and exit code; side effects happen exactly once;
and tests invoke the Typer app with representative arguments rather than
calling only command functions directly.
References
- Command object model
- CLI design and testing
- Version grounding
1---2name: typer-python3description: Use for writing, reviewing, debugging, or testing Python command-line interfaces built with Typer, including typed arguments and options, command groups, callbacks, contexts, exit behavior, help, and CliRunner tests. Do not use merely for terminal styling, arbitrary business logic, a Click-only CLI, shell scripts, or invoking an existing command.4argument-hint: "[Typer CLI task, code, error, or command contract]"5metadata:6 source: https://skillmd.com/skills/schattenspiegel/typer-python7---89# Typer Python1011Build a CLI as a stable user-facing protocol: command path, parameter spelling,12types, defaults, streams, exit codes, help, side effects, and tests are its13contract.1415## Boundary1617Use this skill when the project imports Typer or the user explicitly requests a18Typer CLI. Keep domain operations in ordinary Python functions and let command19functions adapt terminal input/output to them. Do not introduce Typer for a20library API, a Click-only project, a one-off shell invocation, or Rich-only21rendering. Use Rich guidance separately when terminal presentation itself is22the job.2324## Know the runtime objects2526| Object | Meaning | Responsibility |27|---|---|---|28| `typer.Typer` | Command registry and root/group configuration | Own commands, callbacks, sub-apps, and help behavior. |29| Command function | Type-annotated adapter called after parsing | Validate command-level invariants, call domain code, emit output, map failures. |30| `Annotated[T, typer.Argument(...)]` | Positional CLI field | Required ordered input whose position is natural and stable. |31| `Annotated[T, typer.Option(...)]` | Named CLI field | Optional/configuration input, flags, secrets, repeatable values, or a required named field. |32| `typer.Context` | One invocation's Click/Typer state | Shared object state, invoked subcommand, raw extra arguments only when explicitly allowed. |33| `CliRunner` result | Captured invocation outcome | Assert exit code, stdout/stderr-visible output, exception, and side effects. |3435Read [the command object model](references/object-model.md) before changing a36single-command app into groups, adding callbacks, or passing shared state.3738## Ordered workflow39401. Recover the public command contract from documentation, entry points,41 existing invocations, completion, and tests. Preserve names and exit behavior42 unless the task explicitly changes them.432. Separate pure domain work from the command adapter. Do not unit-test domain44 behavior only through terminal text.453. Choose command topology first: one command, several peer commands, or nested46 sub-apps. Do not add a callback merely to make help look different.474. Classify every field as argument or option, then specify its Python type,48 required/default state, aliases, validation, environment source, and49 sensitivity.505. Map expected user errors to concise CLI errors and nonzero exits. Let51 unexpected defects retain useful diagnostics; never print secrets or local52 values in production tracebacks.536. Test help, success, invalid input, and one side-effect boundary with54 `CliRunner`. Test the domain function directly as well.557. Run the real installed entry point, not only `python module.py`, before56 declaring completion.5758## Parameter decisions5960| Condition | Use |61|---|---|62| A value is the primary ordered subject (`FILE`, `NAME`) | `Argument` |63| A value configures behavior or should be self-describing | `Option` |64| Omission means a meaningful default | Option with an explicit default |65| The user must supply a named value | Required option; do not encode a fake sentinel default |66| Exactly two states exist | Boolean flag, with positive/negative spelling when both matter |67| Values come from a closed set | `Enum`/`Literal` supported by the installed Typer version |68| A filesystem precondition is structural | `Path` plus `exists`, file/dir, readable/writable constraints |69| Validation depends on another field or external state | Validate in the command adapter/domain boundary, not an isolated parameter callback |70| Input is secret | Hidden prompt or environment/config source; never echo it |7172Prefer `typing.Annotated` metadata on Python 3.11+. Keep Python defaults as the73source of default/required semantics. Do not blindly copy legacy74`name: str = typer.Option(...)` syntax from a prompt; inspect the installed75version when editing older code.7677## Canonical anchor7879```python80from pathlib import Path81from typing import Annotated8283import typer8485app = typer.Typer(no_args_is_help=True)868788@app.callback()89def main() -> None:90 """File export commands."""919293@app.command()94def export(95 source: Annotated[Path, typer.Argument(exists=True, dir_okay=False)],96 output: Annotated[Path, typer.Option("--output", "-o")],97 force: Annotated[bool, typer.Option("--force/--no-force")] = False,98) -> None:99 if output.exists() and not force:100 raise typer.BadParameter("output exists; pass --force", param_hint="--output")101 export_file(source, output)102 typer.echo(str(output))103104105if __name__ == "__main__":106 app()107```108109The callback keeps `export` as a named subcommand; without it, Typer can promote110a sole command function to the root invocation. `typer.Exit(code=...)`111represents an intentional termination, not a returned112process code. `BadParameter` is for actionable user input errors. Do not catch113`Exception` and convert programmer defects into a friendly success-looking114message.115116## Groups, callbacks, and state117118- Use one root `Typer` and `add_typer` for a coherent noun namespace such as119 `users create`; do not nest a single command without a stable grouping need.120- A group callback runs before its subcommand. Keep it cheap and free of121 irreversible side effects. If `invoke_without_command=True`, branch on122 `ctx.invoked_subcommand is None` when root-only behavior must not also run for123 subcommands.124- Put shared invocation state in a typed object assigned to `ctx.obj`; do not125 use module globals for per-invocation configuration.126- Parameter callbacks also run during completion. They must not print, mutate127 durable state, or perform expensive network work.128- Enable unknown/extra arguments only for an intentional pass-through command;129 otherwise preserve parser rejection.130131Read [design and testing rules](references/design-testing.md) for composition,132error handling, entry points, and `CliRunner` assertions.133134## Verification135136Inspect the installed version with `importlib.metadata.version("typer")` and137the installed signatures when138a parameter or help behavior may drift; read [version grounding](references/version-grounding.md).139Completion requires: the packaged entry point resolves; `--help` and no-args140behavior are intentional; aliases, defaults, env sources, and secret handling141match the contract; invalid input exits nonzero without a traceback; success142uses the correct output stream and exit code; side effects happen exactly once;143and tests invoke the `Typer` app with representative arguments rather than144calling only command functions directly.145146## References147148- [Command object model](references/object-model.md)149- [CLI design and testing](references/design-testing.md)150- [Version grounding](references/version-grounding.md)