CLI: `specify init`

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/agent-file-template.md
• scripts/update-agent-context.sh
• CONTRIBUTING.md

The specify init command is the entry point for bootstrapping a new project using the Spec-Driven Development (SDD) methodology. Its primary purpose is to create a standardized project structure, download the necessary templates, and configure the environment for a specific AI coding agent. This ensures that every new project starts with the correct scaffolding, including directories for specifications, scripts, and agent-specific context files.

This command automates the initial setup, allowing developers to immediately begin the specification process with commands like /specify and /plan. It handles dependency checks, project directory creation, and optional Git repository initialization, making it the foundational first step in the Spec-Driven Development Workflow.

Sources: src/specify_cli/init.py:810-829, README.md:19-22, spec-driven.md:144-153

Command Usage and Parameters

The init command is executed via the specify CLI. It accepts several optional parameters to customize the project setup.

Sources: src/specify_cli/init.py:810-818

Parameter	Type	Description
project_name	string	The name of the new project directory to be created. This is mutually exclusive with the --here flag.
--ai	string	Specifies the AI assistant to use. Valid options are claude, gemini, or copilot. If not provided, an interactive selection menu is shown.
--ignore-agent-tools	bool	Skips the check for required AI agent command-line tools (e.g., claude or gemini CLIs).
--no-git	bool	Skips the initialization of a new Git repository in the project directory.
--here	bool	Initializes the project in the current working directory instead of creating a new one. This is mutually exclusive with project_name.

Examples

Create a new project in a new directory:

specify init my-new-project --ai claude

Initialize a project in the current directory:

specify init --here --ai copilot

Sources: README.md:131-147, src/specify_cli/init.py:822-829

Execution Flow

The init command follows a structured sequence of operations to ensure a robust and consistent project setup. The process includes argument validation, tool checks, user interaction, template fetching, and finalization.

The diagram below illustrates the high-level execution flow of the specify init command.

1. Argument Validation

The command first validates the provided arguments. It ensures that project_name and the --here flag are not used simultaneously. If neither is provided, it exits with an error. If --here is used in a non-empty directory, it prompts the user for confirmation before proceeding.

Sources: src/specify_cli/init.py:835-857

2. Tool and AI Assistant Selection

The CLI checks for the availability of git unless the --no-git flag is present. It then determines the AI assistant. If the --ai flag is not provided, it presents an interactive menu for the user to select an assistant using arrow keys.

The diagram below shows the logic for selecting the AI assistant.

3. Template Download and Extraction

This is the core step where the project template is fetched from the spec-kit GitHub repository.

1. Fetch Latest Release: The CLI makes an API call to GitHub to find the latest release of the spec-kit repository.
2. Find Asset: It searches the release assets for a .zip file matching the selected AI assistant (e.g., spec-kit-template-claude.zip).
3. Download Asset: The template ZIP file is downloaded. A progress bar is displayed during this process.
4. Extract Template: The contents of the ZIP file are extracted into the target project directory. The logic handles nested directories within the archive, ensuring the files are placed at the root of the project.

The following sequence diagram details the interaction between the CLI and GitHub.

4. Git Initialization

If git is available and the --no-git flag was not used, the command initializes a new Git repository in the project directory. It adds all the newly created template files and creates an initial commit with the message "Initial commit from Specify template". If the target directory is already part of a Git repository, this step is skipped.

Sources: src/specify_cli/init.py:441-463, src/specify_cli/init.py:926-938

Core Components

The specify init functionality is primarily implemented in src/specify_cli/__init__.py.

init() Function

This is the main Typer command function that orchestrates the entire initialization process. It handles argument parsing, calls helper functions for each step, and manages the overall flow.

Sources: src/specify_cli/init.py:810-987

download_and_extract_template()

This function is responsible for fetching the template from GitHub, downloading it, and extracting its contents into the project path. It uses the httpx library for making HTTP requests and the zipfile module for extraction. It also handles the common case where GitHub archives contain a single top-level directory, flattening the structure as needed.

Sources: src/specify_cli/init.py:584-681

StepTracker Class

To provide a clean and informative user experience, the CLI uses a StepTracker class. This component renders a live, tree-like view of the setup process, updating the status of each step (e.g., pending, running, done, error) in real-time. This replaces multiple print statements with a single, consolidated status panel.

Sources: src/specify_cli/init.py:80-161

Project Scaffolding

After specify init completes, the project directory is populated with a set of files and folders that form the basis for Spec-Driven Development. This includes:

• specs/: A directory to hold feature specifications.
• scripts/: Contains shell scripts that automate parts of the SDD workflow, such as creating new features (/specify) and plans (/plan).
• memory/: Holds the project's constitution.md, which defines core architectural principles.
• templates/: A collection of markdown templates for specs, plans, and tasks.
• An agent-specific file (e.g., CLAUDE.md, GEMINI.md, or .github/copilot-instructions.md): This file provides development guidelines and context for the selected AI agent. It is generated from templates/agent-file-template.md.

The agent-specific file is designed to be a "living document". It is incrementally updated by scripts like scripts/update-agent-context.sh as new technologies are introduced in subsequent /plan commands.

Sources: README.md:195-212, templates/agent-file-template.md, scripts/update-agent-context.sh