CLI Reference
The horus command gives you everything you need to build, run, and manage your applications. This page covers all 8 commands.
Quick Reference
horus new <name> # Create a new project
horus run [file] # Build and run your app
horus dashboard [port] # Monitor your system
horus pkg <command> # Manage packages (install, publish, etc.)
horus env <command> # Save/restore environments
horus auth <command> # Login to registry
horus version # Show version information
horus new - Create Projects
What it does: Creates a new HORUS project with all the boilerplate set up for you.
Why it's useful: No need to remember dependencies or configuration - just pick a language and start coding.
Basic Usage
# Interactive mode (asks you questions)
horus new my_project
# Rust with helpful macros (recommended!)
horus new my_project --macro
# Python project
horus new my_project --python
# C project ( under development)
horus new my_project --c
Note: C bindings are in alpha. Use Rust or Python for production.
All Options
horus new <NAME> [OPTIONS]
Options:
-m, --macro Rust with node! macro (less boilerplate)
-r, --rust Plain Rust project
-p, --python Python project
-c, --c C 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, Python, and C. For Rust, it auto-generates Cargo.toml from horus.yaml and uses Cargo for compilation. For Python and C, it handles the appropriate tooling.
Basic Usage
# Run current directory (finds main.rs, main.py, or main.c)
horus run
# Run specific file
horus run src/controller.rs
# Run optimized (100x faster!)
horus run --release
All Options
horus run [FILE] [OPTIONS] [-- ARGS]
Options:
-r, --release Optimize for speed (use for real testing!)
-b, --build-only Just compile, don't run
-c, --clean Remove old build files first
-R, --remote <ROBOT> Run on a remote robot
-- <ARGS> Arguments for your program
Why --release Matters
Debug mode (default): Fast to compile, slow to run
- Good for: Trying things quickly
- Speed: Messages take ~5-50μs
Release mode (--release): Slow to compile, fast to run
- Good for: Real testing, benchmarks, production
- Speed: Messages take ~296ns-1.31μs (100x faster!)
Always use --release when measuring performance!
Examples
Daily development:
horus run
# Fast iteration, slower execution
Testing performance:
horus run --release
# See real speed
Build for CI without running:
horus run --build-only --release
Fresh build (when things act weird):
horus run --clean --release
Run on your robot:
horus run --remote 192.168.1.100
# Builds here, runs there
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, main.py, or main.c). 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)
- Single C files (main.c)
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() -> HorusResult<()> {
let mut scheduler = Scheduler::new();
scheduler.register(Box::new(SensorNode::new()?), 0, Some(true));
scheduler.register(Box::new(ControlNode::new()?), 1, Some(true));
scheduler.tick_all()
}
horus dashboard - Monitor Everything
What it does: Opens a visual dashboard 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 dashboard (opens in browser)
horus dashboard
# Different port
horus dashboard 8080
# Text-based (for SSH)
horus dashboard --tui
What You See
The dashboard 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 dashboard
Access from your phone:
horus dashboard
# Visit http://your-computer-ip:3000 from phone
Monitor over SSH:
ssh robot@192.168.1.100
horus dashboard --tui
See Dashboard Guide for detailed features.
horus pkg - 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 pkg install <package>
# Remove a package
horus pkg remove <package>
# List packages
horus pkg list
# Publish current package to registry
horus pkg publish
# Unpublish a package from registry
horus pkg unpublish <package> <version>
Examples
Install a package:
horus pkg install pid-controller
Install specific version:
horus pkg install pid-controller -v 1.2.0
Install globally (share across projects):
horus pkg install common-utils --global
See what's installed:
horus pkg list
Search for packages:
horus pkg list sensor
Remove a package:
horus pkg remove pid-controller
Publish your package to registry:
# First login
horus auth login --github
# Then publish from your project directory
horus pkg publish
Unpublish from registry (irreversible!):
horus pkg 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
# Load saved environment
horus env restore <file>
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 --github
# Generate API key (for CI/CD)
horus auth generate-key
# Check who you are
horus auth whoami
# Logout
horus auth logout
Examples
First time setup:
horus auth login --github
# 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 version - Show Version Information
What it does: Display version information about your HORUS installation.
Why it's useful: Check what version you're running, verify installation, and get system information.
Usage
horus version
Example Output
HORUS - Hybrid Optimized Robotics Unified System
Version: 0.1.0
Build: release
Commit: abc123def456
Platform: linux-x86_64
Rust: 1.70.0
Common uses:
- Verify HORUS is installed correctly
- Check which version you're running
- Report version when filing bugs
- Confirm you have the latest version
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 dashboard
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
# Deploy to robot
horus run --remote production-robot --release
Share Your Work
# Login once
horus auth login --github
# Publish
horus pkg publish
# Others can now:
horus pkg 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 dashboard 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 Hub"
Topic name conflict. Try a unique name or clean up:
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:
./verify.sh # Check installation health
./update.sh # Smart update script (auto git pull)
./recovery_install.sh # Fix broken installations
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
- Dashboard Guide - Master monitoring
- Examples - See real applications
Having issues? Check the Troubleshooting Guide for solutions to common problems.