@mecha10/cli

Command-line interface for managing Mecha10 robot projects.

Features

• ✅ Project Scaffolding - init command with templates
• ✅ Development Mode - dev with hot-reload and runtime integration
• ✅ Production Mode - run for deployment
• ✅ Build System - build with cross-compilation support
• ✅ Simulation - sim for Godot environment generation
• ✅ Topology - topology for static analysis of nodes, pub/sub topics, and ports
• ✅ Topics - topics for message introspection and real-time monitoring
• ✅ Deployment - deploy with canary/rolling strategies
• ✅ Log Viewer - logs for debugging
• ✅ Status Display - status for project overview
• ✅ Cleanup - clean for build artifacts
• ✅ Quality Tools - quality, format, lint commands
• ✅ Library API - Programmatic access to CLI functionality

Status

✅ Production-Ready - 3-layer architecture, 392 tests passing, 70-75% coverage

Architecture

The CLI follows a strict 3-layer architecture:

Commands (clap Args)     → Pure data structures
    ↓
Handlers (orchestration) → Coordinate services, handle UI
    ↓
Services (business logic)→ Reusable, testable logic
    ↓
Mecha10 Core            → Message passing runtime

See CLI_ARCHITECTURE.md for complete details.

Installation

cd packages/cli
cargo install --path .

Verify installation:

mecha10 --version

Commands

mecha10 init

Initialize a new robot project:

# Interactive wizard (recommended)
mecha10 init

# Or with explicit parameters
mecha10 init my-robot --template rover
cd my-robot

Interactive Mode:

When you run mecha10 init without parameters, it launches an interactive wizard that prompts you for:

1. Project name - The name of your robot project
2. Robot type - Choose from:
   • rover - 4-wheeled mobile robot with sensors (camera, lidar, imu)
   • humanoid - Bipedal walking robot
   • arm - 6-DOF robotic arm manipulator
   • basic - Minimal starting template
3. Simulation - Whether to generate Godot RL simulation environments

Example Interactive Session:

🤖 Mecha10 Project Initialization Wizard

? Project name: my-rover
? What type of robot are you building?
  ❯ Rover - 4-wheeled mobile robot with sensors
    Humanoid - Bipedal walking robot
    Robotic Arm - 6-DOF manipulator
    Basic - Minimal starting template

? Generate simulation environments? Yes

📋 Configuration Summary:
  Project: my-rover
  Robot Type: rover
  Simulation: Yes

Command-line Flags:

You can also use command-line flags to skip the interactive prompts:

# Skip interactive mode with all parameters
mecha10 init my-robot --template rover

# Provide only the name, prompt for robot type
mecha10 init my-robot

# Provide only robot type, prompt for name
mecha10 init --template rover

# Skip simulation generation
mecha10 init --skip-sim

Templates:

• basic - Minimal project structure
• rover - Ground robot with navigation (camera, lidar, imu, motor controller)
• arm - Manipulation robot
• humanoid - Bipedal walker

What it creates:

my-robot/
├── .mecha10/          # Framework config
├── config/             # Robot configurations
├── nodes/              # Your node implementations
├── models/             # RL models (ONNX files)
├── environments/       # Simulation environments
├── tests/              # Integration tests
├── logs/               # Runtime logs
└── mecha10.json       # Project manifest

mecha10 dev

Start development mode with hot-reload:

mecha10 dev

Options:

• --env <ENV> - Environment (dev, staging, production)
• --config <PATH> - Custom config path
• --log-level <LEVEL> - Log level (debug, info, warn, error)

What it does:

1. Load .mecha10/config.json and mecha10.json
2. Start all configured nodes
3. Monitor health and auto-restart on crash
4. Watch for config changes (hot-reload)
5. Run until Ctrl+C

mecha10 run

Run in production mode:

mecha10 run --env production

Options:

• --env <ENV> - Environment (default: production)
• --nodes <LIST> - Specific nodes to run (comma-separated)
• --config <PATH> - Custom config path

Example:

# Run only camera and SLAM nodes
mecha10 run --nodes camera,slam

mecha10 build

Build the project:

# Debug build
mecha10 build

# Release build (optimized)
mecha10 build --release

# Cross-compile for Raspberry Pi
mecha10 build --release --target aarch64-unknown-linux-gnu

Options:

• --release - Build with optimizations
• --target <ARCH> - Cross-compile target

mecha10 deploy

Deploy to production:

mecha10 deploy --env production --strategy canary

Options:

• --env <ENV> - Environment (staging, production)
• --strategy <STRATEGY> - Deployment strategy (canary, rolling, blue-green)

Strategies:

• canary - Gradual rollout (10% → 50% → 100%)
• rolling - Node-by-node replacement
• blue-green - Instant switchover with rollback

Note: Requires platform API integration (stub implementation)

mecha10 train

Submit a training job:

mecha10 train training/navigation-policy.yaml --wait

Options:

• --wait - Wait for job to complete

Note: Requires platform API integration (stub implementation)

mecha10 logs

View node logs:

# All nodes
mecha10 logs

# Specific node
mecha10 logs camera

# Follow logs (tail -f)
mecha10 logs --follow

Note: Stub implementation

mecha10 status

Show project status:

mecha10 status

Output:

Project Status:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Robot: my-robot
Platform: rover
Nodes: 3
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

mecha10 topology

Static analysis of project topology - visualize nodes, pub/sub topics, and service ports:

# Show nodes and their topic connections
mecha10 topology

# Group by topics instead of nodes
mecha10 topology --group-by topics

# Export to JSON
mecha10 topology --format json > topology.json

# ASCII graph view
mecha10 topology --format graph

Features:

• No runtime required (static code analysis)
• Multiple views (nodes, topics, graph)
• Shows Redis and service ports
• Analyzes pub/sub relationships from source code

See CLI Guide for complete documentation.

---

mecha10 topics

Discover and monitor Redis stream topics:

# List all topics (interactive browser)
mecha10 topics list

# List topics matching a pattern
mecha10 topics list --pattern "sensor/*"

# Verbose output with topic details
mecha10 topics list --verbose

Features:

• Interactive terminal-based topic browser
• Real-time topic monitoring
• Keyboard navigation (↑/↓ arrows, Enter to select)
• Live message streaming from selected topics
• Pattern matching support

Example Session:

📋 Mecha10 Topics
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Scanning Redis for topics matching: *

Found 3 topic(s)

Use ↑/↓ arrows to navigate, Enter to select, Esc to exit

❯ sensor/camera
  sensor/lidar
  control/motor

mecha10 models

Manage AI models from HuggingFace Hub:

# List available models from catalog
mecha10 models list

# Show only recommended models
mecha10 models list --recommended

# Download a model from catalog
mecha10 models pull mobilenet-v2

# Download all recommended models
mecha10 models pull --all

# Download custom model from HuggingFace
mecha10 models pull --repo user/model --file model.onnx --name my-model

# List installed models
mecha10 models installed

# Show model details
mecha10 models info mobilenet-v2

# Remove cached model
mecha10 models remove mobilenet-v2

Features:

• Curated catalog of robotics/vision models
• Automatic downloads from HuggingFace Hub
• Automatic INT8 quantization for 2x faster inference
• Dual caching (HF cache + project models/)
• Offline support after first download
• Model metadata (size, task, input format)

Model Catalog:

• yolov8n-face (6.3MB) - Fast face detection
• mobilenet-v2 (2.5MB) - Image classification, ImageNet-1000
• Custom models via --repo flag

Integration: Nodes reference models by name (auto-downloads if missing):

# config/image_classifier.toml
[model]
name = "mobilenet-v2"  # Auto-downloads from catalog

Auto-download:

• mecha10 setup downloads recommended models
• Nodes auto-download on first use if model missing
• Works offline once cached

INT8 Quantization: Some models (like yolov8n) automatically generate optimized INT8 versions during download for 2x faster inference. See MODEL_QUANTIZATION.md for details.

mecha10 clean

Clean build artifacts:

# Clean build directories
mecha10 clean

# Also clean model cache
mecha10 clean --cache

Removes:

• build/
• target/
• .mecha10/cache/ (if --cache specified)

Global Options

All commands support:

• --log-level <LEVEL> - Set log level (debug, info, warn, error)
• --config <PATH> - Custom config file path

Example:

mecha10 dev --log-level debug

Configuration

Project Config (mecha10.json)

{
  "$schema": "https://mecha10.dev/schemas/mecha10.schema.json",
  "robot": {
    "id": "my-robot",
    "name": "My Robot",
    "platform": "rover",
    "version": "0.1.0"
  },
  "runtime": {
    "hot_reload": true,
    "health_check_interval_s": 5
  },
  "nodes": {
    "camera": {
      "executable": "./nodes/camera_node",
      "args": ["--resolution=1080p"],
      "mode": "local",
      "auto_restart": true
    }
  },
  "platform": {
    "api_url": "${MECHA10_API_URL:-http://localhost:3006}",
    "fleet_id": "${FLEET_ID:-dev-fleet}"
  }
}

Environment Variables (.env)

# Mecha10 Platform
MECHA10_API_URL=https://api.mecha10.dev
MECHA10_API_KEY=your-api-key

# Redis
REDIS_URL=redis://localhost:6379

# Fleet ID
FLEET_ID=production-fleet

# Development
DEV_MODE=false
LOG_LEVEL=info

Workflow

Development Workflow

# 1. Create project
mecha10 init my-robot
cd my-robot

# 2. Configure environment
cp .env.example .env
# Edit .env with your values

# 3. Implement nodes
# Write your node code in nodes/

# 4. Start development
mecha10 dev

# 5. View status
mecha10 status

# 6. Clean up
mecha10 clean

Production Workflow

# 1. Build for release
mecha10 build --release

# 2. Test locally
mecha10 run --env staging

# 3. Deploy to production
mecha10 deploy --env production --strategy canary

Training Workflow

# 1. Create training config
# Edit training/my-policy.yaml

# 2. Submit training job
mecha10 train training/my-policy.yaml --wait

# 3. Download model
# Model automatically deployed to .mecha10/cache/models/

Integration

With @mecha10/config:

let mut config_manager = ConfigManager::new(".mecha10")?;
let config = config_manager.load("mecha10.json").await?;

With @mecha10/core:

let mut runtime = Runtime::new("robot-1").await?;
runtime.start_node(node_config).await?;
runtime.run().await?;

Logging

Uses tracing for structured logging:

INFO  mecha10_cli: Starting development mode (env: dev)
INFO  mecha10_cli: Loading config from: "mecha10.json"
INFO  mecha10_core: Started node: camera
INFO  mecha10_core: Started node: slam

Enable debug logging:

mecha10 dev --log-level debug

Error Handling

The CLI provides clear error messages:

Error: mecha10.json not found
Run 'mecha10 init <name>' to create a new project.

Error: Failed to start node 'camera'
No such file or directory: ./nodes/camera_node
Build the node first with: mecha10 build

Architecture

┌─────────────────┐
│  mecha10 CLI   │
└────────┬────────┘
         │
         ├──> ConfigManager (load configs)
         │
         ├──> Runtime (start/monitor nodes)
         │
         └──> Platform API (deploy/train)

Examples

See QUICKSTART.md for complete examples.

Library Usage

The CLI can also be used as a library for programmatic access:

use mecha10_cli::{CliContext, CliContextBuilder, services::ProjectService};
use std::path::Path;

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    // Detect existing project
    let project = ProjectService::detect(Path::new("."))?;
    println!("Project: {} v{}", project.name()?, project.version()?);

    // Or use context for complex operations
    let ctx = CliContextBuilder::new()
        .redis_url("redis://localhost:6379".to_string())
        .verbose(true)
        .build()?;

    // Access services
    let docker = ctx.docker();
    docker.check_installation()?;
    docker.compose_up(true).await?;

    Ok(())
}

See lib.rs documentation for complete API examples.

Available Services

All services are accessible through CliContext:

• DockerService - Container and compose operations
• RedisService - Redis connection management
• ConfigService - Project configuration
• ProjectService - Project structure and validation
• SimulationService - Godot simulation generation
• ProcessService - Child process management
• TemplateService - Code generation
• ComponentCatalogService - Component discovery
• DiscoveryService - Network node discovery
• DeploymentService - Deployment operations
• PackageService - Package management

Development

# Build CLI
cd packages/cli
cargo build --release

# Run directly
cargo run -- init test-robot

# Install locally
cargo install --path .

# Run tests
cargo test --lib          # Unit tests
cargo test                # All tests

# Check code quality
cargo clippy --all-targets -- -D warnings
cargo fmt --all -- --check

Testing

The CLI has comprehensive test coverage:

• 392 tests passing
• 70-75% coverage across services
• All services have dedicated unit tests
• Integration tests for key workflows

See CLI_ARCHITECTURE.md for testing patterns.

License

MIT