astral-sh/uv

uv-cli

crates/uv-cli/ defines uv's entire command-line argument schema using Clap derive macros. The crate is essentially one big file — crates/uv-cli/src/lib.rs is 8094 lines, the largest non-test source file in the workspace.

Purpose

Keep all CLI argument types in a single Rust crate so that:

cargo dev generate-all can introspect the schema and regenerate the user-facing CLI reference docs.
The JSON schema in uv.schema.json (and the SchemaStore entry that flows from it) stays in sync.
Shell-completion generators (clap_complete_command) get a single source of truth.
The binary crate uv only owns dispatch logic and command implementations, not parsing.

Directory layout

crates/uv-cli/
├── Cargo.toml
├── README.md
├── build.rs       # Embeds resource info on Windows
└── src/
    ├── lib.rs     # The 8000-line schema (Cli, Commands, every subcommand and its args)
    ├── comma.rs   # Helpers for parsing comma-separated values
    ├── compat.rs  # Shims for accepting pip-style flag forms
    ├── options.rs # Custom value parsers (durations, hosts, requirements)
    └── version.rs # `uv-self-version` rendering

Key abstractions

Type	What it represents
`Cli`	Top-level command. Has a `command: Box<Commands>` and a `top_level: TopLevelArgs`.
`TopLevelArgs`	Global options that apply everywhere (`--config-file`, `--no-config`, `--cache-dir`, `--quiet`/`--verbose`, color, preview, …).
`GlobalArgs`	The bulk of global options: networking (`--offline`, `--allow-insecure-host`, `--native-tls`), Python preference, project/working dir, install metadata.
`Commands`	The top-level subcommand enum (`Auth`, `Project`, `Tool`, `Python`, `Pip`, `Workspace`, `BuildBackend`, `Self`, `Cache`, `Publish`, `Help`).
`ProjectCommand`	The flattened project commands: `Run`, `Init`, `Add`, `Remove`, `Version`, `Sync`, `Lock`, `Export`, `Tree`, `Audit`, `Format`.
`PipCommand` (under `PipNamespace`)	The pip-compatible commands.
`ToolCommand`	`install`, `run`, `list`, `uninstall`, `upgrade`, `update-shell`, `dir`.
`PythonCommand`	`install`, `find`, `list`, `pin`, `uninstall`, `update-shell`, `dir`.
`AuthCommand`	`login`, `logout`, `token`, `dir`, plus the `helper` git-credential helper.
`WorkspaceCommand`	`list`, `metadata`, `dir`.
`CacheCommand`	`clean`, `prune`, `dir`, `size`.
`SelfCommand`	`update`, `version`. Gated on the `self-update` cargo feature.
`BuildBackendCommand`	The dev wrapper exposed via `uv build-backend` to invoke uv's own PEP 517 backend.
`RunArgs`, `AddArgs`, `RemoveArgs`, `LockArgs`, `SyncArgs`, …	Per-subcommand argument structs with all the relevant flags and positional arguments.
`VersionFormat`, `PythonListFormat`, `SyncFormat`, `ListFormat`	Output format enums (`Text`, `Json`, `Columns`, `Freeze`).
`ColorChoice`	Wraps `anstream::ColorChoice` to thread the user's `--color` choice through.

How it works

Clap's derive macros turn each struct/enum into:

A parser (Cli::parse_from(argv)).
A help renderer (Cli::command() produces clap::Command).
A completion generator via clap_complete_command.

The entire schema is one Clap tree, with global args attached via #[command(flatten)] and #[arg(global = true, …)]. Many enums use verbatim_doc_comment to preserve list formatting in the --help output, so the doc comments are themselves the documentation.

A Maybe<T> wrapper appears throughout (defined in crates/uv-cli/src/lib.rs) to allow values like --allow-insecure-host to be cleared by a sentinel, supporting use cases where an env-var default needs to be overridden back to "off".

The compat submodule (crates/uv-cli/src/compat.rs) accepts pip-compatible flags that uv either honors with a different name or reports as unsupported. This lets uv pip install be a near-drop-in replacement.

Integration points

The binary crate uv (crates/uv/src/lib.rs) uses every Clap type from this crate to dispatch and parse. The pattern is use uv_cli::{Cli, Commands, ...};.
The settings layer in crates/uv/src/settings.rs consumes the parsed argument structs and merges them with environment and config-file values via the Combine trait from uv-settings.
cargo dev generate-cli-reference walks Cli::command() to emit the reference Markdown pages in docs/reference/cli/.

Entry points for modification

Add a new subcommand — add a variant to the relevant enum (Commands, ProjectCommand, PipCommand, etc.) and a struct for its args. The #[command(after_help = ...)] directive controls the long-form help displayed by uv help <topic>.
Add a flag — extend the relevant args struct or GlobalArgs. Use env = EnvVars::... for environment-variable support and route it through crates/uv/src/settings.rs.
Add a value type — for non-trivial types (like IndexUrl or TrustedHost), implement clap::builder::ValueParserFactory so Clap can parse and validate the value at the schema level rather than at the use site.
Hide a flag — #[arg(hide = true)] removes it from --help while keeping it functional. Useful for --no-foo partner flags.

Key source files

File	Purpose
`crates/uv-cli/src/lib.rs`	The full 8000-line schema.
`crates/uv-cli/src/compat.rs`	pip-compatible flag handling.
`crates/uv-cli/src/options.rs`	Custom value parsers.
`crates/uv-cli/src/comma.rs`	Comma-separated value parsing helpers.
`crates/uv-cli/build.rs`	Build script (Windows manifest embedding).