This page documents the environment validation subsystem of the Specify CLI, which verifies that required tools and prerequisites are installed before project initialization or during system diagnostics. Environment validation ensures users have the necessary tools (Git, AI agent CLIs) available in their PATH before attempting to create or work with Spec Kit projects.
For information about project initialization that uses these validation functions, see Project Initialization. For the interactive selection system that runs after validation, see Interactive Selection System.
The environment validation system provides two primary capabilities: tool detection via PATH lookup and Git repository detection via subprocess commands. Both mechanisms integrate with the StepTracker system to provide real-time feedback during initialization.
The check_tool() function serves as the central tool validation mechanism, checking whether a given executable exists in the system PATH.
Sources: src/specify_cli/__init__.py484-513
| Function | Purpose | Return Type | Key Behavior |
|---|---|---|---|
check_tool(tool, tracker) | Check if executable exists in PATH | bool | Returns True if found, False otherwise |
| Special Case: Claude CLI | Handle post-migration Claude installation | bool | Checks ~/.claude/local/claude before PATH |
| Tracker Integration | Update UI with validation results | None | Calls tracker.complete() or tracker.error() |
Sources: src/specify_cli/__init__.py484-513
The Claude CLI tool requires special handling due to the claude migrate-installer command, which removes the executable from PATH and creates an alias at ~/.claude/local/claude. This path is checked with priority before falling back to shutil.which():
Sources: src/specify_cli/__init__.py233 src/specify_cli/__init__.py499-503
The is_git_repo() function determines whether a given path is inside a Git working tree by invoking the git rev-parse --is-inside-work-tree command:
Sources: src/specify_cli/__init__.py515-533
This function is used during initialization to determine whether to skip Git setup when reinitializing in an existing repository:
Sources: src/specify_cli/__init__.py1171-1173
The AGENT_CONFIG dictionary serves as the single source of truth for all supported AI agents, defining which agents require CLI tool validation versus IDE-based agents that skip validation.
Sources: src/specify_cli/__init__.py126-229
Each agent entry contains four fields:
| Field | Type | Purpose | Example Values |
|---|---|---|---|
name | str | Display name for user-facing messages | "Claude Code", "GitHub Copilot" |
folder | str | Agent-specific directory in project root | ".claude/", ".gemini/" |
requires_cli | bool | Whether agent needs CLI tool validation | True (CLI), False (IDE) |
install_url | str | None | Download URL for CLI tool | URL string or None for IDE agents |
Sources: src/specify_cli/__init__.py126-229
The validation system distinguishes between two agent categories:
CLI-Based Agents (requires_cli: True):
check_tool() during init--ignore-agent-tools)claude, gemini, qwen, opencode, codex, auggie, codebuddy, qoder, q, amp, shaiIDE-Based Agents (requires_cli: False):
copilot, cursor-agent, windsurf, kilocode, roo, bobSources: src/specify_cli/__init__.py126-229
The check command provides comprehensive system diagnostics, validating all tools that Spec Kit projects might use:
Sources: src/specify_cli/__init__.py1281-1321
The command iterates through all agents in AGENT_CONFIG and performs conditional validation:
Sources: src/specify_cli/__init__.py1293-1304
Output example:
Check Available Tools
● git (available)
● GitHub Copilot (IDE-based, no CLI check)
● claude (available)
○ gemini (not found)
● Cursor (IDE-based, no CLI check)
...
Environment validation is deeply integrated into the init command workflow, occurring at multiple stages:
Sources: src/specify_cli/__init__.py1076-1111
Git validation occurs early in initialization but is non-blocking:
Sources: src/specify_cli/__init__.py1075-1079
Agent tool validation is conditional and can be bypassed:
Sources: src/specify_cli/__init__.py1095-1111
The --ignore-agent-tools flag allows users to bypass agent CLI validation when:
Sources: src/specify_cli/__init__.py986 src/specify_cli/__init__.py1095
Environment validation integrates with the StepTracker system to provide real-time feedback during initialization:
Sources: src/specify_cli/__init__.py484-513 src/specify_cli/__init__.py1156-1183
The tracker receives status updates directly from validation functions:
Sources: src/specify_cli/__init__.py507-511
When validation fails, the system provides actionable error messages with installation URLs:
┌─ Agent Detection Error ────────────────────────────────────┐
│ claude not found │
│ Install from: https://docs.anthropic.com/en/docs/claude- │
│ code/setup │
│ Claude Code is required to continue with this project │
│ type. │
│ │
│ Tip: Use --ignore-agent-tools to skip this check │
└────────────────────────────────────────────────────────────┘
Sources: src/specify_cli/__init__.py1100-1111
[yellow]Git not found - will skip repository initialization[/yellow]
Sources: src/specify_cli/__init__.py1079
The check command includes detection for VS Code variants, even though they're not in AGENT_CONFIG:
This helps users identify available editors for IDE-based agents like GitHub Copilot.
Sources: src/specify_cli/__init__.py1307-1311
The environment validation subsystem provides:
shutil.which()git rev-parseAGENT_CONFIGStepTracker integration--ignore-agent-tools bypass optionThese capabilities ensure users have the necessary tools installed before attempting project operations while providing graceful degradation when optional tools are missing.
Refresh this wiki