Skip to content

installation.md

Latest commit

 

History

History
143 lines (97 loc) · 5.75 KB

installation.md

File metadata and controls

143 lines (97 loc) · 5.75 KB

Installation Guide

Prerequisites

Installation

Initialize a New Project

The easiest way to get started is to initialize a new project. Pin a specific release tag for stability (check Releases for the latest):

# Install from a specific stable release (recommended — replace vX.Y.Z with the latest tag)
uvx --from git+https://github.com/github/spec-kit.git@vX.Y.Z specify init <PROJECT_NAME>

# Or install latest from main (may include unreleased changes)
uvx --from git+https://github.com/github/spec-kit.git specify init <PROJECT_NAME>

Or initialize in the current directory:

uvx --from git+https://github.com/github/spec-kit.git@vX.Y.Z specify init .
# or use the --here flag
uvx --from git+https://github.com/github/spec-kit.git@vX.Y.Z specify init --here

Specify AI Agent

You can proactively specify your AI agent during initialization:

uvx --from git+https://github.com/github/spec-kit.git@vX.Y.Z specify init <project_name> --ai claude
uvx --from git+https://github.com/github/spec-kit.git@vX.Y.Z specify init <project_name> --ai gemini
uvx --from git+https://github.com/github/spec-kit.git@vX.Y.Z specify init <project_name> --ai copilot
uvx --from git+https://github.com/github/spec-kit.git@vX.Y.Z specify init <project_name> --ai codebuddy
uvx --from git+https://github.com/github/spec-kit.git@vX.Y.Z specify init <project_name> --ai 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:

uvx --from git+https://github.com/github/spec-kit.git@vX.Y.Z specify init <project_name> --script sh
uvx --from git+https://github.com/github/spec-kit.git@vX.Y.Z specify init <project_name> --script ps

Ignore Agent Tools Check

If you prefer to get the templates without checking for the right tools:

uvx --from git+https://github.com/github/spec-kit.git@vX.Y.Z specify init <project_name> --ai claude --ignore-agent-tools

Verification

After initialization, you should see the following commands available in your AI agent:

  • /speckit.specify - Create specifications
  • /speckit.plan - Generate implementation plans
  • /speckit.tasks - Break down into actionable tasks

The .specify/scripts directory will contain both .sh and .ps1 scripts.

Troubleshooting

Enterprise / Air-Gapped Installation

If your environment blocks access to PyPI (you see 403 errors when running uv tool install or pip install), you can create a portable wheel bundle on a connected machine and transfer it to the air-gapped target.

Step 1: Build the wheel on a connected machine (same OS and Python version as the target)

# Clone the repository
git clone https://github.com/github/spec-kit.git
cd spec-kit

# Build the wheel
pip install build
python -m build --wheel --outdir dist/

# Download the wheel and all its runtime dependencies
pip download -d dist/ dist/specify_cli-*.whl

Important: pip download resolves platform-specific wheels (e.g., PyYAML includes native extensions). You must run this step on a machine with the same OS and Python version as the air-gapped target. If you need to support multiple platforms, repeat this step on each target OS (Linux, macOS, Windows) and Python version.

Step 2: Transfer the dist/ directory to the air-gapped machine

Copy the entire dist/ directory (which contains the specify-cli wheel and all dependency wheels) to the target machine via USB, network share, or other approved transfer method.

Step 3: Install on the air-gapped machine

pip install --no-index --find-links=./dist specify-cli

Step 4: Initialize a project (no network required)

# Initialize a project — no GitHub access needed
specify init my-project --ai claude --offline

The --offline flag tells the CLI to use the templates, commands, and scripts bundled inside the wheel instead of downloading from GitHub.

Deprecation notice: Starting with v0.6.0, specify init will use bundled assets by default and the --offline flag will be removed. The GitHub download path will be retired because bundled assets eliminate the need for network access, avoid proxy/firewall issues, and guarantee that templates always match the installed CLI version. No action will be needed — specify init will simply work without network access out of the box.

Note: Python 3.11+ is required.

Windows note: Offline scaffolding requires PowerShell 7+ (pwsh), not Windows PowerShell 5.x (powershell.exe). Install from https://aka.ms/powershell.

Git Credential Manager on Linux

If you're having issues with Git authentication on Linux, you can install Git Credential Manager:

#!/usr/bin/env bash
set -e
echo "Downloading Git Credential Manager v2.6.1..."
wget https://github.com/git-ecosystem/git-credential-manager/releases/download/v2.6.1/gcm-linux_amd64.2.6.1.deb
echo "Installing Git Credential Manager..."
sudo dpkg -i gcm-linux_amd64.2.6.1.deb
echo "Configuring Git to use GCM..."
git config --global credential.helper manager
echo "Cleaning up..."
rm gcm-linux_amd64.2.6.1.deb