Installation Guide

Prerequisites

Tool	Version	Required	Purpose
Python	3.11+	Yes	Runtime for the CLI
uv	Latest	Yes	Python package manager
Git	2.x+	Yes	Version control
Claude Code	Latest	Recommended	Default AI assistant

TIP

Other AI agents are also supported. See the full list.

Install the CLI

Persistent Installation (Recommended)

Install once and use everywhere:

uv tool install maistik-specify-cli --from git+ssh://git@gitlab.com/maistik-studio/tools/spec-kit.git

This adds specify to your PATH. Verify with:

specify check

One-Time Usage

Run without installing:

uvx --from git+ssh://git@gitlab.com/maistik-studio/tools/spec-kit.git specify init my-project --ai claude

Self-Hosted GitLab

For private GitLab instances, set environment variables before installing:

export GL_TOKEN=glpat-xxxxxxxxxxxx
export SPECKIT_GITLAB_HOST=gitlab.mycompany.com
export SPECKIT_GITLAB_PROJECT_ID=group%2Fspec-kit

uv tool install maistik-specify-cli --from git+https://gitlab.mycompany.com/group/spec-kit.git

Initialize a Project

New Project

specify init my-project --ai claude

Existing Project

cd my-project
specify init . --ai claude
# or
specify init --here --ai claude

Use --force to skip confirmation in non-empty directories:

specify init . --force --ai claude

Script Type

Scripts auto-detect your OS. Force a specific variant:

# Bash/Zsh (default on macOS/Linux)
specify init my-project --ai claude --script sh

# PowerShell (default on Windows)
specify init my-project --ai claude --script ps

Skip Agent Checks

If you want templates without validating AI tool installation:

specify init my-project --ai claude --ignore-agent-tools

Verification

After initialization, verify commands are available in your AI agent:

# For Claude Code
ls .claude/commands/

# For Gemini
ls .gemini/commands/

# For Cursor
ls .cursor/commands/

You should see files like speckit.specify.md, speckit.plan.md, etc.

Troubleshooting

Git Credential Manager on Linux

If you have Git authentication issues on Linux:

wget https://github.com/git-ecosystem/git-credential-manager/releases/download/v2.6.1/gcm-linux_amd64.2.6.1.deb
sudo dpkg -i gcm-linux_amd64.2.6.1.deb
git config --global credential.helper manager
rm gcm-linux_amd64.2.6.1.deb

TLS Issues on Corporate Networks

specify init my-project --ai claude --skip-tls

WARNING

Only use --skip-tls for troubleshooting. Do not use in production.

Module Not Found

If you get ModuleNotFoundError:

uv pip install -e .

Commands Not Showing in Agent

1. Restart your IDE completely (not just reload)
2. Check command files exist in the agent's directory
3. Ensure you're in the correct project directory