mirror of https://github.com/github/spec-kit.git synced 2026-08-03 06:26:30 +08:00

Files

Manfred Riem ad601e5d52 docs: add PyPI as second supported install route (#3425 ) (#3516 )

* 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>

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

---------

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

2026-07-14 16:05:15 -05:00

3.1 KiB

Raw Blame History

Installing from PyPI

Spec Kit is published to PyPI as specify-cli, maintained by the Spec Kit maintainers. Installing from PyPI is the second supported install route alongside installing from the GitHub source. 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 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:

# 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 or Releases for available versions):

# 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

specify version

Initialize a project

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:

# 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 for details.

Uninstall

# 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 to initialize your first project.

3.1 KiB Raw Blame History