Skip to content

How to Install and Upgrade Spec Kitty

Who is this for (1)

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-kitty binary (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:

Terminal window
pipx install --pip-args=--pre spec-kitty-cli
pipx ensurepath
spec-kitty --version

pipx 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:

Terminal window
uv tool install --prerelease=allow spec-kitty-cli
Terminal window
# Inside an activated virtual environment or managed CI Python image
python -m pip install --pre spec-kitty-cli

Use 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:

Terminal window
spec-kitty upgrade --cli

Spec Kitty detects your install method and prints the right command:

Install methodUpgrade 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
Homebrewbrew upgrade spec-kitty
System packageuse 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:

Terminal window
spec-kitty upgrade # interactive
spec-kitty upgrade --project # same thing, explicit

Preview first:

Terminal window
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_context

Apply non-interactively (CI, scripts):

Terminal window
spec-kitty upgrade --yes # or --force; both work

Migrations 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:

Terminal window
export SPEC_KITTY_PRERELEASE=1
spec-kitty upgrade --agent-check

Or, once, with no per-shell export — write it into .kitty.env:

Terminal window
# .kittify/.kitty.env (per-repo) or ${SPEC_KITTY_HOME}/.kitty.env (machine-wide)
SPEC_KITTY_PRERELEASE=1

With 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:

Terminal window
spec-kitty doctor channel

Stable-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-cli

Throttled to once per 24 hours by default. Configure:

Terminal window
SPEC_KITTY_NAG_THROTTLE_SECONDS=3600 spec-kitty upgrade --cli # 1-hour window

Or in ~/.config/spec-kitty/upgrade.yaml:

nag:
throttle_seconds: 3600

Disable entirely:

Terminal window
spec-kitty upgrade --cli --no-nag # this invocation only
SPEC_KITTY_NO_NAG=1 spec-kitty upgrade --cli # this shell session

The lazy gate

When a project’s schema is incompatible with the installed CLI, unsafe commands are blocked.

Project needs migration — exit code 4:

Terminal window
cd /path/to/oldproj
spec-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-run
echo $? # 4

Remediate: run spec-kitty upgrade, then retry.

Project too new for installed CLI — exit code 5:

Terminal window
cd /path/to/futureproj
spec-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-cli
echo $? # 5

Remediate: upgrade the CLI. --yes and --force do not bypass this block.

Commands that always work regardless of schema:

Terminal window
spec-kitty --help
spec-kitty --version
spec-kitty upgrade --dry-run # always allowed
spec-kitty upgrade --cli # always allowed

After the project schema is compatible, inspect the current Mission’s work packages with:

Terminal window
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.
Terminal window
CI=1 spec-kitty next --agent claude
# no nag; still exits 4 if project needs migration

Exit codes

CodeMeaning
0Success / safe pass-through
2Usage error (e.g. --cli and --project combined)
4Project needs migration — run spec-kitty upgrade
5Project too new for this CLI — upgrade the CLI
6Project metadata corrupt or unreadable

JSON output for tooling

Terminal window
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'
# 3

Schema (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