baobab/core/supervisor/examples/cli/README.md

Hero Supervisor CLI Example

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

Prerequisites

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

   # Install Redis (macOS)
   brew install redis
   
   # Start Redis
   redis-server
   

2. Zinit Process Manager: Install and configure Zinit

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

3. Actor Binaries: The configuration references actor binaries that need to be available:

   • /usr/local/bin/osis_actor
   • /usr/local/bin/sal_actor
   • /usr/local/bin/v_actor
   • /usr/local/bin/python_actor

   For testing purposes, you can create mock actor 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
• Actor configurations: Binary paths and environment variables for each actor type

Usage Examples

1. Build the CLI

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

2. Actor Management

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

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

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

# Start specific actors
./target/release/hive-supervisor --config examples/cli/config.toml actors start osis_actor sal_actor

# Check actor status
./target/release/hive-supervisor --config examples/cli/config.toml actors status

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

# Restart specific actor
./target/release/hive-supervisor --config examples/cli/config.toml actors restart osis_actor

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 actor!");' \
  --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 actors status

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

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

Sample Scripts

The sample_scripts/ directory contains example scripts for different actor 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

1. Redis Connection Error

   • Ensure Redis is running: redis-cli ping
   • Check the Redis URL in config.toml

2. Zinit Socket Error

   • Verify Zinit is running and the socket path is correct
   • Check permissions on the socket file

3. Actor Binary Not Found

   • Update binary paths in config.toml to match your system
   • Ensure actor binaries are executable

4. 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 actors status

Configuration Customization

You can customize the configuration for your environment:

1. Update Redis URL: Change redis_url in the [global] section
2. Update Zinit Socket: Change zinit_socket_path for your Zinit installation
3. Actor Paths: Update binary paths in actor sections to match your setup
4. Environment Variables: Add or modify environment variables for each actor 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 actor 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.