# tiangolo/typer architecture

> Architecture diagram of the GitHub repository tiangolo/typer, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/tiangolo/typer
- Repository: https://github.com/tiangolo/typer

## Overview

Typer is a Python library and command-line tool for building and running type-hint-driven CLI applications. In the main workflow, an application registers commands and parameters, then the CLI parses terminal input, converts values, invokes the selected callback, and presents output or errors. The same runtime supplies nested commands, help, shell completion, prompts, and rich terminal formatting; its `typer` command can also turn ordinary scripts into CLIs. Relationships for unsampled modules are included only where the source index or README supports them.

Main entry points: [`typer/core.py`](https://github.com/tiangolo/typer/blob/master/typer/core.py) (CLI Dispatch), [`typer/_click/core.py`](https://github.com/tiangolo/typer/blob/master/typer/_click/core.py) (Command Context), [`typer/main.py`](https://github.com/tiangolo/typer/blob/master/typer/main.py) (Typer App API), [`typer/_click/termui.py`](https://github.com/tiangolo/typer/blob/master/typer/_click/termui.py) (Terminal Interaction)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["App Definition"]
  node_app_api["Typer App API<br/>[main.py]"]
  node_declarations["Command Metadata<br/>[models.py]"]
  node_parameters["Parameter Declarations<br/>[params.py]"]
end

subgraph group_runtime["CLI Runtime"]
  node_entry["App Builder<br/>[main.py]"]
  node_cli["CLI Dispatch<br/>[core.py]"]
  node_callbacks["Command Callback<br/>[main.py]"]
  node_errors["CLI Errors<br/>[exceptions.py]"]
end

subgraph group_features["CLI Features"]
  node_completion["Shell Completion<br/>[completion.py]"]
  node_completion_shared["Completion Logic"]
  node_help["Help Formatting<br/>[rich_utils.py]"]
  node_terminal["Terminal Interaction<br/>[termui.py]"]
  node_script_cli["Script Runner<br/>[cli.py]"]
end

subgraph group_internal["Click Internals"]
  node_parser["Argument Parser<br/>[parser.py]"]
  node_click_core["Command Context<br/>[core.py]"]
  node_types["Value Conversion<br/>[types.py]"]
  node_file_types["File Parameters<br/>[types.py]"]
  node_text_utils["Terminal Utilities<br/>[utils.py]"]
  node_context_state["Context State<br/>[globals.py]"]
  node_formatting["Text Formatting<br/>[formatting.py]"]
  node_click_errors["Click Exceptions<br/>[exceptions.py]"]
  node_compat["Platform Streams<br/>[_compat.py]"]
  node_typing["Typing Support<br/>[_typing.py]"]
end

node_developer(("Application Author"))
node_shell(("Terminal User"))

node_developer -->|"defines commands"| node_app_api
node_app_api -->|"registers metadata"| node_declarations
node_app_api -->|"declares parameters"| node_parameters
node_shell -->|"provides arguments"| node_cli
node_app_api -->|"runs app"| node_entry
node_entry -->|"builds commands"| node_cli
node_cli -->|"dispatches through"| node_click_core
node_click_core -->|"parses arguments"| node_parser
node_parser -->|"converts values"| node_types
node_cli -.->|"invokes command"| node_callbacks
node_cli -->|"raises errors"| node_errors
node_cli -->|"handles completion"| node_completion
node_completion -->|"uses shared logic"| node_completion_shared
node_completion_shared -->|"reads context"| node_context_state
node_cli -->|"renders help"| node_help
node_cli -->|"supports prompts"| node_terminal
node_terminal -->|"raises usage errors"| node_click_errors
node_terminal -->|"writes terminal text"| node_text_utils
node_cli -->|"accepts file values"| node_file_types
node_shell -->|"runs script"| node_script_cli
node_script_cli -->|"creates CLI app"| node_app_api
node_click_core -->|"manages context"| node_context_state
node_click_core -->|"uses exceptions"| node_click_errors
node_click_core -->|"formats help"| node_formatting
node_click_core -->|"uses utilities"| node_text_utils
node_types -->|"uses stream support"| node_compat
node_cli -->|"uses typing helpers"| node_typing
node_help -->|"renders metadata"| node_declarations

click node_app_api "https://github.com/tiangolo/typer/blob/master/typer/main.py"
click node_declarations "https://github.com/tiangolo/typer/blob/master/typer/models.py"
click node_parameters "https://github.com/tiangolo/typer/blob/master/typer/params.py"
click node_entry "https://github.com/tiangolo/typer/blob/master/typer/main.py"
click node_cli "https://github.com/tiangolo/typer/blob/master/typer/core.py"
click node_parser "https://github.com/tiangolo/typer/blob/master/typer/_click/parser.py"
click node_click_core "https://github.com/tiangolo/typer/blob/master/typer/_click/core.py"
click node_types "https://github.com/tiangolo/typer/blob/master/typer/_click/types.py"
click node_callbacks "https://github.com/tiangolo/typer/blob/master/typer/main.py"
click node_errors "https://github.com/tiangolo/typer/blob/master/typer/exceptions.py"
click node_completion "https://github.com/tiangolo/typer/blob/master/typer/completion.py"
click node_completion_shared "https://github.com/tiangolo/typer/blob/master/typer/_completion_shared.py"
click node_help "https://github.com/tiangolo/typer/blob/master/typer/rich_utils.py"
click node_terminal "https://github.com/tiangolo/typer/blob/master/typer/_click/termui.py"
click node_file_types "https://github.com/tiangolo/typer/blob/master/typer/_click/types.py"
click node_script_cli "https://github.com/tiangolo/typer/blob/master/typer/cli.py"
click node_text_utils "https://github.com/tiangolo/typer/blob/master/typer/_click/utils.py"
click node_context_state "https://github.com/tiangolo/typer/blob/master/typer/_click/globals.py"
click node_formatting "https://github.com/tiangolo/typer/blob/master/typer/_click/formatting.py"
click node_click_errors "https://github.com/tiangolo/typer/blob/master/typer/_click/exceptions.py"
click node_compat "https://github.com/tiangolo/typer/blob/master/typer/_click/_compat.py"
click node_typing "https://github.com/tiangolo/typer/blob/master/typer/_typing.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_app_api,node_declarations,node_parameters,node_shell toneBlue
class node_entry,node_cli,node_callbacks,node_errors toneAmber
class node_completion,node_completion_shared,node_help,node_terminal,node_script_cli toneMint
class node_parser,node_click_core,node_types,node_file_types,node_text_utils,node_context_state,node_formatting,node_click_errors,node_compat,node_typing toneRose
class node_developer toneIndigo
```

## Components

### App Definition

- [Typer App API](https://github.com/tiangolo/typer/blob/master/typer/main.py): `typer/main.py`
- [Command Metadata](https://github.com/tiangolo/typer/blob/master/typer/models.py): `typer/models.py`
- [Parameter Declarations](https://github.com/tiangolo/typer/blob/master/typer/params.py): `typer/params.py`

### CLI Runtime

- [App Builder](https://github.com/tiangolo/typer/blob/master/typer/main.py): `typer/main.py`
- [CLI Dispatch](https://github.com/tiangolo/typer/blob/master/typer/core.py): `typer/core.py`
- [Command Callback](https://github.com/tiangolo/typer/blob/master/typer/main.py): `typer/main.py`
- [CLI Errors](https://github.com/tiangolo/typer/blob/master/typer/exceptions.py): `typer/exceptions.py`

### CLI Features

- [Shell Completion](https://github.com/tiangolo/typer/blob/master/typer/completion.py): `typer/completion.py`
- [Completion Logic](https://github.com/tiangolo/typer/blob/master/typer/_completion_shared.py): `typer/_completion_shared.py`
- [Help Formatting](https://github.com/tiangolo/typer/blob/master/typer/rich_utils.py): `typer/rich_utils.py`
- [Terminal Interaction](https://github.com/tiangolo/typer/blob/master/typer/_click/termui.py): `typer/_click/termui.py`
- [Script Runner](https://github.com/tiangolo/typer/blob/master/typer/cli.py): `typer/cli.py`

### Click Internals

- [Argument Parser](https://github.com/tiangolo/typer/blob/master/typer/_click/parser.py): `typer/_click/parser.py`
- [Command Context](https://github.com/tiangolo/typer/blob/master/typer/_click/core.py): `typer/_click/core.py`
- [Value Conversion](https://github.com/tiangolo/typer/blob/master/typer/_click/types.py): `typer/_click/types.py`
- [File Parameters](https://github.com/tiangolo/typer/blob/master/typer/_click/types.py): `typer/_click/types.py`
- [Terminal Utilities](https://github.com/tiangolo/typer/blob/master/typer/_click/utils.py): `typer/_click/utils.py`
- [Context State](https://github.com/tiangolo/typer/blob/master/typer/_click/globals.py): `typer/_click/globals.py`
- [Text Formatting](https://github.com/tiangolo/typer/blob/master/typer/_click/formatting.py): `typer/_click/formatting.py`
- [Click Exceptions](https://github.com/tiangolo/typer/blob/master/typer/_click/exceptions.py): `typer/_click/exceptions.py`
- [Platform Streams](https://github.com/tiangolo/typer/blob/master/typer/_click/_compat.py): `typer/_click/_compat.py`
- [Typing Support](https://github.com/tiangolo/typer/blob/master/typer/_typing.py): `typer/_typing.py`

### Other components

- **Application Author**
- **Terminal User**

## Connections

- Application Author → Typer App API: defines commands (evidence: `README.md`)
- Typer App API → Command Metadata: registers metadata (evidence: `typer/main.py`)
- Typer App API → Parameter Declarations: declares parameters (evidence: `typer/main.py`)
- Terminal User → CLI Dispatch: provides arguments (evidence: `README.md`)
- Typer App API → App Builder: runs app (evidence: `README.md`)
- App Builder → CLI Dispatch: builds commands (evidence: `typer/main.py`)
- CLI Dispatch → Command Context: dispatches through (evidence: `typer/core.py`)
- Command Context → Argument Parser: parses arguments (evidence: `typer/_click/core.py`)
- Argument Parser → Value Conversion: converts values (evidence: `typer/_click/parser.py`)
- CLI Dispatch → Command Callback: invokes command (evidence: `typer/main.py`)
- CLI Dispatch → CLI Errors: raises errors (evidence: `typer/core.py`)
- CLI Dispatch → Shell Completion: handles completion (evidence: `typer/core.py`)
- Shell Completion → Completion Logic: uses shared logic (evidence: `typer/completion.py`)
- Completion Logic → Context State: reads context (evidence: `typer/_completion_shared.py`)
- CLI Dispatch → Help Formatting: renders help (evidence: `typer/core.py`)
- CLI Dispatch → Terminal Interaction: supports prompts (evidence: `typer/core.py`)
- Terminal Interaction → Click Exceptions: raises usage errors (evidence: `typer/_click/termui.py`)
- Terminal Interaction → Terminal Utilities: writes terminal text (evidence: `typer/_click/termui.py`)
- CLI Dispatch → File Parameters: accepts file values (evidence: `README.md`)
- Terminal User → Script Runner: runs script (evidence: `README.md`)
- Script Runner → Typer App API: creates CLI app (evidence: `typer/cli.py`)
- Command Context → Context State: manages context (evidence: `typer/_click/core.py`)
- Command Context → Click Exceptions: uses exceptions (evidence: `typer/_click/core.py`)
- Command Context → Text Formatting: formats help (evidence: `typer/_click/core.py`)
- Command Context → Terminal Utilities: uses utilities (evidence: `typer/_click/core.py`)
- Value Conversion → Platform Streams: uses stream support (evidence: `typer/_click/types.py`)
- CLI Dispatch → Typing Support: uses typing helpers (evidence: `typer/core.py`)
- Help Formatting → Command Metadata: renders metadata (evidence: `typer/rich_utils.py`)