Configuration

Caasi is configured with layered YAML files. There is no database, no daemon and nothing hidden: caasi config show always prints exactly what the CLI will use, and every command reads the same merged result.

Config files & precedence

Four file locations are merged, lowest precedence first:

Merging is a recursive dict merge: a project file that sets one key under tools: does not wipe the rest of the global registry. After merging, the CAASI_LANG environment variable (if set) overrides language.

Built-in defaults

language: en
defaults:
  output: table
paths:
  runs: ~/.caasi/runs          # where tracked runs live
  datasets: ~/.caasi/datasets  # where generated datasets go
tools: {}                      # the tool registry (see below)

A complete global config example

# ~/.config/caasi/config.yaml
language: en
paths:
  runs: /data/caasi-runs        # big disk for logs and artifacts
tools:
  isaacsim:
    default: "6.0"
    versions:
      "6.0": { path: /opt/isaac-sim-6.0 }
      "5.1": { path: /opt/isaac-sim-5.1 }
  isaaclab:
    versions:
      "2.0": { path: /opt/IsaacLab, python: /opt/IsaacLab/_isaac_sim/python.sh }
remotes:
  gpu-box:
    host: 10.0.0.5
    user: robot
    port: 2222
    identity: ~/.ssh/id_ed25519
    path: ~/experiments          # remote working directory

The tool registry

The registry is how you tell Caasi where your installs are — and which version to use when you have several side by side (very common with Isaac Sim). It lives under the top-level tools: key.

Multi-version form

tools:
  isaacsim:
    default: "6.0"              # which version commands resolve to
    versions:
      "6.0": { path: /opt/isaac-sim-6.0 }
      "5.1": { path: /opt/isaac-sim-5.1, python: /opt/isaac-sim-5.1/python.sh }

Single-install form

tools:
  isaaclab:
    path: /opt/IsaacLab
    python: /opt/IsaacLab/_isaac_sim/python.sh   # optional interpreter override

How a tool is resolved

1. With the multi-version form, the requested version is used; without one, default; without a default, the first version key in file order.
2. Version keys are compared as strings, so a float 6.0 default matches the key "6.0". Quoting version keys in YAML is recommended.
3. Resolution produces {name, version, path, python}; commands then derive their launchers from path: Isaac Sim → <path>/python.sh, Isaac Lab → <path>/isaaclab.sh (unless python is set).

Set registry entries with dotted keys (quote version segments):

shellcaasi config set tools.isaacsim.versions."6.0".path /opt/isaac-sim-6.0
Set tools.isaacsim.versions."6.0".path = /opt/isaac-sim-6.0 (saved to /home/you/.config/caasi/config.yaml)
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

Registry vs. environment variables

If a tool is not in the registry, Caasi falls back to detection (ISAACSIM_PATH/ISAACLAB_PATH env vars, common install locations, pip metadata — see Architecture). The registry always wins when present, and is the only way to manage multiple versions.

Remotes

The remotes: section defines SSH machines for the remote commands:

remotes:
  <name>:
    host: 10.0.0.5            # required — entries without host are ignored
    user: robot               # optional
    port: 2222                # optional
    identity: ~/.ssh/id_ed25519  # optional, ~ is expanded
    path: ~/experiments       # optional remote working directory

Commands accept the exact name or any unique prefix (caasi remote run gpu nvidia-smi matches gpu-box when unambiguous). Caasi only builds ssh command lines — keys, agents and ~/.ssh/config are honored because the system ssh client does the work.

caasi config

Inspect and edit the configuration from the command line.

caasi config show

caasi config show [--json]

Prints the merged effective configuration (human mode renders YAML; --json emits the same object). This is the ground truth of what Caasi will do.

shellcaasi config show
language: en
defaults:
  output: table
paths:
  runs: ~/.caasi/runs
  datasets: ~/.caasi/datasets
tools:
  isaacsim:
    default: '6.0'
    versions:
      '6.0':
        path: /opt/isaac-sim-6.0

caasi config get

caasi config get KEY

Reads one dotted key. Dicts and lists are printed as YAML, scalars as plain text. A missing (or null) key exits 1 with Error: Key '<key>' is not set.

shellcaasi config get paths.runs
~/.caasi/runs
caasi config get tools.isaacsim.versions
'6.0':
  path: /opt/isaac-sim-6.0

caasi config set

caasi config set KEY VALUE

• VALUE is parsed as YAML, so true, 42 and 6.0 become bool/number types; anything unparseable stays a string. Quote values you want to keep as strings (caasi config set tools.isaacsim.default '"6.0"').
• Intermediate dicts along the dotted path are created automatically.
• The result is persisted to the global config file — and note that set writes the fully merged configuration there, so afterwards the global file contains everything (defaults + project + env overrides folded in).

caasi config path

caasi config path

Shows the four possible sources, which of them are active, and the effective merge order — the fastest way to debug “why is my setting ignored?”.

shellcaasi config path
  ✓ --config                     (not set)
  ✓ CAASI_CONFIG                 (not set)
  ✓ Global config file           /home/you/.config/caasi/config.yaml
  • Project config file          ./caasi.yaml
Effective sources in merge order:
  /home/you/.config/caasi/config.yaml

caasi config tools

caasi config tools [--json]

Lists every registered tool with its default version, all versions, and the resolved {version, path, python} (or null when unresolvable). With no registry entries it prints a usage hint. Always exits 0.

shellcaasi config tools --json | jq '.isaacsim.resolved'
{
  "version": "6.0",
  "path": "/opt/isaac-sim-6.0",
  "python": null
}

Environment variables

Consumed by Caasi

Produced for child processes

Caasi sets these in the environment of everything it launches — your scripts can rely on them: