Skip to content

Command-Line Interface

Complete reference for StrataRouter CLI commands and utilities.

Installation

# Install from PyPI
pip install stratarouter

# Install with runtime
pip install stratarouter[runtime]

# Install from source
git clone https://github.com/stratarouter/stratarouter
cd stratarouter
pip install -e .

Core Commands

stratarouter init

Initialize a new StrataRouter project with configuration files.

stratarouter init [OPTIONS] [PATH]

Arguments:

  • PATH - Project directory (default: current directory)

Options:

  • --template TEMPLATE - Project template (basic|advanced|production)
  • --with-runtime - Include runtime configuration
  • --with-examples - Include example routes
  • --force - Overwrite existing files

Examples:

# Basic initialization
stratarouter init

# Advanced project with runtime
stratarouter init my-project --template advanced --with-runtime

# Production setup
stratarouter init --template production --force

stratarouter validate

Validate route configurations and check for errors.

stratarouter validate [OPTIONS] CONFIG_FILE

Arguments:

  • CONFIG_FILE - Path to configuration file

Options:

  • --strict - Enable strict validation mode
  • --fix - Auto-fix common issues
  • --output FORMAT - Output format (text|json|yaml)

Examples:

# Validate configuration
stratarouter validate routes.yaml

# Strict validation with JSON output
stratarouter validate --strict --output json routes.yaml

stratarouter build

Build and optimize route indices.

stratarouter build [OPTIONS] CONFIG_FILE

Options:

  • --embeddings FILE - Precomputed embeddings file
  • --model MODEL - Embedding model name
  • --optimize - Enable optimization
  • --output FILE - Output index file
  • --workers N - Number of parallel workers

Examples:

# Build index from config
stratarouter build routes.yaml

# Build with custom embeddings
stratarouter build routes.yaml --embeddings embeddings.npy

# Optimized build with 8 workers
stratarouter build routes.yaml --optimize --workers 8

Runtime Commands

stratarouter-runtime serve

Start the StrataRouter runtime server.

stratarouter-runtime serve [OPTIONS]

Options:

  • --host HOST - Server host (default: 0.0.0.0)
  • --port PORT - Server port (default: 8080)
  • --workers N - Number of worker processes
  • --config FILE - Configuration file
  • --reload - Enable auto-reload (development)
  • --log-level LEVEL - Logging level
  • --tls-cert FILE - TLS certificate
  • --tls-key FILE - TLS private key

Examples:

# Start server on default port
stratarouter-runtime serve

# Production server with 16 workers
stratarouter-runtime serve --workers 16 --log-level info

# Development server with auto-reload
stratarouter-runtime serve --reload --log-level debug

# HTTPS server
stratarouter-runtime serve --tls-cert cert.pem --tls-key key.pem

stratarouter-runtime health

Check runtime server health status.

stratarouter-runtime health [OPTIONS]

Options:

  • --url URL - Server URL (default: http://localhost:8080)
  • --timeout SECONDS - Request timeout
  • --verbose - Show detailed health info

Examples:

# Check health
stratarouter-runtime health

# Check with details
stratarouter-runtime health --verbose

# Check custom endpoint
stratarouter-runtime health --url https://prod.example.com

Benchmarking

stratarouter bench

Run performance benchmarks.

stratarouter bench [OPTIONS] CONFIG_FILE

Options:

  • --queries FILE - Test queries file
  • --iterations N - Number of iterations (default: 1000)
  • --concurrency N - Concurrent requests (default: 10)
  • --output FILE - Save results to file
  • --compare BASELINE - Compare with baseline results

Examples:

# Basic benchmark
stratarouter bench routes.yaml

# High-concurrency test
stratarouter bench routes.yaml --iterations 10000 --concurrency 100

# Compare with baseline
stratarouter bench routes.yaml --compare baseline.json --output results.json

Testing

stratarouter test

Run route testing suite.

stratarouter test [OPTIONS] CONFIG_FILE

Options:

  • --test-file FILE - Test cases file
  • --coverage - Generate coverage report
  • --verbose - Show detailed test output
  • --fail-fast - Stop on first failure

Examples:

# Run all tests
stratarouter test routes.yaml

# Run with coverage
stratarouter test routes.yaml --coverage

# Verbose output
stratarouter test routes.yaml --verbose --fail-fast

Migration & Export

stratarouter export

Export routes to various formats.

stratarouter export [OPTIONS] CONFIG_FILE OUTPUT

Options:

  • --format FORMAT - Export format (json|yaml|python|typescript)
  • --include-embeddings - Include embedding vectors
  • --compress - Compress output

Examples:

# Export to JSON
stratarouter export routes.yaml routes.json --format json

# Export with embeddings
stratarouter export routes.yaml routes.json --include-embeddings

stratarouter import

Import routes from external sources.

stratarouter import [OPTIONS] SOURCE OUTPUT

Options:

  • --from FORMAT - Source format (semantic-router|llama-index|haystack)
  • --mapping FILE - Field mapping file
  • --validate - Validate after import

Examples:

# Import from semantic-router
stratarouter import old-routes.yaml routes.yaml --from semantic-router

# Import with validation
stratarouter import source.json routes.yaml --validate

Monitoring

stratarouter monitor

Real-time monitoring dashboard (terminal UI).

stratarouter monitor [OPTIONS]

Options:

  • --url URL - Runtime server URL
  • --refresh SECONDS - Refresh interval (default: 1)
  • --metrics METRICS - Metrics to display (comma-separated)

Examples:

# Monitor local server
stratarouter monitor

# Monitor production server
stratarouter monitor --url https://prod.example.com --refresh 5

stratarouter logs

Stream and filter runtime logs.

stratarouter logs [OPTIONS]

Options:

  • --follow - Follow log output
  • --level LEVEL - Filter by log level
  • --filter PATTERN - Filter by pattern
  • --since TIME - Show logs since time
  • --tail N - Show last N lines

Examples:

# Follow logs
stratarouter logs --follow

# Show errors only
stratarouter logs --level error --tail 100

# Filter by pattern
stratarouter logs --filter "routing" --since "1 hour ago"

Diagnostics

stratarouter doctor

Diagnose common issues and check system requirements.

stratarouter doctor [OPTIONS]

Options:

  • --fix - Attempt to fix issues automatically
  • --verbose - Show detailed diagnostic info
  • --check-all - Run all diagnostic checks

Examples:

# Run diagnostics
stratarouter doctor

# Auto-fix issues
stratarouter doctor --fix

# Detailed diagnostics
stratarouter doctor --verbose --check-all

stratarouter version

Display version information.

stratarouter version [OPTIONS]

Options:

  • --verbose - Show detailed version info
  • --check-updates - Check for available updates

Examples:

# Show version
stratarouter version

# Detailed version info
stratarouter version --verbose

# Check for updates
stratarouter version --check-updates

Configuration Management

stratarouter config

Manage configuration files.

stratarouter config [SUBCOMMAND] [OPTIONS]

Subcommands:

  • show - Display current configuration
  • validate - Validate configuration file
  • migrate - Migrate configuration to new version
  • generate - Generate configuration template

Examples:

# Show current config
stratarouter config show

# Validate config
stratarouter config validate --file config.yaml

# Generate template
stratarouter config generate --template production > config.yaml

Development Utilities

stratarouter dev

Development utilities and helpers.

stratarouter dev [SUBCOMMAND] [OPTIONS]

Subcommands:

  • serve - Start development server with hot-reload
  • profile - Profile route performance
  • analyze - Analyze route coverage and accuracy

Examples:

# Development server
stratarouter dev serve --reload

# Profile routes
stratarouter dev profile routes.yaml --queries test-queries.txt

# Analyze coverage
stratarouter dev analyze routes.yaml --test-file tests.yaml

Global Options

Available for all commands:

  • --help, -h - Show help message
  • --version, -V - Show version
  • --verbose, -v - Increase verbosity
  • --quiet, -q - Suppress output
  • --config FILE - Custom config file
  • --no-color - Disable colored output

Environment Variables

CLI commands respect these environment variables:

  • STRATAROUTER_HOME - Base directory for configs
  • STRATAROUTER_LOG_LEVEL - Default log level
  • STRATAROUTER_RUNTIME_URL - Default runtime URL
  • NO_COLOR - Disable colored output

Shell Completion

Generate shell completion scripts:

# Bash
stratarouter completion bash > ~/.stratarouter-completion.bash
echo 'source ~/.stratarouter-completion.bash' >> ~/.bashrc

# Zsh
stratarouter completion zsh > ~/.zsh/completion/_stratarouter

# Fish
stratarouter completion fish > ~/.config/fish/completions/stratarouter.fish

Exit Codes

  • 0 - Success
  • 1 - General error
  • 2 - Configuration error
  • 3 - Validation error
  • 4 - Runtime error
  • 5 - Network error

Examples

Complete Workflow

# 1. Initialize project
stratarouter init my-router --template production

# 2. Validate configuration
cd my-router
stratarouter validate routes.yaml

# 3. Build index
stratarouter build routes.yaml --optimize

# 4. Run tests
stratarouter test routes.yaml --coverage

# 5. Start runtime
stratarouter-runtime serve --workers 8

# 6. Monitor (in another terminal)
stratarouter monitor --refresh 2

CI/CD Integration

#!/bin/bash
# ci-test.sh

set -e

# Validate
stratarouter validate routes.yaml --strict

# Build
stratarouter build routes.yaml --output index.bin

# Test
stratarouter test routes.yaml --coverage

# Benchmark
stratarouter bench routes.yaml --iterations 1000 --output benchmark.json

Next Steps