Initial commit

skills/uv/references/cli_reference.md

@@ -0,0 +1,632 @@
+# uv CLI Reference
+
+Complete command-line interface reference for uv (v0.9.5).
+
+## Global Flags
+
+Available across all commands:
+
+```bash
+--help, -h              Display help
+--verbose, -v           Verbose logging (repeat for more: -vv, -vvv)
+--quiet, -q             Suppress output
+--color <WHEN>          Color output (auto/always/never)
+--no-progress           Hide progress indicators
+--cache-dir <DIR>       Cache directory
+--no-cache              Disable caching
+--offline               Disable network access
+--python <VERSION>      Python interpreter/version
+--directory <PATH>      Working directory
+--config-file <PATH>    Custom config file
+--no-config             Ignore config files
+--preview               Enable preview features
+```
+
+## Project Commands
+
+### uv init
+
+Create new project or script.
+
+```bash
+uv init [OPTIONS] [PATH]
+
+--lib, --library        Create library (implies --package)
+--app, --application    Create application (default)
+--script                Create PEP 723 script
+--package               Distributable package with src/
+--no-package            Non-package (virtual) project
+--bare                  Minimal configuration only
+--build-backend <BACKEND>  Build system (hatchling/setuptools/uv_build)
+--python <VERSION>      Python version requirement
+--vcs <VCS>             Version control (git/none)
+--python-pin            Create .python-version
+```
+
+### uv add
+
+Add dependencies to project.
+
+```bash
+uv add [OPTIONS] <PACKAGES>...
+
+--dev                   Add to dev dependencies
+--group <GROUP>         Add to dependency group
+--optional <EXTRA>      Add to optional dependencies
+--editable, -e          Editable/development mode
+--frozen                Skip lockfile updates
+--locked                Assert lockfile unchanged
+--no-sync               Skip environment sync
+--bounds <TYPE>         Version constraint (lowest/compatible/exact)
+--branch <BRANCH>       Git branch
+--tag <TAG>             Git tag
+--rev <REV>             Git revision
+--raw-sources           Raw source specifiers
+```
+
+### uv remove
+
+Remove dependencies.
+
+```bash
+uv remove [OPTIONS] <PACKAGES>...
+
+--dev                   Remove from dev dependencies
+--group <GROUP>         Remove from dependency group
+--optional <EXTRA>      Remove from optional dependencies
+--frozen                Skip lockfile updates
+--locked                Assert lockfile unchanged
+```
+
+### uv sync
+
+Synchronize project environment with lockfile.
+
+```bash
+uv sync [OPTIONS]
+
+--extra <EXTRA>, -E     Include optional dependencies
+--all-extras            Include all optional dependencies
+--no-dev                Exclude dev dependencies
+--only-dev              Only dev dependencies
+--group <GROUP>         Include dependency group
+--only-group <GROUP>    Only specified group
+--no-install-project    Skip installing project itself
+--frozen                Use existing lockfile
+--locked                Assert lockfile unchanged
+--inexact               Allow non-exact versions
+--python <VERSION>      Target Python version
+```
+
+### uv lock
+
+Update project lockfile.
+
+```bash
+uv lock [OPTIONS]
+
+--frozen                Don't update lockfile
+--locked                Assert lockfile unchanged
+--upgrade, -U           Allow package upgrades
+--upgrade-package <PKG>, -P  Upgrade specific packages
+--dry-run               Show changes without writing
+```
+
+### uv run
+
+Execute commands in project environment.
+
+```bash
+uv run [OPTIONS] <COMMAND> [ARGS]...
+
+--python <VERSION>      Python version
+--module, -m            Run as module
+--script, -s            Treat as PEP 723 script
+--with <PKG>, -w        Include temporary packages
+--isolated              Fresh isolated environment
+--frozen                Skip lockfile updates
+--locked                Assert lockfile unchanged
+--no-sync               Skip environment sync
+--no-project            Don't load project environment
+--no-dev                Exclude dev dependencies
+--extra <EXTRA>         Include optional dependencies
+--all-extras            Include all optional dependencies
+--package <PKG>         Run for specific workspace package
+--env-file <FILE>       Load environment variables
+```
+
+### uv tree
+
+Display dependency tree.
+
+```bash
+uv tree [OPTIONS]
+
+--depth <DEPTH>         Maximum display depth
+--prune <PKG>           Prune packages from tree
+--package <PKG>         Show tree for specific package
+--invert                Show reverse dependencies
+--no-dedupe             Show all occurrences
+```
+
+### uv export
+
+Export dependencies to various formats.
+
+```bash
+uv export [OPTIONS]
+
+--format <FORMAT>       Output format (requirements-txt/pylock)
+-o, --output-file <FILE>  Output file path
+--extra <EXTRA>         Include optional dependencies
+--all-extras            Include all optional dependencies
+--no-dev                Exclude dev dependencies
+--frozen                Use existing lockfile
+```
+
+## Tool Management
+
+### uv tool run (alias: uvx)
+
+Execute tool without persistent installation.
+
+```bash
+uvx [OPTIONS] <COMMAND> [ARGS]...
+uv tool run [OPTIONS] <COMMAND> [ARGS]...
+
+--from <PACKAGE>        Source package
+--with <PACKAGE>        Include additional packages
+--python <VERSION>      Python version
+--isolated              Fresh environment
+```
+
+### uv tool install
+
+Install tool persistently.
+
+```bash
+uv tool install [OPTIONS] <PACKAGE>
+
+--from <PACKAGE>        Install from specific package
+--with <PACKAGE>        Include additional packages
+--python <VERSION>      Python version
+--force                 Overwrite existing
+--editable, -e          Editable mode
+```
+
+### uv tool upgrade
+
+Update installed tool.
+
+```bash
+uv tool upgrade [OPTIONS] [PACKAGE]
+
+--all                   Upgrade all tools
+```
+
+### uv tool list
+
+List installed tools.
+
+```bash
+uv tool list [OPTIONS]
+
+--show-paths            Display installation paths
+```
+
+### uv tool uninstall
+
+Remove installed tool.
+
+```bash
+uv tool uninstall <PACKAGE>
+```
+
+## Python Management
+
+### uv python install
+
+Install Python versions.
+
+```bash
+uv python install [OPTIONS] <VERSIONS>...
+
+--force                 Reinstall if present
+--preview               Allow preview versions
+```
+
+### uv python list
+
+List Python versions.
+
+```bash
+uv python list [OPTIONS]
+
+--all-versions          Show all available versions
+--only-installed        Show only installed versions
+```
+
+### uv python pin
+
+Pin Python version for project.
+
+```bash
+uv python pin [OPTIONS] <VERSION>
+
+--global                Pin globally for user
+--rm                    Remove pin
+--python-preference <PREF>  Preference (only-managed/managed/system/only-system)
+```
+
+### uv python find
+
+Locate Python interpreter.
+
+```bash
+uv python find <VERSION>
+```
+
+### uv python upgrade
+
+Update Python installations.
+
+```bash
+uv python upgrade [OPTIONS] [VERSION]
+
+--all                   Upgrade all installations
+```
+
+## pip Interface
+
+### uv pip install
+
+Install packages.
+
+```bash
+uv pip install [OPTIONS] <PACKAGES>...
+
+--requirement <FILE>, -r     Install from requirements
+--editable <PATH>, -e        Editable mode
+--constraint <FILE>, -c      Apply constraints
+--override <FILE>            Apply overrides
+--extra <EXTRA>              Install optional dependencies
+--all-extras                 Install all optional dependencies
+--no-deps                    Don't install dependencies
+--python <PYTHON>            Target Python environment
+--system                     Install into system Python
+--break-system-packages      Allow system modifications
+--target <DIR>               Install to directory
+--upgrade, -U                Upgrade packages
+--upgrade-package <PKG>, -P  Upgrade specific packages
+--force-reinstall            Reinstall even if satisfied
+--no-build                   Don't build from source
+--no-binary <PKG>            Don't use wheels
+--only-binary <PKG>          Only use wheels
+--dry-run                    Show changes without installing
+```
+
+### uv pip compile
+
+Generate requirements file.
+
+```bash
+uv pip compile [OPTIONS] <INPUT_FILES>...
+
+-o, --output-file <FILE>     Output file
+--extra <EXTRA>              Include optional dependencies
+--all-extras                 Include all optional dependencies
+--constraint <FILE>, -c      Apply constraints
+--override <FILE>            Apply overrides
+--python <VERSION>           Target Python version
+--python-platform <PLATFORM> Target platform
+--python-version <VERSION>   Python version constraint
+--universal                  Cross-platform requirements
+--no-strip-markers           Preserve environment markers
+--resolution <STRATEGY>      Resolution strategy (highest/lowest/lowest-direct)
+--prerelease <MODE>          Pre-release handling (allow/disallow/if-necessary/if-necessary-or-explicit)
+--upgrade, -U                Allow upgrades
+--upgrade-package <PKG>, -P  Upgrade specific packages
+--generate-hashes            Include package hashes
+--annotation-style <STYLE>   Annotation format (line/split)
+```
+
+### uv pip sync
+
+Install from requirements file.
+
+```bash
+uv pip sync [OPTIONS] <FILE>
+
+--python <PYTHON>            Target Python environment
+--system                     Install into system Python
+--break-system-packages      Allow system modifications
+--target <DIR>               Install to directory
+--no-build                   Don't build from source
+--dry-run                    Show changes without installing
+--reinstall                  Reinstall all packages
+--link-mode <MODE>           Installation link mode (clone/copy/hardlink/symlink)
+--compile-bytecode           Compile to bytecode
+--require-hashes             Require package hashes
+```
+
+### uv pip uninstall
+
+Remove packages.
+
+```bash
+uv pip uninstall [OPTIONS] <PACKAGES>...
+
+--requirement <FILE>, -r     Uninstall from requirements
+--python <PYTHON>            Target Python environment
+--system                     Uninstall from system Python
+```
+
+### uv pip freeze
+
+List installed packages.
+
+```bash
+uv pip freeze [OPTIONS]
+
+--exclude-editable           Exclude editable packages
+--strict                     Fail on missing dependencies
+--python <PYTHON>            Target Python environment
+```
+
+### uv pip list
+
+List installed packages with formatting.
+
+```bash
+uv pip list [OPTIONS]
+
+--editable, -e               Show only editable packages
+--exclude-editable           Exclude editable packages
+--format <FORMAT>            Output format (columns/freeze/json)
+--python <PYTHON>            Target Python environment
+--system                     Target system Python
+```
+
+### uv pip show
+
+Display package information.
+
+```bash
+uv pip show <PACKAGE>
+
+--python <PYTHON>            Target Python environment
+--system                     Target system Python
+```
+
+### uv pip tree
+
+Display dependency tree.
+
+```bash
+uv pip tree [OPTIONS]
+
+--depth <DEPTH>              Maximum display depth
+--prune <PKG>                Prune packages
+--package <PKG>              Show tree for specific package
+--invert                     Show reverse dependencies
+--python <PYTHON>            Target Python environment
+--no-dedupe                  Show all occurrences
+```
+
+### uv pip check
+
+Verify dependencies.
+
+```bash
+uv pip check [OPTIONS]
+
+--python <PYTHON>            Target Python environment
+--system                     Target system Python
+```
+
+## Virtual Environments
+
+### uv venv
+
+Create virtual environment.
+
+```bash
+uv venv [OPTIONS] [PATH]
+
+--python <VERSION>           Python version
+--seed                       Install seed packages (pip, setuptools, wheel)
+--prompt <PROMPT>            Custom environment prompt
+--system-site-packages       Access to system packages
+--relocatable                Relocatable environment
+--allow-existing             Allow existing directory
+--no-project                 Don't detect project
+```
+
+## Build and Publish
+
+### uv build
+
+Build Python packages.
+
+```bash
+uv build [OPTIONS] [SRC]
+
+--sdist                      Build source distribution only
+--wheel                      Build wheel only
+--out-dir <DIR>              Output directory (default: dist/)
+--package <PACKAGE>          Build specific workspace package
+--no-build-isolation         Disable build isolation
+--build-constraint <FILE>    Apply build constraints
+--config-setting <KEY=VALUE> Pass settings to build backend
+```
+
+### uv publish
+
+Upload distributions to package indexes.
+
+```bash
+uv publish [OPTIONS] [FILES]...
+
+--username <USER>, -u        Registry username
+--password <PASS>, -p        Registry password
+--token <TOKEN>, -t          Authentication token
+--publish-url <URL>          Registry URL (default: PyPI)
+--index <NAME>               Named index from config
+--keyring-provider <PROVIDER> Keyring authentication
+--trusted-publishing <MODE>  OIDC trusted publishing (always/if-available/never)
+--check-url <URL>            Verify package existence URL
+--build                      Build packages before publishing
+--no-build                   Publish existing distributions
+```
+
+## Cache Management
+
+### uv cache clean
+
+Clear cache.
+
+```bash
+uv cache clean [OPTIONS] [PACKAGE]
+
+--package <PACKAGE>          Clean specific package only
+```
+
+### uv cache prune
+
+Remove unreachable entries.
+
+```bash
+uv cache prune [OPTIONS]
+
+--ci                         Optimize for CI (keep wheels, remove downloads)
+```
+
+### uv cache dir
+
+Show cache directory path.
+
+```bash
+uv cache dir
+```
+
+## Self Management
+
+### uv self update
+
+Update uv itself.
+
+```bash
+uv self update [OPTIONS]
+
+--version <VERSION>          Update to specific version
+```
+
+### uv self version
+
+Show uv version.
+
+```bash
+uv self version
+uv --version      # Equivalent
+uv -V             # Short form
+```
+
+## Utility Commands
+
+### uv generate-shell-completion
+
+Generate shell completions.
+
+```bash
+uv generate-shell-completion <SHELL>
+
+# Shells: bash, zsh, fish, elvish, powershell
+```
+
+## Index and Resolution Flags
+
+Control package index behavior:
+
+```bash
+--index <NAME>=<URL>         Named package index
+--default-index <URL>        Primary index
+--extra-index-url <URL>      Supplementary index
+--find-links <PATH_OR_URL>   Find-links location
+--no-index                   Ignore all indexes
+--index-strategy <STRATEGY>  Resolution strategy (first-index/unsafe-first-match/unsafe-best-match)
+--resolution <STRATEGY>      Version selection (highest/lowest/lowest-direct)
+--prerelease <MODE>          Pre-release handling
+--exclude-newer <TIMESTAMP>  Exclude packages newer than timestamp
+--no-sources                 Ignore [tool.uv.sources]
+```
+
+## Build Flags
+
+Control build and installation:
+
+```bash
+--no-build                   Don't build from source
+--no-binary <PKG>            Don't use wheels (use :all: for all)
+--only-binary <PKG>          Only use wheels (use :all: for all)
+--no-build-isolation         Disable build isolation
+--no-build-isolation-package <PKG>  Disable for specific packages
+--build-constraint <FILE>    Build dependency constraints
+--config-setting <KEY=VALUE> PEP 517 build backend settings
+--link-mode <MODE>           Installation method (clone/copy/hardlink/symlink)
+--compile-bytecode           Compile to bytecode
+--reinstall                  Reinstall all packages
+--reinstall-package <PKG>    Reinstall specific packages
+--require-hashes             Require package hashes
+```
+
+## Examples
+
+**Initialize and manage project:**
+
+```bash
+uv init myproject --lib
+cd myproject
+uv add requests pytest --dev
+uv lock
+uv sync
+uv run pytest
+```
+
+**Create and run script:**
+
+```bash
+uv init --script analyze.py
+uv add --script analyze.py pandas matplotlib
+uv run analyze.py
+```
+
+**Install and use tools:**
+
+```bash
+uvx ruff check
+uv tool install black
+black myfile.py
+```
+
+**Python version management:**
+
+```bash
+uv python install 3.12
+uv python pin 3.12
+uv run --python 3.11 script.py
+```
+
+**pip interface:**
+
+```bash
+uv pip install flask
+uv pip compile requirements.in -o requirements.txt
+uv pip sync requirements.txt
+```
+
+**Build and publish:**
+
+```bash
+uv build
+uv publish --token $PYPI_TOKEN
+```