# basefoundry/base-cli architecture

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

- Interactive diagram: https://gitdiagram.com/basefoundry/base-cli
- Repository: https://github.com/basefoundry/base-cli

## Overview

base-cli is a reusable production lifecycle layer for Click and Typer CLIs, not a parser or application scaffold. A consumer defines commands and calls the runner; the library supplies lifecycle options, a shared context, configuration and runtime policies, then logging, cleanup, history and human or machine-readable output. The README documents optional Typer, Rich and OpenTelemetry support. Relationships below follow the README or SOURCE INDEX references; unsampled subsystems are represented at their known module paths, without assuming their internal call order.

Main entry points: [`lib/python/base_cli/context.py`](https://github.com/basefoundry/base-cli/blob/main/lib/python/base_cli/context.py) (Command context), [`lib/python/base_cli/_app_core.py`](https://github.com/basefoundry/base-cli/blob/main/lib/python/base_cli/_app_core.py) (App and commands), [`lib/python/base_cli/_run.py`](https://github.com/basefoundry/base-cli/blob/main/lib/python/base_cli/_run.py) (Invocation runner), [`lib/python/base_cli/_runtime.py`](https://github.com/basefoundry/base-cli/blob/main/lib/python/base_cli/_runtime.py) (Run directories)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_invocation["Invocation lifecycle"]
  node_app["App and commands<br/>[_app_core.py]"]
  node_options["Lifecycle options"]
  node_runner["Invocation runner<br/>[_run.py]"]
  node_typer["Typer adapter<br/>[typer.py]"]
  node_attachment["Command attachment<br/>[_attach.py]"]
end

subgraph group_context["Context and policy"]
  node_context["Command context<br/>[context.py]"]
  node_config["Configuration<br/>[config.py]"]
  node_profile["Consumer profile<br/>[profile.py]"]
  node_extensions["Extensions<br/>[extensions.py]"]
end

subgraph group_runtime["Runtime state"]
  node_runtime["Runtime layout<br/>[runtime.py]"]
  node_runtime_mgr["Run directories<br/>[_runtime.py]"]
  node_paths["Path policies<br/>[paths.py]"]
  node_private_files["Private files<br/>[_private_files.py]"]
  node_cleanup["Cleanup hooks<br/>[_cleanup.py]"]
end

subgraph group_output["Output and integrations"]
  node_logging["Structured logging<br/>[logging.py]"]
  node_history["Run history<br/>[history.py]"]
  node_redaction["Sensitive redaction<br/>[redaction.py]"]
  node_contracts["JSON contracts<br/>[json_contracts.py]"]
  node_output["Record output<br/>[output.py]"]
  node_integrations["Optional integrations<br/>[integrations.py]"]
end

node_consumer(("CLI consumer"))
node_click["Click parser"]
node_filesystem[("Local filesystem")]
node_rich["Rich"]
node_otel["OpenTelemetry"]

node_consumer -->|"defines commands"| node_app
node_consumer -->|"runs app"| node_runner
node_app -->|"configures"| node_options
node_app -->|"creates context"| node_context
node_runner -->|"invokes"| node_app
node_runner -->|"dispatches to"| node_click
node_typer -->|"adapts dialect"| node_click
node_consumer -.->|"opts into"| node_typer
node_attachment -->|"attaches lifecycle"| node_app
node_context -->|"exposes config"| node_config
node_profile -->|"supplies policy"| node_config
node_profile -->|"resolves layout"| node_runtime
node_context -->|"uses runtime"| node_runtime_mgr
node_context -->|"registers hooks"| node_cleanup
node_runtime_mgr -->|"uses paths"| node_paths
node_runtime_mgr -->|"secures files"| node_private_files
node_runtime_mgr -->|"manages run state"| node_filesystem
node_app -->|"configures logging"| node_logging
node_context -->|"provides logger"| node_logging
node_context -->|"provides history"| node_history
node_history -->|"redacts records"| node_redaction
node_runner -->|"renders JSON errors"| node_contracts
node_runner -->|"captures output"| node_output
node_output -->|"tries rendering"| node_integrations
node_integrations -.->|"renders tables"| node_rich
node_integrations -.->|"starts spans"| node_otel

click node_app "https://github.com/basefoundry/base-cli/blob/main/lib/python/base_cli/_app_core.py"
click node_options "https://github.com/basefoundry/base-cli/blob/main/lib/python/base_cli/lifecycle_options.py"
click node_runner "https://github.com/basefoundry/base-cli/blob/main/lib/python/base_cli/_run.py"
click node_typer "https://github.com/basefoundry/base-cli/blob/main/lib/python/base_cli/typer.py"
click node_attachment "https://github.com/basefoundry/base-cli/blob/main/lib/python/base_cli/_attach.py"
click node_context "https://github.com/basefoundry/base-cli/blob/main/lib/python/base_cli/context.py"
click node_config "https://github.com/basefoundry/base-cli/blob/main/lib/python/base_cli/config.py"
click node_profile "https://github.com/basefoundry/base-cli/blob/main/lib/python/base_cli/profile.py"
click node_extensions "https://github.com/basefoundry/base-cli/blob/main/lib/python/base_cli/extensions.py"
click node_runtime "https://github.com/basefoundry/base-cli/blob/main/lib/python/base_cli/runtime.py"
click node_runtime_mgr "https://github.com/basefoundry/base-cli/blob/main/lib/python/base_cli/_runtime.py"
click node_paths "https://github.com/basefoundry/base-cli/blob/main/lib/python/base_cli/paths.py"
click node_private_files "https://github.com/basefoundry/base-cli/blob/main/lib/python/base_cli/_private_files.py"
click node_cleanup "https://github.com/basefoundry/base-cli/blob/main/lib/python/base_cli/_cleanup.py"
click node_logging "https://github.com/basefoundry/base-cli/blob/main/lib/python/base_cli/logging.py"
click node_history "https://github.com/basefoundry/base-cli/blob/main/lib/python/base_cli/history.py"
click node_redaction "https://github.com/basefoundry/base-cli/blob/main/lib/python/base_cli/redaction.py"
click node_contracts "https://github.com/basefoundry/base-cli/blob/main/lib/python/base_cli/json_contracts.py"
click node_output "https://github.com/basefoundry/base-cli/blob/main/lib/python/base_cli/output.py"
click node_integrations "https://github.com/basefoundry/base-cli/blob/main/lib/python/base_cli/integrations.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,node_options,node_runner,node_typer,node_attachment toneBlue
class node_context,node_config,node_profile,node_extensions,node_filesystem toneAmber
class node_runtime,node_runtime_mgr,node_paths,node_private_files,node_cleanup toneMint
class node_logging,node_history,node_redaction,node_contracts,node_output,node_integrations toneRose
class node_consumer,node_click,node_rich,node_otel toneIndigo
```

## Components

### Invocation lifecycle

- [App and commands](https://github.com/basefoundry/base-cli/blob/main/lib/python/base_cli/_app_core.py): `lib/python/base_cli/_app_core.py`
- [Lifecycle options](https://github.com/basefoundry/base-cli/blob/main/lib/python/base_cli/lifecycle_options.py): `lib/python/base_cli/lifecycle_options.py`
- [Invocation runner](https://github.com/basefoundry/base-cli/blob/main/lib/python/base_cli/_run.py): `lib/python/base_cli/_run.py`
- [Typer adapter](https://github.com/basefoundry/base-cli/blob/main/lib/python/base_cli/typer.py): `lib/python/base_cli/typer.py`
- [Command attachment](https://github.com/basefoundry/base-cli/blob/main/lib/python/base_cli/_attach.py): `lib/python/base_cli/_attach.py`

### Context and policy

- [Command context](https://github.com/basefoundry/base-cli/blob/main/lib/python/base_cli/context.py): `lib/python/base_cli/context.py`
- [Configuration](https://github.com/basefoundry/base-cli/blob/main/lib/python/base_cli/config.py): `lib/python/base_cli/config.py`
- [Consumer profile](https://github.com/basefoundry/base-cli/blob/main/lib/python/base_cli/profile.py): `lib/python/base_cli/profile.py`
- [Extensions](https://github.com/basefoundry/base-cli/blob/main/lib/python/base_cli/extensions.py): `lib/python/base_cli/extensions.py`

### Runtime state

- [Runtime layout](https://github.com/basefoundry/base-cli/blob/main/lib/python/base_cli/runtime.py): `lib/python/base_cli/runtime.py`
- [Run directories](https://github.com/basefoundry/base-cli/blob/main/lib/python/base_cli/_runtime.py): `lib/python/base_cli/_runtime.py`
- [Path policies](https://github.com/basefoundry/base-cli/blob/main/lib/python/base_cli/paths.py): `lib/python/base_cli/paths.py`
- [Private files](https://github.com/basefoundry/base-cli/blob/main/lib/python/base_cli/_private_files.py): `lib/python/base_cli/_private_files.py`
- [Cleanup hooks](https://github.com/basefoundry/base-cli/blob/main/lib/python/base_cli/_cleanup.py): `lib/python/base_cli/_cleanup.py`

### Output and integrations

- [Structured logging](https://github.com/basefoundry/base-cli/blob/main/lib/python/base_cli/logging.py): `lib/python/base_cli/logging.py`
- [Run history](https://github.com/basefoundry/base-cli/blob/main/lib/python/base_cli/history.py): `lib/python/base_cli/history.py`
- [Sensitive redaction](https://github.com/basefoundry/base-cli/blob/main/lib/python/base_cli/redaction.py): `lib/python/base_cli/redaction.py`
- [JSON contracts](https://github.com/basefoundry/base-cli/blob/main/lib/python/base_cli/json_contracts.py): `lib/python/base_cli/json_contracts.py`
- [Record output](https://github.com/basefoundry/base-cli/blob/main/lib/python/base_cli/output.py): `lib/python/base_cli/output.py`
- [Optional integrations](https://github.com/basefoundry/base-cli/blob/main/lib/python/base_cli/integrations.py): `lib/python/base_cli/integrations.py`

### Other components

- **CLI consumer**
- **Click parser**
- **Local filesystem**
- **Rich**
- **OpenTelemetry**

## Connections

- CLI consumer → App and commands: defines commands
- CLI consumer → Invocation runner: runs app
- App and commands → Lifecycle options: configures (evidence: `lib/python/base_cli/_app_core.py`)
- App and commands → Command context: creates context (evidence: `lib/python/base_cli/_app_core.py`)
- Invocation runner → App and commands: invokes (evidence: `lib/python/base_cli/_run.py`)
- Invocation runner → Click parser: dispatches to (evidence: `lib/python/base_cli/_run.py`)
- Typer adapter → Click parser: adapts dialect
- CLI consumer → Typer adapter: opts into
- Command attachment → App and commands: attaches lifecycle (evidence: `lib/python/base_cli/_attach.py`)
- Command context → Configuration: exposes config (evidence: `lib/python/base_cli/context.py`)
- Consumer profile → Configuration: supplies policy (evidence: `lib/python/base_cli/profile.py`)
- Consumer profile → Runtime layout: resolves layout (evidence: `lib/python/base_cli/profile.py`)
- Command context → Run directories: uses runtime (evidence: `lib/python/base_cli/context.py`)
- Command context → Cleanup hooks: registers hooks (evidence: `lib/python/base_cli/context.py`)
- Run directories → Path policies: uses paths (evidence: `lib/python/base_cli/_runtime.py`)
- Run directories → Private files: secures files (evidence: `lib/python/base_cli/_runtime.py`)
- Run directories → Local filesystem: manages run state
- App and commands → Structured logging: configures logging (evidence: `lib/python/base_cli/_app_core.py`)
- Command context → Structured logging: provides logger (evidence: `lib/python/base_cli/context.py`)
- Command context → Run history: provides history (evidence: `lib/python/base_cli/context.py`)
- Run history → Sensitive redaction: redacts records (evidence: `lib/python/base_cli/history.py`)
- Invocation runner → JSON contracts: renders JSON errors (evidence: `lib/python/base_cli/_run.py`)
- Invocation runner → Record output: captures output (evidence: `lib/python/base_cli/_run.py`)
- Record output → Optional integrations: tries rendering (evidence: `lib/python/base_cli/output.py`)
- Optional integrations → Rich: renders tables (evidence: `lib/python/base_cli/integrations.py`)
- Optional integrations → OpenTelemetry: starts spans (evidence: `lib/python/base_cli/integrations.py`)
