This document provides a high-level overview of uv's Command-Line Interface (CLI) system. It covers the overall command structure, common design patterns, and the user-facing interface design. This page serves as a parent guide linking to more detailed child pages on CLI parsing, configuration, and preview features.
For detailed explanations on the CLI’s internal architecture and argument parsing, see CLI Architecture and Parsing. For information about the layered configuration system, see Settings and Configuration. To explore the preview feature system for experimental flags, see Preview Features.
uv’s CLI is built using the Rust clap library with derive macros, allowing concise definition of commands, subcommands, and their arguments. The CLI lifecycle is structured into stages:
Parsing: User command-line inputs are parsed into a strongly typed Cli struct crates/uv-cli/src/lib.rs130-136 This struct represents the hierarchical command and argument structure, enabling strong validation and typed access.
Settings Resolution: A layered configuration system merges CLI arguments, environment variables, project-level configuration files (uv.toml or [tool.uv] in pyproject.toml), user-level config, and system-wide config into a unified runtime settings model crates/uv/src/settings.rs97-161
Command Execution: The fully parsed commands and resolved settings are dispatched to asynchronous handler functions in the commands module crates/uv/src/commands/mod.rs13-76 that implement the desired behaviors.
This layered and modular design ensures extensibility, consistency, and robust validation.
Sources: crates/uv/src/lib.rs112-180 crates/uv-cli/src/lib.rs130-136 crates/uv-cli/src/lib.rs138-174 crates/uv/src/settings.rs97-161
The CLI design models user commands and arguments with the following primary Rust types and their roles:
| Entity (Code) | CLI Role | File Reference |
|---|---|---|
Cli | Root command parser and entry point | crates/uv-cli/src/lib.rs130-136 |
TopLevelArgs | Common CLI arguments applicable to all commands | crates/uv-cli/src/lib.rs138-174 |
GlobalArgs | Cross-cutting flags like --quiet, --preview | crates/uv-cli/src/lib.rs176-364 |
Commands | Enumeration covering all top-level CLI commands | crates/uv-cli/src/lib.rs406-572 |
CacheArgs | Cache-specific CLI flags (e.g., --no-cache) | crates/uv-cache/src/lib.rs |
These structures ensure the CLI arguments are statically typed and validated before reaching business logic.
Sources: crates/uv-cli/src/lib.rs130-174 crates/uv-cli/src/lib.rs406-572
uv structures its CLI commands into namespaces and logical groups to improve usability and clarity. There are two primary command organization patterns:
Namespace Command Pattern: Groups of related functionality are grouped under namespace commands crates/uv-cli/src/lib.rs406-572
uv pip – pip-compatible package management commands.uv python – Python interpreter/version management commands.uv tool – Managing and running tools installed via uv.uv auth – Authentication management.uv workspace – Workspace inspection and management.Flattened Project Commands: Core project management commands like run, add, lock, sync, and init appear as first-level commands without further namespaces for quicker access crates/uv-cli/src/lib.rs414-460
Sources: crates/uv-cli/src/lib.rs406-572 crates/uv/src/lib.rs29-34 crates/uv/tests/it/help.rs10-42
uv employs a sophisticated layered configuration model that merges settings from multiple scopes into unified runtime values. These layers resolve conflicts and provide intuitive defaults.
The layers, ordered by increasing precedence, are:
~/.config/uv/uv.toml) crates/uv-settings/src/lib.rs47-73uv.toml or [tool.uv] in pyproject.toml) crates/uv-settings/src/lib.rs122-185UV_PYTHON, UV_CACHE_DIR) crates/uv-static/src/env_vars.rs6-146These setting layers implement the Combine trait which merges two settings layers by overriding lower-priority fields with higher-priority ones crates/uv-settings/src/combine.rs28-42
The GlobalSettings struct crates/uv/src/settings.rs80-93 embodies merged values such as verbosity level, colorization, network settings, preview features, and Python preferences. The resolve function crates/uv/src/settings.rs97-161 performs the merging logic across CLI, environment, and workspace contexts.
For the detailed mechanisms of configuration discovery, loading, and merging, see Settings and Configuration.
Sources: crates/uv/src/settings.rs80-161 crates/uv/src/lib.rs113-156 crates/uv-settings/src/combine.rs28-42 crates/uv-settings/src/lib.rs47-185
uv features a preview system for gating experimental functionality behind optional flags. This allows stability for general users while developers can test new features.
--preview command-line flag or by setting the UV_PREVIEW environment variable crates/uv-cli/src/lib.rs183-189--preview-features crates/uv-cli/src/lib.rs191-197uv_preview::set() crates/uv/src/lib.rs159 that commands check at runtime.For a complete list of current preview features (e.g., audit, format, check, native-auth) and instructions on usage, see Preview Features.
Sources: crates/uv-preview/src/lib.rs crates/uv-cli/src/lib.rs183-197 crates/uv/src/lib.rs155-160 crates/uv/src/settings.rs138
After parsing CLI arguments and resolving configuration, uv dispatches commands to their respective handler functions in the run function crates/uv/src/lib.rs112-180
run receives the fully parsed Cli struct.Commands enum variant to invoke the correct command handler function imported in crates/uv/src/commands/mod.rs13-76ExitStatus crates/uv/src/commands/mod.rs105-117 indicating success, failure, or errors.| Variant | Meaning |
|---|---|
Success | Command succeeded |
Failure | User input caused command failure |
Error | Internal or unexpected error occurred |
External(u8) | Exit code propagated from external cmd |
Sources: crates/uv/src/lib.rs112-180 crates/uv/src/commands/mod.rs105-117 crates/uv/src/commands/mod.rs13-76
This page introduced the high-level architecture and design of uv’s Command-Line Interface system.
For further technical detail and code-level explanations, please refer to the following child pages:
clap for argument parsing, the internal CLI struct layout, and command flow.Combine trait, and settings resolution.End of page.
Refresh this wiki