Language

CLI Reference¶

UniLab exposes package commands for common training and playback routes, and keeps the lower-level scripts available for debugging Hydra composition.

Unified Commands¶

Goal	Command Shape	Routed Script
PPO	`uv run train --algo ppo --task <task> --sim <backend>`	`src/unilab/scripts/train_rsl_rl.py`
APPO	`uv run train --algo appo --task <task> --sim <backend>`	`src/unilab/scripts/train_appo.py`
SAC	`uv run train --algo sac --task <task> --sim <backend>`	`src/unilab/scripts/train_sac.py`
TD3	`uv run train --algo td3 --task <task> --sim <backend>`	`src/unilab/scripts/train_td3.py`
FlashSAC	`uv run train --algo flashsac --task <task> --sim <backend>`	`src/unilab/scripts/train_flashsac.py`

Examples:

uv run train --algo ppo --task go2_joystick_flat --sim mujoco
uv run train --algo appo --task g1_motion_tracking --sim motrix training.no_play=true
uv run train --algo sac --task g1_walk_flat --sim mujoco training.no_play=true
uv run train --algo flashsac --task go2_joystick_flat --sim mujoco

The CLI builds the owner YAML path from --algo, --task, --sim, and optional --profile. Route-defining values must use the CLI flags; Hydra overrides after the command are for fields such as algo.max_iterations, algo.num_envs, and training.no_play.

Per-Environment Invocation¶

The CLI prefix depends on the install flavor:

ROCm: run make sync-rocm once, then use uv run ....
Intel XPU: use uv run --no-sync ....

Tab Completion¶

Shell completion is optional. It only completes the uv run train / uv run eval entrypoints, their flags, and some choices; it never changes command behavior. On a fresh checkout, one setup command syncs the environment and installs the completion:

# Full default environment (MuJoCo + Motrix):
make setup

# MuJoCo only:
# make setup-mujoco

# Motrix only (the shortest path for Motrix demos):
# make setup-motrix

make setup runs uv sync --extra mujoco --extra motrix followed by uv run --no-sync unilab-complete install; make setup-mujoco and make setup-motrix select only their named extra and install the same completion. Choose one setup path for an environment. The install command picks Bash or Zsh from $SHELL / platform and only writes user-level rc files. The current shell is not auto-activated; reopen the terminal or source the rc file to apply.

If make is unavailable, run the steps directly:

# Full default environment:
uv sync --extra mujoco --extra motrix
uv run --no-sync unilab-complete install

# Or choose one backend extra:
# uv sync --extra mujoco && uv run --no-sync unilab-complete install
# uv sync --extra motrix && uv run --no-sync unilab-complete install

Bash users (Linux / WSL) can instead add this to ~/.bashrc:

source scripts/completions/unilab.bash

Zsh users (default on macOS) can add this to ~/.zshrc:

autoload -Uz compinit
compinit
source scripts/completions/unilab.zsh

After reopening the terminal or sourcing the rc file, candidates appear for uv run <TAB>, uv run train --algo <TAB>, and uv run train --sim <TAB>.

Evaluation¶

uv run eval sets training.play_only=true and optionally maps --load-run to algo.load_run.

uv run eval --algo ppo --task go2_joystick_flat --sim mujoco --load-run -1
uv run eval --algo ppo --task go2_joystick_flat --sim motrix --load-run -1 \
  --render-mode record

Supported render modes are auto, interactive, record, and none.

The MuJoCo interactive mode (--sim mujoco --render-mode interactive) routes directly to play_interactive.py and always rolls out one environment.

Demo¶

uv run demo dance
uv run demo wallflip
uv run demo boxtracking
uv run demo inhandgrasp
uv run demo dance --refresh --device cpu

Available demos: teaser, dance, wallflip, boxtracking, inhandgrasp. Each demo fetches a pre-trained checkpoint from the unilabsim/unilab-checkpoints Hugging Face dataset on first run and caches it under src/unilab/assets/checkpoints/<demo>/model_0.pt. Pass --refresh to re-download.

Mainland China users: when huggingface.co is unreachable, switch to the community mirror before running the demo:

export HF_ENDPOINT=https://hf-mirror.com

The demo entrypoint is implemented by src/unilab/demo.py and routed from src/unilab/cli.py.

Low-Level Scripts¶

The lower-level scripts remain available when you need to inspect Hydra config groups or reproduce a script-level issue. For normal usage, keep route-defining values in the unified CLI flags above.

For off-policy routes, --algo selects the per-algorithm owner tree src/unilab/conf/<algo>/; do not include the algorithm name in --task.

Common Overrides¶

training.no_play=true
algo.max_iterations=10
algo.num_envs=128
algo.load_run=-1
training.logger=wandb

Use uv run eval ... --load-run ... for playback and --render-mode record or --render-mode none for render behavior.

Backend selection belongs to the CLI --sim choice and the resulting owner YAML. Do not use training.sim_backend=<backend> as a standalone switch.