Command-Line Interface

Relevant source files

• crates/uv-cache/src/cli.rs
• crates/uv-cli/src/lib.rs
• crates/uv-static/src/env_vars.rs
• crates/uv/src/commands/help.rs
• crates/uv/src/commands/mod.rs
• crates/uv/src/lib.rs
• crates/uv/src/settings.rs
• crates/uv/tests/it/help.rs

This document describes uv's command-line interface architecture, including its hierarchical command structure, settings resolution system, and command dispatch mechanisms. It covers how user input flows through the CLI system from initial parsing to command execution.

For details about settings and configuration resolution, see Settings and Configuration. For information about specific command implementations, see Project Management, Tool Management, Pip-Compatible Interface, and Python Environment Management.

CLI Architecture Overview

uv's CLI is built using the Clap v4 library with derive macros for declarative command definition. The architecture separates command parsing, settings resolution, and command execution into distinct phases, providing compile-time guarantees for command completeness.

CLI Entry Point Flow

Sources: crates/uv/src/lib.rs73-100 crates/uv-cli/src/lib.rs98-114 crates/uv-cli/src/lib.rs117-153

Core CLI Structs

Struct	Purpose	Key Fields
Cli	Root command struct	command: Box<Commands>, top_level: TopLevelArgs
TopLevelArgs	Global arguments	cache_args, global_args, config_file, no_config
GlobalArgs	Cross-cutting options	quiet, verbose, color, python_preference, offline
CacheArgs	Cache configuration	no_cache, cache_dir
Commands	Command enum	Variants for each top-level command

The Cli struct uses Clap's #[command()] attributes to configure help text, styling, and command metadata. All arguments support both CLI flags and environment variables (e.g., --no-cache or UV_NO_CACHE).

Sources: crates/uv-cli/src/lib.rs98-114 crates/uv-cli/src/lib.rs117-153 crates/uv-cli/src/lib.rs155-364

Command Structure

uv organizes commands into logical namespaces, with project commands flattened to the top level for convenience. The main command structure is defined by the Commands enum in uv-cli/src/lib.rs.

Commands Enum Structure

The Commands enum defines all available uv commands using Clap's derive macros:

Sources: crates/uv-cli/src/lib.rs406-572

Namespace Patterns

uv uses two patterns for organizing commands:

Namespace Pattern (Auth, Tool, Python, Pip, Cache, Self):

• Defined as separate namespace structs (e.g., AuthNamespace, ToolNamespace)
• Each namespace contains a command field with an enum of subcommands
• Accessed as uv <namespace> <command> (e.g., uv tool install)

Flattened Pattern (Project commands):

• Project commands use #[command(flatten)] to appear at top level
• Accessed directly as uv <command> (e.g., uv run, uv add)
• Implementation detail: wrapped in Box<ProjectCommand> for size optimization

Sources: crates/uv-cli/src/lib.rs416-418 crates/uv-cli/src/lib.rs474-479

Common Command Argument Patterns

Most commands support common argument patterns:

Pattern	Example Arguments	Purpose
Python Selection	--python, UV_PYTHON	Specify Python interpreter
Output Control	--quiet, --verbose, --color	Control output verbosity and formatting
Network Control	--offline, --allow-insecure-host	Configure network access
Index Configuration	--index, --default-index, --find-links	Specify package sources
Build Options	--no-build-isolation, --config-setting	Control package building
Upgrade Control	--upgrade, --upgrade-package	Control version resolution

These arguments are defined in reusable structs like ResolverInstallerArgs, BuildArgs, and RefreshArgs that are embedded in command-specific argument structs.

Sources: crates/uv-cli/src/lib.rs1300-1650 crates/uv-cli/src/lib.rs2100-2300

Settings Resolution

uv employs a sophisticated settings resolution system that merges configuration from multiple sources in priority order. The resolution process handles both global settings and command-specific settings.

Settings Resolution Flow

Settings resolution follows a six-layer hierarchy, with each layer able to override settings from lower-priority layers. The Combine trait (from uv-settings) implements the merging logic.

Sources: crates/uv/src/lib.rs144-178 crates/uv/src/settings.rs83-164

Configuration Discovery

Configuration files are discovered using FilesystemOptions::find():

1. Explicit Path: If --config-file is provided, only that file is used (must be uv.toml)
2. No Config Mode: If --no-config is set, configuration discovery is skipped
3. Workspace Discovery: For most commands, uv discovers the workspace root and searches upward
4. User/System Fallback: User and system configs are combined with project config

Special cases:

• uv tool and uv self commands ignore project configuration (user-level only)
• PEP 723 script metadata is parsed from script files and merged into settings
• --isolated (deprecated) prevents configuration discovery

Sources: crates/uv/src/lib.rs144-178 crates/uv/src/lib.rs214-329

Environment Variable Mapping

All CLI arguments can be specified via environment variables using the UV_ prefix. The mapping is defined in EnvVars constants:

Environment Variable	CLI Equivalent	Example Value
UV_PYTHON	--python	3.12, /usr/bin/python3
UV_NO_CACHE	--no-cache	true, 1
UV_CACHE_DIR	--cache-dir	/path/to/cache
UV_INDEX_URL	--index-url	https://pypi.org/simple
UV_OFFLINE	--offline	true
UV_PYTHON_PREFERENCE	(implicit)	only-managed, only-system
UV_PREVIEW	--preview	true
UV_CONCURRENT_DOWNLOADS	(implicit)	8

Sources: crates/uv-static/src/env_vars.rs9-600 crates/uv-cli/src/lib.rs155-364

Settings Structs

Settings are organized into domain-specific structs that implement the resolution logic:

Global Settings (GlobalSettings):

GlobalSettings {
    required_version: Option<RequiredVersion>,
    quiet: u8,
    verbose: u8,
    color: ColorChoice,
    network_settings: NetworkSettings,
    concurrency: Concurrency,
    preview: Preview,
    python_preference: PythonPreference,
    python_downloads: PythonDownloads,
    no_progress: bool,
    installer_metadata: bool,
}

Network Settings (NetworkSettings):

NetworkSettings {
    connectivity: Connectivity,  // Online/Offline
    native_tls: bool,
    allow_insecure_host: Vec<TrustedHost>,
    timeout: Duration,
    retries: u32,
}

Cache Settings (CacheSettings):

CacheSettings {
    no_cache: bool,
    cache_dir: Option<PathBuf>,
}

Command-Specific Settings Examples:

• PipInstallSettings: Install-specific options (link mode, reinstall, etc.)
• RunSettings: Project run configuration (extras, groups, isolation)
• ToolRunSettings: Tool execution settings (with dependencies, constraints)
• InitSettings: Project initialization parameters (name, build backend)

Each settings struct provides a resolve() method that takes CLI arguments, filesystem options, and environment options, then applies the priority hierarchy to produce final settings.

Sources: crates/uv/src/settings.rs66-80 crates/uv/src/settings.rs183-234 crates/uv/src/settings.rs258-535

Command Dispatch Process

Once commands are parsed and settings resolved, uv dispatches to the appropriate command implementation through pattern matching in the main execution loop.

Dispatch Flow

Sources: crates/uv/src/lib.rs446-1200 crates/uv/src/commands/mod.rs1-69

Command Implementation Pattern

Each command follows a consistent implementation pattern:

1. Settings Resolution: Command-specific settings structs resolve configuration
2. Validation: Arguments and settings are validated for consistency
3. Execution: The command logic is executed with resolved settings
4. Error Handling: Results are converted to appropriate ExitStatus values

The main dispatch occurs in the run() function using exhaustive pattern matching on the Commands enum, ensuring all commands are handled and providing compile-time verification of command coverage.

Sources: crates/uv/src/lib.rs64-1200 crates/uv/src/commands/mod.rs90-103

Exit Status Handling

uv uses a structured ExitStatus enum to represent different types of command completion:

• Success: Command completed successfully
• Failure: Command failed due to user error
• Error: Command failed due to unexpected error
• External(u8): Exit code propagated from external process

This allows consistent error handling and appropriate exit code reporting across all commands.

Sources: crates/uv/src/commands/mod.rs90-114