Command Line Interface (CLI)
The Space Robotics Bench provides a comprehensive command-line interface that allows you to interact with most aspects of the framework through a unified interface. The CLI is structured as a set of subcommands, each with its own set of options.
srb <subcommand> [options]
If you need help with a specific subcommand, you can use the -h/--help flag:
srb --help
srb <subcommand> -h
You can also TAB your way through the available subcommands and options via autocompletion:
srb <TAB> <TAB>
Subcommands
The following subcommands are available in the CLI:
| Subcommand | Description |
|---|---|
agent | Agent subcommands (listed below) |
real_agent | Sim-to-real bridge code generation and runtime |
dataset | Inspect, validate, convert, replay, and publish datasets |
model | Package, validate, and publish trained policy checkpoints |
list/ls | List registered assets, action groups and environments |
asset | Manage planetary surface assets, rock sets, sky-domes, and lighting presets |
event-camera | Manage event-camera weights and backend metadata |
ephemeris | Query real Sun/planet geometry, fetch SPICE kernels, import illumination products |
cache | Regenerate generated SRB offline caches |
gui | Launch the Graphical User Interface |
isaac/isaacsim | Isaac Sim utilities (sim, python) |
docs | Build docs and render asset/task thumbnails |
test | Run Python and/or Rust test suites |
clean | Remove cached files (SRB / Isaac Sim / SimForge) |
completions | Manage shell completions (cache + install scripts) |
Agent Subcommands
The agent subcommand is further separated into agent-specific subcommands:
srb agent <action> [options]
| Subcommand | Purpose |
|---|---|
zero | Run a simulation agent with zero-valued actions. |
rand | Run a simulation agent with random actions. |
teleop | Manually teleoperate the agent, directly or through a trained policy. |
ros | Drive the simulation agent from ROS 2 / Space ROS action topics. |
train | Train a reinforcement-learning policy in simulation. |
eval | Evaluate a trained policy in simulation. |
collect | Record demonstration datasets from human, policy, random, or zero controllers. |
learn | Train an imitation-learning policy offline from a demonstration dataset. |
tune | Optimize hyperparameters with Optuna (spawns training subprocesses per trial). |
Shared Agent Options
The following options are shared across the simulation-based agent subcommands (zero, rand, teleop, ros, train, eval, collect). The offline learn and tune subcommands do not launch Isaac Sim directly (tune spawns srb agent train subprocesses that do) and accept their own option groups.
| Argument | Description | Default |
|---|---|---|
-e/--env/--task ENV | ID of the environment | REQUIRED |
--cfg PATH | Hydra config YAML (DEFAULT/IGNORE/NONE/NULL recognised) | DEFAULT |
--headless | Run simulation without display | False |
--hide_ui | Disable Isaac Sim UI and force fullscreen | False |
--livestream {0,1,2} | Force livestreaming (0: off, 1: native, 2: WebRTC). -1 defers to LIVESTREAM env var | -1 |
--rendering_mode {performance,balanced,quality,xr} | Choose rendering preset | unset |
--xr | Enable XR mode for VR/AR applications | False |
--enable_cameras | Launch the rendering app for camera sensors (without video recording). Auto-enabled when the CLI activates a camera-backed sensor category (env.active_sensors=[…,visual] or event_camera), for camera-shipping demo envs, and by --video/--record-events/--snapshot — pass it explicitly only when none of those apply | False |
--kit_args STRING | Extra args forwarded to the Omniverse Kit | "" |
--interface [IFACE …] | Interfaces to enable (gui, ros) | [] |
--logdir/--logs PATH | Path to root logging directory | SRB_LOGS_DIR |
--video | Enable video recording | False |
--record-events/--record_events | Record event-camera rollouts with provenance. Scene materialization, observation delivery, and the recorder are wired, but no concrete event backend (v2e, Metavision, V2CE) ships in the default container image, so provider-backed rollout fidelity is unproven; use srb dataset record-events for the live synthetic path. | False |
--snapshot PATH | Capture a single rendered PNG after the initial reset, then exit (implies --enable_cameras) | unset |
--snapshot-warmup N | Render passes before the snapshot to let path-traced/anti-aliased accumulation converge | 16 |
--snapshot-settle N | Physics steps after the reset and before the snapshot, letting robots settle (0 disables) | 0 |
--perf | Run a performance test instead of the regular workflow | False |
--perf_output PATH | Output path of the performance report (or STDOUT) | STDOUT |
--perf_duration SEC | Maximum duration of the performance test in seconds (0 = unlimited) | 150.0 |
--repl [BACKEND] | Open an interactive Python REPL alongside the running simulation (ptpython/bpython) | unset |
Note: Trailing CLI tokens that do not match the registered options are forwarded to Hydra (
env.foo=bar,agent.lr=1e-3, …). Tokens after a literal--are forwarded to the underlying tool (e.g. pytest, cargo).
Event Camera Subcommands
srb event-camera manages event-camera weights and backend metadata:
| Sub-subcommand | Description |
|---|---|
srb event-camera fetch-weights | Download event-camera weights (SuperSloMo, E2VID, or V2CE) with SHA256 verification |
srb event-camera list-mirrors | List registered event-camera weight mirrors (SuperSloMo + E2VID + V2CE) |
srb event-camera fetch-fixture | Download an event-camera reference fixture (Gen4 HDF5) with SHA256 verification |
srb event-camera list-fixtures | List registered event-camera reference-fixture mirrors (Gen4 HDF5) |
srb event-camera backends | List registered event-generator backends (use --detailed for metadata) |
Cache Subcommands
srb cache manages generated SRB offline caches used by completions and the GUI:
| Sub-subcommand | Description |
|---|---|
srb cache update | Regenerate task, asset, config, enum, and GUI caches |
srb cache claim-clean-root [--target srb|isaacsim|all] | Add path- and inode-bound markers required by srb clean; only fixed cache paths may adopt existing content |
srb cache status [--json] [--strict] | Inspect generated cache files without launching Isaac Sim |
srb cache doctor | Validate generated cache payload shapes without launching Isaac Sim |
Completions Subcommands
srb completions manages shell-completion artefacts:
| Sub-subcommand | Description |
|---|---|
srb completions generate | Regenerate completion cache via srb cache update |
srb completions install | Install Fish/Bash/Zsh completion scripts |
Start a new shell after installation (or run exec "$SHELL" -l) so Bash and
Zsh load their new registrations. Hydra override candidates require jq and a
successful srb completions generate.