# pallets/click architecture

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

- Interactive diagram: https://gitdiagram.com/pallets/click
- Repository: https://github.com/pallets/click
- Video tour (about a minute): https://gitdiagram.com/pallets/click/video

## Overview

Click is a Python library for building composable command-line interfaces. The principal workflow starts when a CLI user invokes a command: Click constructs command/context state, parses arguments and options, converts parameter values, invokes the command callback, and presents output or errors. Groups and decorators support nested command composition; help formatting, shell completion, and terminal interaction are related capabilities. The graph reflects documented behavior and source-index references; unsampled implementations are represented at subsystem level, and unverified links are omitted.

Main entry points: [`src/click/core.py`](https://github.com/pallets/click/blob/main/src/click/core.py) (Commands and Context), [`src/click/utils.py`](https://github.com/pallets/click/blob/main/src/click/utils.py) (CLI Utilities), [`src/click/exceptions.py`](https://github.com/pallets/click/blob/main/src/click/exceptions.py) (CLI Errors), [`src/click/termui.py`](https://github.com/pallets/click/blob/main/src/click/termui.py) (Terminal UI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli["CLI Runtime"]
  node_command["Commands and Context<br/>[core.py]"]
  node_decorators["Command Decorators<br/>[decorators.py]"]
  node_parser["Argument Parser<br/>[parser.py]"]
  node_completion["Shell Completion"]
end

subgraph group_params["Parameters and Errors"]
  node_types["Parameter Types<br/>[types.py]"]
  node_exceptions["CLI Errors<br/>[exceptions.py]"]
end

subgraph group_terminal["Terminal Experience"]
  node_termui["Terminal UI<br/>[termui.py]"]
  node_termui_impl["Terminal UI Internals<br/>[_termui_impl.py]"]
  node_formatting["Help Formatting<br/>[formatting.py]"]
  node_textwrap["Text Wrapping<br/>[_textwrap.py]"]
end

subgraph group_support["Runtime Support"]
  node_utils["CLI Utilities<br/>[utils.py]"]
  node_globals["Context Globals<br/>[globals.py]"]
  node_compat["Stream Compatibility<br/>[_compat.py]"]
  node_winconsole["Windows Console<br/>[_winconsole.py]"]
  node_private_utils["Internal Utilities<br/>[_utils.py]"]
  node_testing["CLI Testing Tools<br/>[testing.py]"]
end

node_user(("CLI User"))

node_user -->|"invokes CLI"| node_command
node_command -->|"parses arguments"| node_parser
node_command -->|"converts values"| node_types
node_command -->|"invokes callbacks"| node_decorators
node_decorators -->|"builds commands"| node_command
node_command -->|"dispatches completion"| node_completion
node_command -->|"formats help"| node_formatting
node_command -->|"manages context"| node_globals
node_command -->|"raises errors"| node_exceptions
node_parser -->|"reports parse errors"| node_exceptions
node_types -->|"reports conversion errors"| node_exceptions
node_termui -->|"delegates UI"| node_termui_impl
node_termui -->|"uses utilities"| node_utils
node_termui_impl -->|"uses utilities"| node_utils
node_termui -->|"raises UI errors"| node_exceptions
node_formatting -->|"wraps text"| node_textwrap
node_formatting -->|"formats options"| node_parser
node_utils -->|"uses types"| node_types
node_utils -->|"reads context"| node_globals
node_exceptions -->|"emits errors"| node_utils
node_exceptions -->|"reads context"| node_globals
node_compat -->|"uses console support"| node_winconsole
node_types -->|"uses compatibility"| node_compat
node_utils -->|"uses compatibility"| node_compat
node_testing -->|"exercises commands"| node_command
node_testing -->|"captures terminal UI"| node_termui
node_command -->|"uses internals"| node_private_utils

click node_command "https://github.com/pallets/click/blob/main/src/click/core.py"
click node_decorators "https://github.com/pallets/click/blob/main/src/click/decorators.py"
click node_parser "https://github.com/pallets/click/blob/main/src/click/parser.py"
click node_completion "https://github.com/pallets/click/blob/main/src/click/shell_completion.py"
click node_types "https://github.com/pallets/click/blob/main/src/click/types.py"
click node_exceptions "https://github.com/pallets/click/blob/main/src/click/exceptions.py"
click node_termui "https://github.com/pallets/click/blob/main/src/click/termui.py"
click node_termui_impl "https://github.com/pallets/click/blob/main/src/click/_termui_impl.py"
click node_formatting "https://github.com/pallets/click/blob/main/src/click/formatting.py"
click node_textwrap "https://github.com/pallets/click/blob/main/src/click/_textwrap.py"
click node_utils "https://github.com/pallets/click/blob/main/src/click/utils.py"
click node_globals "https://github.com/pallets/click/blob/main/src/click/globals.py"
click node_compat "https://github.com/pallets/click/blob/main/src/click/_compat.py"
click node_winconsole "https://github.com/pallets/click/blob/main/src/click/_winconsole.py"
click node_private_utils "https://github.com/pallets/click/blob/main/src/click/_utils.py"
click node_testing "https://github.com/pallets/click/blob/main/src/click/testing.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_command,node_decorators,node_parser,node_completion,node_user toneBlue
class node_types,node_exceptions toneAmber
class node_termui,node_termui_impl,node_formatting,node_textwrap toneMint
class node_utils,node_globals,node_compat,node_winconsole,node_private_utils,node_testing toneRose
```

## Components

### CLI Runtime

- [Commands and Context](https://github.com/pallets/click/blob/main/src/click/core.py): `src/click/core.py`
- [Command Decorators](https://github.com/pallets/click/blob/main/src/click/decorators.py): `src/click/decorators.py`
- [Argument Parser](https://github.com/pallets/click/blob/main/src/click/parser.py): `src/click/parser.py`
- [Shell Completion](https://github.com/pallets/click/blob/main/src/click/shell_completion.py): `src/click/shell_completion.py`

### Parameters and Errors

- [Parameter Types](https://github.com/pallets/click/blob/main/src/click/types.py): `src/click/types.py`
- [CLI Errors](https://github.com/pallets/click/blob/main/src/click/exceptions.py): `src/click/exceptions.py`

### Terminal Experience

- [Terminal UI](https://github.com/pallets/click/blob/main/src/click/termui.py): `src/click/termui.py`
- [Terminal UI Internals](https://github.com/pallets/click/blob/main/src/click/_termui_impl.py): `src/click/_termui_impl.py`
- [Help Formatting](https://github.com/pallets/click/blob/main/src/click/formatting.py): `src/click/formatting.py`
- [Text Wrapping](https://github.com/pallets/click/blob/main/src/click/_textwrap.py): `src/click/_textwrap.py`

### Runtime Support

- [CLI Utilities](https://github.com/pallets/click/blob/main/src/click/utils.py): `src/click/utils.py`
- [Context Globals](https://github.com/pallets/click/blob/main/src/click/globals.py): `src/click/globals.py`
- [Stream Compatibility](https://github.com/pallets/click/blob/main/src/click/_compat.py): `src/click/_compat.py`
- [Windows Console](https://github.com/pallets/click/blob/main/src/click/_winconsole.py): `src/click/_winconsole.py`
- [Internal Utilities](https://github.com/pallets/click/blob/main/src/click/_utils.py): `src/click/_utils.py`
- [CLI Testing Tools](https://github.com/pallets/click/blob/main/src/click/testing.py): `src/click/testing.py`

### Other components

- **CLI User**

## Connections

- CLI User → Commands and Context: invokes CLI (evidence: `README.md`)
- Commands and Context → Argument Parser: parses arguments (evidence: `src/click/core.py`)
- Commands and Context → Parameter Types: converts values (evidence: `src/click/core.py`)
- Commands and Context → Command Decorators: invokes callbacks (evidence: `src/click/core.py`)
- Command Decorators → Commands and Context: builds commands (evidence: `src/click/decorators.py`)
- Commands and Context → Shell Completion: dispatches completion (evidence: `src/click/core.py`)
- Commands and Context → Help Formatting: formats help (evidence: `src/click/core.py`)
- Commands and Context → Context Globals: manages context (evidence: `src/click/core.py`)
- Commands and Context → CLI Errors: raises errors (evidence: `src/click/core.py`)
- Argument Parser → CLI Errors: reports parse errors (evidence: `src/click/parser.py`)
- Parameter Types → CLI Errors: reports conversion errors (evidence: `src/click/types.py`)
- Terminal UI → Terminal UI Internals: delegates UI (evidence: `src/click/termui.py`)
- Terminal UI → CLI Utilities: uses utilities (evidence: `src/click/termui.py`)
- Terminal UI Internals → CLI Utilities: uses utilities (evidence: `src/click/_termui_impl.py`)
- Terminal UI → CLI Errors: raises UI errors (evidence: `src/click/termui.py`)
- Help Formatting → Text Wrapping: wraps text (evidence: `src/click/formatting.py`)
- Help Formatting → Argument Parser: formats options (evidence: `src/click/formatting.py`)
- CLI Utilities → Parameter Types: uses types (evidence: `src/click/utils.py`)
- CLI Utilities → Context Globals: reads context (evidence: `src/click/utils.py`)
- CLI Errors → CLI Utilities: emits errors (evidence: `src/click/exceptions.py`)
- CLI Errors → Context Globals: reads context (evidence: `src/click/exceptions.py`)
- Stream Compatibility → Windows Console: uses console support (evidence: `src/click/_compat.py`)
- Parameter Types → Stream Compatibility: uses compatibility (evidence: `src/click/types.py`)
- CLI Utilities → Stream Compatibility: uses compatibility (evidence: `src/click/utils.py`)
- CLI Testing Tools → Commands and Context: exercises commands (evidence: `src/click/testing.py`)
- CLI Testing Tools → Terminal UI: captures terminal UI (evidence: `src/click/testing.py`)
- Commands and Context → Internal Utilities: uses internals (evidence: `src/click/core.py`)
