CLI Commands

Complete reference for all SpecTacular CLI commands and options.

init

Initialize SpecTacular in a directory, creating the complete spec-driven project structure.

Synopsis

spectacular init [options]

Options

Option	Short	Description	Default
--name <name>	-n	Project name	Directory name
--tech <stack>	-t	Technology stack (comma-separated)	None
--path <directory>	-p	Target directory	Current directory
--language <lang>	-l	Language (en, sk)	en
--tool <tool>		AI tool (claude, cursor, both)	both
--force	-f	Overwrite existing files	false

Examples

Basic initialization:

spectacular init

With project name and tech stack:

spectacular init --name "MyApp" --tech "Node.js, TypeScript, React"

In a different directory:

spectacular init --path ~/projects/new-app --name "NewApp"

Force overwrite:

spectacular init --force

Specify language:

spectacular init --language sk

Generate for Claude Code only:

spectacular init --tool claude

What Gets Created

project-directory/
├── .spectacular/
│   ├── config/
│   │   └── project.json              # Project configuration
│   ├── templates/
│   │   ├── spec-template.md          # Specification template
│   │   ├── spec-foam-template.md     # Alternative spec format
│   │   ├── plan-template.md          # Planning template
│   │   ├── task-template.md          # Task template
│   │   ├── task-foam-template.md     # Alternative task format
│   │   ├── tasks-template.md         # Task checklist
│   │   └── feature-template.md       # Feature template
│   ├── prompts/
│   │   ├── 0-quick.md                # Full pipeline prompt
│   │   ├── 1-spec.md                 # Specification prompt
│   │   ├── 2-plan.md                 # Planning prompt
│   │   ├── 3-tasks.md                # Task breakdown prompt
│   │   ├── 4-implement.md            # Implementation prompt
│   │   └── 5-validate.md             # Validation prompt
│   ├── scripts/
│   │   └── powershell/
│   │       └── generate-commands.ps1 # Command generator
│   ├── memory/
│   │   └── constitution.md           # Project guidelines
│   └── examples/
│       └── 000-example-healthcheck/  # Example feature
├── .claude/
│   ├── commands/
│   │   ├── spectacular.0-quick.md    # Quick pipeline command
│   │   ├── spectacular.1-spec.md     # Spec command
│   │   ├── spectacular.2-plan.md     # Plan command
│   │   ├── spectacular.3-tasks.md    # Tasks command
│   │   ├── spectacular.4-implement.md # Implement command
│   │   └── spectacular.5-validate.md # Validate command
│   └── tasks/
│       ├── backlog.md                # Task backlog
│       ├── decisions.md              # Decision log
│       └── index.md                  # Tasks index
├── .cursor/
│   └── rules/
│       ├── spectacular.0-quick.md    # Quick pipeline rule
│       ├── spectacular.1-spec.md     # Spec rule
│       ├── spectacular.2-plan.md     # Plan rule
│       ├── spectacular.3-tasks.md    # Tasks rule
│       ├── spectacular.4-implement.md # Implement rule
│       └── spectacular.5-validate.md # Validate rule
├── specs/
│   └── .gitkeep                      # Keep directory in git
└── CLAUDE.md                          # Project instructions for AI

Variable Substitution

Templates support these variables:

Variable	Description	Example
	Project name from --name	"MyApp"
	Tech stack from --tech	"Node.js, TypeScript"
	Tech stack as markdown list	"- Node.js\n- TypeScript"
	Current date	"2024-12-22"
	Language from --language	"en"

Example template usage:

---
project: {{PROJECT_NAME}}
created: {{DATE}}
---

# {{PROJECT_NAME}} Specification

## Tech Stack
{{TECH_STACK_LIST}}

Becomes:

---
project: MyApp
created: 2024-12-22
---

# MyApp Specification

## Tech Stack
- Node.js
- TypeScript

project.json

The generated project.json contains:

{
  "projectName": "MyApp",
  "techStack": ["Node.js", "TypeScript", "React"],
  "language": "en",
  "tool": "both",
  "version": "1.7.0",
  "initialized": "2024-12-22T10:30:00Z"
}

---

update

Update SpecTacular CLI to the latest version.

Synopsis

spectacular update [options]

Options

Option	Short	Description
--check	-c	Only check for updates (don't install)

Examples

Check for updates:

spectacular update --check

Output:

Current version: 1.6.4
Latest version:  1.7.0
Update available!

Update to latest:

spectacular update

Output:

Downloading version 1.7.0...
Installing...
Update complete! 🎉
Spectacular is now at version 1.7.0

How It Works

1. Check GitHub Releases - Queries the GitHub API for latest release
2. Compare Versions - Uses semantic versioning comparison
3. Download - Downloads the new executable
4. Replace - Replaces the current executable
5. Update PATH - Updates PATH if needed
6. Verify - Confirms the new version

Update Process

Automatic Update Checks

The CLI checks for updates:

• Every 24 hours (configurable)
• When running spectacular init
• Can be disabled in global config

Configure in ~/.spectacular/config/global.json:

{
  "checkForUpdates": true,
  "updateCheckInterval": 86400
}

Troubleshooting

Update download fails:

# Check internet connection
ping github.com

# Set proxy if needed
$env:HTTP_PROXY = "http://proxy:8080"
spectacular update

Permission denied:

# Close all terminals using spectacular
# Then run update
spectacular update

---

--version

Display version information.

Synopsis

spectacular --version

Output

SpecTacular CLI v1.7.0
.NET 8.0
Copyright © 2024 SpecTacular Contributors

Usage

spectacular --version
# or
spectacular -v

---

--help

Display help information.

Synopsis

spectacular --help
spectacular <command> --help

General Help

spectacular --help

Output:

SpecTacular CLI v1.7.0

Description:
  Specification-driven development toolkit

Usage:
  spectacular [command] [options]

Commands:
  init      Initialize SpecTacular in a directory
  update    Update to the latest version

Options:
  --version    Show version information
  --help       Show help and usage information

Command-Specific Help

spectacular init --help

Output:

Description:
  Initialize SpecTacular in a directory

Usage:
  spectacular init [options]

Options:
  -n, --name <name>       Project name
  -t, --tech <stack>      Technology stack (comma-separated)
  -p, --path <directory>  Target directory
  -l, --language <lang>   Language (en, sk)
  --tool <tool>           AI tool (claude, cursor, both)
  -f, --force             Overwrite existing files
  --help                  Show help

---

Exit Codes

Code	Meaning
0	Success
1	General error
2	Invalid arguments
3	File system error
4	Network error (update)
5	Already initialized (without --force)

Examples

# Check if command succeeded
spectacular init --name "Test"
if ($LASTEXITCODE -eq 0) {
    Write-Host "Success!"
}

# Handle errors
spectacular init
if ($LASTEXITCODE -eq 5) {
    Write-Host "Already initialized. Use --force to overwrite."
}

---

Environment Variables

Variable	Description	Example
SPECTACULAR_HOME	Override default home directory	C:\Tools\SpecTacular
SPECTACULAR_UPDATE_CHECK	Disable update checks	false
HTTP_PROXY	Proxy server for downloads	http://proxy:8080
HTTPS_PROXY	HTTPS proxy server	https://proxy:8080

Usage

# Disable update checks
$env:SPECTACULAR_UPDATE_CHECK = "false"
spectacular init

# Use custom home directory
$env:SPECTACULAR_HOME = "C:\Tools\SpecTacular"
spectacular init

---

Next Steps

• Templates - Customize templates and prompts
• Configuration - Configure global and project settings
• CLI Architecture - Learn how the CLI works internally
• Development - Build and modify the CLI