mirror of
https://github.com/github/spec-kit.git
synced 2026-07-03 12:28:06 +08:00
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.
113 lines
4.5 KiB
Markdown
113 lines
4.5 KiB
Markdown
# Installation Guide
|
|
|
|
## Prerequisites
|
|
|
|
- **Linux/macOS** (or Windows; PowerShell scripts now supported without WSL)
|
|
- AI coding agent: [Claude Code](https://www.anthropic.com/claude-code), [GitHub Copilot](https://code.visualstudio.com/), [Codebuddy CLI](https://www.codebuddy.ai/cli), [Gemini CLI](https://github.com/google-gemini/gemini-cli), or [Pi Coding Agent](https://pi.dev)
|
|
- [uv](https://docs.astral.sh/uv/) for package management (recommended) or [pipx](https://pipx.pypa.io/) for persistent installation
|
|
- [Python 3.11+](https://www.python.org/downloads/)
|
|
- [Git](https://git-scm.com/downloads)
|
|
|
|
## Installation
|
|
|
|
> [!IMPORTANT]
|
|
> The only official, maintained packages for Spec Kit come from the [github/spec-kit](https://github.com/github/spec-kit) GitHub repository. Any packages with the same name available on PyPI (e.g. `specify-cli` on 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](https://github.com/github/spec-kit/releases):
|
|
|
|
> [!NOTE]
|
|
> The command below requires **[uv](https://docs.astral.sh/uv/)**. If you see `command not found: uv`, [install uv first](./install/uv.md).
|
|
|
|
```bash
|
|
uv tool install specify-cli --from git+https://github.com/github/spec-kit.git@vX.Y.Z
|
|
```
|
|
|
|
Then initialize a project:
|
|
|
|
```bash
|
|
specify init <PROJECT_NAME> --integration copilot
|
|
```
|
|
|
|
### One-time Usage
|
|
|
|
Run directly without installing — see the [One-time usage (uvx)](install/one-time.md) guide.
|
|
|
|
### Alternative Package Managers
|
|
|
|
- **pipx** — see the [pipx installation guide](install/pipx.md)
|
|
- **Enterprise / Air-Gapped** — see the [air-gapped installation guide](install/air-gapped.md)
|
|
|
|
### 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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
specify init <project_name> --integration claude --ignore-agent-tools
|
|
```
|
|
|
|
## Verification
|
|
|
|
After installation, run the following command to confirm the correct version is installed:
|
|
|
|
```bash
|
|
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](./upgrade.md).
|
|
|
|
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 `.sh` scripts (default on Linux/macOS)
|
|
- `.specify/scripts/powershell/` — contains `.ps1` scripts (default on Windows)
|
|
|
|
## Troubleshooting
|
|
|
|
### Enterprise / Air-Gapped Installation
|
|
|
|
If your environment blocks access to PyPI or GitHub, see the [Enterprise / Air-Gapped Installation](install/air-gapped.md) 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](install/air-gapped.md#git-credential-manager-on-linux) for Git Credential Manager setup instructions.
|