Upgrade the Spec Kitty CLI
Who is this for (1)
- Stakeholder Persona: Project Owner — Written for the Project Owner reader.
Upgrade the spec-kitty binary to a newer release. This page covers the CLI itself only; for upgrading an existing project’s .kittify/ scaffold to match, see Upgrade a project.
Spec Kitty distinguishes CLI upgrades (installing a new
spec-kitty-cliwheel) from project upgrades (running migrations inside a project). They are separate steps.
Packagers / forks: If you publish Spec Kitty under a different distribution name or private index, do not overlay core sources — register entry-point hooks instead. See Fork packaging hooks.
Quick reference
4.x is in release candidate. Until 4.0.0 is released, a plain install gets the latest stable 3.x release, which has no
consolidatecommand. The pre-release flag in each install command on this page (--pip-args=--prefor pipx,--prerelease=allowfor uv,--prefor pip) installs the latest 4.x release candidate.
| Install method | Upgrade command |
|---|---|
| pipx | pipx upgrade --pip-args=--pre spec-kitty-cli |
| uv tool | uv tool upgrade --prerelease=allow spec-kitty-cli |
| pip (in venv) | pip install --upgrade --pre spec-kitty-cli |
Let the CLI tell you which one applies:
spec-kitty upgrade --cliThis prints the right upgrade command for your detected install method without touching any project state.
Guidance and preview intent is resolved before hidden agent preference
operations. Hidden --agent-check, --agent-choice, and --agent-latest
operations remain standalone; combining them with --cli, --project --json,
--dry-run, or --plan-json is rejected before preference state can change.
--plan-json and --cli are mutually exclusive.
pipx
pipx upgrade --pip-args=--pre spec-kitty-cliTo force a reinstall (handy after a corrupted upgrade):
pipx install --force --pip-args=--pre spec-kitty-cliTo pin a specific version, replace <version> with a released version such as 4.0.0rc8:
pipx install --force 'spec-kitty-cli==<version>'uv tool
uv tool upgrade --prerelease=allow spec-kitty-cliOr reinstall pinned:
uv tool install --force 'spec-kitty-cli==<version>'pip in a venv
Activate the venv first, then:
pip install --upgrade --pre spec-kitty-cliOr pin a version:
pip install --upgrade 'spec-kitty-cli==<version>'Verify the upgrade
spec-kitty --version# spec-kitty-cli version 4.0.0rc8If --version still reports the old number after an upgrade, your shell PATH is picking up a different install. Run which spec-kitty (or where.exe spec-kitty on Windows) and remove or correct the stale entry.
What happens after a CLI upgrade
The CLI does not automatically modify any of your projects. When you next run a project command (e.g. spec-kitty next, spec-kitty implement), spec-kitty checks whether the project schema matches the new CLI:
- Compatible → command runs normally.
- Project needs migration → command exits with code 4 and tells you to run
spec-kitty upgradein the project root. See Upgrade a project. - Project too new for this CLI → command exits with code 5. You upgraded down, not up; reinstall the newer CLI.
Throttled upgrade nag
When a newer CLI version is available on PyPI, spec-kitty prints a single banner before normal output. It is throttled to once per 24 hours. Disable per invocation with --no-nag, per session with SPEC_KITTY_NO_NAG=1, or change the cadence with SPEC_KITTY_NAG_THROTTLE_SECONDS=<seconds>.
Troubleshooting
pipx upgrade says “already at latest” but PyPI has a newer version — Your pipx cache is stale. Run pipx install --force --pip-args=--pre spec-kitty-cli.
uv tool upgrade fails with “tool not installed” — You installed via pipx, not uv. Use the matching upgrade command for your original install method.
spec-kitty --version reports the old version after upgrade — which spec-kitty will reveal a competing install in another bin directory. Remove the stale one or reorder PATH.
Upgrade succeeded but a command now exits 4 or 5 — That is the lazy-gate protecting your project; see Upgrade a project for the next step.
Next steps
- Upgrade an existing project
- Upgrade lifecycle reference
- Install and upgrade overview
- Fork packaging hooks (renamed / private-index distributors)