# jdx/usage architecture

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

- Interactive diagram: https://gitdiagram.com/jdx/usage
- Repository: https://github.com/jdx/usage

## Overview

Usage is a portable CLI-definition system: a KDL spec or Rust declaration describes a command interface, which can be parsed at runtime and used to produce help, completions, documentation, and typed clients. The graph also preserves configuration and dynamic-plugin capabilities. The README documents the CLI outputs and integrations; sampled source confirms the derive-to-parser design and dynamic catalog behavior, but does not expose all CLI dispatch wiring, so uncertain internal calls are omitted.

Main entry points: [`usage-rs/src/lib.rs`](https://github.com/jdx/usage/blob/main/usage-rs/src/lib.rs) (Rust facade), [`lib/src/spec/mod.rs`](https://github.com/jdx/usage/blob/main/lib/src/spec/mod.rs) (Spec model), [`derive/src/lib.rs`](https://github.com/jdx/usage/blob/main/derive/src/lib.rs) (CLI derive), [`cli/src/lib.rs`](https://github.com/jdx/usage/blob/main/cli/src/lib.rs) (CLI command runner)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_definition["CLI definition"]
  node_specfile["KDL spec"]
  node_rustdecl["Rust declarations"]
  node_kdl["KDL parser<br/>[mod.rs]"]
  node_specmodel["Spec model<br/>[mod.rs]"]
  node_derive["CLI derive<br/>[lib.rs]"]
end

subgraph group_runtime["Parsing runtime"]
  node_facade["Rust facade<br/>[lib.rs]"]
  node_argv["Argument parser<br/>[lib.rs]"]
  node_config["Settings resolution<br/>[lib.rs]"]
  node_validation["Value validation<br/>[lib.rs]"]
  node_goargv["Go parser<br/>[parser.go]"]
end

subgraph group_standalone["Standalone CLI"]
  node_cli["Usage executable<br/>[main.rs]"]
  node_cli_run["CLI command runner<br/>[lib.rs]"]
  node_lint["Spec linting<br/>[lint.rs]"]
end

subgraph group_extensions["Extensions"]
  node_dynamic["Plugin catalog<br/>[lib.rs]"]
  node_cobra["Cobra importer<br/>[spec.go]"]
end

subgraph group_clients["Client outputs"]
  node_generate["Output generation<br/>[mod.rs]"]
  node_completion["Shell completions<br/>[mod.rs]"]
  node_sdk["Typed SDKs<br/>[mod.rs]"]
end

node_author(("CLI author"))
node_cliuser(("CLI operator"))

node_author -->|"writes spec"| node_specfile
node_author -->|"declares CLI"| node_rustdecl
node_specfile -->|"parses"| node_kdl
node_kdl -->|"builds spec"| node_specmodel
node_rustdecl -->|"derives from"| node_derive
node_derive -->|"emits parse tables"| node_argv
node_derive -->|"emits metadata"| node_specmodel
node_facade -->|"re-exports"| node_argv
node_cliuser -->|"invokes"| node_cli
node_cli -->|"runs"| node_cli_run
node_cliuser -->|"supplies"| node_specfile
node_cli_run -->|"dispatches lint"| node_lint
node_cli_run -->|"dispatches generation"| node_generate
node_generate -->|"produces completion scripts"| node_completion
node_generate -->|"produces clients"| node_sdk
node_cliuser -->|"uses Rust framework"| node_facade
node_facade -->|"exposes settings"| node_config
node_facade -->|"exposes validation"| node_validation
node_facade -->|"offers completions"| node_completion
node_specmodel -->|"supplies host spec"| node_dynamic
node_specmodel -.->|"accepts imported spec"| node_cobra
node_specmodel -->|"defines Go parser input"| node_goargv

click node_kdl "https://github.com/jdx/usage/blob/main/lib/src/kdl/mod.rs"
click node_specmodel "https://github.com/jdx/usage/blob/main/lib/src/spec/mod.rs"
click node_derive "https://github.com/jdx/usage/blob/main/derive/src/lib.rs"
click node_facade "https://github.com/jdx/usage/blob/main/usage-rs/src/lib.rs"
click node_argv "https://github.com/jdx/usage/blob/main/argv/src/lib.rs"
click node_config "https://github.com/jdx/usage/blob/main/config/src/lib.rs"
click node_validation "https://github.com/jdx/usage/blob/main/validation/src/lib.rs"
click node_cli "https://github.com/jdx/usage/blob/main/cli/src/main.rs"
click node_cli_run "https://github.com/jdx/usage/blob/main/cli/src/lib.rs"
click node_lint "https://github.com/jdx/usage/blob/main/cli/src/cli/lint.rs"
click node_generate "https://github.com/jdx/usage/blob/main/cli/src/cli/generate/mod.rs"
click node_completion "https://github.com/jdx/usage/blob/main/lib/src/complete/mod.rs"
click node_sdk "https://github.com/jdx/usage/blob/main/lib/src/sdk/mod.rs"
click node_dynamic "https://github.com/jdx/usage/blob/main/usage-dynamic/src/lib.rs"
click node_goargv "https://github.com/jdx/usage/blob/main/go/argv/parser.go"
click node_cobra "https://github.com/jdx/usage/blob/main/integrations/cobra/spec.go"

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_specfile,node_rustdecl,node_kdl,node_specmodel,node_derive toneBlue
class node_facade,node_argv,node_config,node_validation,node_goargv toneAmber
class node_cli,node_cli_run,node_lint toneMint
class node_dynamic,node_cobra toneRose
class node_generate,node_completion,node_sdk,node_author,node_cliuser toneIndigo
```

## Components

### CLI definition

- **KDL spec**
- **Rust declarations**
- [KDL parser](https://github.com/jdx/usage/blob/main/lib/src/kdl/mod.rs): `lib/src/kdl/mod.rs`
- [Spec model](https://github.com/jdx/usage/blob/main/lib/src/spec/mod.rs): `lib/src/spec/mod.rs`
- [CLI derive](https://github.com/jdx/usage/blob/main/derive/src/lib.rs): `derive/src/lib.rs`

### Parsing runtime

- [Rust facade](https://github.com/jdx/usage/blob/main/usage-rs/src/lib.rs): `usage-rs/src/lib.rs`
- [Argument parser](https://github.com/jdx/usage/blob/main/argv/src/lib.rs): `argv/src/lib.rs`
- [Settings resolution](https://github.com/jdx/usage/blob/main/config/src/lib.rs): `config/src/lib.rs`
- [Value validation](https://github.com/jdx/usage/blob/main/validation/src/lib.rs): `validation/src/lib.rs`
- [Go parser](https://github.com/jdx/usage/blob/main/go/argv/parser.go): `go/argv/parser.go`

### Standalone CLI

- [Usage executable](https://github.com/jdx/usage/blob/main/cli/src/main.rs): `cli/src/main.rs`
- [CLI command runner](https://github.com/jdx/usage/blob/main/cli/src/lib.rs): `cli/src/lib.rs`
- [Spec linting](https://github.com/jdx/usage/blob/main/cli/src/cli/lint.rs): `cli/src/cli/lint.rs`

### Extensions

- [Plugin catalog](https://github.com/jdx/usage/blob/main/usage-dynamic/src/lib.rs): `usage-dynamic/src/lib.rs`
- [Cobra importer](https://github.com/jdx/usage/blob/main/integrations/cobra/spec.go): `integrations/cobra/spec.go`

### Client outputs

- [Output generation](https://github.com/jdx/usage/blob/main/cli/src/cli/generate/mod.rs): `cli/src/cli/generate/mod.rs`
- [Shell completions](https://github.com/jdx/usage/blob/main/lib/src/complete/mod.rs): `lib/src/complete/mod.rs`
- [Typed SDKs](https://github.com/jdx/usage/blob/main/lib/src/sdk/mod.rs): `lib/src/sdk/mod.rs`

### Other components

- **CLI author**
- **CLI operator**

## Connections

- CLI author → KDL spec: writes spec
- CLI author → Rust declarations: declares CLI
- KDL spec → KDL parser: parses
- KDL parser → Spec model: builds spec
- Rust declarations → CLI derive: derives from
- CLI derive → Argument parser: emits parse tables
- CLI derive → Spec model: emits metadata
- Rust facade → Argument parser: re-exports
- CLI operator → Usage executable: invokes
- Usage executable → CLI command runner: runs
- CLI operator → KDL spec: supplies
- CLI command runner → Spec linting: dispatches lint
- CLI command runner → Output generation: dispatches generation
- Output generation → Shell completions: produces completion scripts
- Output generation → Typed SDKs: produces clients
- CLI operator → Rust facade: uses Rust framework
- Rust facade → Settings resolution: exposes settings
- Rust facade → Value validation: exposes validation
- Rust facade → Shell completions: offers completions
- Spec model → Plugin catalog: supplies host spec
- Spec model → Cobra importer: accepts imported spec
- Spec model → Go parser: defines Go parser input