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: 19 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] [--details SECTION] [--json]

Options

--details <section> renders the expanded Problem / Cause / Evidence / Impact / Action breakdown for a single section — the deep-dive behind the one-line check statuses. It is the deepest read-only view doctor offers, and everything it reports is still machine capability, never a project-compatibility verdict (that is check).

What gets checked

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

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]

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]

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.3.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.3.0
caasi version --json
{
  "name": "caasi",
  "version": "0.3.0"
}

caasi env

The env group turns the read-only inspection above into a stable, comparable fingerprint of the machine and toolchain. Five subcommands: inspect shows a live panel, fingerprint collects one and prints its hash, lock records resolved component versions, compare diffs two fingerprints and show reprints a stored one. Only fingerprint --save and lock write anything; the rest are read-only.

caasi env inspect

A live “CPU-Z”-style panel of everything Caasi can see right now, grouped into system, cpu, memory, gpu, nvidia, compilers, python, ros, isaac, docker and git. Nothing is collected or stored — it is caasi info widened to the whole machine.

caasi env inspect

shellcaasi env inspect
system
  OS          Ubuntu 24.04.1 LTS (x86_64)
  Kernel      6.8.0-45-generic
cpu
  Model       AMD Ryzen 9 7950X (32 cores)
memory
  Total       62.7 GiB    Available  41.2 GiB
gpu
  0           NVIDIA GeForce RTX 4090 (24.0 GiB)
nvidia
  Driver      550.107.02    CUDA  12.4
compilers
  gcc         13.2.0
  clang       (not found)
python
  Version     3.11.9 (/home/you/caasi/.venv/bin/python)
ros
  Distro      jazzy
isaac
  Isaac Sim   6.0 (/opt/isaac-sim-6.0)
  Isaac Lab   (not detected)
docker
  docker      26.1.3 (daemon reachable)
git
  git         2.43.0

caasi env fingerprint

Collects the fingerprint and prints its stable hash, caasi-env-sha256:…. Volatile values — free memory, load, running processes, timestamps — are deliberately excluded, so the same machine and toolchain always produce the same hash. That determinism is what makes two fingerprints comparable across runs, machines and CI jobs. --save persists the snapshot under .caasi/environment/ as a set of *.yaml files plus fingerprint.json.

caasi env fingerprint [--save] [--json]

shellcaasi env fingerprint --save
Collected 11 groups (system, cpu, memory, gpu, nvidia, compilers, python, ros, isaac, docker, git).
Saved under .caasi/environment/ — environment.yaml, hardware.yaml, … + fingerprint.json.
caasi-env-sha256:9f2c1a7b4e8d3051c6a4b2e9d7f1038542ab6c9e1d4f7083b5c2a9e6d1f4078b
caasi env fingerprint --save --json | jq '.hash'
"caasi-env-sha256:9f2c1a7b4e8d3051c6a4b2e9d7f1038542ab6c9e1d4f7083b5c2a9e6d1f4078b"

caasi env lock

Records the resolved versions of the project's components into caasi.lock — the environment counterpart of a dependency lockfile, so a later audit can tell whether today's machine still matches the one that produced a result.

caasi env lock [--json]

shellcaasi env lock
Locked resolved component versions into caasi.lock.

caasi env compare

Diffs two fingerprints and reports only the meaningfully-different components — the volatile values excluded at collection time never surface as noise. With no arguments it compares the latest stored fingerprint against the live environment; pass one or two stored names or hashes to compare snapshots instead.

caasi env compare [left] [right] [--json]

caasi env show

Prints the stored fingerprint and its hash without re-collecting anything — the cheap way to read back what fingerprint --save wrote.

caasi env show [--json]

shellcaasi env show && caasi env compare
Stored fingerprint
  Hash       caasi-env-sha256:9f2c1a7b4e8d3051c6a4b2e9d7f1038542ab6c9e1d4f7083b5c2a9e6d1f4078b
  Collected  2026-09-09T10:15:02Z
  Groups     11

Comparing caasi-env-sha256:9f2c1a7b…078b → live environment
  ~ nvidia.driver   550.107.02 → 555.42.02
  ~ isaac.sim       6.0 → 6.1
  = 9 other groups unchanged (volatile values excluded)
Result: 2 meaningful difference(s)

caasi check

The second verb: can this work here? Where doctor asks whether the machine is capable, check asks whether this project — or one specific run — is compatible with the machine it is about to execute on. It is a preflight gate, and it requires a project: outside one it fails with a project init hint instead of guessing what to check. See the five-verb rule for how check relates to doctor, test, validate and audit.

caasi check [project|run] [QUERY] [--json]

The root check is an orchestrator: it runs only the checkers relevant to the project's registered components and merges them into a single report. The domain specialists — sim check, container check and control check — emit the same Check Contract for their own slice. There is no check sim alias: the scope argument is project or run, never a domain.

The Check Contract

Every check entry point — root or specialist — returns the same uniform JSON: a list of CheckItems wrapped in a CheckReport.

CheckItem {
  name           string    // what is being checked, e.g. "isaac_sim"
  required       bool      // must it be present for this project?
  detected       string    // the value found, or empty when absent
  compatibility  enum      // "compatible" | "untested" | "missing" | "incompatible"
  note           string    // human context / fix hint
}

CheckReport {
  scope      string        // "project" | "run" for the orchestrator; the domain for a specialist
  items      CheckItem[]   // one entry per thing checked
  missing    string[]      // names of required-but-missing items
  warnings   string[]      // names that are untested or otherwise need attention
  result     enum          // "ready" | "warning" | "incompatible"
}

The confidence ladder

The human report renders each item's compatibility as one rung of a ladder, then collapses the whole report to a single Result: line.

The human report prints the verdict as an uppercase Result: READY|WARNING|INCOMPATIBLE line, and check exits 3 when that result is incompatible — a hard preflight failure — so it drops straight into CI and launch scripts as a gate.

shellcaasi check
Preflight check — project: wave-demo

  VERIFIED      isaac_sim     6.0 (required)
  COMPATIBLE    ros2          jazzy
  UNVERIFIED    pytorch       2.4.0 (not validated against Isaac Sim 6.0)
  WARNING       tensorrt      not detected

Result: WARNING
caasi check --json | jq '.result'
"warning"
caasi sim check --json | jq '.scope'
"sim"