Installation Guide

Prerequisites

• Linux/macOS (or Windows; PowerShell scripts now supported without WSL)
• AI coding agent: Claude Code, GitHub Copilot, CodeBuddy CLI, Gemini CLI, Pi Coding Agent, or Oh My Pi
• uv for package management (recommended) or pipx for persistent installation
• Python 3.11+
• Git (optional — required only when the git extension is enabled)

Installation

[!IMPORTANT] Spec Kit is distributed through two official channels, both published and maintained by the Spec Kit maintainers: the github/spec-kit GitHub repository (source installs) and the specify-cli package on PyPI. 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:

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 — keep the leading v (for example, v0.12.11, not 0.12.11):

[!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

Install from PyPI

Spec Kit is also published to PyPI as specify-cli, so you can install it with your preferred Python package manager without referencing the Git URL:

# Using uv (recommended)
uv tool install specify-cli

# Or using pipx
pipx install specify-cli

# Or using pip
pip install specify-cli

If specify-cli is already installed, these commands keep the installed version, even when a newer release exists. Compare the version shown by specify version with the latest version on PyPI. To replace an older install, use the same tool as the original install: uv tool install --force specify-cli, pipx install --force specify-cli or pip install --upgrade specify-cli. A different tool can install a second copy and leave the old specify first on PATH. An old CLI can't set up projects from current releases: with 0.1.6, for example, specify init --integration ... fails with No such option: --integration, and specify init --ai ... fails with No matching release asset found.

To install a specific release, pin the version — for example uv tool install specify-cli==0.12.11. See the PyPI installation guide for details, including how to upgrade and how to install from a custom or private package index.

One-time Usage

Run directly without installing — see the One-time usage (uvx) guide.

Alternative Package Managers

• PyPI — see the PyPI installation guide
• 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 init <project_name> --integration omp

The README examples use GitHub Copilot's default skills mode. To use another supported agent, replace copilot with its integration key. See Command Invocation for the syntax used by each agent and mode.

Specify Script Type (Shell, PowerShell, or Python)

Automation scripts are available as Bash (.sh), PowerShell (.ps1), and Python (.py) 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
specify init <project_name> --script py

CI and AI Agent Harnesses

For environments without a keyboard, or a PTY that cannot send arrow keys, pass --non-interactive so initialization never waits on a picker:

specify init my-project --non-interactive --ignore-agent-tools

--ignore-agent-tools skips the agent executable check when the agent will run elsewhere; omit it when you want that check. Non-interactive initialization defaults to Copilot unless you select another integration explicitly.

For a non-empty directory, --force acknowledges the merge warning. Review the existing-project guide and commit or back up local changes before initializing:

specify init --here --force --non-interactive --integration claude

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 as a local version/runtime check:

specify 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.

After initialization with GitHub Copilot's default skills mode, the following skills should be available. Invoke them in your agent's chat, not in the terminal:

• /speckit-specify - Create specifications
• /speckit-plan - Generate implementation plans
• /speckit-tasks - Break down into actionable tasks
• /speckit-implement - Execute implementation tasks
• /speckit-analyze - Validate cross-artifact consistency
• /speckit-clarify - Identify and resolve ambiguities
• /speckit-checklist - Generate quality checklists
• /speckit-constitution - Create or update project principles
• /speckit-converge - Assess codebase against artifacts and append remaining 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)
• .specify/scripts/python/ — contains .py scripts (chosen with --script py; also installs the platform shell fallback)

Choose a Process

After initialization, launch your coding agent in the project directory and follow the SDD quickstart, bug-fixing quickstart, or idea assessment quickstart. These are independent entry points. SDD is available immediately; the other guides show how to install their bundled, opt-in extensions.

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.

Agent invocation examples on this page use GitHub Copilot's default skills syntax (/speckit-*). For other integrations and modes, see Command invocation.