Improve CLI documentation for uv run

crates/uv-cli/src/lib.rs

@@ -438,6 +438,24 @@ pub enum PipCommand {
 #[derive(Subcommand)]
 pub enum ProjectCommand {
     /// Run a command or script (experimental).
+    ///
+    /// When used with a file ending in `.py`, it will be treated as a script
+    /// and run with a Python interpreter, i.e., `uv run file.py` is equivalent
+    /// to `uv run python file.py`. If the script contains inline dependency
+    /// metadata, it will be installed into an isolated, ephemeral environment.
+    ///
+    /// Arguments following the command (or script) are not interpreted as
+    /// arguments to uv. All options to uv must be provided before the command,
+    /// e.g., `uv run --verbose foo`. A `--` can be used to separate the command
+    /// from uv options for clarity, e.g., `uv run --python 3.12 -- python`.
+    ///
+    /// When used in a project, the project environment will be created and
+    /// updated before invoking the command.
+    ///
+    /// When outside a project, if a virtual environment can be found in the
+    /// current directory or a parent directory, the command will be run in that
+    /// environment. Otherwise, the command will be run in the environment of
+    /// discovered interpreter.
     #[command(
         after_help = "Use `uv help run` for more details.",
         after_long_help = ""
@@ -1962,53 +1980,98 @@ pub struct InitArgs {
 #[derive(Args)]
 #[allow(clippy::struct_excessive_bools)]
 pub struct RunArgs {
-    /// Include optional dependencies from the extra group name; may be provided more than once.
+    /// Include optional dependencies from the extra group name.
     ///
-    /// Only applies to `pyproject.toml`, `setup.py`, and `setup.cfg` sources.
+    /// May be provided more than once.
+    ///
+    /// Optional dependencies are defined at `project.optional-dependencies` in
+    /// a `pyproject.toml`.
+    ///
+    /// This option is only available when running in a project or invoking a
+    /// script with inline metadata.
     #[arg(long, conflicts_with = "all_extras", value_parser = extra_name_with_clap_error)]
     pub extra: Option<Vec<ExtraName>>,
 
     /// Include all optional dependencies.
     ///
-    /// Only applies to `pyproject.toml`, `setup.py`, and `setup.cfg` sources.
+    /// Optional dependencies are defined at `project.optional-dependencies` in
+    /// a `pyproject.toml`.
+    ///
+    /// This option is only available when running in a project or invoking a
+    /// script with inline metadata.
     #[arg(long, conflicts_with = "extra")]
     pub all_extras: bool,
 
     #[arg(long, overrides_with("all_extras"), hide = true)]
     pub no_all_extras: bool,
 
     /// Include development dependencies.
+    ///
+    /// Development dependencies are defined at `tool.uv.dev-dependencies` in a
+    /// `pyproject.toml`.
+    ///
+    /// This option is only available when running in a project or invoking a
+    /// script with inline metadata.
     #[arg(long, overrides_with("no_dev"), hide = true)]
     pub dev: bool,
 
     /// Omit development dependencies.
+    ///
+    /// This option is only available when running in a project or invoking a
+    /// script with inline metadata.
     #[arg(long, overrides_with("dev"))]
     pub no_dev: bool,
 
     /// The command to run.
+    ///
+    /// If the path to a Python script (i.e., ending in `.py`), it will be
+    /// executed with the Python interpreter.
     #[command(subcommand)]
     pub command: ExternalCommand,
 
     /// Run with the given packages installed.
+    ///
+    /// When used in a project, these dependencies will be layered on top of
+    /// the project environment in a separate, ephemeral environment. These
+    /// dependencies are allowed to conflict with those specified by the project.
     #[arg(long)]
     pub with: Vec<String>,
 
     /// Run with all packages listed in the given `requirements.txt` files.
     ///
+    /// The same environment semantics as `--with` apply.
+    ///
     /// Using `pyproject.toml`, `setup.py`, or `setup.cfg` files is not allowed.
     #[arg(long, value_parser = parse_maybe_file_path)]
     pub with_requirements: Vec<Maybe<PathBuf>>,
 
-    /// Run the tool in an isolated virtual environment, rather than leveraging the base environment
-    /// for the current project, to enforce strict isolation between dependencies.
+    /// Run the tool in an isolated virtual environment.
+    ///
+    /// Usually, the project environment is reused for performance. This option
+    /// forces a fresh environment to be used for the project, enforcing strict
+    /// isolation between dependencies and declaration of requirements.
+    ///
+    /// An editable installation is still used for the project.
+    ///
+    /// When used with `--with` or `--with-requirements`, the additional
+    /// dependencies will still be layered in a second environment.
     #[arg(long)]
     pub isolated: bool,
 
     /// Assert that the `uv.lock` will remain unchanged.
+    ///
+    /// Requires that the lockfile is up-to-date. If the lockfile is missing, or
+    /// if it needs to be updated, uv will exit with an error.
     #[arg(long, conflicts_with = "frozen")]
     pub locked: bool,
 
-    /// Install without updating the `uv.lock` file.
+    /// Run without updating the `uv.lock` file.
+    ///
+    /// Instead of checking if the lockfile is up-to-date, uses the versions in
+    /// the lockfile as the source of truth. If the lockfile is missing, uv will
+    /// exit with an error. If the `pyproject.toml` includes new dependencies
+    /// that have not been included in the lockfile yet, they will not be
+    /// present in the environment.
     #[arg(long, conflicts_with = "locked")]
     pub frozen: bool,
 
@@ -2022,11 +2085,21 @@ pub struct RunArgs {
     pub refresh: RefreshArgs,
 
     /// Run the command in a specific package in the workspace.
+    ///
+    /// If not in a workspace, or if the workspace member does not exist, uv
+    /// will exit with an error.
     #[arg(long)]
     pub package: Option<PackageName>,
 
-    /// Avoid discovering the project or workspace in the current directory or any parent directory.
-    /// Instead, run in an isolated, ephemeral environment populated by the `--with` requirements.
+    /// Avoid discovering the project or workspace.
+    ///
+    /// Instead of searching for projects in the current directory and parent
+    /// directories, run in an isolated, ephemeral environment populated by the
+    /// `--with` requirements.
+    ///
+    /// If a virtual environment is active or found in a current or parent
+    /// directory, it will be ignored and a new isolated environment will be
+    /// used.
     #[arg(long, alias = "no_workspace", conflicts_with = "package")]
     pub no_project: bool,
 
@@ -2037,6 +2110,7 @@ pub struct RunArgs {
     /// option allows you to specify a different interpreter.
     ///
     /// Supported formats:
+    ///
     /// - `3.10` looks for an installed Python 3.10 using `py --list-paths` on Windows, or
     ///   `python3.10` on Linux and macOS.
     /// - `python3.10` or `python.exe` looks for a binary with the given name in `PATH`.

docs/reference/cli.md

@@ -44,7 +44,15 @@ uv [OPTIONS] <COMMAND>
 
 ## uv run
 
-Run a command or script (experimental)
+Run a command or script (experimental).
+
+When used with a file ending in `.py`, it will be treated as a script and run with a Python interpreter, i.e., `uv run file.py` is equivalent to `uv run python file.py`. If the script contains inline dependency metadata, it will be installed into an isolated, ephemeral environment.
+
+Arguments following the command (or script) are not interpreted as arguments to uv. All options to uv must be provided before the command, e.g., `uv run --verbose foo`. A `--` can be used to separate the command from uv options for clarity, e.g., `uv run --python 3.12 -- python`.
+
+When used in a project, the project environment will be created and updated before invoking the command.
+
+When outside a project, if a virtual environment can be found in the current directory or a parent directory, the command will be run in that environment. Otherwise, the command will be run in the environment of discovered interpreter.
 
 <h3 class="cli-reference">Usage</h3>
 
@@ -54,14 +62,22 @@ uv run [OPTIONS] <COMMAND>
 
 <h3 class="cli-reference">Options</h3>
 
-<dl class="cli-reference"><dt><code>--extra</code> <i>extra</i></dt><dd><p>Include optional dependencies from the extra group name; may be provided more than once.</p>
+<dl class="cli-reference"><dt><code>--extra</code> <i>extra</i></dt><dd><p>Include optional dependencies from the extra group name.</p>
 
-<p>Only applies to <code>pyproject.toml</code>, <code>setup.py</code>, and <code>setup.cfg</code> sources.</p>
+<p>May be provided more than once.</p>
 
-</dd><dt><code>--with</code> <i>with</i></dt><dd><p>Run with the given packages installed</p>
+<p>Optional dependencies are defined at <code>project.optional-dependencies</code> in a <code>pyproject.toml</code>.</p>
+
+<p>This option is only available when running in a project or invoking a script with inline metadata.</p>
+
+</dd><dt><code>--with</code> <i>with</i></dt><dd><p>Run with the given packages installed.</p>
+
+<p>When used in a project, these dependencies will be layered on top of the project environment in a separate, ephemeral environment. These dependencies are allowed to conflict with those specified by the project.</p>
 
 </dd><dt><code>--with-requirements</code> <i>with-requirements</i></dt><dd><p>Run with all packages listed in the given <code>requirements.txt</code> files.</p>
 
+<p>The same environment semantics as <code>--with</code> apply.</p>
+
 <p>Using <code>pyproject.toml</code>, <code>setup.py</code>, or <code>setup.cfg</code> files is not allowed.</p>
 
 </dd><dt><code>--index-url</code>, <code>-i</code> <i>index-url</i></dt><dd><p>The URL of the Python package index (by default: &lt;https://pypi.org/simple&gt;).</p>
@@ -169,7 +185,9 @@ uv run [OPTIONS] <COMMAND>
 
 </dd><dt><code>--refresh-package</code> <i>refresh-package</i></dt><dd><p>Refresh cached data for a specific package</p>
 
-</dd><dt><code>--package</code> <i>package</i></dt><dd><p>Run the command in a specific package in the workspace</p>
+</dd><dt><code>--package</code> <i>package</i></dt><dd><p>Run the command in a specific package in the workspace.</p>
+
+<p>If not in a workspace, or if the workspace member does not exist, uv will exit with an error.</p>
 
 </dd><dt><code>--python</code>, <code>-p</code> <i>python</i></dt><dd><p>The Python interpreter to use to build the run environment.</p>