From 4d79fd2c04e16677d8e4570b38c951ac7000b8cd Mon Sep 17 00:00:00 2001
From: Zanie Blue <contact@zanie.dev>
Date: Sat, 30 Aug 2025 12:26:38 -0500
Subject: [PATCH] Add documentation on the uv credential store and CLI (#15597)

---
 docs/concepts/authentication/cli.md   | 60 +++++++++++++++++++++++++++
 docs/concepts/authentication/http.md  | 10 ++++-
 docs/concepts/authentication/index.md |  1 +
 mkdocs.template.yml                   |  1 +
 4 files changed, 71 insertions(+), 1 deletion(-)
 create mode 100644 docs/concepts/authentication/cli.md

diff --git a/docs/concepts/authentication/cli.md b/docs/concepts/authentication/cli.md
new file mode 100644
index 000000000..6178b231f
--- /dev/null
+++ b/docs/concepts/authentication/cli.md
@@ -0,0 +1,60 @@
+# The `uv auth` CLI
+
+uv provides a high-level interface for storing and retrieving credentials from services.
+
+## Logging in to a service
+
+To add credentials for service, use the `uv auth login` command:
+
+```console
+$ uv auth login example.com
+```
+
+This will prompt for the credentials.
+
+The credentials can also be provided using the `--username` and `--password` options, or the
+`--token` option for services which use a `__token__` or arbitrary username.
+
+Once credentials are added, uv will use them for packaging operations that require fetching content
+from the given service. At this time, only HTTPS Basic authentication is supported. The credentials
+will not yet be used for Git requests.
+
+!!! note
+
+    The credentials will not be validated, i.e., incorrect credentials will not fail.
+
+## Logging out of a service
+
+To remove credentials, use the `uv auth logout` command:
+
+```console
+$ uv auth logout example.com
+```
+
+!!! note
+
+    The credentials will not be invalidated with the remote server, i.e., they will only be removed
+    from local storage not rendered unusable.
+
+## Showing credentials for a service
+
+To show the credential stored for a given URL, use the `uv auth token` command:
+
+```console
+$ uv auth token example.com
+```
+
+If a username was used to log in, it will need to be provided as well, e.g.:
+
+```console
+$ uv auth token --username foo example.com
+```
+
+## Configuring the storage backend
+
+By default, credentials are persisted in plain text to the uv
+[credentials file](./http.md#the-uv-credentials-file).
+
+If the [native keyring provider](./http.md#the-native-keyring-provider) is enabled, it will be used
+instead, and the credentials will be stored in a secure system store. The native keyring is
+currently experimental, but will become the default in the future.
diff --git a/docs/concepts/authentication/http.md b/docs/concepts/authentication/http.md
index 90a68410f..d9f1835a1 100644
--- a/docs/concepts/authentication/http.md
+++ b/docs/concepts/authentication/http.md
@@ -6,6 +6,7 @@ Authentication can come from the following sources, in order of precedence:
 
 - The URL, e.g., `https://<user>:<password>@<hostname>/...`
 - A [netrc](#netrc-files) configuration file
+- The uv credentials file
 - A [keyring provider](#keyring-providers) (off by default)
 
 Authentication may be used for hosts specified in the following contexts:
@@ -24,6 +25,13 @@ for storing credentials on a system.
 Reading credentials from `.netrc` files is always enabled. The target file path will be loaded from
 the `NETRC` environment variable if defined, falling back to `~/.netrc` if not.
 
+## The uv credentials file
+
+uv will read credentials from `~/.local/share/uv/credentials/credentials.toml`. This file is
+currently not intended to be edited manually.
+
+To add or remove credentials, use the [`uv auth` commands](./cli.md).
+
 ## Keyring providers
 
 A keyring provider typically fetches credentials from an operating system store.
@@ -52,7 +60,7 @@ macOS, it uses the Keychain Services. On Windows, it uses the Windows Credential
 it uses the DBus-based Secret Service API.
 
 Currently, uv only searches the native keyring provider for credentials it has added to the secret
-store.
+store. To add or remove credentials, use the [`uv auth` commands](./cli.md).
 
 Set `--keyring-provider native`, `UV_KEYRING_PROVIDER=native`, or
 `tool.uv.keyring-provider = "native"` to use the provider.
diff --git a/docs/concepts/authentication/index.md b/docs/concepts/authentication/index.md
index ff0ce4d8c..927d8311d 100644
--- a/docs/concepts/authentication/index.md
+++ b/docs/concepts/authentication/index.md
@@ -4,6 +4,7 @@ Authentication is required when working with private repositories or package ind
 
 Learn more about authentication in uv:
 
+- [Using the `uv auth` CLI](./cli.md)
 - [HTTP authentication](./http.md)
 - [Git authentication](./git.md)
 - [TLS certificates](./certificates.md)
diff --git a/mkdocs.template.yml b/mkdocs.template.yml
index 537a1f23b..ed898b3c2 100644
--- a/mkdocs.template.yml
+++ b/mkdocs.template.yml
@@ -212,6 +212,7 @@ nav:
       - Build backend: concepts/build-backend.md
       - Authentication:
           - concepts/authentication/index.md
+          - The auth CLI: concepts/authentication/cli.md
           - HTTP credentials: concepts/authentication/http.md
           - Git credentials: concepts/authentication/git.md
           - TLS certificates: concepts/authentication/certificates.md