Core Commands

The core specify commands handle project initialization, system checks, and version information.

Initialize a Project

specify init [<project_name>]

Option	Description
--integration <key>	AI coding agent integration to use (e.g. copilot, claude, gemini). See the Integrations reference for all available keys
--integration-options	Options for the integration (e.g. --integration-options="--commands-dir .myagent/cmds")
--script sh\|ps\|py	Script type: sh (bash/zsh), ps (PowerShell), or py (Python)
--here	Initialize in the current directory instead of creating a new one
--force	Force merge/overwrite when initializing in an existing directory
--ignore-agent-tools	Skip checks for AI coding agent CLI tools
--preset <id>	Install a preset during initialization

Creates a new Spec Kit project with the necessary directory structure, templates, scripts, and AI coding agent integration files.

Note

Git repository initialization and branching are managed by the git extension, which is not installed by default. Run specify extension add git after init to enable git workflows.

Use <project_name> to create a new directory, or --here (or .) to initialize in the current directory. If the directory already has files, use --force to merge without confirmation.

When --integration is omitted, interactive terminals prompt you to choose an integration. Non-interactive sessions, such as CI or piped runs, default to GitHub Copilot; pass --integration <key> to choose a different integration explicitly, or set SPECKIT_INTEGRATION_DEFAULT to change the fallback (see Environment Variables).

Examples

# Create a new project with an integration
specify init my-project --integration copilot

# Initialize in the current directory
specify init --here --integration copilot

# Force merge into a non-empty directory
specify init --here --force --integration copilot

# Use PowerShell scripts (Windows/cross-platform)
specify init my-project --integration copilot --script ps

# Install a preset during initialization
specify init my-project --integration copilot --preset compliance

Environment Variables

Variable	Description
SPECKIT_INTEGRATION_DEFAULT	Override the fallback integration used by specify init when --integration is omitted (interactive prompt default and non-interactive fallback). Set it to any registered integration key (e.g. gemini, claude). An unrecognized value is ignored with a warning and the built-in default (copilot) is used. An explicit --integration <key> always takes precedence.
SPECIFY_INIT_DIR	Target a member project from outside its directory (e.g. a monorepo root) without cd, for non-interactive / CI use. Set it to the project root — the directory containing .specify/ (relative paths resolve against the current directory). The path must exist and contain .specify/, otherwise the command errors and does not fall back to the current directory. Resolved once in the core root helper (get_repo_root in Bash, Get-RepoRoot in PowerShell), so it is honored by the core feature scripts (/speckit.plan, /speckit.tasks, …) and the Git extension's feature-branch creation, which inherit it. The specify CLI applies the same validation rules to every project-scoped subcommand (specify integration …, specify extension …, specify workflow …, specify preset …, and the rest that operate on a .specify/ project), so those can target a member project too. When unset, Bash/PowerShell helpers keep their existing upward search; the specify CLI keeps its project-scoped resolver cwd-only unless a command explicitly defines broader detection (for example, bundle commands).
SPECIFY_FEATURE_DIRECTORY	Override the active feature directory within the resolved project (takes precedence over .specify/feature.json). Relative paths resolve under the project root. Combine with SPECIFY_INIT_DIR to pick both the project and the feature non-interactively.
SPECIFY_FEATURE	Explicitly override the active feature label (e.g. 001-photo-albums) — the identifier the core helpers report as the current feature/branch (get_current_branch in Bash, Get-CurrentBranch in PowerShell). Those helpers never inspect Git: when the variable is set they return it verbatim, and when it is unset they return an empty string. The basename fallback happens later — get_feature_paths / Get-FeaturePathsEnv substitute the resolved feature directory's basename so the reported label is still usable — so calling the named helpers directly does not give you that fallback. You set it yourself: the Bash and Python feature scripts only print a commented export SPECIFY_FEATURE=… / $env:SPECIFY_FEATURE = … hint for you to run, because a child process cannot change its parent's environment, and /speckit.specify persists feature_directory to .specify/feature.json instead of setting this variable. (The PowerShell feature scripts do assign $env:SPECIFY_FEATURE, but that only reaches you when the script runs inside your current PowerShell session.) It does not locate the feature directory: with only SPECIFY_FEATURE set, get_feature_paths fails with "Feature directory not found. Set SPECIFY_FEATURE_DIRECTORY or run the specify command to create .specify/feature.json." Use SPECIFY_FEATURE_DIRECTORY (above) or .specify/feature.json to select the directory.

Two resolution axes. SPECIFY_INIT_DIR selects the project (which directory contains .specify/); SPECIFY_FEATURE_DIRECTORY / .specify/feature.json select the feature within that project. They are independent — project first, then feature.

Version control. specify init scaffolds a managed .specify/.gitignore that excludes machine-local state — feature.json (the current-feature pointer, rewritten on every feature switch) and per-machine extension extensions/*/local-config.yml overrides — while leaving everything else under .specify/ (constitution, templates, scripts, extension config) shareable so teams stay aligned. Like the rest of .specify/'s shared scripts and templates, the file is tracked in the shared-infrastructure manifest: your edits are preserved on re-init and specify init --here --force restores the managed content. It is intentionally left in place by specify integration uninstall, which only removes the uninstalled agent's own files.

Symlinked project roots. SPECIFY_INIT_DIR relocates where the project is, not how a command treats symlinks: each command keeps its existing cwd-path stance. Commands that traverse and write project files through broad input paths (bundle, workflow run <file>) refuse a symlinked .specify/ to preserve write confinement. Other project-scoped commands keep their existing behavior when SPECIFY_INIT_DIR points at a project root, which may include following a symlinked .specify/.

Naming Features with the Helper Scripts

When calling the bundled create-new-feature helper scripts directly, generated names retain only ASCII letters and digits. A description entirely in a non-Latin script, or made only of punctuation, can therefore produce an empty suffix such as 001-. The scripts warn on stderr when this happens, including during a dry run; JSON output remains parseable.

Keep the original description and supply a readable ASCII short name:

bash .specify/scripts/bash/create-new-feature.sh --json --short-name user-auth "添加用户"

The Python helper also accepts --short-name; the PowerShell helper uses -ShortName. A supplied short name is cleaned by the same rules, so it must contain at least one ASCII letter or digit.

Check Installed Tools

specify check

Checks that CLI-based AI coding agents are available on your system. IDE-based agents are skipped since they don't require a CLI tool.

This command stays offline. If a command behaves like an older Spec Kit version or an expected CLI feature is missing, run specify self check to check whether your local CLI is behind the latest release.

Version Information

specify version

Displays the Spec Kit CLI version, Python version, platform, and architecture.

To inspect local CLI capabilities without checking the network:

specify version --features
specify version --features --json

The JSON form is intended for scripts and coding agents that need to choose a workflow based on the installed CLI's supported features.

A quick version check is also available via:

specify --version
specify -V