Non-Interactive Init Mode
Who is this for (1)
- Stakeholder Persona: Project Owner — Written for the Project Owner reader.
Summary
✅ spec-kitty init IS fully non-interactive when --non-interactive (or the environment variable) is set and required options are provided.
Complete Non-Interactive Syntax
spec-kitty init <project-name> \ --ai <agents> \ [--non-interactive]Required Arguments for Non-Interactive Mode
1. Project Name or Location
Option A: New project directory
spec-kitty init my-projectOption B: Current directory
spec-kitty init .2. AI Assistants (--ai)
Syntax: Comma-separated list of agent keys (no spaces)
--ai codex--ai claude,codex--ai claude,codex,cursor,windsurf--ai copilot,gemini,qwenValid agent keys:
| Key | Agent Name |
|---|---|
codex | Codex CLI (OpenAI) |
claude | Claude Code |
gemini | Gemini CLI |
cursor | Cursor |
qwen | Qwen Code |
opencode | opencode |
windsurf | Windsurf |
kilocode | Kilo Code |
auggie | Auggie CLI (Augment Code) |
copilot | GitHub Copilot |
q | Amazon Q Developer CLI (legacy; rebranded to Kiro) |
kiro | Kiro CLI (formerly Amazon Q Developer CLI) |
antigravity | Google Antigravity |
vibe | Mistral Vibe |
pi | Pi |
letta | Letta Code |
Case-sensitive: Use lowercase exactly as shown
Optional Flags
| Flag | Purpose | Default |
|---|---|---|
--non-interactive / --yes | Disable prompts (required for CI) | Off |
Complete Non-Interactive Examples
Example 1: New project with Codex
spec-kitty init my-project \ --ai codex \ --non-interactiveExample 2: Current directory with multiple agents
spec-kitty init . \ --ai claude,codex,cursor \ --non-interactiveExample 3: Minimal (relies on defaults)
# In non-interactive environment (CI/CD):spec-kitty init my-project --ai codex --non-interactiveExample 4: CI/CD friendly
spec-kitty init . \ --ai claude \ --non-interactiveExample 5: All init-surface agents
spec-kitty init my-project \ --ai codex,claude,gemini,cursor,qwen,opencode,windsurf,kilocode,auggie,copilot,q,kiro \ --non-interactiveInteractive vs Non-Interactive Behavior
Interactive Mode (Default)
Triggered when:
- Running from a terminal (TTY)
--non-interactive/--yesis NOT provided
Presents:
- Multi-select menu for AI assistants (space to select, enter to confirm)
- Confirmation prompt if directory not empty
Non-Interactive Mode
Triggered when:
--non-interactive/--yesis provided- OR
SPEC_KITTY_NON_INTERACTIVE=1is set - OR running in non-TTY environment (pipes, CI/CD, scripts)
Behavior:
- Uses provided values
- Falls back to defaults for omitted options
- No prompts
- Suitable for automation
CI/CD Usage
# GitHub Actions example- name: Initialize Spec Kitty run: |spec-kitty init . \ --ai codex \ --non-interactive# Docker/script example#!/bin/bashspec-kitty init /app/project \ --ai claude,codex \ --non-interactiveWhat Gets Created (Agent-Specific)
When you specify agents with --ai, spec-kitty creates:
For --ai codex
.agents/skills/spec-kitty-*/SKILL.md(command-skill packages).kittify/command-skills-manifest.json(records Codex as a skill package consumer).kittify/AGENTS.md(project guidance used by Spec Kitty worktrees)
For --ai claude
.claude/commands/spec-kitty.*.md(13 command files).kittify/AGENTS.mdCLAUDE.md→ symlink to.kittify/AGENTS.md
For --ai cursor
.cursor/commands/spec-kitty.*.md(13 command files).kittify/AGENTS.md.cursorrules→ symlink to.kittify/AGENTS.md(legacy).cursor/rules/AGENTS.md→ symlink to.kittify/AGENTS.md(modern)
For --ai windsurf
.windsurf/workflows/spec-kitty.*.md(13 workflow files).kittify/AGENTS.md.windsurfrules→ symlink to.kittify/AGENTS.md(legacy).windsurf/rules/AGENTS.md→ symlink to.kittify/AGENTS.md(modern)
For --ai gemini
.gemini/commands/spec-kitty.*.toml(13 command files in TOML format).kittify/AGENTS.mdGEMINI.md→ symlink to.kittify/AGENTS.md
For --ai copilot
.github/prompts/spec-kitty.*.prompt.md(13 prompt files).kittify/AGENTS.md.github/copilot-instructions.md→ symlink to.kittify/AGENTS.md
For --ai kilocode
.kilocode/workflows/spec-kitty.*.md(13 workflow files).kittify/AGENTS.md.kilocoderules→ symlink to.kittify/AGENTS.md
For --ai opencode
.opencode/command/spec-kitty.*.md(13 command files).kittify/AGENTS.md- Note: Requires manual config entry in opencode.json
For --ai auggie
.augment/commands/spec-kitty.*.md(13 command files).kittify/AGENTS.md.augmentrules→ symlink to.kittify/AGENTS.md(assumed)
For --ai qwen
.qwen/commands/spec-kitty.*.toml(13 command files in TOML format).kittify/AGENTS.md
For --ai q
.amazonq/prompts/spec-kitty.*.md(13 prompt files).kittify/AGENTS.md- Note: May have discovery issues (known bug)
For --ai antigravity
.agents/skills/spec-kitty-*/SKILL.md(command-skill packages).kittify/command-skills-manifest.json(records Antigravity as a skill package consumer).kittify/AGENTS.md- No
.agent/workflows/files: Antigravity stopped reading that folder on 2026-10-19
For --ai vibe
.agents/skills/spec-kitty-*/SKILL.md(command-skill packages).vibe/config.tomlwith askill_pathsentry pointing at.agents/skills/.kittify/command-skills-manifest.json(records Vibe as a skill package consumer)
For --ai pi
.agents/skills/spec-kitty-*/SKILL.md(command-skill packages).kittify/command-skills-manifest.json(records Pi as a skill package consumer)
For --ai letta
.agents/skills/spec-kitty-*/SKILL.md(command-skill packages).kittify/command-skills-manifest.json(records Letta as a skill package consumer)
Always Created (Regardless of Agent Selection)
.kittify/directory structure.kittify/AGENTS.md(master copy).kittify/templates/(command templates).kittify/scripts/(helper scripts).kittify/memory/(for charter, etc.)
Platform-Specific Behavior
Unix/Mac (Has Symlinks)
All agent-specific context files are symlinks to .kittify/AGENTS.md:
ls -l CLAUDE.md# lrwxr-xr-x CLAUDE.md -> .kittify/AGENTS.mdBenefit: Single source of truth, updates to AGENTS.md instantly affect all agents
Windows (No Symlinks by Default)
All agent-specific context files are copies of .kittify/AGENTS.md:
ls CLAUDE.md# -rw-r--r-- CLAUDE.mdTradeoff: Multiple copies, need to update each if editing manually
Recommended: Edit .kittify/AGENTS.md and run spec-kitty upgrade to refresh
Verification
After non-interactive init, verify with:
# Check what was createdls -la | grep -E "^(l|-).*AGENTS|rules$"
# Check command or skill files for specific agentsls .agents/skills/ # Codex, Vibe, Pi, Letta command skillsls .claude/commands/ # Claudels .cursor/commands/ # Cursorls .gemini/commands/ # GeminiTroubleshooting
“Invalid AI assistant”
# ERRORspec-kitty init proj --ai CODEX
# CORRECT (lowercase)spec-kitty init proj --ai codexValid keys are lowercase: codex, claude, gemini, cursor, qwen, opencode, windsurf, kilocode, auggie, copilot, q, kiro, vibe, pi, letta, llxprt
Complete Reference
Minimal Non-Interactive Init
spec-kitty init my-project --ai codex --non-interactiveMaximum Options
spec-kitty init my-project \ --ai codex,claude,cursor \ --non-interactiveCurrent Directory
spec-kitty init . --ai codex --non-interactiveEnvironment Variables
Can also be set via environment:
SPECIFY_TEMPLATE_REPO- Override template source (e.g.,myorg/custom-templates)SPEC_KITTY_NON_INTERACTIVE- Force non-interactive mode (set to1)
Exit Codes
| Code | Meaning |
|---|---|
| 0 | Success |
| 1 | Error (invalid args, missing tools, directory conflict, etc.) |
Use in scripts:
if spec-kitty init my-project --ai codex; then echo "Init succeeded"else echo "Init failed with code $?"fiAutomation Example
#!/bin/bash# Automated project setup script
PROJECT_NAME="$1"AI_AGENTS="${2:-codex}" # Default to codex
spec-kitty init "$PROJECT_NAME" \ --ai "$AI_AGENTS" \ --non-interactive || exit 1
cd "$PROJECT_NAME"echo "Project initialized successfully!"Usage:
./setup-project.sh my-new-project codex./setup-project.sh another-project "claude,codex,cursor"