Skip to content

Non-Interactive Init Mode

Who is this for (1)

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

Terminal window
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

Terminal window
spec-kitty init my-project

Option B: Current directory

Terminal window
spec-kitty init .

2. AI Assistants (--ai)

Syntax: Comma-separated list of agent keys (no spaces)

Terminal window
--ai codex
--ai claude,codex
--ai claude,codex,cursor,windsurf
--ai copilot,gemini,qwen

Valid agent keys:

KeyAgent Name
codexCodex CLI (OpenAI)
claudeClaude Code
geminiGemini CLI
cursorCursor
qwenQwen Code
opencodeopencode
windsurfWindsurf
kilocodeKilo Code
auggieAuggie CLI (Augment Code)
copilotGitHub Copilot
qAmazon Q Developer CLI (legacy; rebranded to Kiro)
kiroKiro CLI (formerly Amazon Q Developer CLI)
antigravityGoogle Antigravity
vibeMistral Vibe
piPi
lettaLetta Code

Case-sensitive: Use lowercase exactly as shown

Optional Flags

FlagPurposeDefault
--non-interactive / --yesDisable prompts (required for CI)Off

Complete Non-Interactive Examples

Example 1: New project with Codex

Terminal window
spec-kitty init my-project \
--ai codex \
--non-interactive

Example 2: Current directory with multiple agents

Terminal window
spec-kitty init . \
--ai claude,codex,cursor \
--non-interactive

Example 3: Minimal (relies on defaults)

Terminal window
# In non-interactive environment (CI/CD):
spec-kitty init my-project --ai codex --non-interactive

Example 4: CI/CD friendly

Terminal window
spec-kitty init . \
--ai claude \
--non-interactive

Example 5: All init-surface agents

Terminal window
spec-kitty init my-project \
--ai codex,claude,gemini,cursor,qwen,opencode,windsurf,kilocode,auggie,copilot,q,kiro \
--non-interactive

Interactive vs Non-Interactive Behavior

Interactive Mode (Default)

Triggered when:

  • Running from a terminal (TTY)
  • --non-interactive / --yes is 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 / --yes is provided
  • OR SPEC_KITTY_NON_INTERACTIVE=1 is 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/bash
spec-kitty init /app/project \
--ai claude,codex \
--non-interactive

What 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.md
  • CLAUDE.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.md
  • GEMINI.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.toml with a skill_paths entry 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

All agent-specific context files are symlinks to .kittify/AGENTS.md:

Terminal window
ls -l CLAUDE.md
# lrwxr-xr-x CLAUDE.md -> .kittify/AGENTS.md

Benefit: Single source of truth, updates to AGENTS.md instantly affect all agents

All agent-specific context files are copies of .kittify/AGENTS.md:

Terminal window
ls CLAUDE.md
# -rw-r--r-- CLAUDE.md

Tradeoff: 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:

Terminal window
# Check what was created
ls -la | grep -E "^(l|-).*AGENTS|rules$"
# Check command or skill files for specific agents
ls .agents/skills/ # Codex, Vibe, Pi, Letta command skills
ls .claude/commands/ # Claude
ls .cursor/commands/ # Cursor
ls .gemini/commands/ # Gemini

Troubleshooting

“Invalid AI assistant”

Terminal window
# ERROR
spec-kitty init proj --ai CODEX
# CORRECT (lowercase)
spec-kitty init proj --ai codex

Valid 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

Terminal window
spec-kitty init my-project --ai codex --non-interactive

Maximum Options

Terminal window
spec-kitty init my-project \
--ai codex,claude,cursor \
--non-interactive

Current Directory

Terminal window
spec-kitty init . --ai codex --non-interactive

Environment 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 to 1)

Exit Codes

CodeMeaning
0Success
1Error (invalid args, missing tools, directory conflict, etc.)

Use in scripts:

Terminal window
if spec-kitty init my-project --ai codex; then
echo "Init succeeded"
else
echo "Init failed with code $?"
fi

Automation 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:

Terminal window
./setup-project.sh my-new-project codex
./setup-project.sh another-project "claude,codex,cursor"

Command Reference

See Also

Background