🚀 Spectral CLI Commands Guide

Complete reference for all Spectral CLI commands with interactive features, AI model selection, and code generation.

Table of Contents

• Installation & Updates
• Interactive Commands
  • Chat Command
  • Implement Command
  • Inference Command
• Core Commands
  • Parse Command
  • Validate Command
  • Analyze Command
  • Docs Command
• Model Selection
• Tool Integration
• Command Reference

Installation & Updates

Install Spectral

# Install via curl (Aexol team)
export GITLAB_TOKEN=<your_private_token>
curl --fail --show-error --location \
  --header "Private-Token: $GITLAB_TOKEN" \
  https://gitlab.aexol.com/api/v4/projects/725/packages/generic/spectral/latest/install.sh | bash

Update Spectral

# Update to latest version
spectral update

# Install specific version
spectral update --version 0.4.4

Interactive Commands

Chat Command

AI-powered conversational interface for designing and refining Spectral specifications.

Basic Usage

# Start interactive chat with model selection
spectral chat

# On first run, you'll see:
🤖 Select AI Model

🚀 Codex CLI
  ▶ Codex CLI - GPT-5 (recommended)
    Codex CLI - GPT-5-Codex
    Codex CLI - GPT-4o

🤖 GitHub Copilot CLI
  ▶ GitHub Copilot CLI - Claude Sonnet 4

Anthropic Claude Models
  ▶ claude-sonnet-4-5-20250929 - Latest Sonnet
    claude-haiku-4-5-20251001 - Fast and efficient

OpenAI GPT-5 Series (Latest)
  ▶ gpt-5 - Best for coding & agentic tasks
    gpt-5-mini - Faster, cost-efficient

Chat Features

🔧 15 Available Tools (for API models only - Claude, GPT):

File Operations (8 tools):

• list_files(path?) - List files and directories
• read_file(file_path, start_line?, end_line?) - Read file contents
• write_file(file_path, content) - Create or overwrite files
• delete_file(file_path) - Delete files
• search_files(pattern, file_pattern?) - Search text in files
• replace_in_file(file_path, old_text, new_text) - Replace text
• create_directory(path) - Create directories
• get_file_info(path) - Get file/directory info

Spectral Commands (7 tools):

• spectral_parse(file_path, json?, validate?) - Parse Spectral files
• spectral_validate(file_path, json?, verbose?) - Validate files
• spectral_docs(file_path, output?, format?) - Generate docs
• spectral_analyze(file_path, verbose?) - Analyze specifications
• spectral_version() - Get CLI version
• spectral_help(command?) - Get command help

Chat Commands

During a chat session, use these commands:

• /exit or :q - End the session
• /model - Change AI model (saved to .spectral/config.json)
• /tools - Show available AI tools
• /help - Show help message

Chat Command Options

# Use specific model
spectral chat --model claude-sonnet-4-5-20250929

# Use Codex CLI for interactive terminal
spectral chat --model codex-cli

# Use GitHub Copilot CLI
spectral chat --model copilot-cli

# Start with a prompt/goal
spectral chat --prompt "Help me design an authentication workflow"

Example Conversation

$ spectral chat

spectral> Can you help me design a todo application workflow?

AI: I can help you design a comprehensive todo workflow. Let me first check
if there are any existing examples...

spectral> Create a workflow file for me

AI: I'll create a workflow specification for your todo application with the
necessary states and transitions...

[File created: workflows/todo.spectral]

spectral> /exit
Session ended.

Implement Command

Generate project structure and implement methods with AI agent guidance.

Basic Usage

# Interactive agent selection
spectral implement app.spectral

# On first run, you'll see:
🤖 Select AI Agent for Implementation

🤖 AI Agents
  ▶ GitHub Copilot CLI - Interactive coding with GitHub Copilot
    Codex CLI - Coding agent from Aexol
    Claude Code CLI - Anthropic Claude coding assistant

Implement Options

# Use specific agent
spectral implement app.spectral --agent copilot

# Specify target language
spectral implement api.spectral --language python

# Provide implementation guidance
spectral implement todo.spectral --guidance "Use async/await, add validation"

# Dry run (generate structure only)
spectral implement app.spectral --dry-run

# Specify output directory
spectral implement app.spectral -o ./src

How It Works

1. Generates skeleton code with TODOs from your Spectral specification
2. Implements each method interactively using your chosen AI agent

Supported Agents

• GitHub Copilot CLI: npm install -g @githubnext/github-copilot-cli
• Codex CLI: npm install -g codex-cli
• Claude CLI: Note - Anthropic does not provide a CLI tool. Use API models instead.

Example

$ spectral implement todo.spectral --agent copilot --language typescript

✓ Parsed todo.spectral
✓ Generated project structure

📁 Generated files:
  → src/TodoList.ts (3 TODOs)
  → src/TodoItem.ts (2 TODOs)
  → src/api/routes.ts (4 TODOs)

🤖 Launching GitHub Copilot CLI for implementation...

[Interactive session begins...]

Inference Command

Generate artifacts (GraphQL, Prisma, Routes, Webhooks, Cron, E2E Tests) from Spectral specifications using AI inference.

The inference command analyzes your Spectral specification and generates production-ready artifacts for various parts of your stack.

Available Subcommands

GraphQL Schema Generation

Generate a complete GraphQL schema from your types and visitor capabilities.

# Basic usage
spectral inference graphql app.spectral

# Specify output file
spectral inference graphql app.spectral -o schema.graphql

# With Apollo Federation directives
spectral inference graphql app.spectral --federated

# Use specific AI agent
spectral inference graphql app.spectral -a claude-sonnet-4-5-20250929

What it generates:

• GraphQL types from Spectral types
• Query operations from "can view/browse/list/search" capabilities
• Mutation operations from "can create/update/delete" capabilities
• Subscription operations from "can subscribe/watch" capabilities
• Input types for mutations (CreateInput, UpdateInput)
• Descriptions from your specification

Prisma Schema Generation

Generate a Prisma schema with auto-detected relations.

# Basic usage
spectral inference prisma app.spectral

# Specify output and database provider
spectral inference prisma app.spectral -o prisma/schema.prisma --provider postgresql

# Available providers: postgresql, mysql, sqlite, mongodb
spectral inference prisma app.spectral --provider mysql

What it generates:

• Prisma models from Spectral types
• Auto-detected relations from field naming patterns (e.g., customerId → relation to Customer)
• Appropriate attributes (@id, @unique, @default, @relation)
• Indexes for frequently queried fields

Route Tree Generation

Generate route configurations for various frontend frameworks.

# Generate JSON route tree (framework-agnostic)
spectral inference routes app.spectral

# React Router v6 format
spectral inference routes app.spectral --framework react-router -o src/routes.tsx

# Next.js App Router structure
spectral inference routes app.spectral --framework nextjs

# Vue Router v4 format
spectral inference routes app.spectral --framework vue-router -o src/router/routes.ts

Route inference from visitors:

visitor Dashboard {
  can view overview         # → /dashboard (index)
  can manage orders {       # → /dashboard/orders
    can view order          # → /dashboard/orders/:id
    can edit order          # → /dashboard/orders/:id/edit
    can create order        # → /dashboard/orders/new
  }
}

Webhook Specifications

Generate webhook endpoint specifications from agent definitions.

# Basic usage
spectral inference webhooks app.spectral

# Specify framework context
spectral inference webhooks app.spectral --framework express
spectral inference webhooks app.spectral --framework nextjs
spectral inference webhooks app.spectral --framework hono

Output format (JSON):

{
  "webhooks": [
    {
      "path": "/webhooks/stripe/payment-succeeded",
      "method": "POST",
      "source": "stripe",
      "event": "payment_intent.succeeded",
      "description": "Handles successful payment events",
      "handler": "PaymentProcessor agent"
    }
  ]
}

Cron Job Specifications

Generate scheduled job definitions from agent schedules.

# node-cron format (default)
spectral inference cron app.spectral

# GitHub Actions workflow
spectral inference cron app.spectral --format github-actions -o .github/workflows/scheduled.yml

# Kubernetes CronJob manifests
spectral inference cron app.spectral --format kubernetes -o k8s/cronjobs.yaml

E2E Test Specifications

Generate comprehensive test specifications from visitor journeys.

# Markdown format (default)
spectral inference e2e app.spectral -o tests/

# Gherkin/Cucumber format
spectral inference e2e app.spectral --format gherkin -o tests/

# Simple checklist format
spectral inference e2e app.spectral --format checklist

What it generates:

• Test flows for each visitor
• Happy path and error scenarios
• Preconditions based on state requirements
• Step-by-step test instructions

Inference Command Options

All subcommands support these common options:

-o, --output <path>    # Output file or directory
-a, --agent <agent>    # AI agent to use (interactive if not specified)
-h, --help             # Show help for the subcommand

Example: Full Stack Generation

# Generate all artifacts for an e-commerce app
spectral inference graphql ecommerce.spectral -o generated/schema.graphql
spectral inference prisma ecommerce.spectral -o generated/prisma/schema.prisma
spectral inference routes ecommerce.spectral -o generated/routes.tsx --framework react-router
spectral inference webhooks ecommerce.spectral -o generated/webhooks.json
spectral inference e2e ecommerce.spectral -o generated/tests/

Core Commands

Parse Command

Parse a Spectral file and display the Abstract Syntax Tree (AST).

Basic Usage

# Parse and show AST
spectral parse app.spectral

# Parse with JSON output
spectral parse app.spectral --json

# Parse directory of specs
spectral parse ./specs

# Verbose output
spectral parse app.spectral --verbose

Example Output

$ spectral parse examples/todo.spectral

✓ Parsed successfully

📊 Summary:
  - 3 visitors
  - 2 roles
  - 1 workflow
  - 4 types
  - 0 agents

AST Structure:
  ├─ Visitor: TodoUser
  ├─ Role: Admin
  ├─ Workflow: TodoLifecycle
  └─ Type: Todo

Validate Command

Validate a Spectral file for syntax and semantic errors.

Basic Usage

# Validate specification
spectral validate app.spectral

# Validate with JSON output
spectral validate app.spectral --json

# Verbose validation
spectral validate app.spectral --verbose

Example Output

$ spectral validate app.spectral

✓ Validation passed

✓ 0 errors
⚠ 2 warnings:
  - Workflow 'TodoLifecycle' missing initial state (line 45)
  - Agent 'TaskManager' role 'Undefined' not found (line 67)

Analyze Command

Analyze a Spectral specification and generate a detailed complexity report.

Basic Usage

# Analyze specification
spectral analyze app.spectral

# Analyze with verbose output
spectral analyze app.spectral --verbose

# Analyze directory
spectral analyze ./specs

Example Output

$ spectral analyze ecommerce.spectral

📊 Spectral Analysis Report

Complexity Metrics:
  - Total Definitions: 42
  - Visitors: 5 (depth: 3-5 levels)
  - Workflows: 3 (avg 8 states)
  - Agents: 7 (avg 4 capabilities)
  - Types: 12
  - Roles: 4

Recommendations:
  ✓ Well-structured specification
  ⚠ Consider splitting large workflows
  → ProductCheckout workflow has 15 states

Docs Command

Generate comprehensive Markdown documentation from Spectral specifications.

Basic Usage

# Generate documentation
spectral docs app.spectral

# Save to file
spectral docs app.spectral -o API.md

# Generate for directory
spectral docs ./specs -o documentation.md

Example Output

$ spectral docs ecommerce.spectral -o API.md

✓ Parsed ecommerce.spectral
✓ Generating documentation...

📄 Generated documentation:
  → API.md (1,234 lines)

Includes:
  - Overview
  - Type Definitions (12 types)
  - Workflows (3 workflows, 24 states)
  - Agents (7 agents)
  - Visitors (5 visitors)
  - Roles & Permissions

Model Selection

Available Models

CLI Tools (Interactive Terminal Sessions)

• codex-cli:gpt-5 - Codex CLI with GPT-5 (recommended)
• codex-cli:gpt-5-codex - Optimized for agentic coding
• codex-cli:gpt-4o - Fast & intelligent
• copilot-cli - GitHub Copilot CLI (Claude Sonnet 4)

Anthropic Claude (API)

• claude-sonnet-4-5-20250929 - Latest Sonnet (recommended)
• claude-haiku-4-5-20251001 - Fast and efficient

OpenAI GPT-5 Series (API - Latest)

• gpt-5 - Best for coding & agentic tasks
• gpt-5-mini - Faster, cost-efficient
• gpt-5-nano - Fastest, most cost-efficient
• gpt-5-pro - Smarter, more precise
• gpt-5-codex - Optimized for Codex

OpenAI GPT-4.1 Series (API)

• gpt-4.1 - Smartest non-reasoning
• gpt-4.1-mini - Smaller, faster
• gpt-4.1-nano - Fastest GPT-4.1

OpenAI o-series (Reasoning Models)

• o3 - Latest reasoning model
• o3-mini - Small reasoning model
• o3-pro - More compute, better responses
• o4-mini - Fast reasoning model

Model Configuration

Models are saved to .spectral/config.json and persist across sessions.

# Models are selected interactively
spectral chat
# → Select model from menu
# → Saved to .spectral/config.json

# Or specify directly
spectral chat --model claude-sonnet-4-5-20250929

Environment Variables

# Anthropic API Key (for Claude models)
export ANTHROPIC_API_KEY=your_key

# OpenAI API Key (for GPT models)
export OPENAI_API_KEY=your_key

# Disable colors in output
export NO_COLOR=1

Tool Integration

AI Tools (API Models Only)

Tools are available for API models (Claude, GPT) but not for CLI models (Codex CLI, Copilot CLI).

File Operations (8 tools)

list_files(path?)
read_file(file_path, start_line?, end_line?)
write_file(file_path, content)
delete_file(file_path)
search_files(pattern, file_pattern?)
replace_in_file(file_path, old_text, new_text)
create_directory(path)
get_file_info(path)

Spectral Commands (7 tools)

spectral_parse(file_path, json?, validate?)
spectral_validate(file_path, json?, verbose?)
spectral_docs(file_path, output?, format?)
spectral_analyze(file_path, verbose?)
spectral_version()
spectral_help(command?)

Using Tools in Chat

AI can use tools automatically by describing the action:

You: Can you read the package.json file?

AI: Let me read_file(package.json)...

🔧 Executing tools...
  → read_file(package.json)
  ✅ File contents loaded

Here's what I found in package.json...

Command Reference

Quick Reference

# Core commands
spectral parse <file>              # Parse Spectral file
spectral validate <file>           # Validate specification
spectral analyze <file>            # Analyze complexity
spectral docs <file>               # Generate documentation

# Interactive commands
spectral chat                      # Interactive AI chat
spectral implement <file>          # AI-assisted implementation

# Inference commands (generate artifacts)
spectral inference graphql <file>  # Generate GraphQL schema
spectral inference prisma <file>   # Generate Prisma schema
spectral inference routes <file>   # Generate route tree
spectral inference webhooks <file> # Generate webhook specs
spectral inference cron <file>     # Generate cron job specs
spectral inference e2e <file>      # Generate E2E test specs

# Utility commands
spectral update                    # Update Spectral CLI
spectral help                      # Show help

Common Workflows

1. Design a Specification

# Start with interactive chat
spectral chat

# Design your specification interactively
spectral> I need a user authentication workflow

# AI helps you design the spec
# Save it to a .spectral file

2. Validate & Analyze

# Validate the specification
spectral validate auth.spectral

# Analyze complexity
spectral analyze auth.spectral

3. Generate Artifacts with Inference

# Generate GraphQL schema
spectral inference graphql auth.spectral -o schema.graphql

# Generate Prisma schema
spectral inference prisma auth.spectral -o prisma/schema.prisma

# Generate routes
spectral inference routes auth.spectral --framework react-router

4. Implement with AI

# Implement with AI agent
spectral implement auth.spectral --agent copilot --language typescript

5. Generate Documentation

# Create API documentation
spectral docs auth.spectral -o API.md

Examples

Complete Project Setup

# 1. Design specification
spectral chat --prompt "Design a todo application"

# 2. Validate design
spectral validate todo.spectral

# 3. Generate artifacts
spectral inference graphql todo.spectral -o schema.graphql
spectral inference prisma todo.spectral -o prisma/schema.prisma
spectral inference routes todo.spectral --framework react-router -o src/routes.tsx

# 4. Implement with AI
spectral implement todo.spectral --agent copilot

# 5. Generate documentation
spectral docs todo.spectral -o TODO_API.md

# 6. Generate E2E tests
spectral inference e2e todo.spectral -o tests/

Getting Help

# Show general help
spectral help

# Show command-specific help
spectral parse --help
spectral chat --help
spectral implement --help
spectral inference --help

# Show inference subcommand help
spectral inference graphql --help
spectral inference prisma --help

For more information, visit: https://github.com/aexol/spectral