Skip to main content

Saga CLI Reference

Complete reference guide for all Saga CLI commands, options, and flags.

Table of Contents​

Overview​

The Saga CLI provides comprehensive management for the Saga service discovery system. All commands can be executed via:

saga <command> [subcommand] [options]

Or using cargo during development:

cargo run -- <command> [subcommand] [options]

Command Structure​

Saga uses a hierarchical command structure:

saga
├── start/stop/restart/status/update
├── service
│   ├── register
│   ├── unregister
│   ├── list
│   ├── get
│   ├── health
│   ├── update
│   ├── heartbeat
│   ├── update-version
│   ├── check-updates
│   ├── rollback
│   ├── update-policy
│   └── history
├── resource
│   ├── create
│   ├── list
│   ├── get
│   ├── update
│   └── delete
├── lifecycle
│   ├── init
│   ├── start/stop/restart/status
│   ├── install
│   └── uninstall
├── config
│   ├── get
│   ├── set
│   ├── list
│   ├── validate
│   └── reset
├── backup
├── restore
├── debug
│   ├── redis
│   ├── cache
│   ├── services
│   ├── stats
│   └── test
├── generate
│   └── service
└── loadtest
    ├── service
    ├── all
    ├── mock
    ├── draining
    ├── overload
    └── schedule

Server Management​

Start Server​

Start the Saga HTTP server.

saga start [options]

Options:

  • --host <HOST> - Server host address (default: 0.0.0.0)
  • --port <PORT> - Server port number (default: 8030)
  • --redis-url <URL> - Redis connection URL (e.g., redis://localhost:6379)
  • --daemon - Run as background daemon process

Examples:

# Start with defaults
saga start

# Start on custom port
saga start --port 9000

# Start with custom Redis URL
saga start --redis-url redis://redis.example.com:6379

# Start as daemon
saga start --daemon

Aliases: up

Stop Server​

Stop the running Saga HTTP server.

saga stop

Examples:

saga stop

Aliases: down

Restart Server​

Restart the Saga HTTP server.

saga restart

Examples:

saga restart

Status​

Check Saga service status including health, registered services, Redis connection, and cache statistics.

saga status

Output includes:

  • Service health status
  • Redis connection status
  • Number of registered services
  • Cache statistics
  • Server uptime

Examples:

saga status

Update​

Rebuild, reinstall CLI globally, and restart service if running.

saga update

Examples:

saga update

Service Management​

Register Service​

Register a new service in the Saga service discovery system.

saga service register <NAME> <URL> [options]

Arguments:

  • NAME - Service name (unique identifier, required)
  • URL - Service URL (e.g., http://localhost:8000, required)

Options:

  • --capabilities <CAPS> - Service capabilities as comma-separated list (e.g., graphql,rest,mcp,grpc)

Examples:

# Register a basic REST service
saga service register payment-service http://localhost:8001

# Register with capabilities
saga service register gateway http://localhost:8000 --capabilities graphql,rest

# Register gRPC service
saga service register payment-rpc http://localhost:50051 --capabilities grpc

Unregister Service​

Remove a service from the Saga system.

saga service unregister <NAME>

Arguments:

  • NAME - Service name to unregister (required)

Examples:

saga service unregister payment-service

List Services​

List all services registered in the Saga system.

saga service list [options]

Examples:

# List all services in beautiful table format
saga service list

Note: All service management commands now use beautiful table formatting by default with colors and emojis for better readability. JSON format option has been removed in favor of consistent, visually appealing output.

Get Service​

Get detailed metadata for a specific service.

saga service get <NAME>

Arguments:

  • NAME - Service name to query (required)

Output includes:

  • Service name and URL
  • Capabilities
  • Registration timestamp
  • Last heartbeat timestamp
  • TTL expiration
  • Health status

Examples:

saga service get payment-service

Health Check​

Check if a service is healthy by calling its health endpoint.

saga service health <NAME>

Arguments:

  • NAME - Service name to check (required)

Exit codes:

  • 0 - Service is healthy
  • 1 - Service is unhealthy or unreachable
  • 2 - Service not found in registry

Examples:

saga service health payment-service

Update Service​

Update service registration metadata.

saga service update <NAME> [options]

Arguments:

  • NAME - Service name to update (required)

Options:

  • --url <URL> - New service URL
  • --capabilities <CAPS> - New capabilities as comma-separated list

Examples:

# Update service URL
saga service update payment-service --url http://localhost:8002

# Update capabilities
saga service update gateway --capabilities graphql,rest,grpc

Heartbeat​

Manually refresh service registration TTL (heartbeat).

saga service heartbeat <NAME>

Arguments:

  • NAME - Service name to refresh (required)

Examples:

saga service heartbeat payment-service

Update Management​

Saga provides comprehensive update management capabilities for services, including version tracking, update checking, rollback functionality, and update policy management. All update management commands use beautiful table formatting with colors and emojis for clear visual feedback.

Update Version​

Update a service to a new version manually.

saga service update-version <NAME> [options]

Arguments:

  • NAME - Service name to update (required)

Options:

  • --version <VERSION> - Target version to update to (optional, will check for latest if not provided)
  • --artifact-url <URL> - Artifact URL override (optional)
  • --artifact-type <TYPE> - Artifact type: binary, docker, archive (default: binary)
  • --checksum <CHECKSUM> - Checksum for artifact verification (optional, format: sha256:abc123...)

Examples:

# Update to latest version (checks for updates automatically)
saga service update-version payment-service

# Update to specific version
saga service update-version payment-service --version 1.2.3

# Update with custom artifact URL and checksum
saga service update-version payment-service \
  --version 1.2.3 \
  --artifact-url https://example.com/releases/payment-v1.2.3.tar.gz \
  --checksum sha256:abc123def456...

# Update Docker service
saga service update-version payment-service \
  --version 1.2.3 \
  --artifact-type docker \
  --artifact-url docker.io/payment-service:1.2.3

Output: The command displays a beautiful table showing:

  • ✅ Update status with emojis
  • Service name and version information
  • Update job ID for tracking
  • Artifact details (URL, type, checksum)
  • Timestamp of the update

Check Updates​

Check for available updates for one or all services.

saga service check-updates [NAME]

Arguments:

  • NAME - Service name (optional, checks all services if not provided)

Examples:

# Check updates for all services
saga service check-updates

# Check updates for specific service
saga service check-updates payment-service

Output: The command displays a beautiful table showing:

  • Service name and current version
  • Latest available version
  • Update availability status (✅ Available, ⏳ Up to date, ⚠️ Unknown)
  • Update policy
  • Last checked timestamp

Exit codes:

  • 0 - Check completed successfully
  • 1 - Error checking updates

Rollback​

Rollback a service to its previous version.

saga service rollback <NAME> [options]

Arguments:

  • NAME - Service name to rollback (required)

Options:

  • --yes - Skip confirmation prompt

Examples:

# Rollback with confirmation prompt
saga service rollback payment-service

# Rollback without confirmation
saga service rollback payment-service --yes

Output: The command displays:

  • ⚠️ Confirmation prompt (unless --yes is used)
  • ✅ Rollback status with emojis
  • Service name and version information
  • Previous version being restored
  • Rollback job ID for tracking
  • Timestamp of the rollback

Exit codes:

  • 0 - Rollback completed successfully
  • 1 - Rollback failed or no previous version available
  • 2 - User cancelled rollback (when confirmation prompt is shown)

Update Policy​

Set the update policy for a service.

saga service update-policy <NAME> <POLICY>

Arguments:

  • NAME - Service name (required)
  • POLICY - Update policy: auto, manual, scheduled, never (required)

Update Policies:

  • auto - Automatically update when new versions are available
  • manual - Require manual approval for updates
  • scheduled - Update on a schedule (configured separately)
  • never - Never update automatically

Examples:

# Set automatic update policy
saga service update-policy payment-service auto

# Set manual update policy
saga service update-policy payment-service manual

# Disable automatic updates
saga service update-policy payment-service never

Output: The command displays:

  • ✅ Success message with emoji
  • Service name
  • New update policy with color-coded formatting
  • Policy description

History​

View update history for a service.

saga service history <NAME> [options]

Arguments:

  • NAME - Service name (required)

Options:

  • --limit <N> - Limit number of entries to show (optional, default: all)

Examples:

# View all update history
saga service history payment-service

# View last 10 updates
saga service history payment-service --limit 10

# View last 5 updates
saga service history payment-service --limit 5

Output: The command displays a beautiful table showing:

  • Update job ID
  • Version information (from → to)
  • Update type (update, rollback)
  • Status (✅ Success, ❌ Failed, ⏳ In Progress)
  • Timestamp of each update
  • Duration of update operation
  • Artifact details (if available)

Table columns:

  • Job ID (formatted with emoji)
  • Version (color-coded)
  • Type (update/rollback)
  • Status (with emoji indicators)
  • Timestamp (formatted for readability)
  • Duration (human-readable format)

Resource Management​

Resources in Saga include services, endpoints, routes, policies, and cache entries.

Create Resource​

Create a new resource.

saga resource create <TYPE> <NAME> [options]

Arguments:

  • TYPE - Resource type: service, endpoint, route, policy, cache (required)
  • NAME - Resource name (required)

Options:

  • --data <JSON> - Resource data as JSON string
  • --format <FORMAT> - Output format: table or json (default: table)

Examples:

# Create endpoint resource
saga resource create endpoint payment-api --data '{"path":"/api/payment","method":"POST"}'

# Create policy resource
saga resource create policy rate-limit --data '{"max_requests":100,"window":"1m"}'

List Resources​

List all resources, optionally filtered by type.

saga resource list [TYPE] [options]

Arguments:

  • TYPE - Resource type filter (optional): service, endpoint, route, policy, cache

Options:

  • --format <FORMAT> - Output format: table or json (default: table)

Examples:

# List all resources
saga resource list

# List only endpoints
saga resource list endpoint

# JSON output
saga resource list --format json

Get Resource​

Get detailed information about a specific resource.

saga resource get <TYPE> <NAME> [options]

Arguments:

  • TYPE - Resource type (required)
  • NAME - Resource name (required)

Options:

  • --format <FORMAT> - Output format: table or json (default: table)

Examples:

saga resource get endpoint payment-api
saga resource get policy rate-limit --format json

Update Resource​

Update an existing resource.

saga resource update <TYPE> <NAME> [options]

Arguments:

  • TYPE - Resource type (required)
  • NAME - Resource name (required)

Options:

  • --data <JSON> - Updated resource data as JSON string
  • --format <FORMAT> - Output format: table or json (default: table)

Examples:

saga resource update policy rate-limit --data '{"max_requests":200,"window":"2m"}'

Delete Resource​

Delete a resource.

saga resource delete <TYPE> <NAME>

Arguments:

  • TYPE - Resource type (required)
  • NAME - Resource name (required)

Examples:

saga resource delete policy rate-limit

Lifecycle Management​

Initialize​

Initialize Saga configuration and directories.

saga lifecycle init [options]

Options:

  • --config-dir <PATH> - Configuration directory path (default: ~/.saga/)

What it does:

  • Creates config directory
  • Generates default config.toml file
  • Tests Redis connection
  • Validates configuration

Examples:

# Initialize with defaults
saga lifecycle init

# Initialize with custom config directory
saga lifecycle init --config-dir /etc/saga

Lifecycle Start/Stop/Restart/Status​

These commands work the same as the top-level server management commands but are accessible via the lifecycle subcommand.

saga lifecycle start [options]
saga lifecycle stop
saga lifecycle restart
saga lifecycle status

Install Service​

Install Saga as a systemd service (Linux) or launchd service (macOS) to auto-start on boot.

saga lifecycle install

Examples:

saga lifecycle install

What it does:

  • Installs service template based on OS (systemd/launchd)
  • Enables service to start on boot
  • Starts the service immediately

Uninstall Service​

Uninstall Saga systemd/launchd service.

saga lifecycle uninstall

Examples:

saga lifecycle uninstall

Configuration Management​

Get Configuration​

Get configuration value(s).

saga config get [KEY]

Arguments:

  • KEY - Configuration key (optional - shows all if not provided)

Examples:

# Get all configuration
saga config get

# Get specific key
saga config get redis_url
saga config get port

Set Configuration​

Set a configuration value.

saga config set <KEY> <VALUE>

Arguments:

  • KEY - Configuration key (required)
  • VALUE - Configuration value (required)

Examples:

saga config set redis_url redis://localhost:6379
saga config set port 8030
saga config set heartbeat_interval 60

List Configuration​

List all configuration values.

saga config list

Examples:

saga config list

Validate Configuration​

Validate the current configuration.

saga config validate

Examples:

saga config validate

Exit codes:

  • 0 - Configuration is valid
  • 1 - Configuration has errors

Reset Configuration​

Reset configuration to default values.

saga config reset

Examples:

saga config reset

Backup & Restore​

Backup​

Backup service registry to a file.

saga backup [PATH]

Arguments:

  • PATH - Backup file path (optional, default: ~/.saga/backups/registry-{timestamp}.json)

Examples:

# Backup with auto-generated filename
saga backup

# Backup to specific location
saga backup /tmp/saga-backup.json

Restore​

Restore service registry from a backup file.

saga restore <PATH>

Arguments:

  • PATH - Backup file path (required)

Examples:

saga restore ~/.saga/backups/registry-2024-01-15.json

Debug Commands​

Redis Command​

Execute a Redis command directly.

saga debug redis <COMMAND>

Arguments:

  • COMMAND - Redis command to execute (required)

Examples:

saga debug redis "KEYS *"
saga debug redis "GET saga:service:payment-service"
saga debug redis "INFO memory"

Cache​

Show cache contents.

saga debug cache

Examples:

saga debug cache

Services​

Show all service details in debug format.

saga debug services

Examples:

saga debug services

Stats​

Show statistics about the Saga service.

saga debug stats

Examples:

saga debug stats

Test Connection​

Test connection to a specific service.

saga debug test <NAME>

Arguments:

  • NAME - Service name to test (required)

Examples:

saga debug test payment-service

Service Generation​

Generate service registration code for different programming languages.

saga generate service <NAME> [options]

Arguments:

  • NAME - Service name (required)

Options:

  • --language <LANG> - Target language: rust, python, elixir, node (required)
  • --path <PATH> - Output path (optional, default: current directory)
  • --capabilities <CAPS> - Service capabilities as comma-separated list
  • --port <PORT> - Service port (optional, default: 8000)
  • --template <PATH> - Custom template directory
  • --redis-url <URL> - Redis URL for generated code
  • --saga-url <URL> - Saga service URL (default: http://localhost:8030)

Examples:

# Generate Rust service
saga generate service payment-service --language rust --port 8001

# Generate Python service with capabilities
saga generate service gateway --language python --capabilities graphql,rest --port 8000

# Generate Elixir service to custom path
saga generate service auth-service --language elixir --path ./services/auth

# Generate Node.js service with custom Redis URL
saga generate service notification --language node --redis-url redis://redis.example.com:6379

See Service Generation Guide for detailed information.

Load Testing​

Saga includes comprehensive load testing capabilities.

Test Single Service​

Run load test against a specific service.

saga loadtest service <NAME> [options]

Arguments:

  • NAME - Service name to test (required)

Options:

  • --concurrency <N> - Number of concurrent requests (default: 10)
  • --requests <N> - Total number of requests (default: 100)
  • --endpoint <PATH> - Endpoint path to test (default: /health)
  • --timeout <SECONDS> - Request timeout in seconds (default: 10)
  • --format <FORMAT> - Output format: table or json (default: table)

Examples:

# Basic load test
saga loadtest service payment-service

# Custom concurrency and requests
saga loadtest service gateway --concurrency 50 --requests 1000

# Test specific endpoint
saga loadtest service payment-service --endpoint /api/v1/status --concurrency 20

Test All Services​

Run load test against all registered services.

saga loadtest all [options]

Options: Same as service command

Examples:

saga loadtest all --concurrency 10 --requests 100

Mock Load Test​

Run mock load test with simulated responses (no real HTTP calls).

saga loadtest mock <NAME> [options]

Options:

  • --latency-ms <MS> - Simulated response latency in milliseconds (default: 50)
  • --error-rate <PERCENT> - Simulated error rate percentage 0-100 (default: 0)
  • Other options same as service command

Examples:

saga loadtest mock payment-service --latency-ms 100 --error-rate 5

Draining Test​

Run draining test that gradually reduces load over time.

saga loadtest draining <NAME> [options]

Options:

  • --initial-concurrency <N> - Initial concurrent requests (default: 100)
  • --final-concurrency <N> - Final concurrent requests (default: 0)
  • --duration <SECONDS> - Duration of draining phase (default: 60)
  • --initial-rps <N> - Requests per second at start (default: 100)
  • Other options same as service command

Examples:

saga loadtest draining payment-service --duration 120

Overload Test​

Run overload test to find breaking points.

saga loadtest overload <NAME> [options]

Options:

  • --start-concurrency <N> - Starting concurrent requests (default: 10)
  • --max-concurrency <N> - Maximum concurrent requests (default: 1000)
  • --increment <N> - Concurrency increment per step (default: 50)
  • --step-duration <SECONDS> - Duration per step (default: 10)
  • --error-threshold <PERCENT> - Error rate threshold to stop (default: 50)
  • Other options same as service command

Examples:

saga loadtest overload payment-service --max-concurrency 2000

Schedule Load Tests​

Schedule load tests to run at specific times.

Create Schedule​

saga loadtest schedule create <NAME> [options]

Arguments:

  • NAME - Schedule name/ID (required)

Options:

  • --test-type <TYPE> - Test type: service, all, mock, draining, overload (required)
  • --service-name <NAME> - Service name (required for service, draining, overload)
  • <SCHEDULE> - Cron expression or ISO 8601 datetime (required)
  • --concurrency <N> - Number of concurrent requests
  • --requests <N> - Total number of requests
  • --endpoint <PATH> - Endpoint path
  • --timeout <SECONDS> - Request timeout
  • --format <FORMAT> - Output format
  • --params <JSON> - Additional test-specific parameters as JSON

Examples:

# Schedule daily load test at midnight
saga loadtest schedule create daily-test --test-type service \
  --service-name payment-service "0 0 * * *" --concurrency 50 --requests 1000

# Schedule one-time test for specific datetime
saga loadtest schedule create maintenance-test --test-type all \
  "2024-12-25T02:00:00Z" --concurrency 10 --requests 100

List Schedules​

saga loadtest schedule list [options]

Options:

  • --format <FORMAT> - Output format: table or json (default: table)

Examples:

saga loadtest schedule list

Get Schedule​

saga loadtest schedule get <NAME> [options]

Examples:

saga loadtest schedule get daily-test

Delete Schedule​

saga loadtest schedule delete <NAME>

Examples:

saga loadtest schedule delete daily-test

Run Scheduled Tests​

Run scheduled tests that are due now.

saga loadtest schedule run [options]

Options:

  • --dry-run - Show what would run without executing

Examples:

# Run due tests
saga loadtest schedule run

# Preview what would run
saga loadtest schedule run --dry-run

Aliases: loti (for loadtest)

Exit Codes​

Saga CLI uses standard exit codes:

  • 0 - Success
  • 1 - General error or command failure
  • 2 - Invalid arguments or configuration
  • 3 - Service not found
  • 4 - Connection error (Redis, HTTP, etc.)
  • 5 - Validation error

Error Handling​

Common Errors​

Connection Errors:

Error: Failed to connect to Redis: Connection refused

Solution: Ensure Redis is running and accessible at the configured URL.

Service Not Found:

Error: Service 'payment-service' not found

Solution: Register the service first using saga service register.

Invalid Configuration:

Error: Invalid configuration: missing redis_url

Solution: Set configuration using saga config set redis_url <URL> or environment variable.

Debugging​

Use debug commands to troubleshoot issues:

# Check Redis connection
saga debug redis "PING"

# View cache contents
saga debug cache

# Test service connection
saga debug test payment-service

# View statistics
saga debug stats

Getting Help​

All commands support --help flag:

saga --help
saga service --help
saga service register --help

Logging​

Enable verbose logging by setting environment variable:

RUST_LOG=debug saga start

Log levels: error, warn, info, debug, trace