Skip to content

Toolchain cheatsheet

Always use just and uv. Never pip install inside the workspace — use uv add <pkg> --package <member>. Never call colcon build outside just unless you know why.

Bootstrap (Ubuntu 22/24, macOS 14+)

just bootstrap                  # installs uv, ROS 2, system deps via scripts/

Python workspace

just sync                       # resolve & install all workspace deps
                                # (wraps `uv sync` + scripts/repair_hf_libero_install.py)
just sync --group robocasa      # + an opt-in dep group (sim / libero / robocasa / rldx / …)
just test                       # run unit tests (<30 s)
just test-doctest               # run docstring examples on the curated set
uv run pytest -k so100          # filter by keyword
just lint                       # ruff check + ruff format --check + mypy --strict
                                # (mypy targets: openral_core, openral_cli, openral_sim, tools/)
uv run ruff check . --fix       # autofix
uv run ruff format .            # format

ROS 2

just ros2-build                 # colcon build (msgs + hal_so100 + world_state + reasoner_ros
                                # + prompt_router + safety + safety_watchdog + safety_kernel
                                # + human_estop + skill_ros)
just ros2-test                  # colcon test + colcon test-result --verbose
source install/setup.bash       # after build

Sim

just sim-eval <config>          # canonical config-driven entry point — ADR-0002
                                # (`openral sim run --config FILE`)
just sim-libero                 # SmolVLA × LIBERO (real lerobot[libero]; needs GPU + MUJOCO_GL)
just sim-xvla-libero            # xVLA × LIBERO   (Florence-2 backbone)
just sim-pi05-libero            # π0.5 × LIBERO   (≥8 GB VRAM)
just sim-metaworld --task TASK  # SmolVLA × MetaWorld (e.g. --task metaworld/reach-v3)
just sim-act-aloha              # ACT × gym-aloha bimanual cube transfer
just sim-diffusion-pusht        # Diffusion Policy × gym-pusht (CPU)
just sim-custom                 # custom example — ACT × gym-aloha insertion

Hardware-in-loop (requires connected robot + USB perms)

just hil so100                  # SO-100 HIL tests
                                # (UR / Franka / G1 HIL are planned)

Docs

just docs                       # mkdocs serve at :8000
just docs-build                 # mkdocs build --strict (CI parity)
just schema-export              # regenerate JSON Schema (CI compares)

CLI (openral)

just quickstart automatically installs a ~/.local/bin/openral wrapper so you can run openral (or openral <cmd>) from any terminal without just. To install or re-install it independently (e.g. after moving the repo):

just install-cli

The wrapper sources the ROS 2 distro overlay and the colcon workspace overlay before delegating to .venv/bin/openral, so ROS 2 node/topic/action commands work transparently. Pure-Python commands (openral doctor, openral detect, etc.) still work even if ROS 2 is not yet built.

Bare openral (no args) drops into an interactive REPL where subcommands run without the prefix (sim run --config …); pass a subcommand for one-shot mode in scripts/CI. See ADR-0021.

openral doctor                   # diagnose host: Python, OS, ROS 2 distro, GPU, USB
openral detect                   # auto-detect robot + sensors + GPU; write a full robot.yaml
openral connect --robot so100    # open a HAL connection (only so100 wired today)
openral calibrate camera --sensor S  # ros2 camera_calibration helper
openral install sim              # post-install opt-in dep groups (ADR-0021)
openral install ros              # re-run scripts/bootstrap_ubuntu.sh (sudo)
openral install list             # show every known dep group
openral skill install <hub-id>   # download an rSkill from HF Hub (license-gated)
openral skill list               # list installed rSkills
openral skill new <id>           # scaffold a new local rSkill from rskills/template/
openral sensor list              # browse the sensor catalog
openral sensor show <id>         # resolve a catalog entry to a SensorSpec/Bundle
openral benchmark report         # aggregate rskills/<id>/eval/*.json benchmark blocks
openral sim run --config FILE    # run a SimEnvironment YAML end-to-end (ADR-0009)

Planned (not yet wired): openral run, openral benchmark run.

Tooling self-help

  • openral prints AMENT_TRACE_SETUP_FILES: unbound variable and exits? Your ~/.local/bin/openral predates the fix that sources the (not-set -u-safe) ROS 2 overlays with nounset disabled. Re-run just install-cli to regenerate it.
  • Python import unclear? uv run python -c 'import openral_<pkg>; print(openral_<pkg>.__file__)'.
  • ROS 2 topic missing? ros2 topic list -t in a source install/setup.bash-ed shell.
  • Schema diff? just schema-export and check git diff python/openral_core/schemas/.
  • CI flake? Re-run once. If it flakes again, triage with the flake label and don't merge.
  • Hardware test fails on a runner? Check the runner's e-stop log first. Never push a "fix" that makes a hardware test pass without understanding why it failed.
  • Out of GPU memory? Lower batch / quantize / use a smaller skill variant — never silently downcast or skip frames.
  • uv sync fails with "Unable to uninstall hf-libero==0.1.3. distutils-installed distributions..."? The PyPI sdist for hf-libero drops a spurious top-level *.egg-info FILE next to the proper .dist-info/ directory; uv then misclassifies the install as distutils-built. Run just sync <flags> instead of uv sync <flags> — the wrapper pre/post-runs scripts/repair_hf_libero_install.py to strip the bogus file + RECORD line. Idempotent and safe on every host.
  • No module named 'openral_core' after switching dependency groups? You ran bare uv sync --group <x>. Without --all-packages that syncs only the workspace root and uninstalls every editable openral-* member, so the next REPL / openral deploy sim can't import the workspace. Always use just sync, which forces --all-packages for you (unless you scoped to a single --package/-p) — just sync --group robocasa is equivalent to uv sync --all-packages --group robocasa. Repair an already-broken venv with just sync --all-packages.