From 6a0fc9f6895caa193bb4f4c26a6b465f3eb0a519 Mon Sep 17 00:00:00 2001 From: D7x7z49 <85430783+D7x7z49@users.noreply.github.com> Date: Tue, 21 Apr 2026 10:04:50 +0800 Subject: [PATCH 1/4] docs(install): add pipx as alternative installation method - Add pipx commands to README.md installation section - Add note about pipx compatibility to docs/installation.md - Mention pipx persistent installation in docs/quickstart.md - Add pipx upgrade instructions to docs/upgrade.md - Clarify that project has no uv-specific dependencies Refs: https://github.com/github/spec-kit/discussions/2255 --- README.md | 4 ++++ docs/installation.md | 7 +++++++ docs/quickstart.md | 6 ++++++ docs/upgrade.md | 8 ++++++++ 4 files changed, 25 insertions(+) diff --git a/README.md b/README.md index 38d319c9fa..6d91289070 100644 --- a/README.md +++ b/README.md @@ -62,6 +62,10 @@ uv tool install specify-cli --from git+https://github.com/github/spec-kit.git@vX # Or install latest from main (may include unreleased changes) uv tool install specify-cli --from git+https://github.com/github/spec-kit.git + +# Alternative: using pipx (also works) +pipx install git+https://github.com/github/spec-kit.git@vX.Y.Z +pipx install git+https://github.com/github/spec-kit.git ``` Then verify the correct version is installed: diff --git a/docs/installation.md b/docs/installation.md index ed253902af..0d37eda72b 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -24,6 +24,13 @@ uvx --from git+https://github.com/github/spec-kit.git@vX.Y.Z specify init ``` +> [!NOTE] +> For a persistent installation, `pipx` works equally well: +> ```bash +> pipx install git+https://github.com/github/spec-kit.git@vX.Y.Z +> ``` +> The project uses a standard `hatchling` build backend and has no uv-specific dependencies. + Or initialize in the current directory: ```bash diff --git a/docs/quickstart.md b/docs/quickstart.md index 4b2c3c8807..4be0dea814 100644 --- a/docs/quickstart.md +++ b/docs/quickstart.md @@ -22,6 +22,12 @@ uvx --from git+https://github.com/github/spec-kit.git specify init [!NOTE] +> You can also install the CLI persistently with `pipx`: +> ```bash +> pipx install git+https://github.com/github/spec-kit.git +> ``` + Pick script type explicitly (optional): ```bash diff --git a/docs/upgrade.md b/docs/upgrade.md index 020360d222..e51438e29a 100644 --- a/docs/upgrade.md +++ b/docs/upgrade.md @@ -34,6 +34,14 @@ Specify the desired release tag: uvx --from git+https://github.com/github/spec-kit.git@vX.Y.Z specify init --here --ai copilot ``` +### If you installed with `pipx` + +Upgrade to a specific release: + +```bash +pipx install --force git+https://github.com/github/spec-kit.git@vX.Y.Z +``` + ### Verify the upgrade ```bash From c8511f433cbb3ddca61d9d44dcf5dfb774bd91fd Mon Sep 17 00:00:00 2001 From: D7x7z49 <85430783+D7x7z49@users.noreply.github.com> Date: Wed, 22 Apr 2026 10:01:08 +0800 Subject: [PATCH 2/4] docs(install): address Copilot feedback - update prerequisites and upgrade references for pipx --- README.md | 3 ++- docs/installation.md | 2 +- docs/quickstart.md | 6 ++++++ docs/upgrade.md | 1 + 4 files changed, 10 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 6d91289070..b424326e55 100644 --- a/README.md +++ b/README.md @@ -93,6 +93,7 @@ To upgrade Specify, see the [Upgrade Guide](./docs/upgrade.md) for detailed inst ```bash uv tool install specify-cli --force --from git+https://github.com/github/spec-kit.git@vX.Y.Z +# pipx users: pipx install --force git+https://github.com/github/spec-kit.git@vX.Y.Z ``` #### Option 2: One-time Usage @@ -459,7 +460,7 @@ Our research and experimentation focus on: - **Linux/macOS/Windows** - [Supported](#-supported-ai-coding-agent-integrations) AI coding agent. -- [uv](https://docs.astral.sh/uv/) for package management +- [uv](https://docs.astral.sh/uv/) for package management (recommended) or [pipx](https://pypa.github.io/pipx/) for persistent installation - [Python 3.11+](https://www.python.org/downloads/) - [Git](https://git-scm.com/downloads) diff --git a/docs/installation.md b/docs/installation.md index 0d37eda72b..c99810f706 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -4,7 +4,7 @@ - **Linux/macOS** (or Windows; PowerShell scripts now supported without WSL) - AI coding agent: [Claude Code](https://www.anthropic.com/claude-code), [GitHub Copilot](https://code.visualstudio.com/), [Codebuddy CLI](https://www.codebuddy.ai/cli), [Gemini CLI](https://github.com/google-gemini/gemini-cli), or [Pi Coding Agent](https://pi.dev) -- [uv](https://docs.astral.sh/uv/) for package management +- [uv](https://docs.astral.sh/uv/) for package management (recommended) or [pipx](https://pypa.github.io/pipx/) for persistent installation - [Python 3.11+](https://www.python.org/downloads/) - [Git](https://git-scm.com/downloads) diff --git a/docs/quickstart.md b/docs/quickstart.md index 4be0dea814..05c3218094 100644 --- a/docs/quickstart.md +++ b/docs/quickstart.md @@ -27,6 +27,12 @@ uvx --from git+https://github.com/github/spec-kit.git specify init . > ```bash > pipx install git+https://github.com/github/spec-kit.git > ``` +> After installing with `pipx`, run `specify` directly instead of `uvx --from ... specify`, for example: +> ```bash +> specify init +> specify init . +> ``` + Pick script type explicitly (optional): diff --git a/docs/upgrade.md b/docs/upgrade.md index e51438e29a..09202c144d 100644 --- a/docs/upgrade.md +++ b/docs/upgrade.md @@ -9,6 +9,7 @@ | What to Upgrade | Command | When to Use | |----------------|---------|-------------| | **CLI Tool Only** | `uv tool install specify-cli --force --from git+https://github.com/github/spec-kit.git@vX.Y.Z` | Get latest CLI features without touching project files | +| **pipx upgrade** | `pipx install --force git+https://github.com/github/spec-kit.git@vX.Y.Z` | Upgrade pipx-installed CLI | | **Project Files** | `specify init --here --force --ai ` | Update slash commands, templates, and scripts in your project | | **Both** | Run CLI upgrade, then project update | Recommended for major version updates | From 9fa1091932c6cb0a9588cc1f32b5cc74aa357757 Mon Sep 17 00:00:00 2001 From: sha0dow <85430783+D7x7z49@users.noreply.github.com> Date: Thu, 23 Apr 2026 18:07:39 +0800 Subject: [PATCH 3/4] Update docs/quickstart.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit markdownlint’s MD012 (enabled in this repo) flags multiple consecutive blank lines Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- docs/quickstart.md | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/quickstart.md b/docs/quickstart.md index 05c3218094..5c0f009306 100644 --- a/docs/quickstart.md +++ b/docs/quickstart.md @@ -33,7 +33,6 @@ uvx --from git+https://github.com/github/spec-kit.git specify init . > specify init . > ``` - Pick script type explicitly (optional): ```bash From fdd33b44c1cd65833f409529e489f5cecdf5cac6 Mon Sep 17 00:00:00 2001 From: sha0dow <85430783+D7x7z49@users.noreply.github.com> Date: Thu, 23 Apr 2026 18:08:52 +0800 Subject: [PATCH 4/4] Update docs/upgrade.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit In the Quick Reference table, the label “pipx upgrade” is misleading because the command shown is `pipx install --force ...` (a reinstall). by copilot. Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- docs/upgrade.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/upgrade.md b/docs/upgrade.md index 09202c144d..1d164a3a25 100644 --- a/docs/upgrade.md +++ b/docs/upgrade.md @@ -9,7 +9,7 @@ | What to Upgrade | Command | When to Use | |----------------|---------|-------------| | **CLI Tool Only** | `uv tool install specify-cli --force --from git+https://github.com/github/spec-kit.git@vX.Y.Z` | Get latest CLI features without touching project files | -| **pipx upgrade** | `pipx install --force git+https://github.com/github/spec-kit.git@vX.Y.Z` | Upgrade pipx-installed CLI | +| **CLI Tool Only (pipx)** | `pipx install --force git+https://github.com/github/spec-kit.git@vX.Y.Z` | Reinstall/upgrade a pipx-installed CLI to a specific release | | **Project Files** | `specify init --here --force --ai ` | Update slash commands, templates, and scripts in your project | | **Both** | Run CLI upgrade, then project update | Recommended for major version updates |