Overview

The firestone CLI provides commands to generate various outputs from resource definitions. This reference covers all commands, global options, and generator-specific options.

Command Structure

firestone [GLOBAL_OPTIONS] generate [GENERATE_OPTIONS] <generator> [GENERATOR_OPTIONS]

Global Options

These options apply to all firestone commands:

Generate Command

The main command for generating outputs from resource definitions.

Syntax

firestone generate [OPTIONS] <generator>

Common Options

Generators

Firestone supports four generators: openapi, asyncapi, cli, and streamlit.

OpenAPI Generator

Generate OpenAPI 3.0.0 specifications from resources.

Syntax

firestone generate --resources <path> [OPTIONS] openapi [OPENAPI_OPTIONS]

Options

Examples

Basic generation:

firestone generate \
  --resources resources/ \
  --title "My API" \
  openapi > openapi.yaml

With servers and version:

firestone generate \
  --resources user.yaml \
  --title "User API" \
  --description "User management system" \
  --version "2.1.0" \
  openapi \
  --server https://api.example.com \
  --server https://api-staging.example.com \
  > openapi.yaml

With Swagger UI:

firestone generate \
  --resources resources/ \
  --title "My API" \
  openapi \
  --ui-server \
  --ui-port 8080

This opens Swagger UI at http://localhost:8080/apidocs.

Output

Generates OpenAPI 3.0.0 YAML with:

• Complete path definitions (resource and instance endpoints)
• Request/response schemas
• Query parameters
• Security schemes
• Server configurations

AsyncAPI Generator

Generate AsyncAPI 2.5.0 specifications for event-driven APIs.

Syntax

firestone generate --resources <path> [OPTIONS] asyncapi [ASYNCAPI_OPTIONS]

Options

Examples

WebSocket API:

firestone generate \
  --resources message.yaml \
  --title "Chat API" \
  asyncapi \
  --protocol wss \
  --server wss://chat.example.com > asyncapi.yaml

HTTP streaming:

firestone generate \
  --resources events.yaml \
  --title "Event Stream" \
  asyncapi \
  --protocol https \
  --server https://events.example.com > asyncapi.yaml

Output

Generates AsyncAPI 2.5.0 YAML with:

• Channel definitions
• Message schemas
• Subscribe/publish operations
• Server and protocol bindings

CLI Generator

Generate Python Click-based command-line interfaces.

Syntax

firestone generate --resources <path> [OPTIONS] cli [CLI_OPTIONS]

Options

Examples

Generate CLI:

firestone generate \
  --resources user.yaml \
  --title "User CLI" \
  cli \
  --pkg myapp_cli \
  --client-pkg myapp_client > cli.py

Multi-resource CLI:

firestone generate \
  --resources resources/ \
  --title "Management CLI" \
  cli \
  --pkg management \
  --client-pkg api_client > management_cli.py

Output

Generates Python file with:

• Click CLI application
• CRUD commands (list, get, create, update, delete)
• JSON output formatting
• Error handling
• Integration with API client

Generated Commands

For a resource named users:

python cli.py users list              # List all users
python cli.py users get <user_id>     # Get specific user
python cli.py users create <json>     # Create user
python cli.py users update <id> <json> # Update user
python cli.py users delete <user_id>  # Delete user

Streamlit Generator

Generate Streamlit data applications for CRUD operations.

Syntax

firestone generate --resources <path> [OPTIONS] streamlit [STREAMLIT_OPTIONS]

Options

Examples

Generate Streamlit app:

firestone generate \
  --resources product.yaml \
  --title "Product Manager" \
  streamlit \
  --backend-url http://localhost:8000 > app.py

Multi-resource dashboard:

firestone generate \
  --resources resources/ \
  --title "Admin Dashboard" \
  streamlit \
  --backend-url https://api.example.com > dashboard.py

Output

Generates Python Streamlit application with:

• Sidebar navigation
• List/table view
• Create form
• Edit form
• Delete confirmation
• API integration

Running Generated App

streamlit run app.py

Opens at http://localhost:8501.

Multiple Resources

All generators support multiple resources via:

Directory of resource files:

firestone generate --resources resources/ openapi

Multiple file arguments:

firestone generate \
  --resources user.yaml \
  --resources product.yaml \
  --resources order.yaml \
  openapi

Glob patterns (shell expansion):

firestone generate --resources resources/*.yaml openapi

Output Redirection

All generators output to stdout by default. Redirect to files:

# Redirect stdout
firestone generate --resources user.yaml openapi > spec.yaml

# Use --output flag
firestone generate --resources user.yaml --output spec.yaml openapi

# Pipe to other commands
firestone generate --resources user.yaml openapi | spectral lint -

Environment Variables

Firestone respects these environment variables:

Exit Codes

Common Patterns

Generate All Outputs

# Generate OpenAPI spec
firestone generate -r resources/ -t "My API" openapi > openapi.yaml

# Generate AsyncAPI spec
firestone generate -r resources/ -t "My API" asyncapi > asyncapi.yaml

# Generate CLI
firestone generate -r resources/ -t "My API" cli --pkg myapi --client-pkg myapi_client > cli.py

# Generate Streamlit UI
firestone generate -r resources/ -t "My API" streamlit --backend-url http://localhost:8000 > app.py

CI/CD Integration

#!/bin/bash
set -e

# Generate spec
firestone generate \
  --resources resources/ \
  --title "${API_TITLE}" \
  --version "${GIT_SHA}" \
  openapi > openapi.yaml

# Validate
spectral lint openapi.yaml

# Generate clients
openapi-generator generate -i openapi.yaml -g python -o client/

Development Workflow

# Watch for changes and regenerate
while inotifywait -e modify resources/*.yaml; do
  firestone generate -r resources/ -t "Dev API" openapi --ui-server
done

Getting Help

Command help:

firestone --help
firestone generate --help
firestone generate openapi --help

Version information:

firestone --version

Debug output:

firestone --debug generate --resources user.yaml openapi

See Also

• Quickstart Tutorial - First steps with firestone
• Resource Schema Reference - YAML structure reference
• Examples - Complete working examples
• Best Practices - Recommended patterns