Skip to content

💫 Toolkit to help you get started with SDD or any other process!

docs: clarify CLI upgrade discovery (#2519)

Asish Kumarcd951acb9e6b
diff --git a/docs/reference/integrations.md b/docs/reference/integrations.md
index 42332b1fe..d41119a98 100644
--- a/docs/reference/integrations.md
+++ b/docs/reference/integrations.md
@@ -65,6 +65,8 @@ Installing an additional integration does not change the default integration. Us
> **Note:** All integration management commands require a project already initialized with `specify init`. To start a new project with a specific agent, use `specify init <project> --integration <key>` instead.
+**Version note:** Controlled multi-install support was introduced in Spec Kit 0.8.5. If `specify integration install <key>` says another integration is already installed and only suggests `switch` or `uninstall`, check your local CLI with `specify version` and upgrade it. Running a one-shot command such as `uvx --from git+https://github.com/github/spec-kit.git specify ...` uses a temporary copy for that command only; it does not update the persistent `specify` executable on your `PATH`.
+
## Uninstall an Integration
```bash
diff --git a/docs/upgrade.md b/docs/upgrade.md
index ec87662cb..83edc58c2 100644
--- a/docs/upgrade.md
+++ b/docs/upgrade.md
@@ -19,6 +19,12 @@
The CLI tool (`specify`) is separate from your project files. Upgrade it to get the latest features and bug fixes.
+Before upgrading, you can check whether a newer released version is available:
+
+```bash
+specify self check
+```
+
### If you installed with `uv tool install`
Upgrade to a specific release (check [Releases](https://github.com/github/spec-kit/releases) for the latest tag):
@@ -35,6 +41,8 @@ Specify the desired release tag:
uvx --from git+https://github.com/github/[email protected] specify init --here --integration copilot
```
+`uvx` runs a temporary copy of Spec Kit for that single command. It does not update a persistent `specify` installed with `uv tool install`, `pipx`, or another tool manager. If a newer feature works through `uvx` but your local `specify` still reports an older version, upgrade the persistent CLI with the command that matches your install method.
+
### If you installed with `pipx`
Upgrade to a specific release:
@@ -49,7 +57,7 @@ pipx install --force git+https://github.com/github/[email protected]
specify check
```
-This shows installed tools and confirms the CLI is working.
+This shows installed tools and confirms the CLI is working. Use `specify version` to confirm which persistent CLI version is currently on your `PATH`.
---