local-development.md

Local Development Guide

This guide shows how to iterate on the specify CLI locally without publishing a release or committing to main first.

Scripts are available as Bash (.sh), PowerShell (.ps1), and Python (.py) variants. Interactive specify init prompts you to choose one; non-interactive runs (no TTY, or --non-interactive) default to a shell variant for your OS. Pass --script sh|ps|py to select explicitly.

For how the project uses its own SDD and assessment processes, see Does Spec Kit use Spec Kit? in the contributor guide.

1. Clone and Switch Branches

git clone https://github.com/github/spec-kit.git
cd spec-kit
# Work on a feature branch
git checkout -b your-feature-branch

2. Run the CLI Directly (Fastest Feedback)

You can execute the CLI via the module entrypoint without installing anything:

# From repo root
python -m src.specify_cli --help
python -m src.specify_cli init demo-project --integration claude --ignore-agent-tools --script sh

If you prefer invoking the script file style (uses shebang):

python src/specify_cli/__init__.py init demo-project --script ps

3. Use Editable Install (Isolated Environment)

Create an isolated environment using uv so dependencies resolve exactly like end users get them:

# Create & activate virtual env (uv auto-manages .venv)
uv venv
source .venv/bin/activate  # or on Windows PowerShell: .venv\Scripts\Activate.ps1

# Install project in editable mode
uv pip install -e .

# Now 'specify' entrypoint is available
specify --help

Re-running after code edits requires no reinstall because of editable mode.

4. Invoke with uvx Directly From Git (Current Branch)

uvx can run from a local path (or a Git ref) to simulate user flows:

uvx --from . specify init demo-uvx --integration copilot --ignore-agent-tools --script sh

You can also point uvx at a specific branch without merging:

# Push your working branch first
git push origin your-feature-branch
uvx --from git+https://github.com/github/spec-kit.git@your-feature-branch specify init demo-branch-test --script ps