@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:

Project name - The name of your robot project
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
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:

Load .mecha10/config.json and mecha10.json
Start all configured nodes
Monitor health and auto-restart on crash
Watch for config changes (hot-reload)
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

mecha10-cli 0.1.21

@mecha10/cli

Features

Status

Architecture

Installation

Commands

mecha10 init

mecha10 dev

mecha10 run

mecha10 build

mecha10 deploy

mecha10 train

mecha10 logs

mecha10 status

mecha10 topology

mecha10 topics

mecha10 models

mecha10 clean

Global Options

Configuration

Project Config (mecha10.json)

Environment Variables (.env)

Workflow

Development Workflow

Production Workflow

Training Workflow

Integration

Logging

Error Handling

Architecture

Examples

Library Usage

Available Services

Development

Testing

License

`mecha10 init`

`mecha10 dev`

`mecha10 run`

`mecha10 build`

`mecha10 deploy`

`mecha10 train`

`mecha10 logs`

`mecha10 status`

`mecha10 topology`

`mecha10 topics`

`mecha10 models`

`mecha10 clean`