Skip to content

docs: say how to replace an older install before specify init - #5004

Open
kartsan03 wants to merge 1 commit into
github:mainfrom
kartsan03:docs/4994-reinstall-older-cli
Open

kartsan03 wants to merge 1 commit into
github:mainfrom
kartsan03:docs/4994-reinstall-older-cli

Conversation

@kartsan03

Copy link
Copy Markdown
Contributor

Description

In #4994 a fresh-looking install of specify-cli reports CLI 0.1.6, and specify init fails with No such option: --integration, then No matching release asset found for claude. The README tells you to run uv tool install specify-cli, and when specify-cli is already installed, that command keeps the installed version. uv still exits 0 and prints Installed 1 executable: specify, so it looks like it worked. uv tool upgrade specify-cli doesn't help either when the old install came from a Git tag. PyPI's oldest specify-cli release is 0.9.4, so 0.1.6 must be an earlier Git install that was left in place.

Reproduced with uv 0.12.21, using a scratch UV_TOOL_DIR/UV_TOOL_BIN_DIR:

$ uv tool install specify-cli --from git+https://github.com/github/spec-kit.git@v0.1.6
$ specify version               # CLI Version 0.1.6
$ uv tool install specify-cli   # exit 0: "Checked 22 packages ... Installed 1 executable: specify"
$ specify version               # CLI Version 0.1.6
$ uv tool upgrade specify-cli   # "Nothing to upgrade"
$ specify init demo --integration claude
No such option: --integration
$ specify init demo --ai claude --script sh --ignore-agent-tools
No matching release asset found for claude (expected pattern: spec-kit-template-claude-sh)
Initialization failed: 1
$ uv tool install --force specify-cli
$ specify version               # CLI Version 1.2.1

The same happens over a PyPI install: with 1.1.3 installed, uv tool install specify-cli keeps 1.1.3. pipx install specify-cli keeps it too (it does say to pass --force), and pip install specify-cli stops at Requirement already satisfied.

This PR adds that to the two places that show the install commands:

  • README.md, under the Get started commands: if Spec Kit is already installed, check specify version and reinstall with uv tool install --force specify-cli before specify init.
  • docs/installation.md, under "Install from PyPI": the same, with the pipx and pip equivalents (the commands docs/install/pypi.md already gives for upgrades), plus the two error messages an old CLI prints, so the page can be found by searching for them.

Docs only, +6 lines. Refs #4994

Testing

  • Tested locally with uv run specify --help
  • Ran existing tests with uv sync && uv run pytest
  • Tested with a sample project (if applicable)

I didn't run the test suite, since nothing outside the two Markdown files changed. I ran every command in the description, plus the 1.1.3, pipx and pip cases, against PyPI and GitHub with uv 0.12.21, each in its own scratch tool directory.

AI Disclosure

  • I did not use AI assistance for this contribution
  • I did use AI assistance (fill in the disclosure below)

AI disclosure: Claude Code (model: claude-opus-5-5, default reasoning effort, autonomous) reproduced the install behaviour with uv, pipx and pip, wrote the docs change and this description, and made the commit (it carries an Assisted-by trailer). Extent: docs only.

`uv tool install specify-cli` keeps an already installed specify-cli,
so a machine with an old CLI (0.1.6 in github#4994) keeps it and `specify init`
fails. Note the --force/--upgrade commands next to the install commands.

Refs github#4994

Assisted-by: Claude Code (model: claude-opus-5-5, autonomous)
@kartsan03
kartsan03 requested a review from mnriem as a code owner October 17, 2026 10:30
@mnriem mnriem added the triage-must-have Verdict: high-value, important work for Spec Kit — do first label Oct 18, 2026

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

triage-must-have Verdict: high-value, important work for Spec Kit — do first

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants