Caasi CLI

Caasi is a lightweight, CLI-first orchestration layer for NVIDIA Isaac Sim, Isaac Lab and the wider robotics ecosystem (ROS 2, Nav2, MoveIt 2, ros2_control, …). It discovers the tools you already have, launches them headlessly, tracks every long-running process as a first-class run, and gives you uniform, scriptable output for all of it.

Philosophy

• Use existing software. Don't reinvent it. Caasi discovers, configures, launches, connects, monitors and manages tools that already exist. It never reimplements a simulator, a trainer, or a ROS middleware.
• Simulation is not visualization. Everything runs headless by default; a viewer (rviz2, Foxglove, Open3D) is attached only when you ask for it.
• Minimum required stack. The CLI process never imports Isaac Sim, Isaac Lab, PyTorch or rclpy. It stays fast and installs with three small dependencies (typer, rich, pyyaml).
• Don't become another ROS. ROS orchestration delegates to the real ros2 binary of the distro you already have installed.
• Unix-friendly. Small commands, --json output everywhere it matters, meaningful exit codes, errors on stderr.

Architecture: delegation, not reimplementation

Caasi is an orchestrator. Every heavy operation is delegated to the real tool, located through a layered discovery process:

            ┌────────────────────────────────────────────────┐
            │                    caasi                        │
            │  (typer + rich + yaml — nothing else imported)  │
            └───────┬──────────────┬──────────────┬──────────┘
                    │              │              │
        discover    │      launch  │      inspect │
                    ▼              ▼              ▼
     ┌──────────────────┐  ┌──────────────┐  ┌──────────────────┐
     │ tool registry    │  │ run manager  │  │ real binaries    │
     │ ~/.config/caasi  │  │ ~/.caasi/runs│  │ python.sh        │
     │ env vars         │  │ detached +   │  │ isaaclab.sh      │
     │ common paths     │  │ tracked      │  │ ros2 · ssh ·     │
     │ pip metadata     │  │ processes    │  │ docker · nvidia- │
     └──────────────────┘  └──────────────┘  │ smi …            │
                                             └──────────────────┘

How tools are found

Each ecosystem component is located in a fixed priority order — no imports, no daemons:

Runs: every long process is tracked

Simulations, training jobs, ROS launches, SSH batch jobs and container runs are all started detached and recorded under ~/.caasi/runs/. The CLI returns immediately; the run keeps going after you close the terminal. See Runs & Logs for the full model. The short version:

terminalcaasi sim run experiments/wave.yaml
Run 20260905-142301-wave started in the background.
  Follow it with: caasi logs 20260905-142301-wave -f
caasi run list
  ID                      Name   Backend  Status   Created              PID
  20260905-142301-wave    wave   sim      running  2026-09-05 14:23:01  48213
caasi logs latest -f
[14:23:04] stage loaded, 4096 envs
[14:23:11] step 1000/100000 …

Installation

Requirements: Python 3.10+ on Linux. Nothing else — the Isaac stack, ROS 2, PyTorch etc. are discovered, not installed, by Caasi.

shellgit clone <this repository> caasi && cd caasi
pip install -e .
# development (adds pytest):
pip install -e ".[dev]"
caasi version
caasi 0.1.0

This installs the caasi console command. Shell completion is available:

shellcaasi --install-completion
bash completion installed in /home/you/.bashrc

Quickstart: a first project, end to end

The typical Caasi workflow — diagnose, scaffold, run, follow, review:

1. Check what your machine has

shellcaasi doctor
Environment Diagnostics
── system ──────────────
✓ OS — Ubuntu 24.04.1 LTS
✓ Kernel — 6.8.0-45-generic
── nvidia ──────────────
✓ nvidia-smi — 550.107.02
✓ GPU 0 — NVIDIA GeForce RTX 4090 (24564 MiB)
✓ CUDA — 12.4
── isaac ───────────────
! Isaac Sim — not detected
── ros ─────────────────
✓ ROS 2 distro — jazzy at /opt/ros/jazzy
2 warning(s)
caasi setup
# shows which components are missing and how to install them

2. Scaffold a project

shellcaasi init ~/experiments/demo --name demo
Created project 'demo' at /home/you/experiments/demo
  caasi.yaml
  robots/  scenes/  tasks/  experiments/  datasets/  runs/
cd ~/experiments/demo && caasi robot create agv -d "Warehouse AGV"
Created robot 'agv' at /home/you/experiments/demo/robots/agv.yaml.

3. Register your Isaac install once

shellcaasi config set tools.isaacsim.versions."6.0".path /opt/isaac-sim-6.0
caasi config set tools.isaacsim.default "6.0"
caasi config tools
  Tool       Default  Versions  Resolved path
  isaacsim   6.0      6.0       /opt/isaac-sim-6.0

4. Describe an experiment and run it headless

experiments/wave.yamlname: wave
backend: sim            # sim | lab | python
script: scripts/wave.py # resolved relative to this YAML
headless: true
args: ["--steps", "10000"]

shellcaasi sim run experiments/wave.yaml
Run 20260905-142301-wave started in the background.
caasi logs latest -f
# Ctrl+C stops following — the run keeps going
caasi run status latest
wave (20260905-142301-wave)
  Status    succeeded
  Backend   sim

5. Train, benchmark, collect data, review

shellcaasi train experiments/ant.yaml --steps 500000 --envs 4096
caasi benchmark start experiments/fps.yaml --steps 20000
caasi benchmark report latest
caasi dataset generate experiments/collect.yaml --episodes 100 --record-images
caasi replay latest --viewer rviz

Global options & output conventions

Global options

These belong to the root command and must come before the subcommand (caasi --json gpu status, not caasi gpu --json status).

Output conventions

• JSON mode — most data commands accept --json (locally or globally). JSON always goes to stdout, pretty-printed with 2-space indent, and prints even under --quiet. It is safe to pipe into jq.
• Errors — handled failures print Error: <message> in red to stderr and exit 1. Errors never emit JSON.
• Exit codes — 0 success · 1 handled failure or a failing readiness check · 2 usage error (bad flag, missing argument — Click convention). Readiness commands (doctor, nav test, container check, …) deliberately use the exit code so you can script them: if caasi doctor -q; then …; fi.
• Bare groups — invoking a group with no subcommand (caasi gpu) prints its help and exits 0.

Command map