Installation Guide

Prerequisites

Linux/macOS (or Windows; PowerShell scripts now supported without WSL)
AI coding agent: Claude Code, GitHub Copilot, Codebuddy CLI, Gemini CLI, or Pi Coding Agent
uv for package management (recommended) or pipx for persistent installation
Python 3.11+
Git

Installation

[!IMPORTANT] The only official, maintained packages for Spec Kit come from the 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:

[!NOTE] The command below requires uv. If you see command not found: uv, install uv first.

bash

uv tool install specify-cli --from git+https://github.com/github/[email protected]

Then initialize a project:

bash

specify init <PROJECT_NAME> --integration copilot

One-time Usage

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

Alternative Package Managers

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:

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.

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