ac2cb5daf5
* feat(cli): implement specify self upgrade
* fix(cli): normalize self-upgrade prerelease tags
* fix(cli): tighten self-upgrade diagnostics
* fix(cli): harden self-upgrade verification parsing
* fix(cli): sanitize self-check fallback tags
* fix(cli): harden self-check release display
* fix(cli): validate resolved upgrade tags
* fix(cli): tolerate invalid install metadata
* test(cli): align upgrade network mocks
* fix(cli): respect relative installer paths
* fix(cli): tighten upgrade failure handling
* fix(cli): align installer path diagnostics
* fix(cli): validate release and version output
* fix(cli): clarify source checkout guidance
* fix(cli): harden upgrade detection helpers
* fix(cli): avoid echoing invalid release tags
* fix(cli): tolerate argv path resolve failures
* chore: remove self-upgrade formatting-only diffs
* fix: address self-upgrade review feedback
* fix: address self-upgrade review followups
* fix: address self-upgrade review edge cases
* fix: address self-upgrade review docs
* fix: refine self-upgrade review followups
* fix: address self-upgrade review cleanup
* fix: handle self-upgrade review edge cases
* fix: address self-upgrade review nits
* fix: address follow-up self-upgrade review
* fix: resolve self-upgrade review and Windows CI failures
- README: promote "Optional Commands" to ### so it is a sibling of
"Core Commands" under "Available Slash Commands" (consistent heading
levels; avoids the h2->h4 jump a revert would create).
- _version: allow --tag prerelease/dev and build-metadata suffixes to
compose (e.g. v1.0.0-rc1+build.42), matching PEP 440 / semver; the
Version() check still enforces canonical validity.
- tests: compare resolved argv0 as Path objects instead of POSIX strings
so the assertion holds on Windows; skip the relative-installer-path
executable-bit tests on Windows via a new requires_posix marker (they
rely on chmod/X_OK semantics and chdir-into-tmp teardown that do not
hold there). Add a combined prerelease+build-metadata tag test.
* fix: address second self-upgrade review round
- self_check: clarify that the "up to date" branch is reached only for
parseable latest tags (the unparseable case returns earlier), so the
InvalidVersion fallback assumption is not reintroduced.
- self_upgrade: compare target/current as Version instances directly
instead of re-parsing the canonical strings through _is_newer; the
empty-current case stays explicit via the not-None guard.
- tests: document the intentional broad GH_/GITHUB_ env scrub with a test
asserting non-credential context vars (GH_HOST, GITHUB_REPOSITORY, …) are
stripped from the installer subprocess env — a deliberate fail-safe that
also catches credential-adjacent names without a recognized suffix.
* fix: address third self-upgrade review round
- self_upgrade: unify the no-op short-circuits on packaging Version
equality instead of canonical-string equality. Version("1.0") equals
Version("1.0.0") but their str() forms differ, so the old check could
misreport an equal install as "already on latest release or newer".
Both the unpinned and pinned branches now use Version comparison.
- self_upgrade: compare the verified version as a parsed Version against
the target so a non-version verifier result is a mismatch (exit 2)
rather than a coincidental canonical-string match.
- resolver: map HTTP 429 (Too Many Requests / secondary rate limit) to
the rate-limited category so users get the same actionable token hint
as 403.
- _is_github_credential_env_key: document the precise (intentionally
broad) scrub matching contract in the docstring.
- tests: add a trailing-zero Version-equality regression test and a
parametrized HTTP-status categorization test (429 -> rate limited;
404/502 -> verbatim).
* fix: address fourth self-upgrade review round
- self_upgrade: label a pinned target older than the installed version as
"Downgrading" rather than "Upgrading" so `--tag <older>` is not mistaken
for a forward upgrade.
- resolver: drop the unused `typing.Optional` import and annotate the
`--tag` option as `str | None`, consistent with the rest of the module
(verified Typer resolves it on the supported Python versions).
- _is_github_credential_env_key: add `_PASSWORD` and `_CREDENTIALS` to the
recognized credential suffixes and document that only these shapes are
scrubbed (not blanket coverage).
- tests: assert the precise exit code (1) for the re-raised transient
OSError path; skip the InvalidMetadataError test on Pythons where the
real exception is absent instead of fabricating it; update the pinned
downgrade test to expect the "Downgrading" label.
* fix: accept uppercase V prefix in --tag
Fold a leading uppercase `V` (a common paste) to the canonical lowercase
`v` before validating `--tag`. The remainder of the tag stays
case-sensitive on purpose: the validated value is used verbatim as a git
ref, which is case-sensitive on GitHub, so rewriting label/build-metadata
casing could point at a tag that does not exist. Adds a normalization test.
4.5 KiB
Installation Guide
Prerequisites
- Linux/macOS (or Windows; PowerShell scripts now supported without WSL)
- AI coding agent: Claude Code, GitHub Copilot, Codebuddy CLI, Gemini CLI, or Pi Coding Agent
- uv for package management (recommended) or pipx for persistent installation
- Python 3.11+
- Git
Installation
Important
The only official, maintained packages for Spec Kit come from the github/spec-kit GitHub repository. Any packages with the same name available on PyPI (e.g.
specify-clion pypi.org) are not affiliated with this project and are not maintained by the Spec Kit maintainers. For normal installs, use the GitHub-based commands shown below. For offline or air-gapped environments, locally built wheels created from this repository are also valid.
Persistent Installation (Recommended)
Install once and use everywhere. Replace vX.Y.Z with a tag from Releases:
Note
The command below requires uv. If you see
command not found: uv, install uv first.
uv tool install specify-cli --from git+https://github.com/github/spec-kit.git@vX.Y.Z
Then initialize a project:
specify init <PROJECT_NAME> --integration copilot
One-time Usage
Run directly without installing — see the One-time usage (uvx) guide.
Alternative Package Managers
- pipx — see the pipx installation guide
- Enterprise / Air-Gapped — see the air-gapped installation guide
Specify Integration
Interactive terminals prompt you to choose a coding agent integration during initialization. Non-interactive sessions, such as CI or piped runs, default to GitHub Copilot unless you pass --integration.
You can proactively specify your coding agent integration during initialization:
specify init <project_name> --integration claude
specify init <project_name> --integration gemini
specify init <project_name> --integration copilot
specify init <project_name> --integration codebuddy
specify init <project_name> --integration pi
Specify Script Type (Shell vs PowerShell)
All automation scripts now have both Bash (.sh) and PowerShell (.ps1) variants.
Auto behavior:
- Windows default:
ps - Other OS default:
sh - Interactive mode: you'll be prompted unless you pass
--script
Force a specific script type:
specify init <project_name> --script sh
specify init <project_name> --script ps
Ignore Agent Tools Check
If you prefer to get the templates without checking for the right tools:
specify init <project_name> --integration claude --ignore-agent-tools
Verification
After installation, run the following command to confirm the correct version is installed:
specify version
This helps verify you are running the official Spec Kit build from GitHub, not an unrelated package with the same name.
Stay current: Run specify self check periodically to learn whether a newer release is available — it is read-only and never modifies your installation. When you are ready to upgrade, follow the Upgrade Guide.
After initialization, you should see the following commands available in your coding agent:
/speckit.specify- Create specifications/speckit.plan- Generate implementation plans/speckit.tasks- Break down into actionable tasks
Scripts are installed into a variant subdirectory matching the chosen script type:
.specify/scripts/bash/— contains.shscripts (default on Linux/macOS).specify/scripts/powershell/— contains.ps1scripts (default on Windows)
Troubleshooting
Enterprise / Air-Gapped Installation
If your environment blocks access to PyPI or GitHub, see the Enterprise / Air-Gapped Installation guide for step-by-step instructions on creating portable wheel bundles.
Git Credential Manager on Linux
If you're having issues with Git authentication on Linux, see the Air-Gapped Installation guide for Git Credential Manager setup instructions.