From 3396871f2eec2c3fad46cd4adb71dad330e70572 Mon Sep 17 00:00:00 2001
From: Zanie Blue <contact@zanie.dev>
Date: Wed, 10 Jul 2024 17:55:15 -0500
Subject: [PATCH] Add guide for tools

---
 docs/SUMMARY.md      |   2 +-
 docs/guides/tools.md | 133 ++++++++++++++++++++++++++++++++++++++++++-
 2 files changed, 133 insertions(+), 2 deletions(-)

diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md
index 87c1226b3a98..e3869cb0bddb 100644
--- a/docs/SUMMARY.md
+++ b/docs/SUMMARY.md
@@ -11,7 +11,7 @@
 
 - [Installing Python](guides/install-python.md)
 - [Running scripts](guides/scripts.md)
-- [Installing tools](guides/tools.md)
+- [Using tools](guides/tools.md)
 - [Creating a project](guides/projects.md)
 
 # Concepts
diff --git a/docs/guides/tools.md b/docs/guides/tools.md
index 01e2a10e9da2..578988f5a647 100644
--- a/docs/guides/tools.md
+++ b/docs/guides/tools.md
@@ -1 +1,132 @@
-# Installing tools
+# Using tools
+
+Many Python packages provide command-line tools. uv has specialized support for invoking tools provided by these packages.
+
+## Using `uvx`
+
+The `uvx` command is an alias for `uv tool run` which can be used to invoke a tool without installing it.
+
+For example, to run `ruff`:
+
+```console
+$ uvx ruff
+```
+
+Note this is exactly equivalent to:
+
+```console
+$ uv tool run ruff
+```
+
+Arguments can be passed to the tools:
+
+```console
+$ uvx pycowsay hello from uv
+
+  -------------
+< hello from uv >
+  -------------
+   \   ^__^
+    \  (oo)\_______
+       (__)\       )\/\
+           ||----w |
+           ||     ||
+
+```
+
+## Commands with different package names
+
+In `uvx ruff`, the `ruff` package is installed to provide the `ruff` command. However, sometimes the package name differs from the command name.
+
+To invoke a command from a specific package, e.g., `http` which is provided by `httpie`:
+
+```console
+$ uvx --from httpie http
+```
+
+## Requesting specific versions
+
+To run a tool at a specific version, use `command@<version>`:
+
+```console
+$ uvx ruff@0.3.0 check
+```
+
+The `--from` option can also be used to specify package versions:
+
+To constrain to a range of versions:
+
+```console
+$ uvx --from 'ruff>0.2.0,<0.3.0' ruff check
+```
+
+## Requesting different sources
+
+The `--from` option can also be used to install from alternative sources.
+
+To pull from git:
+
+```console
+$ uvx --from git+https://github.com/httpie/cli httpie
+```
+
+## Commands with plugins
+
+Additional dependencies can be included, e.g., to include `mkdocs-material` when running `mkdocs`:
+
+```console
+$ uvx --with mkdocs-material mkdocs --help
+```
+
+## Relationship to `uv run`
+
+The invocation `uv tool run ruff` is nearly equivalent to:
+
+```console
+$ uv run --isolated --with ruff -- ruff
+```
+
+However, there are a couple notable differences when using uv's tool interface:
+
+- The `--with` is not needed — the required package is inferred from the command name.
+- The temporary environment is cached in a dedicated location.
+- The `--isolated` flag is not needed — tools are always run isolated from the project.
+- If a tool is already installed, `uv tool run` will use the installed version but `uv run` will not.
+
+## Installing tools
+
+If a tool is used often, it can be useful to install it to a persistent environment instead of invoking `uvx` repeatedly. 
+
+To install `ruff`:
+
+```console
+$ uv tool install ruff
+```
+
+When a tool is installed, its executables are placed in a `bin` directory on the `PATH` which allows the tool to be run without uv (if it's not on the `PATH`, we'll warn you).
+
+After installing `ruff`, it should be available:
+
+```console
+$ ruff --version
+```
+
+Unlike `uvx`, `uv tool install` operates on a _package_ and will install all executables provided by the tool.
+
+For example, the following will install `http`, `https`, and `httpie`:
+
+```console
+$ uv tool install httpie
+```
+
+Additionally, package versions can be included without `--from`:
+
+```console
+$ uv tool install 'httpie>0.1.0'
+```
+
+And similarly for package sources:
+
+```console
+$ uv tool install git+https://github.com/httpie/cli
+```