# explosion/radicli architecture

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

- Interactive diagram: https://gitdiagram.com/explosion/radicli
- Repository: https://github.com/explosion/radicli

## Overview

#### Purpose and Public Entry Points
`radicli` is a Python 3.8+ zero-dependency library for declaring `argparse` CLIs directly from typed Python functions. Its public API is exported from `radicli/__init__.py`; primary runtime classes and decorators are implemented in `radicli/cli.py`. Consumer applications instantiate `Radicli`, register functions with decorators, then invoke `run()` or `call()`.

#### Command Registration and Internal Model
`Radicli` maintains registries of top-level commands and one-level subcommands. Decorators convert function signatures, annotations, defaults, docstrings, and optional `Arg` metadata into a structured `Command` representation. Placeholder parent commands support subcommand-only groups.
- `radicli/cli.py`
- `radicli/parser.py`

#### Type-Driven Argument Construction
The parser layer translates `Command` argument metadata into `argparse` definitions. Function type hints control coercion and validation for primitives, booleans, lists, literals, enums, unions/optionals, and registered custom types. Per-argument converters override type-derived conversion; global converters are selected by exact generic type or origin.
- `radicli/parser.py`
- `radicli/util.py`
- `radicli/cli.py`

#### Runtime Dispatch and Error Boundary
`Radicli.run()` reads `sys.argv` (or supplied args), resolves a command/subcommand, parses values, and invokes the original function with keyword arguments. Commands allowing extras preserve unrecognized tokens under a configurable parameter name. Exceptions remain normal Python exceptions for direct invocation, but CLI dispatch can map configured exception classes to presentation/exit handlers.
- `radicli/cli.py`
- `radicli/parser.py`

#### Built-In Conversion Utilities
Reusable utility types and converters provide filesystem validation, path-or-stdin conventions, UUID handling, and list-converter construction. These are a boundary between raw CLI strings and application-level typed inputs, while retaining a standard-library-only runtime.
- `radicli/util.py`
- `radicli/__init__.py`

#### Static CLI Fast Path
A live CLI can serialize command topology and argument metadata to JSON. `StaticRadicli` loads that representation and performs help rendering plus basic command/argument validation before expensive application imports. It exits for help or invalid input; otherwise callers proceed to import and execute the live CLI for conversion and function execution.
- `radicli/static.py`
- `radicli/cli.py`
- `radicli/parser.py`

#### Documentation and Distribution
Markdown CLI documentation is generated from the same command model, preventing a separate documentation schema. The package is distributed as a typed Python library via setuptools configuration; CI tests and publishes releases through GitHub Actions. There are no runtime external services or infrastructure dependencies beyond Python’s standard library and `argparse`.
- `radicli/document.py`
- `pyproject.toml`
- `setup.py`
- `.github/workflows/publish.yml`

Main entry points: [`radicli/cli.py`](https://github.com/explosion/radicli/blob/main/radicli/cli.py) (Radicli), [`radicli/__init__.py`](https://github.com/explosion/radicli/blob/main/radicli/__init__.py) (Package exports), [`radicli/parser.py`](https://github.com/explosion/radicli/blob/main/radicli/parser.py) (Command model), [`radicli/static.py`](https://github.com/explosion/radicli/blob/main/radicli/static.py) (StaticRadicli)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_public["Public API"]
  node_package_api["Package exports<br/>Python package API<br/>[__init__.py]"]
  node_consumer["Consumer application<br/>Python application"]
end

subgraph group_core["CLI Runtime"]
  node_radicli["Radicli<br/>CLI registry and dispatcher<br/>[cli.py]"]
  node_command_model["Command model<br/>command metadata<br/>[parser.py]"]
  node_registration["Command registration<br/>decorators<br/>[cli.py]"]
  node_parser["Argument parser<br/>argparse builder<br/>[parser.py]"]
  node_converters["Type converters<br/>conversion utilities<br/>[util.py]"]
  node_dispatch["Runtime dispatch<br/>execution boundary<br/>[cli.py]"]
  node_static["StaticRadicli<br/>static CLI validator<br/>[static.py]"]
end

subgraph group_support["Support &amp; Distribution"]
  node_docs["Markdown docs generator<br/>documentation generator<br/>[document.py]"]
  node_distribution["Package distribution<br/>setuptools packaging<br/>[pyproject.toml]"]
  node_publish_ci["Publish workflow<br/>GitHub Actions release CI<br/>[publish.yml]"]
end

node_package_api -->|"exports"| node_radicli
node_package_api -->|"exports utilities"| node_converters
node_consumer -->|"imports"| node_package_api
node_consumer -->|"decorates functions"| node_registration
node_consumer -->|"run&#40;&#41; / call&#40;&#41;"| node_dispatch
node_registration -->|"creates"| node_command_model
node_radicli -->|"maintains registries"| node_command_model
node_radicli -->|"coordinates"| node_dispatch
node_command_model -->|"defines arguments"| node_parser
node_parser -->|"selects coercion"| node_converters
node_dispatch -->|"parses argv"| node_parser
node_dispatch -->|"invokes registered function"| node_consumer
node_radicli -->|"serializes command metadata"| node_static
node_static -->|"validates topology"| node_parser
node_command_model -->|"generates documentation"| node_docs
node_distribution -->|"packages"| node_package_api
node_publish_ci -->|"publishes"| node_distribution

click node_package_api "https://github.com/explosion/radicli/blob/main/radicli/__init__.py"
click node_radicli "https://github.com/explosion/radicli/blob/main/radicli/cli.py"
click node_command_model "https://github.com/explosion/radicli/blob/main/radicli/parser.py"
click node_registration "https://github.com/explosion/radicli/blob/main/radicli/cli.py"
click node_parser "https://github.com/explosion/radicli/blob/main/radicli/parser.py"
click node_converters "https://github.com/explosion/radicli/blob/main/radicli/util.py"
click node_dispatch "https://github.com/explosion/radicli/blob/main/radicli/cli.py"
click node_static "https://github.com/explosion/radicli/blob/main/radicli/static.py"
click node_docs "https://github.com/explosion/radicli/blob/main/radicli/document.py"
click node_distribution "https://github.com/explosion/radicli/blob/main/pyproject.toml"
click node_publish_ci "https://github.com/explosion/radicli/blob/main/.github/workflows/publish.yml"

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_package_api,node_consumer toneBlue
class node_radicli,node_command_model,node_registration,node_parser,node_converters,node_dispatch,node_static toneAmber
class node_docs,node_distribution,node_publish_ci toneMint
```

## Components

### Public API

- [Package exports](https://github.com/explosion/radicli/blob/main/radicli/__init__.py): Python package API · Public library entry point. · `radicli/__init__.py`
- **Consumer application**: Python application · Registers typed functions and invokes the CLI.

### CLI Runtime

- [Radicli](https://github.com/explosion/radicli/blob/main/radicli/cli.py): CLI registry and dispatcher · Registers commands, resolves dispatch, and invokes functions. · `radicli/cli.py`
- [Command model](https://github.com/explosion/radicli/blob/main/radicli/parser.py): command metadata · Structured commands derived from function signatures and decorator metadata. · `radicli/parser.py`
- [Command registration](https://github.com/explosion/radicli/blob/main/radicli/cli.py): decorators · Builds top-level, subcommand, and placeholder-parent registrations. · `radicli/cli.py`
- [Argument parser](https://github.com/explosion/radicli/blob/main/radicli/parser.py): argparse builder · Turns command metadata into argparse definitions and parsed values. · `radicli/parser.py`
- [Type converters](https://github.com/explosion/radicli/blob/main/radicli/util.py): conversion utilities · Provides typed string conversion and filesystem, UUID, stdin, and list helpers. · `radicli/util.py`
- [Runtime dispatch](https://github.com/explosion/radicli/blob/main/radicli/cli.py): execution boundary · Handles argv, extras, invocation, and configured CLI exception handlers. · `radicli/cli.py`
- [StaticRadicli](https://github.com/explosion/radicli/blob/main/radicli/static.py): static CLI validator · Uses serialized metadata for early help and basic validation. · `radicli/static.py`

### Support & Distribution

- [Markdown docs generator](https://github.com/explosion/radicli/blob/main/radicli/document.py): documentation generator · Renders CLI documentation from command metadata. · `radicli/document.py`
- [Package distribution](https://github.com/explosion/radicli/blob/main/pyproject.toml): setuptools packaging · Defines typed library packaging and release metadata. · `pyproject.toml`
- [Publish workflow](https://github.com/explosion/radicli/blob/main/.github/workflows/publish.yml): GitHub Actions release CI · Tests and publishes releases. · `.github/workflows/publish.yml`

## Connections

- Package exports → Radicli: exports
- Package exports → Type converters: exports utilities
- Consumer application → Package exports: imports
- Consumer application → Command registration: decorates functions
- Consumer application → Runtime dispatch: run() / call()
- Command registration → Command model: creates
- Radicli → Command model: maintains registries
- Radicli → Runtime dispatch: coordinates
- Command model → Argument parser: defines arguments
- Argument parser → Type converters: selects coercion
- Runtime dispatch → Argument parser: parses argv
- Runtime dispatch → Consumer application: invokes registered function
- Radicli → StaticRadicli: serializes command metadata
- StaticRadicli → Argument parser: validates topology
- Command model → Markdown docs generator: generates documentation
- Package distribution → Package exports: packages
- Publish workflow → Package distribution: publishes