How to Install and Upgrade Spec Kitty
Who is this for (1)
- Stakeholder Persona: Project Owner — Written for the Project Owner reader.
Formal requirements:
kitty-specs/cli-upgrade-nag-lazy-project-migrations-01KQ6YDN/spec.md
Two upgrades, not one
Spec Kitty has two distinct upgrade concepts:
- Upgrading the CLI — installing a newer
spec-kittybinary (pipx, pip, Homebrew, etc.). - Migrating a project — updating
.kittify/schema inside one specific project to match the installed CLI.
Spec Kitty never silently upgrades itself and never touches projects you are not currently inside.
Install the CLI
For new installations, prefer pipx:
pipx install --pip-args=--pre spec-kitty-clipipx ensurepathspec-kitty --versionpipx keeps the CLI in its own virtual environment while exposing the
spec-kitty command on your PATH. This avoids the PEP 668
externally-managed-environment failure that direct pip install commands can
hit on Ubuntu 24.04, Debian 12, Fedora, and other distro-managed Python
installations.
Other supported install methods:
uv tool install --prerelease=allow spec-kitty-cli# Inside an activated virtual environment or managed CI Python imagepython -m pip install --pre spec-kitty-cliUse pip when you are intentionally managing the Python environment yourself.
Do not use --break-system-packages as a normal Spec Kitty install path.
Upgrade the CLI
Run from anywhere:
spec-kitty upgrade --cliSpec Kitty detects your install method and prints the right command:
| Install method | Upgrade command |
|---|---|
| pipx (preferred) | pipx upgrade --pip-args=--pre spec-kitty-cli |
| pip (user) | pip install --upgrade --user --pre spec-kitty-cli |
| pip (venv/system) | pip install --upgrade --pre spec-kitty-cli |
| Homebrew | brew upgrade spec-kitty |
| System package | use your package manager |
If the install method cannot be detected, Spec Kitty prints manual instructions instead
of a runnable command — rerun spec-kitty upgrade --cli after you upgrade to confirm
detection works.
Migrate the current project
Run from inside the project root:
spec-kitty upgrade # interactivespec-kitty upgrade --project # same thing, explicitPreview first:
spec-kitty upgrade --dry-run# Project: schema 1, target schema 3# Migrations:# m_2_0_0_lane_layout# m_2_5_0_lane_consolidation# m_3_0_0_canonical_contextApply non-interactively (CI, scripts):
spec-kitty upgrade --yes # or --force; both workMigrations are idempotent and applied in version order.
Opt in to the rc (pre-release) channel
By default the CLI only ever advises you toward the latest stable release, even when a
newer release candidate (rcN) exists on the configured index. Early adopters and internal
team members who want to catfood rc builds can opt in with SPEC_KITTY_PRERELEASE:
export SPEC_KITTY_PRERELEASE=1spec-kitty upgrade --agent-checkOr, once, with no per-shell export — write it into .kitty.env:
# .kittify/.kitty.env (per-repo) or ${SPEC_KITTY_HOME}/.kitty.env (machine-wide)SPEC_KITTY_PRERELEASE=1With the channel on, the newest pre-release is surfaced and the proposed upgrade command is a
pinned install (pip install spec-kitty-cli==4.0.0rc8, for example) — never a floating
--pre flag, so you always know exactly which candidate you are about to install. Check which
channel is active at any time:
spec-kitty doctor channelStable-channel users (the default, and the overwhelming majority) never see an rc advisory —
this is a structural guarantee, not a UX nicety. See ADR: default-off rc release
channel for the design rationale, and
Environment Variables Reference § The .kitty.env
file for the general
per-repo/machine-wide config mechanism this preference uses.
The throttled nag
When a newer CLI version is available, Spec Kitty prints one line before normal output:
Spec Kitty 3.2.1 is available; you have 3.2.0.Upgrade with: pipx upgrade spec-kitty-cliThrottled to once per 24 hours by default. Configure:
SPEC_KITTY_NAG_THROTTLE_SECONDS=3600 spec-kitty upgrade --cli # 1-hour windowOr in ~/.config/spec-kitty/upgrade.yaml:
nag: throttle_seconds: 3600Disable entirely:
spec-kitty upgrade --cli --no-nag # this invocation onlySPEC_KITTY_NO_NAG=1 spec-kitty upgrade --cli # this shell sessionThe lazy gate
When a project’s schema is incompatible with the installed CLI, unsafe commands are blocked.
Project needs migration — exit code 4:
cd /path/to/oldprojspec-kitty next --agent claude# This project needs Spec Kitty project migrations before this command can run.# Run: spec-kitty upgrade# Preview first: spec-kitty upgrade --dry-runecho $? # 4Remediate: run spec-kitty upgrade, then retry.
Project too new for installed CLI — exit code 5:
cd /path/to/futureprojspec-kitty implement WP01# This project uses Spec Kitty project schema 7, but this CLI supports up to schema 6.# Upgrade the CLI: pipx upgrade spec-kitty-cliecho $? # 5Remediate: upgrade the CLI. --yes and --force do not bypass this block.
Commands that always work regardless of schema:
spec-kitty --helpspec-kitty --versionspec-kitty upgrade --dry-run # always allowedspec-kitty upgrade --cli # always allowedAfter the project schema is compatible, inspect the current Mission’s work packages with:
spec-kitty agent tasks status --mission <mission>Behavior in CI
When CI=1 is set (or stdout is not a TTY):
- The nag is suppressed and no PyPI fetch is made.
- The project compatibility gate still runs — incompatible projects exit with code 4 or 5 as normal.
CI=1 spec-kitty next --agent claude# no nag; still exits 4 if project needs migrationExit codes
| Code | Meaning |
|---|---|
0 | Success / safe pass-through |
2 | Usage error (e.g. --cli and --project combined) |
4 | Project needs migration — run spec-kitty upgrade |
5 | Project too new for this CLI — upgrade the CLI |
6 | Project metadata corrupt or unreadable |
JSON output for tooling
spec-kitty upgrade --dry-run --json | jq .case# "project_migration_needed"
spec-kitty upgrade --dry-run --json | jq -r '.upgrade_hint.command'# pipx upgrade spec-kitty-cli
spec-kitty upgrade --dry-run --json | jq '.pending_migrations | length'# 3Schema (stable across patch releases):
kitty-specs/cli-upgrade-nag-lazy-project-migrations-01KQ6YDN/contracts/compat-planner.json
Troubleshooting
I get the nag every time.
The cache lives at upgrade-nag.json in the per-user cache directory: ~/.cache/spec-kitty
on Linux, ~/Library/Caches/spec-kitty on macOS, %LOCALAPPDATA%\spec-kitty\Cache on
Windows (one authority since #6488). If it is being cleared between runs, set
SPEC_KITTY_NAG_THROTTLE_SECONDS=86400 explicitly or check for a process that deletes the
cache directory.
The CLI won’t upgrade with the printed command.
Your install method may have changed. Rerun spec-kitty upgrade --cli to get a fresh
detection result.
I’m told my project is corrupt (exit 6).
Check that .kittify/metadata.yaml exists, is valid YAML, and has
spec_kitty.schema_version as an integer.
I’m in CI with no nag but commands still block.
Expected — the nag is suppressed in CI but the compatibility gate is not. Add
spec-kitty upgrade --yes to your CI setup step.
See also
- CLI Commands
- Environment Variables
- Getting Started Tutorial
- Non-Interactive Init
- Fork packaging hooks — renamed / private-index distributors
- ADR: default-off rc release channel