CLI Reference

The horus command gives you everything you need to build, run, and manage your applications.

Quick Reference

# Project Management
horus init                 # Initialize workspace in current directory
horus new <name>           # Create a new project
horus run [files...]       # Build and run your app
horus build [files...]     # Build without running
horus test [filter]        # Run tests
horus check [path]         # Validate horus.toml and workspace
horus clean                # Clean build artifacts and shared memory

# Monitoring & Debugging
horus monitor [port]       # Monitor your system (web or TUI)
horus topic <command>      # Topic introspection (list, echo, info, hz, pub)
horus node <command>       # Node management (list, info, kill, restart, pause, resume)
horus log [node]           # View and filter logs
horus blackbox             # Inspect BlackBox flight recorder (alias: bb)

# Coordinate Frames
horus tf <command>         # Transform Frames (list, echo, tree, info, can, hz)

# Package Management
horus install <name>       # Install a package, driver, or plugin (smart detection)
horus remove <name>        # Remove package, driver, or plugin
horus list [query]         # List/search packages
horus update [package]     # Update packages
horus publish              # Publish current package to registry
horus search <query>       # Search for available packages/plugins
horus cache <command>      # Cache management (info, list, clean, purge)

# Parameters & Messages
horus param <command>      # Parameter management (get, set, list, delete, reset, dump, load, save)
horus msg <command>        # Message type introspection (list, show, md5)

# Advanced
horus launch <file>        # Launch multiple nodes from YAML
horus deploy [target]      # Deploy to remote robot
horus record <command>     # Record/replay for debugging and testing
# Environment & Auth
horus env <command>        # Save/restore environments (freeze, restore, list)
horus auth <command>       # Login to registry

`horus init` - Initialize Workspace

What it does: Initializes a HORUS workspace in the current directory, creating the necessary configuration files.

Why it's useful: Quickly set up an existing directory as a HORUS project without creating new files from templates.

Basic Usage

# Initialize in current directory (uses directory name)
horus init

# Initialize with custom name
horus init --name my_robot

All Options

horus init [OPTIONS]

Options:
  -n, --name <NAME>    Workspace name (defaults to directory name)

Examples

Initialize existing code as HORUS project:

cd ~/my-robot-code
horus init
# Creates horus.toml with project configuration

Initialize with specific name:

horus init --name sensor_array

What Gets Created

Running horus init creates:

horus.toml - Project config with name and version

This is useful when you have existing code and want to add HORUS support, or when setting up a workspace that will contain multiple HORUS projects.

`horus new` - Create Projects

What it does: Creates a new HORUS project with all the boilerplate set up for you.

Why it's useful: Minimal configuration required. Select a language and begin development.

Basic Usage

# Interactive mode (asks you questions)
horus new my_project

# Rust with node! macro (recommended for reduced boilerplate)
horus new my_project --macro

# Python project
horus new my_project --python

All Options

horus new <NAME> [OPTIONS]

Options:
  -m, --macro              Rust with node! macro (less boilerplate)
  -r, --rust               Plain Rust project
  -p, --python             Python project
  -o, --output <PATH>      Where to create it (default: current directory)

Examples

Start with Rust + macros (easiest):

horus new temperature_monitor --macro
cd temperature_monitor
horus run

Python for prototyping:

horus new sensor_test --python
cd sensor_test
python main.py

Put it somewhere specific:

horus new robot_controller --output ~/projects/robots

`horus run` - Build and Run

What it does: Compiles your code and runs it. Handles all the build tools for you.

Why it's useful: One command works for Rust and Python. Language is auto-detected from native build files (Cargo.toml for Rust, pyproject.toml for Python). For Rust, it builds with Cargo. For Python, it handles the appropriate tooling.

Basic Usage

# Run current directory (finds main.rs or main.py)
horus run

# Run specific file
horus run src/controller.rs

# Run optimized (release mode)
horus run --release

All Options

horus run [FILES...] [OPTIONS] [-- ARGS]

Options:
  -r, --release            Optimize for speed (recommended for benchmarks)
  -c, --clean              Remove cached build artifacts and dependencies
                           (Use after updating HORUS or when compilation fails)
  -q, --quiet              Suppress progress indicators
  -d, --drivers <LIST>     Override detected drivers (comma-separated)
                           Example: --drivers camera,lidar,imu
  -e, --enable <LIST>      Enable capabilities (comma-separated)
                           Example: --enable cuda,editor,python
      --record <NAME>      Enable recording for this session
  -- <ARGS>                Arguments for your program

Using --enable for Capabilities

The --enable flag lets you quickly enable features without editing horus.toml:

# Enable CUDA GPU acceleration
horus run --enable cuda

# Enable multiple capabilities
horus run --enable cuda,editor,python

# Combine with hardware features
horus run --enable gpio,i2c --release

Available capabilities:

Capability	Description
`cuda`, `gpu`	CUDA GPU acceleration
`editor`	Scene editor UI
`python`, `py`	Python bindings
`headless`	No rendering (for training)
`gpio`, `i2c`, `spi`, `can`, `serial`	Hardware interfaces
`opencv`	OpenCV backend
`realsense`	Intel RealSense support
`full`	All features

Or configure in horus.toml:

enable = ["cuda", "editor"]

Why --release Matters

Debug builds have significantly higher overhead than release builds due to runtime checks and lack of optimizations.

Debug mode (default): Fast compilation, slower execution

Use case: Development iteration
Typical tick time: 60-200μs
Includes overflow checks, bounds checking, assertions

Release mode (--release): Slower compilation, optimized execution

Use case: Performance testing, benchmarks, production deployment
Typical tick time: 1-3μs
Full compiler optimizations enabled

Common Mistake:

horus run  # Debug mode
# You see: [IPC: 1862ns | Tick: 87μs] - Looks slow!

horus run --release  # Release mode
# You see: [IPC: 947ns | Tick: 2μs] - Actually fast!

The tick time difference is dramatic:

Debug: 60-200μs per tick (too slow for real-time control)
Release: 1-3μs per tick (production-ready performance)

Rule of thumb: Always use --release when:

Measuring performance
Running benchmarks
Testing real-time control loops
Deploying to production
Wondering "why is HORUS slow?"

Why --clean Matters

The --clean flag removes the .horus/target/ directory, which contains cached build artifacts and dependencies.

When to use --clean:

After updating HORUS - Most common use case

# You updated horus CLI to a new version
horus run --clean

This fixes version mismatch errors like:

error: the package `horus` depends on `horus_core 0.1.0`,
but `horus_core 0.1.3` is installed

Compilation fails mysteriously

horus run --clean
# Sometimes cached state gets corrupted

Dependencies changed

# You modified Cargo.toml dependencies
horus run --clean

What it does:

Removes .horus/target/ (build artifacts)
Removes cached lock files
Forces fresh dependency resolution
Next build rebuilds everything from scratch

Trade-off:

First build after --clean is slower (5-30 seconds)
Subsequent builds are fast again (incremental compilation)

Note: The --clean flag only affects the current project's .horus/ directory, not the global ~/.horus/ cache.

Examples

Daily development:

horus run
# Fast iteration, slower execution

Testing performance:

horus run --release
# See real speed

Build for CI without running (use horus build):

horus build --release

Fresh build (when things act weird or after updating HORUS):

horus run --clean --release

After updating HORUS CLI (fixes version mismatch errors):

# Clean removes cached dependencies from .horus/target/
horus run --clean

Pass arguments to your program:

horus run -- --config robot.yaml --verbose

Important: Single-File Projects Only

horus run is designed for single-file HORUS projects (main.rs or main.py). It creates a temporary workspace in .horus/ and automatically handles dependencies.

What works with horus run:

Single main.rs with all nodes defined in one file
Simple Python scripts (main.py)

What doesn't work:

Multi-crate Cargo workspaces
Projects with multiple Cargo.toml files
Complex module structures with separate crate directories

For multi-crate projects, use cargo directly:

cd your_multi_crate_project
cargo build --release
cargo run --release

Example of a proper single-file structure:

// main.rs - everything in one file
use horus::prelude::*;

struct SensorNode { /* ... */ }
impl Node for SensorNode { /* ... */ }

struct ControlNode { /* ... */ }
impl Node for ControlNode { /* ... */ }

fn main() -> Result<()> {
    let mut scheduler = Scheduler::new();
    scheduler.add(SensorNode::new()?).order(0).build()?;
    scheduler.add(ControlNode::new()?).order(1).build()?;
    scheduler.run()
}

Concurrent Multi-Process Execution

HORUS supports running multiple node files concurrently as separate processes using glob patterns. This is ideal for distributed robotics systems where nodes need to run independently.

Basic Usage:

horus run "nodes/*.py"          # Run all Python nodes concurrently
horus run "src/*.rs"            # Run all Rust nodes concurrently

How it works:

Phase 1 (Build): Builds all files sequentially, respecting Cargo's file lock
Phase 2 (Execute): Spawns all processes concurrently with their own schedulers
Each process communicates via HORUS shared memory IPC

Features:

-Color-coded output: Each node is prefixed with [node_name] in a unique color
-Graceful shutdown: Ctrl+C cleanly terminates all processes
-Multi-language: Works with Rust and Python
-Automatic detection: No flags needed, just use glob patterns

Example output:

$ horus run "nodes/*.py"
 Executing 3 files concurrently:
  1. nodes/sensor.py (python)
  2. nodes/controller.py (python)
  3. nodes/logger.py (python)

 Phase 1: Building all files...
 Phase 2: Starting all processes...
   Started [sensor]
   Started [controller]
   Started [logger]

 All processes running. Press Ctrl+C to stop.

[sensor] Sensor reading: 25.3°C
[controller] Motor speed: 45%
[logger] System operational
[sensor] Sensor reading: 26.1°C
[controller] Motor speed: 50%
[logger] System operational

When to use concurrent execution:

Multi-node systems where each node is in a separate file
Distributed control architectures (similar to ROS nodes)
Testing multiple nodes simultaneously
Microservices-style robotics architectures

When to use single-process execution:

All nodes in one file (typical for simple projects)
Projects requiring predictable scheduling across all nodes
Maximum performance with minimal overhead

Important: Each process runs its own scheduler. Nodes communicate through HORUS shared memory topics (/dev/shm/horus/), not direct function calls.

`horus check` - Validate Project

What it does: Validates horus.toml, source files, and the workspace configuration.

Why it's useful: Quickly diagnose configuration issues, missing dependencies, or environment problems before building.

Basic Usage

# Check current directory
horus check

# Check a specific path
horus check path/to/project

# Quiet mode (errors only)
horus check --quiet

All Options

horus check [OPTIONS] [PATH]

Arguments:
  [PATH]  Path to file, directory, or workspace (default: current directory)

Options:
  -q, --quiet    Only show errors, suppress warnings
  -h, --help     Print help

Examples

Validate before building:

horus check
# Validates horus.toml, build files, and environment

CI/CD validation:

#!/bin/bash
if ! horus check --quiet; then
  echo "Validation failed"
  exit 1
fi
horus build --release

`horus monitor` - Monitor Everything

What it does: Opens a visual monitor showing all your running nodes, messages, and performance.

Why it's useful: Debug problems visually. See message flow in real-time. Monitor performance.

Basic Usage

# Web monitor (opens in browser)
horus monitor

# Different port
horus monitor 8080

# Text-based (for SSH)
horus monitor --tui

# Reset monitor password before starting
horus monitor --reset-password

What You See

The monitor shows:

All running nodes - Names, status, tick rates
Message flow - What's talking to what
Performance - CPU, memory, latency per node
Topics - All active communication channels
Graph view - Visual network of your system

Examples

Start monitoring (in a second terminal):

# Terminal 1: Run your app
horus run --release

# Terminal 2: Watch it
horus monitor

Access from your phone:

horus monitor
# Visit http://your-computer-ip:3000 from phone

Monitor over SSH:

ssh robot@192.168.1.100
horus monitor --tui

See Monitor Guide for detailed features.

`horus install` / `horus remove` / `horus list` / `horus update` / `horus publish` - Package Management

What it does: Install and manage reusable components.

Why it's useful: Don't reinvent the wheel. Use components others have built and tested.

Commands

# Install a package
horus install <package>

# Remove a package
horus remove <package>

# List packages
horus list [query]

# Update packages
horus update [package]

# Publish current package to registry
horus publish

# Unpublish a package from registry
horus unpublish <package> <version>

# Generate signing key pair
horus keygen

Examples

Install a package:

horus install pid-controller

Install specific version:

horus install pid-controller --ver 1.2.0

Install globally (share across projects):

horus install common-utils --global

See what's installed:

horus list

Search for packages:

horus search sensor

Remove a package:

horus remove pid-controller

Publish your package to registry:

# First login
horus auth login

# Then publish from your project directory
horus publish

Unpublish from registry (irreversible!):

horus unpublish my-package 1.0.0

`horus env` - Environment Management

What it does: Save and restore your exact setup (all package versions).

Why it's useful: Share your setup with teammates. Deploy the same version to production. Time-travel to old configurations.

Commands

# Save current environment
horus env freeze

# Save and publish to registry for sharing
horus env freeze --publish

# Load saved environment from file or registry ID
horus env restore <source>

# List all published environments
horus env list

# Show details of an environment
horus env show <id>

Examples

Save your setup:

horus env freeze
# Creates horus-freeze.yaml

Load teammate's setup:

horus env restore teammate-setup.yaml

Deploy exact production environment:

# On production machine
horus env restore production.yaml

`horus auth` - Login to Registry

What it does: Authenticate so you can publish packages.

Why it's useful: Secure access to the package registry.

Commands

# Login with GitHub
horus auth login

# Generate API key (for CI/CD)
horus auth generate-key

# Check who you are
horus auth whoami

# Logout
horus auth logout

# Organization info (HORUS Cloud)
horus auth org

# Billing usage (HORUS Cloud)
horus auth usage

# Plan details (HORUS Cloud)
horus auth plan

# Manage API keys
horus auth keys list
horus auth keys revoke <key_id>

Examples

First time setup:

horus auth login
# Opens browser for GitHub login

Check you're logged in:

horus auth whoami

Generate API key for CI/CD:

horus auth generate-key --name github-actions --environment ci-cd
# Save the generated key in your CI secrets

Logout:

horus auth logout

`horus build` - Build Without Running

What it does: Compiles your project without executing it.

Why it's useful: Validate compilation, prepare for deployment, or integrate with CI/CD pipelines.

Basic Usage

# Build current project
horus build

# Build in release mode
horus build --release

# Clean build (remove cached artifacts first)
horus build --clean

All Options

horus build [FILES...] [OPTIONS]

Options:
  -r, --release            Build in release mode (optimized)
  -c, --clean              Clean before building
  -q, --quiet              Suppress progress indicators
  -d, --drivers <LIST>     Override detected drivers (comma-separated)
  -e, --enable <LIST>      Enable capabilities (comma-separated)
  -h, --help               Print help

Examples

CI/CD build validation:

horus build --release
# Exit code 0 = success, non-zero = failure

Clean release build for deployment:

horus build --clean --release

`horus test` - Run Tests

What it does: Runs your HORUS project's test suite.

Why it's useful: Validate functionality, run integration tests with simulation, and ensure code quality.

Basic Usage

# Run all tests
horus test

# Run tests matching a filter
horus test my_node

# Run with parallel execution
horus test --parallel

# Run simulation tests
horus test --sim

All Options

horus test [OPTIONS] [FILTER]

Arguments:
  [FILTER]  Test name filter (runs tests matching this string)

Options:
  -r, --release            Run tests in release mode
      --parallel           Allow parallel test execution
      --sim                Enable simulation mode (no hardware required)
      --integration        Run integration tests (tests marked #[ignore])
      --nocapture          Show test output
  -j, --test-threads <N>   Number of test threads (default: 1)
      --no-build           Skip the build step
      --no-cleanup         Skip shared memory cleanup after tests
  -v, --verbose            Verbose output
  -d, --drivers <LIST>     Override detected drivers (comma-separated)
  -e, --enable <LIST>      Enable capabilities (comma-separated)
  -h, --help               Print help

Examples

Run specific tests:

horus test sensor_node --nocapture

Fast parallel test run:

horus test --parallel --release

Integration tests with simulator:

horus test --integration --sim

`horus clean` - Clean Build Artifacts

What it does: Removes build artifacts, cached dependencies, and shared memory files.

Why it's useful: Fix corrupted builds, reclaim disk space, or reset shared memory after crashes.

Basic Usage

# Clean everything (build + shared memory + cache)
horus clean --all

# Only clean shared memory
horus clean --shm

# Preview what would be cleaned
horus clean --dry-run

All Options

horus clean [OPTIONS]

Options:
      --shm      Only clean shared memory
  -a, --all      Clean everything (build cache + shared memory + horus cache)
  -n, --dry-run  Show what would be cleaned without removing anything
  -h, --help     Print help
  -V, --version  Print version

Examples

After a crash (clean stale shared memory):

horus clean --shm

Full reset before deployment:

horus clean --all
horus build --release

`horus topic` - Topic Introspection

What it does: Inspect, monitor, and interact with HORUS topics (shared memory communication channels).

Why it's useful: Debug message flow, verify data publishing, and measure topic rates.

Subcommands

horus topic list              # List all active topics
horus topic echo <topic>      # Print messages as they arrive
horus topic info <topic>      # Show topic details (type, publishers, subscribers)
horus topic hz <topic>        # Measure publishing rate
horus topic pub <topic> <msg> # Publish a message

Examples

List all topics:

horus topic list
# Output:
# cmd_vel (CmdVel) - 2 publishers, 1 subscriber
# scan (LaserScan) - 1 publisher, 3 subscribers
# odom (Odometry) - 1 publisher, 1 subscriber

Monitor a topic in real-time:

horus topic echo scan
# Prints each LaserScan message as it arrives

Check publishing rate:

horus topic hz cmd_vel
# Output: average rate: 50.0 Hz, min: 49.2, max: 50.8

Publish test message:

horus topic pub cmd_vel '{"stamp_nanos": 0, "linear": 1.0, "angular": 0.5}'

`horus node` - Node Management

What it does: List, inspect, and control running HORUS nodes.

Why it's useful: Debug node states, restart misbehaving nodes, or pause nodes during testing.

Subcommands

horus node list               # List all running nodes
horus node info <node>        # Show detailed node information
horus node kill <node>        # Terminate a node
horus node restart <node>     # Restart a node
horus node pause <node>       # Pause a node's tick execution
horus node resume <node>      # Resume a paused node

Examples

List all running nodes:

horus node list
# Output:
# NAME              PID     RATE   CPU    MEMORY   STATUS
# SensorNode        12345   100Hz  1.2%   10MB     Running
# ControllerNode    12346   50Hz   2.5%   15MB     Running
# LoggerNode        12347   10Hz   0.1%   5MB      Paused

Get detailed node info:

horus node info SensorNode
# Shows: tick count, error count, subscribed topics, published topics

Restart a stuck node:

horus node restart ControllerNode

Pause/resume for debugging:

horus node pause SensorNode
# ... inspect state ...
horus node resume SensorNode

`horus log` - View and Filter Logs

What it does: View, filter, and follow HORUS system logs.

Why it's useful: Debug issues, monitor specific nodes, and track errors in real-time.

Basic Usage

# View all recent logs
horus log

# Filter by node
horus log SensorNode

# Follow logs in real-time
horus log --follow

# Show only errors
horus log --level error

All Options

horus log [OPTIONS] [NODE]

Arguments:
  [NODE]  Filter by node name

Options:
  -l, --level <LEVEL>  Filter by log level (trace, debug, info, warn, error)
  -s, --since <SINCE>  Show logs from last duration (e.g., "5m", "1h", "30s")
  -f, --follow         Follow log output in real-time
  -n, --count <COUNT>  Number of recent log entries to show
      --clear          Clear logs instead of viewing
      --clear-all      Clear all logs (including file-based logs)
  -h, --help           Print help

Examples

Follow logs from a specific node:

horus log SensorNode --follow

View errors from last 10 minutes:

horus log --level error --since 10m

Show last 50 warnings and errors:

horus log --level warn --count 50

`horus param` - Parameter Management

What it does: Manage node parameters at runtime (get, set, list, dump, save, load).

Why it's useful: Tune robot behavior without recompiling, persist configurations, and debug parameter values.

Subcommands

horus param list                  # List all parameters
horus param get <key>             # Get parameter value
horus param set <key> <value>     # Set parameter value
horus param delete <key>          # Delete a parameter
horus param reset                 # Reset all parameters to defaults
horus param load <file>           # Load parameters from YAML file
horus param save [-o <file>]      # Save parameters to YAML file
horus param dump                  # Dump all parameters as YAML to stdout

Examples

List all parameters:

horus param list
# Output:
# /SensorNode/sample_rate: 100
# /SensorNode/filter_size: 5
# /ControllerNode/kp: 1.5
# /ControllerNode/ki: 0.1

Tune a controller at runtime:

horus param set ControllerNode kp 2.0
horus param set ControllerNode ki 0.2

Save and restore configuration:

# Save current params
horus param save robot_config.yaml

# Later, restore them
horus param load robot_config.yaml

`horus tf` - Transform Frames (Coordinate Transforms)

What it does: Inspect and monitor coordinate frame transforms (similar to ROS tf).

Why it's useful: Debug transform chains, visualize frame relationships, and verify sensor mounting.

Subcommands

horus tf list                    # List all frames
horus tf echo <source> <target>  # Echo transform between two frames
horus tf tree                    # Show frame tree hierarchy
horus tf info <frame>            # Detailed frame information
horus tf can <source> <target>   # Check if transform is possible
horus tf hz                      # Monitor frame update rates

Examples

View frame tree:

horus tf tree
# Output:
# world
# └── base_link
#     ├── laser_frame
#     ├── camera_frame
#     └── imu_frame

Monitor a transform:

horus tf echo laser_frame world
# Prints: translation [x, y, z] rotation [qx, qy, qz, qw]

Check transform chain:

horus tf can laser_frame world
# Output: Yes, chain: laser_frame -> base_link -> world

`horus msg` - Message Type Introspection

What it does: Inspect HORUS message type definitions and schemas.

Why it's useful: Understand message structures, debug serialization issues, and verify type compatibility.

Subcommands

horus msg list               # List all message types
horus msg show <type>        # Show message definition
horus msg md5 <type>         # Show MD5 hash (for compatibility checking)

Examples

List available message types:

horus msg list
# Output:
# CmdVel (horus_library::messages::cmd_vel)
# LaserScan (horus_library::messages::sensor)
# Odometry (horus_library::messages::sensor)
# Image (horus_library::messages::vision)

Show message definition:

horus msg show CmdVel
# Output:
# struct CmdVel {
#   stamp_nanos: u64,  // nanoseconds
#   linear: f32,       // m/s forward velocity
#   angular: f32,      // rad/s turning velocity
# }

`horus launch` - Launch Multiple Nodes

What it does: Launch multiple nodes from a YAML configuration file.

Why it's useful: Start complex multi-node systems with one command, define node dependencies and parameters.

Basic Usage

# Launch from file
horus launch robot.yaml

# Preview without launching
horus launch robot.yaml --dry-run

# Launch with namespace
horus launch robot.yaml --namespace robot1

All Options

horus launch [OPTIONS] <FILE>

Arguments:
  <FILE>  Path to launch file (YAML)

Options:
  -n, --dry-run                Show what would launch without actually launching
      --namespace <NAMESPACE>  Namespace prefix for all nodes
      --list                   List nodes in the launch file without launching
  -h, --help                   Print help

Launch File Format

# robot.yaml
nodes:
  - name: sensor_node
    file: src/sensor.rs
    rate: 100
    params:
      sample_rate: 100

  - name: controller
    file: src/controller.rs
    rate: 50
    depends_on: [sensor_node]
    params:
      kp: 1.5
      ki: 0.1

  - name: logger
    file: src/logger.py
    rate: 10

Examples

Launch robot system:

horus launch robot.yaml

Launch with namespace (for multi-robot):

horus launch robot.yaml --namespace robot1
horus launch robot.yaml --namespace robot2

`horus deploy` - Deploy to Remote Robot

What it does: Cross-compile and deploy your project to a remote robot over SSH.

Why it's useful: Deploy from development machine to embedded robot, supports multiple architectures.

Basic Usage

# Deploy to configured target
horus deploy robot@192.168.1.100

# Deploy and run immediately
horus deploy robot@192.168.1.100 --run

# Deploy to specific architecture
horus deploy robot@192.168.1.100 --arch aarch64

All Options

horus deploy [OPTIONS] [TARGET]

Arguments:
  [TARGET]  Target host (user@host or configured target name)

Options:
  -d, --dir <REMOTE_DIR>     Remote directory (default: ~/horus_deploy)
  -a, --arch <ARCH>          Target architecture (aarch64, armv7, x86_64, native)
  -r, --run                  Run the project after deploying
      --debug                Build in debug mode instead of release
  -p, --port <PORT>          SSH port (default: 22)
  -i, --identity <IDENTITY>  SSH identity file
  -n, --dry-run              Show what would be done without doing it
      --list                 List configured deployment targets
  -h, --help                 Print help

Examples

Deploy to Raspberry Pi:

horus deploy pi@raspberrypi.local --arch aarch64

Deploy and run on NVIDIA Jetson:

horus deploy ubuntu@jetson.local --arch aarch64 --run

Configure named targets in horus.toml:

[deploy.targets.jetson]
host = "ubuntu@192.168.1.50"
arch = "aarch64"

[deploy.targets.pi]
host = "pi@192.168.1.51"
arch = "aarch64"

Then deploy with:

horus deploy jetson --run

`horus install` - Install Package/Driver/Plugin

What it does: Smart package installer that auto-detects whether you're installing a package, driver, or plugin.

Why it's useful: Single command for all installations, handles dependencies automatically.

Basic Usage

# Install a package (auto-detected)
horus install pid-controller

# Install with specific version
horus install sensor-fusion --ver 1.2.0

# Force install as driver
horus install camera-driver --driver

# Install globally
horus install common-utils --global

All Options

horus install [OPTIONS] <NAME>

Arguments:
  <NAME>  Package/driver/plugin name to install

Options:
  -v, --ver <VER>  Specific version (optional)
      --driver     Force install as driver
      --plugin     Force install as plugin
      --local      Force local installation
  -g, --global     Force global installation
      --no-system  Skip installing system dependencies
  -h, --help       Print help

Examples

Install common packages:

horus install kalman-filter
horus install pid-controller --ver 2.0.0

Install hardware drivers:

horus install realsense-driver --driver
horus install rplidar-driver --driver

`horus remove` - Remove Package/Driver/Plugin

What it does: Removes installed packages, drivers, or plugins.

Why it's useful: Clean up unused dependencies, switch to alternative implementations.

Basic Usage

# Remove a package
horus remove pid-controller

# Remove and purge unused dependencies
horus remove sensor-fusion --purge

# Remove global package
horus remove common-utils --global

All Options

horus remove [OPTIONS] <NAME>

Arguments:
  <NAME>  Package/driver/plugin name to remove

Options:
  -g, --global   Remove from global scope
      --purge    Also remove unused dependencies
  -h, --help     Print help

`horus plugin` - Plugin Management

What it does: Manage HORUS plugins (extensions that add CLI commands or features).

Why it's useful: Enable/disable plugins, verify plugin integrity.

Subcommands

horus list --plugins           # List installed plugins
horus search <query>           # Search for available packages/plugins
horus plugin available         # Show all available plugins from registry
horus plugin info <plugin>     # Show detailed plugin info
horus plugin enable <plugin>   # Enable a disabled plugin
horus plugin disable <plugin>  # Disable a plugin
horus plugin verify [plugin]   # Verify plugin integrity
horus install <plugin>         # Install a plugin from registry
horus remove <plugin>          # Remove an installed plugin

Examples

List plugins:

horus list --plugins

Search and install a plugin:

horus search visualizer
horus install horus-visualizer

Disable a plugin temporarily:

horus plugin disable horus-ros2-bridge --reason "debugging"

`horus cache` - Cache Management

What it does: Manage the HORUS package cache (downloaded packages, compiled artifacts).

Why it's useful: Reclaim disk space, troubleshoot package issues.

Subcommands

horus cache info               # Show cache statistics (size, package count)
horus cache list               # List all cached packages
horus cache clean              # Remove unused packages (--dry-run to preview)
horus cache purge              # Remove ALL cached packages (-y to skip confirmation)

Examples

Check cache usage:

horus cache info
# Output:
# Location: ~/.horus/cache
# Total size: 1.2 GB
# Packages: 45
# Last cleaned: 7 days ago

Clean unused packages:

horus cache clean
# Removes packages not used by any project

`horus record` - Record/Replay Management

What it does: Manage recorded sessions for debugging and testing.

Why it's useful: Replay exact scenarios, compare runs, debug timing-sensitive issues.

Subcommands

horus record list              # List all recordings
horus record info <session>    # Show recording details
horus record replay <session>  # Replay a recording
horus record delete <session>  # Delete a recording
horus record diff <a> <b>      # Compare two recordings
horus record export <session>  # Export to different format
horus record inject <session>  # Inject recorded data into live scheduler

Examples

List recordings:

horus record list
# Output:
# ID         DATE                 DURATION   NODES   SIZE
# rec_001    2024-01-15 10:30:00  5m 23s     4       45MB
# rec_002    2024-01-15 14:15:00  2m 10s     3       18MB

Replay a session:

horus record replay rec_001

Compare two runs:

horus record diff rec_001 rec_002
# Shows differences in timing, message counts, errors

Inject recorded data into live system:

# Use recorded sensor data with live controller
horus record inject rec_001 --nodes SensorNode

`horus blackbox` - BlackBox Flight Recorder

Alias: horus bb

What it does: Inspects the BlackBox flight recorder for post-mortem crash analysis. The BlackBox automatically records scheduler events, errors, deadline misses, and safety state changes.

Why it's useful: After a crash or anomaly, review exactly what happened — which nodes failed, when deadlines were missed, and what the safety state was at each tick.

Basic Usage

# View all recorded events
horus blackbox

# Show only anomalies (errors, deadline misses, WCET violations, e-stops)
horus blackbox --anomalies

# Follow mode — stream events in real-time (like tail -f)
horus blackbox --tail

All Options

horus blackbox [OPTIONS]

Options:
  -a, --anomalies          Show only anomalies (errors, deadline misses,
                           WCET violations, e-stops)
  -f, --tail               Follow mode — stream new events as they arrive
  -t, --tick <RANGE>       Filter by tick range (e.g. "4500-4510" or "4500")
  -n, --node <NAME>        Filter by node name (partial, case-insensitive)
  -e, --event <TYPE>       Filter by event type (e.g. "DeadlineMiss", "NodeError")
      --json               Output as machine-readable JSON
  -l, --last <N>           Show only the last N events
  -p, --path <DIR>         Custom blackbox directory (default: .horus/blackbox/)
      --clear              Clear all blackbox data (with confirmation)

Examples

View recent anomalies:

horus bb --anomalies --last 20

Filter by node and tick range:

horus bb --node controller --tick 4500-4510

Stream events in real-time while debugging:

horus bb --tail --anomalies

Export to JSON for external analysis:

horus bb --json > blackbox_dump.json

Clear old data:

horus bb --clear

Common Workflows

First Time Using HORUS

# Create a project
horus new my_first_app --macro
cd my_first_app

# Run it
horus run --release

# Monitor it (new terminal)
horus monitor

Daily Development

# Make changes to code
vim src/main.rs

# Test quickly
horus run

# Test for real
horus run --release

Deploy to Production

# Clean build
horus run --clean --release

# Save the environment
horus env freeze --output production.yaml

# Run in production mode
horus run --release

# Login once
horus auth login

# Publish
horus publish

# Others can now:
horus install your-package-name

Troubleshooting

"command not found: horus"

Add cargo to your PATH:

export PATH="$HOME/.cargo/bin:$PATH"
echo 'export PATH="$HOME/.cargo/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

"Port already in use"

# Use different port
horus monitor 3001

# Or kill the old process
lsof -ti:3000 | xargs kill -9

Build is slow

First build is always slow (5-10 min). After that it's fast (seconds).

Use --release only when you need speed, not during development.

"Failed to create Topic"

Topic name conflict. Try a unique name or clean up stale shared memory.

Note: HORUS automatically cleans up shared memory after each run using session isolation. This error usually means a previous run crashed.

# Clean all HORUS shared memory (if needed after crashes)
rm -rf /dev/shm/horus/

Environment Variables

Optional configuration:

# Custom registry (for companies)
export HORUS_REGISTRY_URL=https://your-company-registry.com

# Debug mode (see what's happening)
export RUST_LOG=debug
horus run

# CI/CD authentication
export HORUS_API_KEY=your-key-here

Utility Scripts

Beyond the horus CLI, the repository includes helpful scripts:

./install.sh             # Install or update HORUS

See Troubleshooting & Maintenance for complete details.

Next Steps

Now that you know the commands:

Quick Start - Build your first app
node! Macro - Write less code
Monitor Guide - Master monitoring
Examples - See real applications

Having issues? Check the Troubleshooting Guide for solutions to common problems.

CLI Reference

Quick Reference

horus init - Initialize Workspace

Basic Usage

All Options

Examples

What Gets Created

horus new - Create Projects

Basic Usage

All Options

Examples

horus run - Build and Run

Basic Usage

All Options

Using --enable for Capabilities

Why --release Matters

Why --clean Matters

Examples

Important: Single-File Projects Only

Concurrent Multi-Process Execution

horus check - Validate Project

Basic Usage

All Options

Examples

horus monitor - Monitor Everything

Basic Usage

What You See

Examples

horus install / horus remove / horus list / horus update / horus publish - Package Management

Commands

Examples

horus env - Environment Management

Commands

Examples

horus auth - Login to Registry

Commands

Examples

horus build - Build Without Running

Basic Usage

All Options

Examples

horus test - Run Tests

Basic Usage

All Options

Examples

horus clean - Clean Build Artifacts

Basic Usage

All Options

Examples

horus topic - Topic Introspection

Subcommands

Examples

horus node - Node Management

Subcommands

Examples

horus log - View and Filter Logs

Basic Usage

All Options

Examples

horus param - Parameter Management

Subcommands

Examples

horus tf - Transform Frames (Coordinate Transforms)

Subcommands

Examples

horus msg - Message Type Introspection

Subcommands

Examples

horus launch - Launch Multiple Nodes

Basic Usage

All Options

Launch File Format

Examples

horus deploy - Deploy to Remote Robot

Basic Usage

All Options

Examples

horus install - Install Package/Driver/Plugin

Basic Usage

All Options

`horus init` - Initialize Workspace

`horus new` - Create Projects

`horus run` - Build and Run

`horus check` - Validate Project

`horus monitor` - Monitor Everything

`horus install` / `horus remove` / `horus list` / `horus update` / `horus publish` - Package Management

`horus env` - Environment Management

`horus auth` - Login to Registry

`horus build` - Build Without Running

`horus test` - Run Tests

`horus clean` - Clean Build Artifacts

`horus topic` - Topic Introspection

`horus node` - Node Management

`horus log` - View and Filter Logs

`horus param` - Parameter Management

`horus tf` - Transform Frames (Coordinate Transforms)

`horus msg` - Message Type Introspection

`horus launch` - Launch Multiple Nodes

`horus deploy` - Deploy to Remote Robot

`horus install` - Install Package/Driver/Plugin

`horus remove` - Remove Package/Driver/Plugin

`horus plugin` - Plugin Management

`horus cache` - Cache Management

`horus record` - Record/Replay Management

`horus blackbox` - BlackBox Flight Recorder