From d751231468223551a67140ba927fc1a78b0a3aa5 Mon Sep 17 00:00:00 2001
From: Manfred Riem <15701806+mnriem@users.noreply.github.com>
Date: Mon, 10 Aug 2026 08:15:14 -0500
Subject: [PATCH] docs: document installing specify-cli from a custom package
 index (#4032)

* docs: document installing specify-cli from a custom package index

Add a generic section to the PyPI install guide covering how to point
uv, pipx, and pip at a non-default package index (env var and flags),
with a placeholder URL, plus notes on pins/upgrades and authentication.
Link to it from the main installation guide.

Assisted-by: GitHub Copilot (model: Claude Opus 4.8, autonomous)
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot-Session: d6ef3f75-54e9-4789-902b-4f0adeaadfad

* Potential fix for pull request finding

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

---------

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
Copilot-Session: d6ef3f75-54e9-4789-902b-4f0adeaadfad
---
 docs/install/pypi.md | 21 +++++++++++++++++++++
 docs/installation.md |  2 +-
 2 files changed, 22 insertions(+), 1 deletion(-)

diff --git a/docs/install/pypi.md b/docs/install/pypi.md
index 1b89d78e4..6f36df0a5 100644
--- a/docs/install/pypi.md
+++ b/docs/install/pypi.md
@@ -35,6 +35,27 @@ pipx install specify-cli==0.12.11
 pip install specify-cli==0.12.11
 ```
 
+## Install from a custom or private package index
+
+Some environments (corporate networks, mirrors, proxies, or artifact feeds) require installing `specify-cli` from a package index other than the default public PyPI. Each Python tool exposes a way to point at a different index — configure it before running the install commands above. Substitute your own index URL for the placeholder shown here.
+
+```bash
+# uv — via environment variable (applies to the whole command)
+UV_DEFAULT_INDEX=https://your-index.example.com/pypi/simple/ uv tool install specify-cli
+
+# uv — via flag
+uv tool install --default-index https://your-index.example.com/pypi/simple/ specify-cli
+
+# pipx — pass a pip argument through
+pipx install specify-cli --index-url https://your-index.example.com/pypi/simple/
+
+# pip
+pip install specify-cli --index-url https://your-index.example.com/pypi/simple/
+```
+
+> [!NOTE]
+> The same index configuration applies to pinned installs, upgrades (`--force`/`--upgrade`), and one-time usage — set the environment variable or flag on those commands too. If your index requires authentication, follow your tool's documentation and prefer credential environment variables, keyring, or netrc; do not embed secrets in command-line URLs because they can leak through shell history, process listings, or logs. Avoid committing secrets. For fully offline installs, see the [air-gapped installation guide](air-gapped.md).
+
 ## Verify
 
 ```bash
diff --git a/docs/installation.md b/docs/installation.md
index 4fa279564..67b69505e 100644
--- a/docs/installation.md
+++ b/docs/installation.md
@@ -50,7 +50,7 @@ pipx install specify-cli
 pip install specify-cli
 ```
 
-To install a specific release, pin the version — for example `uv tool install specify-cli==0.12.11`. See the [PyPI installation guide](install/pypi.md) for details, including how to upgrade.
+To install a specific release, pin the version — for example `uv tool install specify-cli==0.12.11`. See the [PyPI installation guide](install/pypi.md) for details, including how to upgrade and how to [install from a custom or private package index](install/pypi.md#install-from-a-custom-or-private-package-index).
 
 ### One-time Usage