Hero Supervisor CLI Example

This example demonstrates how to use the hive-supervisor CLI tool for managing workers and jobs in the Hero ecosystem.

Prerequisites

Redis Server: Make sure Redis is running on localhost:6379

# Install Redis (macOS)
brew install redis

# Start Redis
redis-server

Zinit Process Manager: Install and configure Zinit

# Install Zinit (example for Linux/macOS)
# Follow Zinit installation instructions for your platform

Worker Binaries: The configuration references worker binaries that need to be available:
- /usr/local/bin/osis_worker
- /usr/local/bin/sal_worker
- /usr/local/bin/v_worker
- /usr/local/bin/python_worker
For testing purposes, you can create mock worker binaries or update the paths in config.toml to point to existing binaries.

Configuration

The config.toml file contains the supervisor configuration:

Global settings: Redis URL and Zinit socket path
Worker configurations: Binary paths and environment variables for each worker type

Usage Examples

1. Build the CLI

# From the supervisor directory
cargo build --bin hive-supervisor --release

2. Worker Management

# Show help
./target/release/hive-supervisor --config examples/cli/config.toml --help

# List all configured workers
./target/release/hive-supervisor --config examples/cli/config.toml workers list

# Start all workers
./target/release/hive-supervisor --config examples/cli/config.toml workers start

# Start specific workers
./target/release/hive-supervisor --config examples/cli/config.toml workers start osis_worker sal_worker

# Check worker status
./target/release/hive-supervisor --config examples/cli/config.toml workers status

# Stop all workers
./target/release/hive-supervisor --config examples/cli/config.toml workers stop

# Restart specific worker
./target/release/hive-supervisor --config examples/cli/config.toml workers restart osis_worker

3. Job Management

# Create a job with inline script
./target/release/hive-supervisor --config examples/cli/config.toml jobs create \
  --script 'print("Hello from OSIS worker!");' \
  --script-type osis \
  --caller-id "user123" \
  --context-id "session456"

# Create a job from file
./target/release/hive-supervisor --config examples/cli/config.toml jobs create \
  --file examples/cli/sample_script.rhai \
  --script-type osis \
  --caller-id "user123" \
  --context-id "session456"

# List all jobs
./target/release/hive-supervisor --config examples/cli/config.toml jobs list

# Check job status
./target/release/hive-supervisor --config examples/cli/config.toml jobs status <JOB_ID>

# View job logs
./target/release/hive-supervisor --config examples/cli/config.toml jobs logs <JOB_ID>

# Stop a job
./target/release/hive-supervisor --config examples/cli/config.toml jobs stop <JOB_ID>

4. Interactive REPL Mode

# Enter REPL mode for OSIS scripts
./target/release/hive-supervisor --config examples/cli/config.toml repl \
  --caller-id "user123" \
  --context-id "session456" \
  --script-type osis \
  --timeout 60

# In REPL mode, you can:
# - Type scripts directly and press Enter to execute
# - Type 'help' for available commands
# - Type 'exit' or 'quit' to leave REPL mode

5. Verbose Logging

# Enable debug logging
./target/release/hive-supervisor --config examples/cli/config.toml -v workers status

# Enable trace logging
./target/release/hive-supervisor --config examples/cli/config.toml -vv workers status

# Disable timestamps
./target/release/hive-supervisor --config examples/cli/config.toml --no-timestamp workers status

Sample Scripts

The sample_scripts/ directory contains example scripts for different worker types:

hello_osis.rhai - Simple OSIS/HeroScript example
system_sal.rhai - SAL system operation example
math_v.v - V language calculation example
data_python.py - Python data processing example

Troubleshooting

Common Issues

Redis Connection Error
- Ensure Redis is running: redis-cli ping
- Check the Redis URL in config.toml
Zinit Socket Error
- Verify Zinit is running and the socket path is correct
- Check permissions on the socket file
Worker Binary Not Found
- Update binary paths in config.toml to match your system
- Ensure worker binaries are executable
Permission Denied
- Check file permissions on configuration and binary files
- Ensure the user has access to the Zinit socket

Debug Mode

Run with verbose logging to see detailed operation information:

RUST_LOG=debug ./target/release/hive-supervisor --config examples/cli/config.toml -vv workers status

Configuration Customization

You can customize the configuration for your environment:

Update Redis URL: Change redis_url in the [global] section
Update Zinit Socket: Change zinit_socket_path for your Zinit installation
Worker Paths: Update binary paths in worker sections to match your setup
Environment Variables: Add or modify environment variables for each worker type

Integration with Hero Ecosystem

This CLI integrates with the broader Hero ecosystem:

Job Queue: Uses Redis for job queuing and status tracking
Process Management: Uses Zinit for worker lifecycle management
Script Execution: Supports multiple script types (OSIS, SAL, V, Python)
Monitoring: Provides real-time status and logging capabilities

For more information about the Hero ecosystem, see the main project documentation.

5.5 KiB Raw Blame History