From e39d2a6f3b4c6b716675003a3a9b93c762abd9ab Mon Sep 17 00:00:00 2001 From: Manfred Riem <15701806+mnriem@users.noreply.github.com> Date: Tue, 14 Jul 2026 10:32:56 -0500 Subject: [PATCH 1/4] docs: add PyPI as second supported install route (#3425) The specify-cli package is now officially published to PyPI via the publish-pypi.yml trusted-publishing workflow. Document PyPI as a supported install route alongside the GitHub source install: - Revise the outdated "not affiliated" warning in installation.md to reflect that specify-cli on PyPI is an official, maintained channel. - Add an "Install from PyPI" section and list PyPI under alternative package managers. - Add a dedicated docs/install/pypi.md guide (install, pin version, verify, upgrade, uninstall). - Add the PyPI guide to the docs TOC. - Mention the PyPI route in the README quick start. Assisted-by: GitHub Copilot (model: Claude Opus 4.8, autonomous) Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --- README.md | 6 ++++ docs/install/pypi.md | 83 ++++++++++++++++++++++++++++++++++++++++++++ docs/installation.md | 29 ++++++++++++++-- docs/toc.yml | 2 ++ 4 files changed, 117 insertions(+), 3 deletions(-) create mode 100644 docs/install/pypi.md diff --git a/README.md b/README.md index 1386905297..77ef313f2d 100644 --- a/README.md +++ b/README.md @@ -51,6 +51,12 @@ Requires **[uv](https://docs.astral.sh/uv/)** ([install uv](./docs/install/uv.md uv tool install specify-cli --from git+https://github.com/github/spec-kit.git@vX.Y.Z ``` +Prefer installing from PyPI? The `specify-cli` package is also published there: + +```bash +uv tool install specify-cli +``` + See the [Installation Guide](./docs/installation.md) for alternative methods, verification, upgrade, and troubleshooting. ### 2. Initialize a project diff --git a/docs/install/pypi.md b/docs/install/pypi.md new file mode 100644 index 0000000000..7a018ae524 --- /dev/null +++ b/docs/install/pypi.md @@ -0,0 +1,83 @@ +# Installing from PyPI + +Spec Kit is published to PyPI as [`specify-cli`](https://pypi.org/project/specify-cli/), maintained by the Spec Kit maintainers. Installing from PyPI is the second supported install route alongside installing from the [GitHub source](../installation.md#install-from-source--persistent-installation-recommended). Use whichever fits your workflow — both provide the same official `specify` CLI. + +> [!NOTE] +> The PyPI release version tracks the GitHub release tags (for example, PyPI `0.12.11` corresponds to the `v0.12.11` tag). Confirm what you installed with `specify version`. + +## Install Specify CLI + +Use whichever Python tool you already have: + +```bash +# Using uv (recommended) +uv tool install specify-cli + +# Or using pipx +pipx install specify-cli + +# Or using pip +pip install specify-cli +``` + +### Install a specific release + +Pin an exact version for reproducible installs (check [PyPI](https://pypi.org/project/specify-cli/#history) or [Releases](https://github.com/github/spec-kit/releases) for available versions): + +```bash +# Using uv +uv tool install specify-cli==0.12.11 + +# Or using pipx +pipx install specify-cli==0.12.11 + +# Or using pip +pip install specify-cli==0.12.11 +``` + +## Verify + +```bash +specify version +``` + +## Initialize a project + +```bash +specify init --integration copilot +``` + +## Upgrade + +Upgrade with the same tool you installed with: + +```bash +# Using uv +uv tool upgrade specify-cli + +# Or using pipx +pipx upgrade specify-cli + +# Or using pip +pip install --upgrade specify-cli +``` + +> [!NOTE] +> `specify self upgrade` automatically manages `uv tool` and `pipx` installs. A plain `pip install specify-cli` is treated as an unmanaged install — upgrade it with `pip install --upgrade specify-cli`. See the [Upgrade Guide](../upgrade.md) for details. + +## Uninstall + +```bash +# Using uv +uv tool uninstall specify-cli + +# Or using pipx +pipx uninstall specify-cli + +# Or using pip +pip uninstall specify-cli +``` + +## Next steps + +Head to the [Quick Start](../quickstart.md) to initialize your first project. diff --git a/docs/installation.md b/docs/installation.md index 509c353829..4e32fb5b48 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -11,9 +11,14 @@ ## 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. +> Spec Kit is distributed through two official channels, both published and maintained by the Spec Kit maintainers: the [github/spec-kit](https://github.com/github/spec-kit) GitHub repository (source installs) and the [`specify-cli`](https://pypi.org/project/specify-cli/) package on [PyPI](https://pypi.org/project/specify-cli/). Either route is supported for normal installs — use the commands shown below. After installing, confirm you are running the official build with `specify version`. For offline or air-gapped environments, locally built wheels created from this repository are also valid. -### Persistent Installation (Recommended) +Spec Kit supports two install routes: + +1. **Install from source (GitHub)** — the recommended route, pinned to a release tag. +2. **Install from PyPI** — install the published `specify-cli` package with your usual Python tooling. + +### Install from Source — Persistent Installation (Recommended) Install once and use everywhere. Replace `vX.Y.Z` with a release tag from [Releases](https://github.com/github/spec-kit/releases) — keep the leading `v` (for example, `v0.12.11`, not `0.12.11`): @@ -30,12 +35,30 @@ Then initialize a project: specify init --integration copilot ``` +### Install from PyPI + +Spec Kit is also published to PyPI as [`specify-cli`](https://pypi.org/project/specify-cli/), so you can install it with your preferred Python package manager without referencing the Git URL: + +```bash +# Using uv (recommended) +uv tool install specify-cli + +# Or using pipx +pipx install specify-cli + +# Or using pip +pip install specify-cli +``` + +To install a specific release, pin the version — for example `uv tool install specify-cli==0.12.11`. See the [PyPI installation guide](install/pypi.md) for details, including how to upgrade. + ### One-time Usage Run directly without installing — see the [One-time usage (uvx)](install/one-time.md) guide. ### Alternative Package Managers +- **PyPI** — see the [PyPI installation guide](install/pypi.md) - **pipx** — see the [pipx installation guide](install/pipx.md) - **Enterprise / Air-Gapped** — see the [air-gapped installation guide](install/air-gapped.md) @@ -87,7 +110,7 @@ After installation, run the following command to confirm the correct version is specify version ``` -This helps verify you are running the official Spec Kit build from GitHub, not an unrelated package with the same name. +This helps verify you are running an official Spec Kit build — whether installed from the GitHub source or the `specify-cli` package on PyPI. **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). diff --git a/docs/toc.yml b/docs/toc.yml index ca9fba235d..6e348f6e66 100644 --- a/docs/toc.yml +++ b/docs/toc.yml @@ -13,6 +13,8 @@ href: upgrade.md - name: Install uv href: install/uv.md + - name: Install from PyPI + href: install/pypi.md - name: Install with pipx href: install/pipx.md - name: One-time Usage (uvx) From 6ffe12ed9b229e51fbc818c51a7f63d4b4213fc2 Mon Sep 17 00:00:00 2001 From: Manfred Riem <15701806+mnriem@users.noreply.github.com> Date: Tue, 14 Jul 2026 11:27:08 -0500 Subject: [PATCH 2/4] docs: refine PyPI install guidance from review (#3516) Address review feedback for the PyPI install documentation: - Reword the verification guidance so `specify version` is described as a local version/runtime check rather than proof of package provenance. - Clarify that upgrading a pinned `uv tool` install to the newest PyPI release requires an unpinned reinstall command. - Note that `specify self upgrade` rebuilds `uv tool` and `pipx` installs from the GitHub source release URL rather than preserving a PyPI-based installation. Assisted-by: GitHub Copilot (model: Claude Opus 4.8, autonomous) Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --- docs/install/pypi.md | 12 ++++++------ docs/installation.md | 4 ++-- 2 files changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/install/pypi.md b/docs/install/pypi.md index 7a018ae524..0ed13f4ff0 100644 --- a/docs/install/pypi.md +++ b/docs/install/pypi.md @@ -1,9 +1,9 @@ # Installing from PyPI -Spec Kit is published to PyPI as [`specify-cli`](https://pypi.org/project/specify-cli/), maintained by the Spec Kit maintainers. Installing from PyPI is the second supported install route alongside installing from the [GitHub source](../installation.md#install-from-source--persistent-installation-recommended). Use whichever fits your workflow — both provide the same official `specify` CLI. +Spec Kit is published to PyPI as [`specify-cli`](https://pypi.org/project/specify-cli/), maintained by the Spec Kit maintainers. Installing from PyPI is the second supported install route alongside installing from the [GitHub source](../installation.md#install-from-source--persistent-installation-recommended). Use whichever fits your workflow — both provide the same `specify` CLI. > [!NOTE] -> The PyPI release version tracks the GitHub release tags (for example, PyPI `0.12.11` corresponds to the `v0.12.11` tag). Confirm what you installed with `specify version`. +> The PyPI release version tracks the GitHub release tags (for example, PyPI `0.12.11` corresponds to the `v0.12.11` tag). Use `specify version` as a local sanity check, and inspect your package manager's record (for example `uv tool list`, `pipx list`, or `pip show specify-cli`) if you need to confirm the installed package source. ## Install Specify CLI @@ -49,21 +49,21 @@ specify init --integration copilot ## Upgrade -Upgrade with the same tool you installed with: +Upgrade by reinstalling the package through the same tool you used for the original install. If you want to move to the newest PyPI release, use an unpinned install command so you do not keep the existing version pin: ```bash # Using uv -uv tool upgrade specify-cli +uv tool install --force specify-cli # Or using pipx -pipx upgrade specify-cli +pipx install --force specify-cli # Or using pip pip install --upgrade specify-cli ``` > [!NOTE] -> `specify self upgrade` automatically manages `uv tool` and `pipx` installs. A plain `pip install specify-cli` is treated as an unmanaged install — upgrade it with `pip install --upgrade specify-cli`. See the [Upgrade Guide](../upgrade.md) for details. +> `specify self upgrade` currently rebuilds `uv tool` and `pipx` installs from the GitHub source release URL rather than preserving a PyPI-based installation. If you want to stay on the PyPI route, use the package-manager commands above. A plain `pip install specify-cli` is treated as an unmanaged install — upgrade it with `pip install --upgrade specify-cli`. See the [Upgrade Guide](../upgrade.md) for details. ## Uninstall diff --git a/docs/installation.md b/docs/installation.md index 4e32fb5b48..27172c4ff9 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -11,7 +11,7 @@ ## Installation > [!IMPORTANT] -> Spec Kit is distributed through two official channels, both published and maintained by the Spec Kit maintainers: the [github/spec-kit](https://github.com/github/spec-kit) GitHub repository (source installs) and the [`specify-cli`](https://pypi.org/project/specify-cli/) package on [PyPI](https://pypi.org/project/specify-cli/). Either route is supported for normal installs — use the commands shown below. After installing, confirm you are running the official build with `specify version`. For offline or air-gapped environments, locally built wheels created from this repository are also valid. +> Spec Kit is distributed through two official channels, both published and maintained by the Spec Kit maintainers: the [github/spec-kit](https://github.com/github/spec-kit) GitHub repository (source installs) and the [`specify-cli`](https://pypi.org/project/specify-cli/) package on [PyPI](https://pypi.org/project/specify-cli/). Either route is supported for normal installs — use the commands shown below. After installing, run `specify version` to confirm that the `specify` command is available and to check the installed version. For offline or air-gapped environments, locally built wheels created from this repository are also valid. Spec Kit supports two install routes: @@ -110,7 +110,7 @@ After installation, run the following command to confirm the correct version is specify version ``` -This helps verify you are running an official Spec Kit build — whether installed from the GitHub source or the `specify-cli` package on PyPI. +This helps confirm that the `specify` command is available and reporting the expected version. **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). From 48ba89dcb47d64ec9da6ededfc7bc6f1d1656a69 Mon Sep 17 00:00:00 2001 From: Manfred Riem <15701806+mnriem@users.noreply.github.com> Date: Tue, 14 Jul 2026 11:57:22 -0500 Subject: [PATCH 3/4] docs: clarify PyPI verification and upgrade guidance Assisted-by: GitHub Copilot (model: MAI-Code-1-Flash, autonomous) Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --- docs/install/pypi.md | 4 ++-- docs/installation.md | 6 +++--- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/install/pypi.md b/docs/install/pypi.md index 0ed13f4ff0..6a04abf203 100644 --- a/docs/install/pypi.md +++ b/docs/install/pypi.md @@ -3,7 +3,7 @@ Spec Kit is published to PyPI as [`specify-cli`](https://pypi.org/project/specify-cli/), maintained by the Spec Kit maintainers. Installing from PyPI is the second supported install route alongside installing from the [GitHub source](../installation.md#install-from-source--persistent-installation-recommended). Use whichever fits your workflow — both provide the same `specify` CLI. > [!NOTE] -> The PyPI release version tracks the GitHub release tags (for example, PyPI `0.12.11` corresponds to the `v0.12.11` tag). Use `specify version` as a local sanity check, and inspect your package manager's record (for example `uv tool list`, `pipx list`, or `pip show specify-cli`) if you need to confirm the installed package source. +> The PyPI release version tracks the GitHub release tags (for example, PyPI `0.12.11` corresponds to the `v0.12.11` tag). Use `specify version` as a local version/runtime sanity check. It does not prove whether the `specify` executable came from PyPI or GitHub; inspect your package manager's record (for example `uv tool list`, `pipx list`, or `pip show specify-cli`) if you need to confirm the installed package source. ## Install Specify CLI @@ -49,7 +49,7 @@ specify init --integration copilot ## Upgrade -Upgrade by reinstalling the package through the same tool you used for the original install. If you want to move to the newest PyPI release, use an unpinned install command so you do not keep the existing version pin: +Upgrade by reinstalling the package through the same tool you used for the original install. If you originally pinned a version, note that `uv tool upgrade` preserves that pin; to move to the newest PyPI release, use an unpinned install command so you do not keep the existing version pin: ```bash # Using uv diff --git a/docs/installation.md b/docs/installation.md index 27172c4ff9..9fb2bf519f 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -11,7 +11,7 @@ ## Installation > [!IMPORTANT] -> Spec Kit is distributed through two official channels, both published and maintained by the Spec Kit maintainers: the [github/spec-kit](https://github.com/github/spec-kit) GitHub repository (source installs) and the [`specify-cli`](https://pypi.org/project/specify-cli/) package on [PyPI](https://pypi.org/project/specify-cli/). Either route is supported for normal installs — use the commands shown below. After installing, run `specify version` to confirm that the `specify` command is available and to check the installed version. For offline or air-gapped environments, locally built wheels created from this repository are also valid. +> Spec Kit is distributed through two official channels, both published and maintained by the Spec Kit maintainers: the [github/spec-kit](https://github.com/github/spec-kit) GitHub repository (source installs) and the [`specify-cli`](https://pypi.org/project/specify-cli/) package on [PyPI](https://pypi.org/project/specify-cli/). Either route is supported for normal installs — use the commands shown below. After installing, run `specify version` as a local version/runtime sanity check. It confirms that the `specify` command is available and reports its version, but it does not prove whether the executable came from PyPI or GitHub. For offline or air-gapped environments, locally built wheels created from this repository are also valid. Spec Kit supports two install routes: @@ -104,13 +104,13 @@ specify init --integration claude --ignore-agent-tools ## Verification -After installation, run the following command to confirm the correct version is installed: +After installation, run the following command as a local version/runtime check: ```bash specify version ``` -This helps confirm that the `specify` command is available and reporting the expected version. +This confirms that the `specify` command is available and reporting the expected version. It does not prove whether that executable came from PyPI or GitHub. **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). From bb118143160938f6f9a0faa39b9c80c8c678dc5d Mon Sep 17 00:00:00 2001 From: Manfred Riem <15701806+mnriem@users.noreply.github.com> Date: Tue, 14 Jul 2026 15:22:13 -0500 Subject: [PATCH 4/4] docs: point PyPI provenance check to source metadata Address review feedback: version/list commands do not reveal install provenance. Direct readers to the source metadata their package manager records (pipx list --json, PEP 610 direct_url.json) to confirm whether an install came from PyPI or a Git URL, and note pip show cannot see uv/pipx-managed environments. Assisted-by: GitHub Copilot (model: Claude Opus 4.8, autonomous) Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --- docs/install/pypi.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/install/pypi.md b/docs/install/pypi.md index 6a04abf203..1b89d78e44 100644 --- a/docs/install/pypi.md +++ b/docs/install/pypi.md @@ -3,7 +3,7 @@ Spec Kit is published to PyPI as [`specify-cli`](https://pypi.org/project/specify-cli/), maintained by the Spec Kit maintainers. Installing from PyPI is the second supported install route alongside installing from the [GitHub source](../installation.md#install-from-source--persistent-installation-recommended). Use whichever fits your workflow — both provide the same `specify` CLI. > [!NOTE] -> The PyPI release version tracks the GitHub release tags (for example, PyPI `0.12.11` corresponds to the `v0.12.11` tag). Use `specify version` as a local version/runtime sanity check. It does not prove whether the `specify` executable came from PyPI or GitHub; inspect your package manager's record (for example `uv tool list`, `pipx list`, or `pip show specify-cli`) if you need to confirm the installed package source. +> The PyPI release version tracks the GitHub release tags (for example, PyPI `0.12.11` corresponds to the `v0.12.11` tag). `specify version` is only a local version/runtime sanity check — it reports the installed version but not where the `specify` executable came from, so it cannot distinguish a PyPI install from a Git install. To confirm the install source, inspect the source metadata your package manager records: `pipx list --json` reports the exact install specification for each tool, and for uv/pip installs you can check the package's [PEP 610](https://peps.python.org/pep-0610/) `direct_url.json` inside its `*.dist-info` directory (a Git or URL install records the repository/archive URL there, while a plain PyPI index install does not create that file). Note that `pip show specify-cli` only prints package metadata and will not see uv/pipx-managed environments from the host interpreter. ## Install Specify CLI