Environment

Answer the question “can this machine actually run my stack?” before wasting an hour on a launch that was going to fail anyway. These commands inspect the OS, GPUs, drivers, Python environment and the detected ecosystem — all read-only, all scriptable.

caasi doctor

Runs the full environment diagnostics suite: 18 sections, each made of small independent checks. Every check reports one of four statuses and, when useful, a fix hint.

caasi doctor [--component|-c NAME] [--verbose] [--quiet|-q] [--json]

Options

Option	Short	Type	Default	Description
`--component`	`-c`	str	all	Run a single section only (see table below).
`--verbose`		flag	off	Show details and hints for every check, not only problems.
`--quiet`	`-q`	flag	off	Print nothing; only the exit code speaks.
`--json`		flag	off	Machine-readable report.

What gets checked

Section (`--component`)	Checks
`system`	OS (fails unless Linux), kernel version
`hardware`	CPU model/cores, RAM (warns below 16 GiB)
`nvidia`	`nvidia-smi` presence (fails if missing), driver version, every GPU, CUDA version
`graphics`	Vulkan (`vulkaninfo` or libvulkan via `ldconfig`), display server (skipped headless)
`python`	Python ≥ 3.10 (fails otherwise), environment kind (conda / venv / system)
`isaac`	Isaac Sim and Isaac Lab detection (registry → env → common paths → pip)
`ros`	ROS 2 distro, `setup.bash`, `ros2` CLI, RMW middleware
`robotics`	Nav2, MoveIt 2, ros2_control via `ros2 pkg prefix` (skipped without ros2)
`accelerated`	GPU-Accelerated Robotics: the Isaac ROS capabilities (NITROS, visual SLAM, nvblox, cuMotion, perception), NITROS types/bridge, cuRobo and the MoveIt 2 planners, then the prerequisites — CUDA, TensorRT, `RMW_IMPLEMENTATION`, `ROS_DOMAIN_ID` (skipped without ros2)
`physics`	Physics Engines: PhysX (fails when absent), Newton, Warp, MuJoCo, Gazebo
`assets`	Assets & USD: `usdcat` and `usdchecker` (fail when absent), `usdview`, `usdrecord`, the URDF importer, `check_urdf`, `xacro`, NuRec
`data`	Data & Recording: Replicator (fails when absent), the rosbag2 MCAP and SQLite3 storage plugins, the Hugging Face CLI, the NGC CLI
`platform`	Foundation Models & Teleop: the GR00T repository and package, the Cosmos package and CLI, NuRec, keyboard and joystick teleop (teleop rows skip without ros2)
`ml`	PyTorch, TensorRT, ONNX Runtime (pip metadata), cuDNN
`vision`	OpenCV, Open3D
`simulators`	Gazebo, MuJoCo (skipped when absent)
`containers`	Docker, Podman (warns if neither)
`storage`	Free disk on `paths.runs` (fails < 5 GiB, warns < 20 GiB)

The five sections added in 0.2.0 — accelerated, physics, assets, data and platform — probe the capability catalog: a missing capability marked core reports fail, every other missing capability reports skip, and a renamed upstream is fixed with caasi config set catalog.<domain>.<capability>.<field> [...] rather than a Caasi upgrade. The groups behind them are documented on Isaac ROS & accelerated groups, physics & foundation models and synthetic data & teleoperation.

Example — full report

shellcaasi doctor
Environment Diagnostics

system
  ✓ OS — Ubuntu 24.04.1 LTS
  ✓ Kernel — 6.8.0-45-generic

hardware
  ✓ CPU — AMD Ryzen 9 7950X (32 cores)
  ✓ RAM — 62.7 GiB

nvidia
  ✓ nvidia-smi — 550.107.02
  ✓ GPU 0 — NVIDIA GeForce RTX 4090 (24564 MiB)
  ✓ CUDA — 12.4

python
  ✓ Python — 3.11.9
  ✓ Environment — venv

isaac
  ✗ Isaac Sim — not detected
    ↳ Install it or register a path: caasi setup isaacsim

ros
  ✓ ROS 2 distro — jazzy
  ✓ ros2 CLI — /opt/ros/jazzy/bin/ros2

storage
  ✓ Disk (runs) — 412.9 GiB free

1 failure(s), 0 warning(s)
exit code: 1

Example — one section, and scripting with exit codes

shellcaasi doctor -c nvidia --verbose
nvidia
  ✓ nvidia-smi — 550.107.02
    ↳ Install the NVIDIA driver if this check fails.
  ✓ GPU 0 — NVIDIA GeForce RTX 4090 (24564 MiB)
  ✓ CUDA — 12.4
caasi doctor -q && echo ready || echo broken
broken

Example — the sections added in 0.2.0

On a machine with ROS 2 jazzy but no Isaac Sim, -c physics shows PhysX failing while Gazebo still passes:

shellcaasi doctor -c physics
Environment Diagnostics

Physics Engines
  ✗ PhysX — not found (extsPhysics/*physx*, exts/omni.physx*)
      ↳ Install it, or point Caasi at the renamed upstream with `caasi config set catalog.physics.physx.paths [...]`.
  • Newton — not found (newton-physics, newton, isaac-sim.newton.sh)
  • Warp — not found (warp, warp-lang)
  • MuJoCo — not found (mujoco)
  ✓ Gazebo — /opt/ros/jazzy/opt/gz_tools_vendor/bin/gz

✘ 1 issue(s) found, 0 warning(s). Run with --verbose for hints.
exit code: 1

PhysX is only discoverable inside an Isaac Sim install — its probe is a pair of extension globs under the isaacsim tool root — so without one it reports fail. Gazebo is found by its gz binary on PATH. Newton is probed as a pip distribution (newton-physics, newton) and as the isaac-sim.newton.sh launcher script, Warp as warp / warp-lang and MuJoCo as mujoco: metadata and filesystem only, nothing is imported. -c platform covers the foundation-model and teleop stacks the same way:

shellcaasi doctor -c platform
Environment Diagnostics

Foundation Models & Teleop
  ✗ GR00T repository — not found (GR00T_PATH, ~/Isaac-GR00T, ~/gr00t, ~/workspaces/Isaac-GR00T)
      ↳ Install it, or point Caasi at the renamed upstream with `caasi config set catalog.groot.repo.env [...]`.
  • gr00t package — not found (gr00t)
  • Cosmos package — not found (cosmos_predict1, cosmos1)
  • Cosmos CLI — not found (cosmos, ngc)
  • NuRec (neural reconstruction) — not found (nurec)
  ✗ Keyboard teleop — not found (teleop_twist_keyboard)
      ↳ Install it, or point Caasi at the renamed upstream with `caasi config set catalog.teleop.keyboard.packages [...]`.
  • Joystick teleop — not found (teleop_twist_joy, joy)

✘ 2 issue(s) found, 0 warning(s). Run with --verbose for hints.
exit code: 1

Both exit 1 because a core capability is missing — the same contract as the full report. caasi physics and caasi groot describe what Caasi delegates to once those probes succeed.

JSON output

shellcaasi doctor --json | jq '.summary'
{
  "checks": [
    { "section": "nvidia", "name": "nvidia-smi", "status": "ok",
      "detail": "550.107.02", "hint": null },
    { "section": "isaac", "name": "Isaac Sim", "status": "fail",
      "detail": "Isaac Sim not detected",
      "hint": "Install it or register a path: caasi setup isaacsim" }
  ],
  "summary": { "ok": 11, "warn": 0, "fail": 1, "skip": 4 },
  "exit_code": 1
}

status is one of ok warn fail skip.

Exit codes

Code	Meaning
`0`	No check reported `fail` (warnings are fine).
`1`	At least one check failed, or `--component` named an unknown section.

Note: --quiet wins over --json — doctor -q --json prints nothing.

caasi gpu

Inspects NVIDIA GPUs by querying nvidia-smi — no NVML bindings, no imports. If nvidia-smi is missing or fails, every subcommand exits 1 with Error: GPU information unavailable (…).

caasi gpu status

One-line-per-GPU overview: name, VRAM, utilization, temperature, power, driver/CUDA.

caasi gpu status [--json]

shellcaasi gpu status
GPU  Name                     VRAM            Util  Temp  Power  Driver / CUDA
0    NVIDIA GeForce RTX 4090  3.0 / 24.0 GiB  12%   46°C  28 W   550.107.02 / CUDA 12.4
caasi gpu status --json | jq '.gpus[0]["memory.used"]'
3111

JSON payload: {"cuda": "12.4", "gpus": [ … ]}; each GPU object carries index, name, driver_version, memory.total, memory.used, memory.free, utilization.gpu, temperature.gpu, power.draw.

caasi gpu info

Static hardware identity per GPU — useful for bug reports and inventory.

caasi gpu info [--json]

shellcaasi gpu info
GPU 0
  Name         NVIDIA GeForce RTX 4090
  UUID         GPU-9c1e2b34-…
  Serial       (not available)
  PCI          00000000:0B:00.0
  Compute cap. 8.9
  ECC          Disabled
  Driver       550.107.02
  CUDA         12.4

caasi gpu memory

VRAM overview plus the compute processes currently occupying the GPUs (answer “who is eating my VRAM?”).

caasi gpu memory [--json]

shellcaasi gpu memory
GPU Memory
GPU  Name                     VRAM             Free
0    NVIDIA GeForce RTX 4090  17.8 / 24.0 GiB  6.2 GiB
Compute Processes
PID    Process                   VRAM
48213  /opt/isaac-sim/python.sh  17.47 GiB
caasi gpu memory --json | jq '.compute_apps'
[ { "gpu_uuid": "GPU-9c1e…", "pid": 48213,
    "process_name": "/opt/isaac-sim/python.sh", "used_memory_mb": 17890 } ]

caasi gpu doctor

Just the nvidia and graphics doctor sections: driver, every GPU, CUDA, Vulkan and the display server. It shares the caasi doctor contract — exit 0 when no check failed, 1 as soon as one does (warnings alone do not fail) — so it works as a readiness gate in front of a GPU job. A missing nvidia-smi shows up here as a failed driver check rather than the Error: GPU information unavailable abort the query subcommands use; the exit code is 1 either way.

caasi gpu doctor [--verbose] [--json]

shellcaasi gpu doctor
✓ NVIDIA driver — driver 580.173.02
✓ GPU — NVIDIA GeForce RTX 3080, 10.0 GiB VRAM
✓ CUDA — CUDA 13.0 (driver-reported)
✓ Vulkan — libvulkan available
✓ Display server — display available
caasi gpu doctor --json | jq '{sections, exit_code}'
{
  "sections": [
    "nvidia",
    "graphics"
  ],
  "exit_code": 0
}

caasi gpu monitor

A live table — utilization, VRAM, temperature, power — refreshed in place until Ctrl+C stops it. --once prints a single sample and exits; --json implies a single sample and never loops. A transient nvidia-smi failure inside the loop is skipped, not fatal.

caasi gpu monitor [--interval SECONDS] [--once] [--json]

Option	Type	Default	Description
`--interval`	float ≥ 0.1	`2.0`	Seconds between refreshes.
`--once`	flag	off	Print a single sample and exit (for scripts).
`--json`	flag	off	Single sample as `{"interval": …, "gpus": [ … ]}`, using the same per-GPU keys as `gpu status`.

shellcaasi gpu monitor --once
GPU  Name                     Util  VRAM            Temp  Power
0    NVIDIA GeForce RTX 3080  19%   0.1 / 10.0 GiB  53°C  29.6 W
caasi gpu monitor --once --json | jq '.gpus[0]["memory.used"]'
71.0

caasi gpu test

Proves the GPU actually computes: verifies the driver responds, then runs a tiny CUDA matmul in a subprocess via PyTorch. If PyTorch is not importable the compute step is skipped with a warning (exit stays 0).

caasi gpu test

shellcaasi gpu test
Driver responds; 1 GPU(s) visible.
CUDA compute test passed (torch CUDA 12.4).
caasi gpu test; echo $?
0

Exit codes: 0 driver ok (and compute passed or skipped), 1 no nvidia-smi or the CUDA compute test failed. No --json.

caasi system

OS, CPU, RAM and process inspection, read from /proc and standard tools.

caasi system status

caasi system status [--json]

shellcaasi system status
OS                Ubuntu 24.04.1 LTS (x86_64)
Kernel            6.8.0-45-generic
CPU               AMD Ryzen 9 7950X 16-Core Processor (32 cores)
Load (1/5/15m)    1.24, 0.98, 0.71
RAM               41.2 / 62.7 GiB available
NVIDIA GPUs       1
Disk free (home)  412.9 GiB

JSON keys: os, kernel, arch, cpu, cores, load, ram_total_gib, ram_available_gib, gpu_count, disk_free_home. Always exits 0.

caasi system doctor

The system, hardware and storage doctor sections: OS, kernel, CPU, RAM and the free disk under paths.runs. Same exit-code contract as caasi doctor — 1 when a check failed, 0 otherwise; a warning (low RAM, tight disk) does not fail.

caasi system doctor [--verbose] [--json]

shellcaasi system doctor
✓ Operating system — Ubuntu 24.04.4 LTS
✓ Kernel — 6.8.0-139-generic (x86_64)
✓ CPU — 12th Gen Intel(R) Core(TM) i7-12700K, 20 cores
! RAM — 15.4 GiB total, 9.9 GiB available
    ↳ Isaac workflows are memory-hungry; 32 GiB+ is recommended.
✓ Disk space — 25.1 GiB free at /home/you/.caasi/runs
caasi system doctor --json | jq '{group, sections, exit_code}'
{
  "group": "system",
  "sections": [
    "system",
    "hardware",
    "storage"
  ],
  "exit_code": 0
}

caasi system memory

caasi system memory [--json]

Detailed /proc/meminfo breakdown: total_gib, available_gib, free_gib, buffers_gib, cached_gib, swap_total_gib, swap_free_gib. Exits 1 if /proc/meminfo cannot be read (Linux only).

caasi system processes

caasi system processes [--limit|-n N] [--json]

Option	Short	Type	Default	Description
`--limit`	`-n`	int	`10`	Number of processes to show.
`--json`		flag	off	Machine-readable output.

Top processes by resident memory — via ps -eo pid,user,pmem,rss,comm --sort=-rss, falling back to a /proc scan. JSON is an array of {pid, user, mem_percent, rss, command}. Always exits 0.

shellcaasi system processes -n 3
PID    User  Mem %  RSS        Command
48213  you   27.4   17890 MiB  python.sh
2210   you   3.1    2013 MiB   code
1874   root  0.8    512 MiB    Xorg

caasi info

One-screen summary of the CLI itself, your effective configuration, registered tools and everything Caasi was able to detect about the ecosystem.

caasi info [--json]

shellcaasi info
CLI
  Name        caasi
  Version     0.2.0
  Python      3.11.9 (/home/you/caasi/.venv/bin/python)
Configuration
  Language    en
  Sources     ~/.config/caasi/config.yaml
Registered tools
  isaacsim    6.0 → /opt/isaac-sim-6.0
Ecosystem (detected)
  Isaac Sim   6.0 (/opt/isaac-sim-6.0)
  Isaac Lab   (not detected)
  ROS 2       jazzy
  CUDA        12.4
  PyTorch     2.4.0
  TensorRT    (not detected)

JSON payload top-level keys: cli (name, version, python, executable, platform), config (language, sources), tools (one entry per resolved registry tool: version, path, python), and ecosystem (isaac_sim, isaac_lab, ros2, cuda, pytorch, tensorrt — null when not detected). Detection failures are data, never errors: exit code is always 0.

caasi version

caasi version [--json]        # or the global flag: caasi --version

shellcaasi version
caasi 0.2.0
caasi version --json
{
  "name": "caasi",
  "version": "0.2.0"
}

Previous← Overview NextConfiguration →

Caasi CLI 0.2.0 — these pages live in docs/ and need no build step. Source: github.com/a6y3ap/caasi.