Skip to main content

CLI Command Reference

A detailed reference of all available Artisan commands and options in Laravel Spectrum.

📋 Command List​

CommandDescription
spectrum:generateGenerate OpenAPI documentation
spectrum:generate:optimizedOptimized generation (for large projects)
spectrum:watchReal-time preview mode
spectrum:mockLaunch mock API server
spectrum:export:postmanExport to Postman collection
spectrum:export:insomniaExport to Insomnia workspace
spectrum:sdkGenerate typed SDK client code
spectrum:validateValidate OpenAPI spec compliance
spectrum:diffCompare two OpenAPI specs and detect breaking changes
spectrum:version-compareAlias of spectrum:diff with migration-focused reporting
spectrum:cacheManage cache (clear, stats, warm)

🔧 spectrum:generate​

The basic command to generate API documentation.

Usage​

php artisan spectrum:generate [options]

Options​

OptionDefaultDescription
--outputstorage/app/spectrum/openapi.jsonOutput file path
--formatjsonOutput format (json/yaml/html)
--no-cachefalseDon't use cache
--clear-cachefalseClear cache before generation
--fail-on-errorfalseStop execution on first error
--ignore-errorsfalseContinue generation ignoring errors
--error-reportnoneSave error report to file
--viewerswagger-uiHTML viewer (swagger-ui/elements/scalar/rapidoc)
--no-try-it-outfalseDisable "Try It Out" feature in HTML output

Examples​

# Basic generation
php artisan spectrum:generate

# Output in YAML format
php artisan spectrum:generate --format=yaml --output=docs/api.yaml

# Output in HTML format (with Swagger UI)
php artisan spectrum:generate --format=html --output=docs/api.html

# Output in HTML format with Stoplight Elements
php artisan spectrum:generate --format=html --viewer=elements --output=docs/api-elements.html

# Output in HTML format with Scalar
php artisan spectrum:generate --format=html --viewer=scalar --output=docs/api-scalar.html

# Output in HTML format with RapiDoc
php artisan spectrum:generate --format=html --viewer=rapidoc --output=docs/api-rapidoc.html

# Clear cache and regenerate
php artisan spectrum:generate --clear-cache

# Generate without using cache
php artisan spectrum:generate --no-cache

# Stop on error
php artisan spectrum:generate --fail-on-error

# Ignore errors and continue
php artisan spectrum:generate --ignore-errors

# Save error report
php artisan spectrum:generate --error-report=storage/spectrum-errors.json

# Generate with verbose output
php artisan spectrum:generate -vvv

⚡ spectrum:generate:optimized​

Optimized generation command for large projects.

Usage​

php artisan spectrum:generate:optimized [options]

Options​

OptionDefaultDescription
--formatjsonOutput format (json/yaml)
--outputstorage/app/spectrum/openapi.jsonOutput file path
--parallelfalseEnable parallel processing
--workersnoneNumber of parallel workers
--chunk-sizeautoNumber of routes processed per chunk
--memory-limitnoneMemory limit override (example: 1G)
--incrementalfalseProcess only changed files

Examples​

# Generate with automatic optimization
php artisan spectrum:generate:optimized

# Enable parallel processing
php artisan spectrum:generate:optimized --parallel

# Parallel processing with 8 workers
php artisan spectrum:generate:optimized --parallel --workers=8

# Adjust memory and chunk size
php artisan spectrum:generate:optimized --memory-limit=1G --chunk-size=50

# Incremental generation
php artisan spectrum:generate:optimized --incremental

# Output in YAML format
php artisan spectrum:generate:optimized --format=yaml

# Generate with verbose output
php artisan spectrum:generate:optimized -v

✅ spectrum:validate​

Validate an OpenAPI document for structural compliance and best-practice warnings.

Usage​

php artisan spectrum:validate [path] [options]

Options​

OptionDefaultDescription
pathstorage/app/spectrum/openapi.jsonOpenAPI file path (json/yaml)
--generatefalseGenerate spec first, then validate
--strictfalseTreat warnings as errors
--formattextOutput format (text/json/junit)

Examples​

# Validate existing JSON spec
php artisan spectrum:validate storage/app/spectrum/openapi.json

# Generate and validate in one step
php artisan spectrum:validate --generate

# Fail CI when warnings exist
php artisan spectrum:validate --strict

# Machine-readable outputs
php artisan spectrum:validate --format=json
php artisan spectrum:validate --format=junit

🔍 spectrum:diff​

Compare two OpenAPI documents and highlight breaking changes.

Usage​

php artisan spectrum:diff [from] [to] [options]

Options​

OptionDefaultDescription
fromnoneBaseline OpenAPI file path (json/yaml)
tononeTarget OpenAPI file path (json/yaml)
--againstnoneCompare against last, a git ref, or a file path
--breaking-onlyfalseShow only breaking changes
--migration-guidefalseShow endpoint mappings and migration coverage (v1 → v2)
--formattextOutput format (text/json)

Examples​

# Compare two explicit files
php artisan spectrum:diff docs/openapi-v1.json docs/openapi-v2.json

# Compare current generated spec against the last snapshot
php artisan spectrum:diff --against=last

# Compare a spec file against the same path in main branch
php artisan spectrum:diff docs/openapi.json --against=main

# Only show breaking changes
php artisan spectrum:diff docs/openapi-v1.json docs/openapi-v2.json --breaking-only

# CI-friendly output
php artisan spectrum:diff docs/openapi-v1.json docs/openapi-v2.json --format=json

# Version-to-version migration report
php artisan spectrum:version-compare docs/openapi-v1.json docs/openapi-v2.json --migration-guide

# JSON report with migration coverage data
php artisan spectrum:version-compare docs/openapi-v1.json docs/openapi-v2.json --migration-guide --format=json

👁️ spectrum:watch​

Watch file changes and update documentation in real-time.

Usage​

php artisan spectrum:watch [options]

Options​

OptionDefaultDescription
--port8080Preview server port
--host127.0.0.1Preview server host
--no-openfalseDon't open browser automatically

Examples​

# Basic usage
php artisan spectrum:watch

# Launch on custom port
php artisan spectrum:watch --port=3000

# Launch without opening browser
php artisan spectrum:watch --no-open

# Make externally accessible
php artisan spectrum:watch --host=0.0.0.0

🎭 spectrum:mock​

Launch a mock API server based on OpenAPI documentation.

Usage​

php artisan spectrum:mock [options]

Options​

OptionDefaultDescription
--host127.0.0.1Host address to bind
--port8081Port number to listen on
--specstorage/app/spectrum/openapi.jsonPath to OpenAPI specification file
--delaynoneResponse delay (milliseconds)
--scenariosuccessDefault response scenario

Examples​

# Basic launch
php artisan spectrum:mock

# Custom port and host
php artisan spectrum:mock --host=0.0.0.0 --port=3000

# Add response delay
php artisan spectrum:mock --delay=500

# Set error scenario as default
php artisan spectrum:mock --scenario=error

# Custom OpenAPI file
php artisan spectrum:mock --spec=docs/custom-api.json

📤 spectrum:export:postman​

Export API documentation as a Postman collection.

Usage​

php artisan spectrum:export:postman [options]

Options​

OptionDefaultDescription
--outputstorage/app/spectrum/postmanOutput directory
--environmentslocalEnvironments to export (comma-separated)
--single-filefalseExport as a single file with embedded environments

Examples​

# Basic export
php artisan spectrum:export:postman

# Custom output location
php artisan spectrum:export:postman --output=postman/

# Export multiple environments
php artisan spectrum:export:postman --environments=local,staging,production

# Export as single file
php artisan spectrum:export:postman --single-file

🦊 spectrum:export:insomnia​

Export API documentation as an Insomnia workspace.

Usage​

php artisan spectrum:export:insomnia [options]

Options​

OptionDefaultDescription
--outputstorage/app/spectrum/insomnia/insomnia_collection.jsonOutput file path

Examples​

# Basic export
php artisan spectrum:export:insomnia

# Custom output location (file path)
php artisan spectrum:export:insomnia --output=insomnia/api.json

# Custom output location (directory)
php artisan spectrum:export:insomnia --output=insomnia/

🧩 spectrum:sdk​

Generate type-safe SDK client code from an OpenAPI specification.

Usage​

php artisan spectrum:sdk {language} [options]

Options​

OptionDefaultDescription
languagerequiredTarget language (typescript, swift, kotlin)
--specauto-generatePath to OpenAPI specification file
--outputfrom config/spectrum.phpOutput directory
--generatoropenapi-generatorSDK generator (openapi-generator, openapi-typescript, kiota)
--package-namenonePackage/namespace name override
--dry-runfalseShow command without executing it

Examples​

# Generate TypeScript SDK with default settings
php artisan spectrum:sdk typescript

# Generate Swift SDK to a custom directory
php artisan spectrum:sdk swift --output=sdk/swift

# Generate Kotlin SDK from an existing spec
php artisan spectrum:sdk kotlin --spec=docs/openapi.json --output=sdk/kotlin

# Use openapi-typescript generator explicitly
php artisan spectrum:sdk typescript --generator=openapi-typescript --output=sdk/typescript

# Override package name
php artisan spectrum:sdk typescript --package-name=@myapp/api-client

🗑️ spectrum:cache​

Manage Laravel Spectrum cache (clear, show statistics, or warm up).

Usage​

php artisan spectrum:cache {action}

Actions​

ActionDescription
clearClear all cached documentation
statsShow cache statistics (size, files, etc.)
warmClear and regenerate cache

Examples​

# Clear all cache
php artisan spectrum:cache clear

# Show cache statistics
php artisan spectrum:cache stats

# Warm up cache (clear and regenerate)
php artisan spectrum:cache warm

🔍 Global Options​

Laravel global options available for all commands:

OptionShortDescription
--help-hShow help
--quiet-qSuppress output
--verbose-v/-vv/-vvvIncrease verbosity
--version-VDisplay version
--ansiForce ANSI output
--no-ansiDisable ANSI output
--no-interaction-nDon't ask interactive questions
--envSpecify environment

💡 Useful Tips​

Setting Aliases​

# Add to ~/.bashrc or ~/.zshrc
alias specgen="php artisan spectrum:generate"
alias specwatch="php artisan spectrum:watch"
alias specmock="php artisan spectrum:mock"

Using Makefile​

# Makefile
.PHONY: docs docs-watch docs-mock

docs:
	php artisan spectrum:generate

docs-watch:
	php artisan spectrum:watch

docs-mock:
	php artisan spectrum:mock

docs-export:
	php artisan spectrum:export:postman --environments=local
	php artisan spectrum:export:insomnia
	php artisan spectrum:sdk typescript --output=sdk/typescript

Integration with npm scripts​

{
  "scripts": {
    "api:docs": "php artisan spectrum:generate",
    "api:watch": "php artisan spectrum:watch",
    "api:mock": "php artisan spectrum:mock",
    "dev": "concurrently \"npm run api:mock\" \"npm run serve\""
  }
}

📚 Related Documentation​