CLI Command Reference

This reference lists the user-facing spec-kitty CLI commands and their flags exactly as surfaced by --help. For agent-only commands, see docs/reference/agent-subcommands.md.

spec-kitty

Synopsis: spec-kitty [OPTIONS] COMMAND [ARGS]...

Description: Spec Kitty CLI entry point.

Options:

Flag	Description
`--version`, `-v`	Show version and exit
`--help`	Show this message and exit

Commands:

init - Initialize a new Spec Kitty project from templates
specify - Create a feature scaffold in kitty-specs/
plan - Scaffold plan.md for a feature
tasks - Finalize task metadata after task generation
accept - Validate feature readiness before merging to main
dashboard - Open or stop the Spec Kitty dashboard
implement - Create workspace for work package implementation
merge - Merge a completed feature branch into the target branch and clean up resources
sync - Synchronize workspace with upstream changes
context - Query workspace context information
ops - Operation history and undo (git reflog)
orchestrator-api - Host contract for external orchestrators (JSON envelope interface)
research - Execute Phase 0 research workflow to scaffold artifacts
upgrade - Upgrade a Spec Kitty project to the current version
list-legacy-features - List legacy worktrees blocking 0.11.0 upgrade
validate-encoding - Validate and optionally fix file encoding in feature artifacts
validate-tasks - Validate and optionally fix task metadata inconsistencies
verify-setup - Verify that the current environment matches Spec Kitty expectations
agent - Commands for AI agents to execute spec-kitty workflows programmatically
mission - View available Spec Kitty missions
repair - Repair broken templates

spec-kitty init

Synopsis: spec-kitty init [OPTIONS] [PROJECT_NAME]

Description: Initialize a new Spec Kitty project from templates.

Arguments:

PROJECT_NAME: Name for your new project directory (optional if using --here, or use . for current directory)

Options:

Flag	Description
`--ignore-agent-tools`	Skip checks for AI agent tools like Claude Code
`--no-git`	Skip git repository initialization
`--here`	Initialize project in the current directory instead of creating a new one
`--force`	Force merge/overwrite when using `--here` (skip confirmation)
`--skip-tls`	Skip SSL/TLS verification (not recommended)
`--debug`	Show verbose diagnostic output for network and extraction failures
`--github-token TEXT`	GitHub token to use for API requests (or set `GH_TOKEN`/`GITHUB_TOKEN`)
`--template-root TEXT`	Override default template location (useful for development mode)
`--ai TEXT`	Comma-separated AI assistants (claude,codex,gemini,...)
`--script TEXT`	Script type to use: `sh` or `ps`
`--non-interactive` / `--yes`	Disable prompts (CI/CD)
`--help`	Show this message and exit

Examples:

spec-kitty init my-project
spec-kitty init my-project --ai codex
spec-kitty init my-project --ai codex,claude --script sh
spec-kitty init . --ai codex --force
spec-kitty init --here --ai claude
spec-kitty init my-project --ai codex --non-interactive

See Also: docs/non-interactive-init.md

spec-kitty specify

Synopsis: spec-kitty specify [OPTIONS] FEATURE

Description: Create a feature scaffold in kitty-specs/.

Arguments:

FEATURE: Feature name or slug (for example user-authentication) [required]

Options:

Flag	Description
`--mission TEXT`	Mission type (for example `software-dev`, `research`)
`--json`	Emit JSON result
`--help`	Show this message and exit

spec-kitty plan

Synopsis: spec-kitty plan [OPTIONS]

Description: Scaffold plan.md for a feature.

Options:

Flag	Description
`--feature TEXT`	Feature slug (for example `001-user-authentication`)
`--json`	Emit JSON result
`--help`	Show this message and exit

spec-kitty tasks

Synopsis: spec-kitty tasks [OPTIONS]

Description: Finalize tasks metadata after task generation.

Options:

Flag	Description
`--json`	Emit JSON result
`--help`	Show this message and exit

spec-kitty upgrade

Synopsis: spec-kitty upgrade [OPTIONS]

Description: Upgrade a Spec Kitty project to the current version.

Options:

Flag	Description
`--dry-run`	Preview changes without applying
`--force`	Skip confirmation prompts
`--target TEXT`	Target version (defaults to current CLI version)
`--json`	Output results as JSON
`--verbose`, `-v`	Show detailed migration information
`--no-worktrees`	Skip upgrading worktrees
`--help`	Show this message and exit

Examples:

spec-kitty upgrade
spec-kitty upgrade --dry-run
spec-kitty upgrade --target 0.6.5

spec-kitty implement

Synopsis: spec-kitty implement [OPTIONS] WP_ID

Description: Create workspace for work package implementation (git worktree).

Arguments:

WP_ID: Work package ID (e.g., WP01) [required]

Options:

Flag	Description
`--base TEXT`	Base WP to branch from (e.g., `WP01`)
`--feature TEXT`	Feature slug (e.g., `001-my-feature`)
`--json`	Output in JSON format
`--help`	Show this message and exit

Examples:

spec-kitty implement WP01
spec-kitty implement WP02 --base WP01
spec-kitty implement WP01 --feature 001-my-feature
spec-kitty implement WP01 --json

spec-kitty accept

Synopsis: spec-kitty accept [OPTIONS]

Description: Validate feature readiness before merging to main.

Options:

Flag	Description
`--feature TEXT`	Feature slug to accept (auto-detected by default)
`--mode TEXT`	Acceptance mode: `auto`, `pr`, `local`, or `checklist` (default: `auto`)
`--actor TEXT`	Name to record as the acceptance actor
`--test TEXT`	Validation command executed (repeatable)
`--json`	Emit JSON instead of formatted text
`--lenient`	Skip strict metadata validation
`--no-commit`	Skip auto-commit; report only
`--allow-fail`	Return checklist even when issues remain
`--help`	Show this message and exit

spec-kitty merge

Synopsis: spec-kitty merge [OPTIONS]

Description: Merge a completed feature branch into the target branch and clean up resources.

Options:

Flag	Description
`--strategy TEXT`	Merge strategy: `merge`, `squash`, or `rebase` (default: `merge`)
`--delete-branch`, `--keep-branch`	Delete or keep feature branch after merge (default: delete)
`--remove-worktree`, `--keep-worktree`	Remove or keep feature worktree after merge (default: remove)
`--push`	Push to origin after merge
`--target TEXT`	Target branch to merge into (default: `main`)
`--dry-run`	Show what would be done without executing
`--help`	Show this message and exit

spec-kitty dashboard

Synopsis: spec-kitty dashboard [OPTIONS]

Description: Open or stop the Spec Kitty dashboard.

Options:

Flag	Description
`--port INTEGER`	Preferred port for the dashboard (falls back to first available port)
`--kill`	Stop the running dashboard for this project and clear its metadata
`--help`	Show this message and exit

spec-kitty research

Synopsis: spec-kitty research [OPTIONS]

Description: Execute Phase 0 research workflow to scaffold artifacts.

Options:

Flag	Description
`--feature TEXT`	Feature slug to target (auto-detected when omitted)
`--force`	Overwrite existing research artifacts
`--help`	Show this message and exit

spec-kitty orchestrator-api

Synopsis: spec-kitty orchestrator-api [OPTIONS] COMMAND [ARGS]...

Description: Machine-contract API for external orchestrators. Every command emits exactly one JSON envelope and exits non-zero on failure.

Options:

Flag	Description
`--help`	Show this message and exit

Commands:

contract-version - Return host contract version and provider compatibility minimum
feature-state - Return full feature/WP state snapshot
list-ready - Return planned WPs whose dependencies are done
start-implementation - Composite claim/start transition for a WP
start-review - Move rejected WP from for_review back to in_progress
transition - Apply explicit lane transition with state-machine validation
append-history - Append activity history to a WP prompt
accept-feature - Accept a feature when all WPs are done
merge-feature - Run preflight and merge all WP branches

See Also: Orchestrator API Reference

spec-kitty sync

Synopsis: spec-kitty sync [OPTIONS] COMMAND [ARGS]...

Description: Synchronization commands for workspaces and server connectivity.

Options:

Flag	Description
`--help`	Show this message and exit

Commands:

workspace - Sync workspace with upstream changes (local)

spec-kitty sync workspace

Synopsis: spec-kitty sync workspace [OPTIONS]

Description: Synchronize the current workspace with upstream changes. Updates the current workspace with changes from its base branch or parent using git rebase <base-branch>.

Options:

Flag	Description
`--repair`, `-r`	Attempt workspace recovery (may lose uncommitted work)
`--verbose`, `-v`	Show detailed sync output
`--help`	Show this message and exit

Examples:

spec-kitty sync workspace
spec-kitty sync workspace --verbose
spec-kitty sync workspace --repair

Note: Sync may fail on conflicts. You must resolve conflicts before continuing.

See Also: Sync Workspaces

spec-kitty context

Synopsis: spec-kitty context [OPTIONS] COMMAND [ARGS]...

Description: Query workspace context information.

Options:

Flag	Description
`--help`	Show this message and exit

Commands:

info - Show context information for current or specified workspace
list - List all workspace contexts
cleanup - Clean up orphaned workspace contexts

spec-kitty ops

Synopsis: spec-kitty ops COMMAND [ARGS]...

Description: Operation history and undo (jj: full undo, git: reflog-only history).

Options:

Flag	Description
`--help`	Show this message and exit

Commands:

log - Show operation history
undo - Undo last operation (jj only)
restore - Restore to a specific operation (jj only)

spec-kitty ops log

Synopsis: spec-kitty ops log [OPTIONS]

Description: Show git reflog entries. Displays recent git operations that have modified the repository state.

Options:

Flag	Description
`--limit`, `-n INTEGER`	Number of operations to show (default: 20)
`--verbose`, `-v`	Show full operation IDs and details
`--help`	Show this message and exit

Examples:

spec-kitty ops log
spec-kitty ops log -n 50
spec-kitty ops log --verbose

spec-kitty mission

Synopsis: spec-kitty mission [OPTIONS] COMMAND [ARGS]...

Description: View available Spec Kitty missions. Missions are selected per-feature during /spec-kitty.specify.

Options:

Flag	Description
`--help`	Show this message and exit

Commands:

list - List all available missions with source (project or built-in)
current - Show currently active mission for a feature
info - Show mission details without switching
switch - Deprecated alias retained for compatibility (removed behavior)
join - Join mission as participant
status - Display mission roster and status
comment - Post a comment to the mission
decide - Capture a mission decision
focus - Focus management commands
drive - Drive management commands

spec-kitty mission list

Synopsis: spec-kitty mission list [OPTIONS]

Description: List all available missions with their source (project/built-in).

Options:

Flag	Description
`--help`	Show this message and exit

spec-kitty mission current

Synopsis: spec-kitty mission current [OPTIONS]

Description: Show currently active mission.

Options:

Flag	Description
`--help`	Show this message and exit

spec-kitty mission info

Synopsis: spec-kitty mission info [OPTIONS] MISSION_NAME

Description: Show details for a specific mission without switching.

Arguments:

MISSION_NAME: Mission name to display details for [required]

Options:

Flag	Description
`--help`	Show this message and exit

spec-kitty mission switch

Synopsis: spec-kitty mission switch [OPTIONS] MISSION_NAME

Description: (deprecated) Switch active mission - removed in v0.8.0.

Arguments:

MISSION_NAME: Mission name (no longer supported) [required]

Options:

Flag	Description
`--force`	(ignored)
`--help`	Show this message and exit

spec-kitty validate-encoding

Synopsis: spec-kitty validate-encoding [OPTIONS]

Description: Validate and optionally fix file encoding in feature artifacts.

Options:

Flag	Description
`--feature TEXT`	Feature slug to validate (auto-detected when omitted)
`--fix`	Automatically fix encoding errors by sanitizing files
`--all`	Check all features, not just one
`--backup`, `--no-backup`	Create .bak files before fixing (default: backup)
`--help`	Show this message and exit

spec-kitty validate-tasks

Synopsis: spec-kitty validate-tasks [OPTIONS]

Description: Validate and optionally fix task metadata inconsistencies.

Options:

Flag	Description
`--feature TEXT`	Feature slug to validate (auto-detected when omitted)
`--fix`	Automatically repair metadata inconsistencies
`--all`	Check all features, not just one
`--agent TEXT`	Agent name for activity log
`--shell-pid TEXT`	Shell PID for activity log
`--help`	Show this message and exit

spec-kitty verify-setup

Synopsis: spec-kitty verify-setup [OPTIONS]

Description: Verify that the current environment matches Spec Kitty expectations.

Options:

Flag	Description
`--feature TEXT`	Feature slug to verify (auto-detected when omitted)
`--json`	Output in JSON format for AI agents
`--check-files`	Check mission file integrity (default: True)
`--check-tools`	Check for installed development tools (default: True)
`--diagnostics`	Show detailed diagnostics with dashboard health
`--help`	Show this message and exit

spec-kitty list-legacy-features

Synopsis: spec-kitty list-legacy-features [OPTIONS]

Description: List legacy worktrees blocking 0.11.0 upgrade.

Options:

Flag	Description
`--help`	Show this message and exit

spec-kitty repair

Synopsis: spec-kitty repair [OPTIONS] COMMAND [ARGS]...

Description: Repair broken templates.

Options:

Flag	Description
`--help`	Show this message and exit

Commands:

repair - Repair broken templates caused by v0.10.0-v0.10.8 bundling bug
worktree - Diagnose worktree kitty-specs/ status

spec-kitty repair repair

Synopsis: spec-kitty repair repair [OPTIONS]

Description: Repair broken templates caused by v0.10.0-0.10.8 bundling bug.

Options:

Flag	Description
`--project-path PATH`, `-p`	Path to project to repair
`--dry-run`	Show what would be changed without making changes
`--help`	Show this message and exit

spec-kitty repair worktree

Synopsis: spec-kitty repair worktree [OPTIONS] [WORKTREE_PATH]

Description: Diagnose worktree kitty-specs/ status and report repair guidance.

Arguments:

WORKTREE_PATH: Specific worktree path to check (optional)

Options:

Flag	Description
`--all`	Check all worktrees in `.worktrees/`
`--help`	Show this message and exit

spec-kitty agent

Synopsis: spec-kitty agent [OPTIONS] COMMAND [ARGS]...

Description: Commands for AI agents to execute spec-kitty workflows programmatically.

Options:

Flag	Description
`--help`	Show this message and exit

See Also: docs/reference/agent-subcommands.md

spec-kitty agent config

Manage project AI agent configuration (add, remove, list agents).

Usage:

spec-kitty agent config [OPTIONS] COMMAND [ARGS]...

Description: The config subcommand provides tools for managing which AI agents are active in your project. Agent configuration is stored in .kittify/config.yaml and controls which agent directories are present on the filesystem.

Subcommands:

Command	Description
`list`	View configured agents and available options
`add`	Add one or more agents to your project
`remove`	Remove one or more agents from your project
`status`	Audit agent configuration sync status
`sync`	Synchronize filesystem with config.yaml

See also: Managing AI Agents for task-oriented guidance on agent management workflows.

Note: Starting in 0.12.0, agent configuration is config-driven. .kittify/config.yaml is the single source of truth, and migrations respect your configuration choices. See Upgrading to 0.12.0 for migration details.

spec-kitty agent config list

View configured agents and available options.

Synopsis:

spec-kitty agent config list

Description:

Lists agents currently configured in your project (from .kittify/config.yaml) with status indicators, and shows available agents that can be added.

Arguments: None

Options: None

Output:

Two sections:

Configured agents: Agents in config.yaml with status indicators:
- ✓ (green) - Directory exists
- ⚠ (yellow) - Configured but directory missing
Available but not configured: Agents you can add

Examples:

View configured agents:

spec-kitty agent config list

Example output:

Configured agents:
  ✓ opencode (.opencode/command/)
  ✓ claude (.claude/commands/)

Available but not configured:
  - codex
  - gemini
  - cursor
  ...

spec-kitty agent config add

Add one or more agents to your project.

Synopsis:

spec-kitty agent config add <agent1> [agent2] [agent3] ...

Description:

Adds specified agents to your project by creating agent directories, copying slash command templates, and updating .kittify/config.yaml.

Arguments:

<agents>: Space-separated list of agent keys to add. Valid keys: claude, codex, gemini, cursor, qwen, opencode, windsurf, kilocode, roo, copilot, auggie, q.

Options: None

Output:

Success: ✓ Added <agent-dir>/<subdir>/ for each agent
Already configured: Already configured: <agent> (informational, not an error)
Error: Error: Invalid agent keys: <keys> with list of valid keys

Side Effects:

Creates agent directory (e.g., .claude/commands/)
Copies slash command templates from mission templates
Adds agent key to .kittify/config.yaml under agents.available

Examples:

Add a single agent:

spec-kitty agent config add claude

Add multiple agents:

spec-kitty agent config add codex gemini cursor

Example output:

✓ Added .codex/prompts/
✓ Added .gemini/commands/
✓ Added .cursor/commands/
Updated .kittify/config.yaml

Error handling (invalid key):

spec-kitty agent config add cluade

Output:

Error: Invalid agent keys: cluade

Valid agent keys:
  claude, codex, gemini, cursor, qwen, opencode,
  windsurf, kilocode, roo, copilot, auggie, q

spec-kitty agent config remove

Remove one or more agents from your project.

Synopsis:

spec-kitty agent config remove [OPTIONS] <agent1> [agent2] [agent3] ...

Description:

Removes specified agents from your project by deleting agent directories and updating .kittify/config.yaml.

Arguments:

<agents>: Space-separated list of agent keys to remove. Valid keys: same as add command.

Options:

--keep-config: Keep agent in config.yaml but delete directory (default: False)

Output:

Success: ✓ Removed <agent-dir>/ for each agent
Already removed: • <agent-dir>/ already removed (dim, informational)
Error: Error: Invalid agent keys: <keys> with list of valid keys

Side Effects:

Deletes entire agent directory (e.g., .gemini/ and all contents)
Removes agent key from .kittify/config.yaml (unless --keep-config used)

Warning: Directory deletion is permanent. Ensure you don't have custom modifications in template files before removing.

Examples:

Remove a single agent:

spec-kitty agent config remove gemini

Remove multiple agents:

spec-kitty agent config remove cursor qwen windsurf

Example output:

✓ Removed .cursor/
✓ Removed .qwen/
✓ Removed .windsurf/
Updated .kittify/config.yaml

Keep in config but remove directory:

spec-kitty agent config remove gemini --keep-config

Restore later with:

spec-kitty agent config sync --create-missing

spec-kitty agent config status

Audit agent configuration sync status.

Synopsis:

spec-kitty agent config status

Description:

Displays a comprehensive table showing all 12 supported agents, whether they're configured, whether directories exist, and sync status.

Arguments: None

Options: None

Output:

Rich table with columns:

Agent Key (cyan): Agent identifier
Directory (dim): Filesystem path
Configured: ✓ if in config.yaml, ✗ otherwise
Exists: ✓ if directory present, ✗ otherwise
Status: Colored status indicator

Status values:

[green]OK[/green]: Configured and directory exists (normal state)
[yellow]Missing[/yellow]: Configured but directory doesn't exist (needs sync)
[red]Orphaned[/red]: Directory exists but not configured (should be cleaned up)
[dim]Not used[/dim]: Neither configured nor present (available to add)

Actionable message: If orphaned directories detected, shows: "Run 'spec-kitty agent config sync --remove-orphaned' to clean up"

Examples:

Audit agent configuration:

spec-kitty agent config status

Example output:

Agent Key  Directory                Configured  Exists  Status
──────────────────────────────────────────────────────────────────
claude     .claude/commands/        ✓           ✓       OK
codex      .codex/prompts/          ✗           ✓       Orphaned
gemini     .gemini/commands/        ✓           ✗       Missing
cursor     .cursor/commands/        ✗           ✗       Not used
qwen       .qwen/commands/          ✓           ✓       OK
...

⚠ Found 1 orphaned directory
Run 'spec-kitty agent config sync --remove-orphaned' to clean up

spec-kitty agent config sync

Synchronize filesystem with config.yaml.

Synopsis:

spec-kitty agent config sync [OPTIONS]

Description:

Automatically aligns filesystem with .kittify/config.yaml by creating missing directories and/or removing orphaned directories.

Arguments: None

Options:

--create-missing: Create directories for configured agents that are missing from filesystem (default: False)
--remove-orphaned / --keep-orphaned: Remove orphaned directories (directories present but not configured). Default: --remove-orphaned (True)

Default behavior (no flags): Removes orphaned directories only. Does NOT create missing directories.

Output:

Creating: ✓ Created <agent-dir>/<subdir>/
Removing: ✓ Removed orphaned <agent-dir>/
No changes: No changes needed - filesystem matches config

Side Effects:

Creates agent directories with slash command templates (if --create-missing)
Deletes orphaned agent directories (if --remove-orphaned, default)

Examples:

Default sync (remove orphaned only):

spec-kitty agent config sync

Create missing configured agents:

spec-kitty agent config sync --create-missing

Complete sync (both directions):

spec-kitty agent config sync --create-missing --remove-orphaned

Keep orphaned directories:

spec-kitty agent config sync --keep-orphaned

Example output:

✓ Created .claude/commands/
✓ Removed orphaned .gemini/

No changes needed:

No changes needed - filesystem matches config

Table of Contents

CLI Command Reference

spec-kitty

spec-kitty init

spec-kitty specify

spec-kitty plan

spec-kitty tasks

spec-kitty upgrade

spec-kitty implement

spec-kitty accept

spec-kitty merge

spec-kitty dashboard

spec-kitty research

spec-kitty orchestrator-api

spec-kitty sync

spec-kitty sync workspace

spec-kitty context

spec-kitty ops

spec-kitty ops log

spec-kitty mission

spec-kitty mission list

spec-kitty mission current

spec-kitty mission info

spec-kitty mission switch

spec-kitty validate-encoding

spec-kitty validate-tasks

spec-kitty verify-setup

spec-kitty list-legacy-features

spec-kitty repair

spec-kitty repair repair

spec-kitty repair worktree

spec-kitty agent

spec-kitty agent config

spec-kitty agent config list

spec-kitty agent config add

spec-kitty agent config remove

spec-kitty agent config status

spec-kitty agent config sync

Getting Started

Practical Usage