# Command reference Install this checkout in a Python 3.10–3.13 environment with `python -m pip install -e ".[dev]"`. See [Agent setup](AGENT_SETUP.md) for platform-specific setup. The editable install connects both package roots. ## Onboard ```bash python scripts/onboard.py --help python scripts/onboard.py inspect --profile python scripts/onboard.py build-mjcf --output python scripts/onboard.py extract-tier1 env.yaml agent.yaml --model --output python scripts/onboard.py adapt-tier1 --metadata --model --output python scripts/onboard.py adapt-tier1 --config env.yaml --config agent.yaml --overrides reviewed.json --model --output python scripts/onboard.py setup-tier2 --model --config --output python scripts/onboard.py calibrate --model --config --report python scripts/onboard.py verify --model --config --report python scripts/onboard.py scaffold-tier3 --config --calibration ``` Each subcommand has its own `--help`. `inspect` accepts optional `--policy`, `--metadata`, and `--mesh-root`. In an asset directory, `build-mjcf` searches recursively for one URDF or MJCF, or one STL, OBJ, or MSH when there is no model. Pass a file explicitly when the directory has several candidates at the selected level. The requested output path is excluded from the search. `--floating-base` adds a free URDF root, `--mesh-root` extends URDF asset search, `--mesh-scale` scales standalone meshes, and `--visual-fallback` opts into approximate URDF collision geometry. Choose fresh report and output paths unless the command explicitly allows replacement. Calibration and verification emit JSON and return a failing status when the requested checks fail. `extract-tier1` reads selected YAML, JSON or static Python training configs. Use `--overrides` to supply reviewed JSON or YAML values and `--report` for a separate extraction report. The output directory contains `metadata.json` and `manifest.json`, including on an incomplete extraction with exit status 1. Review the provenance and unresolved fields. Adapt from a manifest with `ready: true`, or supply the same reviewed inputs through repeated `--config` arguments in place of `--metadata`. See the [Tier 1 walkthrough](CONTROLLER_SETUP.md#extract-metadata-from-upstream-configs). ### Python API ```python from mjrl.onboarding import build_mjcf, calibrate_model, inspect_asset, scaffold_task, verify_model intake = inspect_asset(source, profile=profile) build = build_mjcf(source, model_path) calibration = calibrate_model(model_path, stance_config) verification = verify_model(model_path, probe_config, base_dir=config_directory) registration = scaffold_task(robot_config, base_dir=config_directory, calibration=calibration) ``` These functions return report dictionaries. The profiles and configs are Python mappings. `base_dir` resolves relative verification configuration paths and defaults to the model's directory for verification. Scaffolding requires `base_dir` for relative model and controls paths. Supply `tasks_root` to write the specification into a different task directory. Use `mjrl.onboarding.extract_policy_metadata` for programmatic Tier 1 metadata extraction and readiness diagnostics. Pass a sequence of config paths and, if available, the compiled MuJoCo model and a mapping of reviewed overrides. ```python from mjrl.onboarding import extract_policy_metadata extraction = extract_policy_metadata( [env_config_path, agent_config_path], overrides=reviewed, model=compiled_model ) ``` The result contains the canonical draft under `metadata` and the readiness and provenance fields written by the CLI. ### Robot specification The calibrated scaffold config names `robot_id`, `family`, `model_path`, and `action_scales` keyed by calibrated position-joint name. It can also name `controls_path`, `velocity_joints`, `foot_sites`, `penalized_contact_geoms`, and `termination_contact_geoms`. Model and controls paths resolve relative to the input JSON. The calibration must match the model XML and compiled dependencies. Optional `posture_stds` is an exact-name map covering every calibrated position joint with a positive finite value. Scaffolding writes these values into each joint's `posture_std` and consumes the top-level map; omitting it uses `0.35`. Without `--calibration`, give a full `RobotSpec` from verified model facts. This example shows the file shape: ```json { "robot_id": "sample_biped", "family": "biped", "model_path": "assets/sample_biped/robot.xml", "base_body": "base", "base_height": 0.32, "foot_geoms": ["left_foot", "right_foot"], "penalized_contact_geoms": ["left_shin", "right_shin"], "termination_contact_geoms": ["torso"], "position_joints": [ {"name": "left_hip", "kp": 20, "kd": 1, "effort_limit": 8, "action_scale": 0.25, "home": 0.1}, {"name": "right_hip", "kp": 20, "kd": 1, "effort_limit": 8, "action_scale": 0.25, "home": 0.1} ] } ``` Use calibrated values for the robot. `base_height` is its standing root height. Each joint's `home` supplies its default joint position. Optional `armature` is additional inertia at that joint. Supply either `foot_geoms` or `foot_bodies`. Each named foot body needs named collision geoms directly on it. The minimum support counts are two for biped and wheeled biped, four for quadruped, and five for multipod. A wheeled biped also needs at least two named unlimited wheel hinges in `velocity_joints`, with `kp: 0`, positive `kd`, an effort limit, and a velocity action scale. Optional `posture_std` on each joint is its positive finite posture allowance in radians, defaulting to `0.35`. It supplies calibration data for the template's speed-dependent pose term, not a reward weight. Different joints can declare different allowances without adding robot-specific logic to the template. Optional `foot_sites` lists one unique, nonempty, unqualified MuJoCo site name per named foot support, in the same order as `foot_geoms` or `foot_bodies`. These sites provide authored measurement locations for foot-clearance terms. The default empty list preserves existing specifications without sites. A nonempty list must match the support count; use actual sites in the robot model. Full `RobotSpec` input and literal scaffolding preserve both fields. Scaffolding writes only `tasks//robot_spec.py` in the task tree. The robot ID is the task ID. Family values are `biped`, `quadruped`, `wheeled_biped`, and `multipod`. The controls file for a locomotion policy uses the body-frame `twist` term feeding `velocity_commands`, with `lin_vel_x`, `lin_vel_y`, and `ang_vel_z` in that order. A new biped defaults to W/S for forward/reverse and A/D for left/right yaw. To supply a custom layout, set `controls_path` in the input JSON. See the [control profiles](CONTROLS.md#training-template-controls) for wheeled and omnidirectional layouts. ## Train and replay ```bash python scripts/train.py --list python scripts/train.py --task --dry-run python scripts/train.py --task --backend native --device cpu --num_envs 64 --headless python scripts/train.py --task --resume --max-iterations 100 python scripts/play.py --task --checkpoint --headless --steps 300 --speed 0 --measure ``` Use `--backend warp --device cuda` for the GPU path. Explicit requests fail when their device is unavailable. Native starts at 64 parallel environments and Warp at 4096 when no count is set. Start with fewer for an execution smoke or an asset with high memory use. Warp constraint and contact capacities can be set with positive integers using `--warp-max-constraints N` and `--warp-max-contacts N`. Constraints are capped per world. Contacts share a pool sized from the per-world setting and the environment count. A Warp buffer overflow stops the run before it uses the affected observations. For example, the G1 flat setup uses `--warp-max-constraints 300`. EPA horizon overflow is a separate convex-collision scratch-buffer limit; increasing contact or constraint pools does not enlarge it. The checked Warp backend reserves at least 128 horizon entries before capturing simulation graphs (MuJoCo Warp 3.11 defaults to 24), preserves larger upstream buffers, and records the effective size. It still stops on every reported overflow. A Warp run saves selected and effective capacities in `warp-allocation.json` beside its checkpoints. Warp resume, replay, and export read this file when present. Explicit flags take precedence. Otherwise, the larger of the saved capacity and the task or scene requirement is used. Without a run record or a configured capacity, Warp chooses the size. Training logs to `logs////`. The default `--logger` is `tensorboard`. Use `--no-tensorboard` to skip starting its server. `--max-iterations` caps this invocation. `--resume` selects the latest checkpoint and `--checkpoint` selects a particular one. Both restore the optimizer, iteration, and curriculum state. On resume, `--max-iterations` is the number of additional iterations. Replay retains actor observation noise by default. Use `--no-obs-noise` for a clean comparison. `--checkpoint-command-ranges` restores the checkpoint's command curriculum ranges. To evaluate a fixed body command, use `--command VX VY YAW --evaluation-out ` with a trained checkpoint and positive `--steps`. `--measure` records joint signals. Use `--physics-hz` only when deliberately evaluating a different integration rate. The default task simulation rate comes from its template. Built-in scenes work in training and replay. Imported `.map` scenes are replay-only. Rough terrain uses explicit nominal dimensions, not a hidden robot model: `--terrain-robot-height 0.25`, `--terrain-stance 0.40`, and `--terrain-foot-lift 0.04` (metres). With `--scene rough`, set these to the calibrated asset's dimensions when comparing terrain difficulty. Height and stance scale vertical and horizontal obstacles independently; foot lift sets continuous roughness. The Python scene arguments are `robot_height`, `stance`, and `foot_lift`. All must be finite and positive. ## Export and package ```bash python scripts/export.py --task --checkpoint --out python scripts/deploy.py --robot --model --bundle python scripts/play.py --app /.app --headless --steps 100 ``` Export writes the actor, its layout, a checkpoint copy, and a README. It checks observation and action dimensions, home pose, and ONNX parity. Add `--native-layout` to export a replay-ready native model and controller next to the policy. Hybrid position and velocity actions automatically use the native layout. Legacy Rust consumers accept their position-action layout. See [Controller setup](CONTROLLER_SETUP.md#native-hybrid-policy-export). A model-only build creates a viewer app. A controlled native build includes `--control `, `--verification `, and `--controls ` when the report verified operator bindings. For a compatible ONNX mode, also pass `--policy `. For multiple modes, use `--platform-manifest `. See the [bundle format](../deploy/BUNDLE.md) for mode fields and runtime requirements. The legacy target flags build the separate Rust bundle format. ## Defaults Precedence is command line, shell environment, `.env.local`, `.env`, then the argument default. Copy `.env.example` to `.env` to set local defaults. A blank task means a task is required on task entry points. A blank model selects the robot's registered model. The effective defaults are: ```dotenv MJRL_TASK= MJRL_MODEL= MJRL_SCENE= MJRL_TERRAIN_ROW= MJRL_TERRAIN_COL= MJRL_BACKEND=auto MJRL_DEVICE=auto MJRL_NUM_ENVS= MJRL_PLAY_NUM_ENVS=1 MJRL_CPU_THREADS=0 MJRL_STRIP_VISUAL=auto MJRL_TENSORBOARD=on MJRL_TB_PORT=6006 ``` The terrain row and column select one rough-terrain tile when set. Native `MJRL_CPU_THREADS=0` selects threads automatically. Native visual stripping can reduce per-environment memory and affects camera sensor appearance. TensorBoard binds to localhost and skips occupied ports.