π« Toolkit to help you get started with SDD or any other process!
docs: add PyPI as second supported install route (#3425) (#3516)
Manfred Riemad601e5d5225
diff --git a/README.md b/README.mdindex 138690529..77ef313f2 100644--- a/README.md+++ b/README.md@@ -51,6 +51,12 @@ Requires **[uv](https://docs.astral.sh/uv/)** ([install uv](./docs/install/uv.mduv tool install specify-cli --from git+https://github.com/github/[email protected]```+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 projectdiff --git a/docs/install/pypi.md b/docs/install/pypi.mdnew file mode 100644index 000000000..1b89d78e4--- /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 `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). `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++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 <PROJECT_NAME> --integration copilot+```++## Upgrade++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+uv tool install --force specify-cli++# Or using pipx+pipx install --force specify-cli++# Or using pip+pip install --upgrade specify-cli+```++> [!NOTE]+> `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++```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.mdindex 509c35382..9fb2bf519 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, 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.-### 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 <PROJECT_NAME> --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 UsageRun 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)@@ -81,13 +104,13 @@ specify init <project_name> --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:```bashspecify version```-This helps verify you are running the official Spec Kit build from GitHub, not an unrelated package with the same name.+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).diff --git a/docs/toc.yml b/docs/toc.ymlindex ca9fba235..6e348f6e6 100644--- a/docs/toc.yml+++ b/docs/toc.yml@@ -13,6 +13,8 @@href: upgrade.md- name: Install uvhref: install/uv.md+ - name: Install from PyPI+ href: install/pypi.md- name: Install with pipxhref: install/pipx.md- name: One-time Usage (uvx)