The `specify` CLI Deep Dive

Relevant source files

The following files were used as context for generating this wiki page:

• src/specify_cli/init.py
• README.md
• spec-driven.md
• templates/plan-template.md
• templates/spec-template.md
• CONTRIBUTING.md
• scripts/create-new-feature.sh

The specify command-line interface is a Python-based bootstrapping tool designed to initialize projects for the Spec-Driven Development (SDD) workflow. Its primary function is to set up a new or existing directory with the necessary templates, scripts, and structure required to interact with AI coding agents like Claude Code, Gemini, or GitHub Copilot. The CLI automates the initial setup, allowing developers to immediately begin the specification process.

The tool is built using Typer for the command-line interface structure and Rich for enhanced terminal UI, providing an interactive and user-friendly experience. The main commands provided are init for project initialization and check for verifying tool dependencies. This document provides a deep dive into the architecture and functionality of the specify CLI.

Sources: src/specify_cli/init.py:1-26, README.md:20-26

Core Architecture and Components

The CLI is a single-file Python script with several key dependencies that define its capabilities.

Dependency	Purpose
typer	The core framework for creating the CLI commands and options.
rich	Used for all styled output, including panels, progress bars, tables, and the interactive selection menu.
httpx	Handles all HTTP requests, specifically for downloading the project templates from the GitHub API.
readchar	Captures single keypresses for the interactive arrow-key selection menu.

Sources: src/specify_cli/init.py:3-9

Key Classes

The CLI uses a few helper classes to manage its UI and structure.

This diagram shows the main helper classes. BannerGroup extends TyperGroup to display a banner, and StepTracker manages the progress display.

• BannerGroup: A custom TyperGroup that overrides format_help to display an ASCII art banner before showing the standard help text.
• StepTracker: A class responsible for rendering a hierarchical, tree-like progress display. It tracks the status of various steps (e.g., pending, running, done, error) and renders them using rich.tree.Tree, mimicking the output style of tools like Claude Code.

Sources: src/specify_cli/init.py:58-132, src/specify_cli/init.py:250-257

Command Breakdown

The specify CLI has two main commands: init and check.

specify init

This is the primary command for bootstrapping a project. It downloads the latest template release from the github/spec-kit repository and sets up the project directory.

Sources: src/specify_cli/init.py:621-639

Arguments and Options

Parameter	Type	Description
project_name	Argument	The name of the new project directory to create. Not used with --here.
--ai	Option	Specifies the AI assistant to use (claude, gemini, or copilot). If omitted, an interactive prompt is shown.
--here	Option	Initializes the project in the current directory instead of creating a new one.
--ignore-agent-tools	Option	Skips the check for required AI agent command-line tools (e.g., claude CLI).
--no-git	Option	Skips the automatic initialization of a Git repository.

Sources: src/specify_cli/init.py:622-628

Execution Flow

The init command follows a structured sequence of operations to ensure a project is set up correctly.

This diagram illustrates the step-by-step process of the init command, from argument validation to final output.

Sources: src/specify_cli/init.py:640-775

Template Download and Extraction

A core function of the init command is to fetch the correct project template from GitHub.

1. Fetch Release Info: The download_template_from_github function sends a GET request to the GitHub API endpoint https://api.github.com/repos/github/spec-kit/releases/latest.
2. Find Asset: It parses the JSON response to find a release asset whose name matches the pattern spec-kit-template-{ai_assistant}.zip.
3. Download Asset: Using httpx, it streams the download of the zip file, displaying a progress bar with rich.progress.
4. Extract Files: The download_and_extract_template function unzips the archive. It is designed to handle the common GitHub pattern where all files are nested inside a single root directory within the zip file, and it flattens this structure into the target project path.
5. Handle --here: If the --here flag is used, the CLI extracts to a temporary location first and then merges the contents into the current working directory, warning the user about potential overwrites.

Sources: src/specify_cli/init.py:365-558

This sequence diagram shows the interaction between the CLI and GitHub to download the template.

specify check

This is a utility command to verify that the local environment has all the necessary tools for the SDD workflow.

It performs the following checks:

• Internet Connectivity: Attempts to connect to api.github.com.
• Git: Checks if git is in the system's PATH.
• AI Tools: Checks for claude and gemini CLIs.

Sources: src/specify_cli/init.py:778-800

UI and User Experience

The CLI heavily leverages the rich library to provide a modern and intuitive user experience.

• Banner: A custom BannerGroup displays a large ASCII art banner for the main command and help output.
• Interactive Selection: The select_with_arrows function provides a user-friendly menu for choosing an AI assistant, using arrow keys for navigation and Enter to select. This is built with rich.live.Live for a responsive feel.
• Progress Tracking: The StepTracker class provides detailed, real-time feedback during the init process. It displays steps in a tree, with status indicators (pending, running, done, error) that update live.
• Styled Output: All informational messages, warnings, and errors are color-coded and formatted in panels for high readability.

Sources: src/specify_cli/init.py:58-132, src/specify_cli/init.py:180-247, src/specify_cli/init.py:250-270

Project Initialization Logic

Git Integration

The CLI automates Git repository setup to encourage version control from the start.

• The is_git_repo function checks if the target directory is already part of a Git work tree by running git rev-parse --is-inside-work-tree.
• If Git is available and the project is not already a repository, the init_git_repo function is called.
• This function executes git init, git add ., and git commit -m "Initial commit from Specify template" to create a clean initial commit.
• This behavior can be disabled with the --no-git flag.

Sources: src/specify_cli/init.py:321-362, src/specify_cli/init.py:722-734

Conclusion

The specify CLI is the foundational tool for the Spec-Driven Development process within the spec-kit ecosystem. It effectively abstracts away the manual and error-prone process of project setup by providing a single, robust command (specify init). Through its interactive UI, automated template fetching from GitHub, and built-in Git integration, it enables developers to bootstrap a complete, agent-ready development environment in seconds. This allows teams to focus immediately on the core of SDD: writing and refining specifications.