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 …            │
                                             └──────────────────┘

The 0.3.0 ecosystem surface sits on the same three verbs. Layers, top to bottom:

┌──────────────────────────────────────┐
│               CAASI CLI              │
│  Commands / Help / Completion / JSON │
└───────────────────┬──────────────────┘
                    │
┌───────────────────▼──────────────────┐
│         Orchestration Layer          │
│  Detect / Configure / Launch         │
│  Connect / Monitor / Stop            │
│  (capability catalog + adapters)     │
└───────────────────┬──────────────────┘
                    │
      ┌─────────────┼─────────────┐
      │             │             │
┌─────▼─────┐ ┌─────▼─────┐ ┌─────▼─────┐
│Simulation │ │ Robotics  │ │   AI/ML   │
└─────┬─────┘ └─────┬─────┘ └─────┬─────┘
      │             │             │
 Isaac Sim        ROS 2       Isaac Lab
 PhysX · Newton   Nav2        PyTorch · Warp
 Replicator       MoveIt 2    GR00T · Cosmos
                  ros2_control TensorRT
                  Isaac ROS · NITROS
                  nvblox · cuMotion

Nothing in the bottom two rows is implemented by Caasi. Each box is reached through a capability — a declarative list of packages, binaries, Python modules, env vars and paths to probe — and an adapter that turns a resolved capability into the command line of the real tool. A new upstream release is a config change, not a code change:

shellcaasi config catalog slam
caasi config set catalog.slam.toolbox.packages '["slam_toolbox"]'

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-05T14:23:01+08:00  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.

shell# recommended: isolated env, command linked into ~/.local/bin
pipx install caasi
# or into the active environment:
pip install caasi
caasi version
caasi 0.3.0

Both install the caasi console script into the environment's bin/; pipx additionally links it into ~/.local/bin so it is available system-wide for your user (pipx ensurepath if that is not on your PATH). On PEP 668 distros (Ubuntu 23.04+, Debian 12+, Fedora) a bare system-wide pip install is refused — use pipx or a dedicated venv:

shellpython3 -m venv ~/.venvs/caasi && ~/.venvs/caasi/bin/pip install caasi

From source:

shellgit clone https://github.com/7a6172/caasi.git && cd caasi
pip install -e .
# development (adds pytest):
pip install -e ".[dev]"

Upgrade with pipx upgrade caasi or pip install -U caasi. 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/
  artifacts/  logs/  .caasi/
cd ~/experiments/demo && caasi project 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) · 3 a check report resolved to incompatible. Readiness commands (doctor, check, 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.

The five verbs

One organising principle runs through the whole CLI: every diagnostic-ish command is one of five verbs, each with exactly one job. doctor never absorbs check or audit — they answer different questions. Full walkthrough in Observability.

inspect is the per-domain deep-dive (env inspect, project inspect, run inspect); setup provisions the machine/toolchain; project manages the robotics project.

The check contract

One check architecture, multiple entry points. Root caasi check orchestrates only the checkers relevant to the project's registered components; domain specialists (sim check, container check, control check) call the same engine for one scope. There is deliberately no caasi check sim alias — root aggregates, a domain specialises. Every entry point emits the same CheckReport (full detail in Environment):

The human report renders each item's compatibility as a rung of a confidence ladder, then collapses to one Result: line — and check exits 3 when that result is incompatible, so it drops straight into CI as a gate:

Command map