CLI
The roboloom commands. In a uv environment, prefix them with uv run. roboloom --version (-V) prints the version, and roboloom <command> --help lists each command's arguments. The CLI is a thin layer that calls the Python API and prints the result.
Choosing the configuration and devices
Each robot has one configuration (.roboloom/<robot>/config.yaml). [robot] in a synopsis is optional: when .roboloom/ holds a single robot, that one is used. A robot name (rakuda2) or a YAML file path also works. For commands that take other positional words, the first word is the configuration only when it names one (roboloom commission follower and roboloom commission rakuda2 follower, roboloom session home and roboloom session rakuda2 home are all valid).
Common options
Real hardware is the default. Most commands that read the configuration accept these (the commands whose table lists "Common options"):
| Option | Type | Default | Description |
|---|---|---|---|
--with A,B |
list of names | — | Enable launch options (what they requires is enabled too; what conflicts is disabled) |
--without A,B |
list of names | — | Disable launch options (also ones with default: true; options requiring them are disabled too) |
--mock |
flag | off | Use mock devices instead of the hardware |
--video-codec CODEC |
av1, libsvtav1, h264 |
the recorder YAML | Codec of storage: video images (omitted: the recorder YAML; when appending, the saved videos' codec; H.264 when neither says; Video codec) |
--experiment NAME |
name or path | — | An experiment file (configs/roboloom/<NAME>.yaml of the project, or a file path). It gives the robot, the options, what the nodes are given (the policy) and the dataset, and for record and infer the task, length, episodes and home. Values on the command line win (experiment files) |
--sensors A,B |
list of names | the configuration's defaults | Sensors to start and record ("" selects none; sensor selection) |
--observe A,B |
list of names | the policy YAML's observe |
Sensors the policy observes ("" selects none) |
--hardware has been removed; passing it is an error that suggests --mock. For how launch options are defined and the rules they follow, see Launch options.
Launcher
Running roboloom in a terminal (or roboloom launch) first opens the robot list: the robots with a .roboloom/<robot>/config.yaml, each with its dataset name and default options. In a terminal, run, record, and infer also open the launcher first unless --with, --without, or --plain is given; the command's arguments become its initial values. For the screens and keys, see the launcher on the operator screen page.
Before a hardware launch from a terminal, the CLI compares each Dynamixel node's EEPROM (Operating Mode, Current Limit) with the chosen options. If they differ, it prints the differences and writes them after the operator confirms (the same procedure as roboloom commission). For example, turning gravity on or off changes the leader's Operating Mode.
run operations
A running run takes these operations from the operator screen or from roboloom session.
| Input | Action |
|---|---|
start <task> |
Check readiness and start following and recording |
stop |
Stop following and recording (saving is a separate operation) |
save |
Save the episode |
discard |
Discard the episode |
release |
Stop following and release actuated inputs and followers after confirming support |
home |
Move the leader and follower slowly to the initial pose chosen in the controller; after arriving the leader returns to its normal laws |
estop |
Emergency stop |
quit |
Open the exit confirmation: Cancel, follower hold, choose options again, or supported release |
The Textual operations menu shows unavailable actions with reasons, including home without a configured pose. Ctrl-L opens the editable command input; Ctrl-G requests emergency stop. Ctrl-C and Ctrl-Q open the same exit dialog, initially selecting Cancel. See Operator screen for keys, panes, confirmations, fixed-duration modes, and extension contracts.
run --plain retains line input; record --plain and infer --plain collect without key input. Non-TTY invocation selects these paths automatically (no launcher). tune-gravity requires a TTY before device open. Python API Rich displays and prompts retain their existing behavior.
stop does not turn off torque. FAULT / ESTOP / RELEASED do not recover automatically. The start and shutdown procedure on hardware is in Rakuda2: teleoperated collection.
Sensor selection
--sensors camera,audio --observe camera selects the sensors to start and record independently from the sensors the policy observes; --sensors "" --observe "" selects none. The launcher provides separate sensor and observation checkboxes and remembers selections. The rules are in Sensor selection; selecting from Python is shown in Session.
Commands
| Command | Purpose |
|---|---|
launch |
Open the launcher (same as roboloom [robot]) |
init |
Generate the robot configuration |
skills |
Install or check the Agent Skill for coding agents |
validate |
Validate the configuration and dataflow without opening devices |
run |
Collect with the operator screen |
record |
Collect episodes of a fixed length |
infer |
Run episodes with a policy |
session |
Send an operation to a running run |
serve-policy |
Serve a policy from another process |
check-dataset |
Check a recorded dataset |
label |
Give a saved episode its evaluation verdict |
convert-handheld |
Turn a hand-held recording into a training dataset |
setup |
Find which device is which node and write it to the configuration (PiPER, Pika) |
probe |
Inspect a bus or device read-only |
calibrate-joints |
Save the measured counts at the URDF zero pose |
measure-travel |
Save the range of motion moved by hand |
identify-gravity |
Identify the gravity model |
capture-pose |
Save a follower's current pose |
commission |
Bring the EEPROM in line with the configuration |
watchdog-test |
Bench test: the Bus Watchdog |
check-hold |
Bench test: does a follower keep its pose once commands stop |
tune-gravity |
Tune gravity compensation interactively |
gravity-check |
Measure the change in pose with and without compensation |
calibrate-joints, measure-travel, identify-gravity, commission, watchdog-test, tune-gravity and gravity-check are for Dynamixel robots only (probe reads Dynamixel, PiPER, Pika Gripper and Pika Sense); given a node that is not Dynamixel, they refuse and say why. commission, watchdog-test, check-hold, and gravity-check refuse a mock configuration.
A bus is opened by one process at a time: opening the bus a dataflow uses with probe or tune-gravity (or the other way round) stops the second one with ... is in use by another process.
roboloom launch
Open the launcher, choose the operation (run, record, infer) and the options, then start (Launcher).
roboloom [robot] [COMMON_OPTIONS]
roboloom launch [robot] [COMMON_OPTIONS]
| Option | Type | Default | Description |
|---|---|---|---|
robot |
robot name or path | the only robot | Given, the robot list is skipped and the next screen opens |
| Common options | — | — | Common options; they become the launcher's initial values |
uv run roboloom # launcher
roboloom init
Generate the robot configuration (.roboloom/<robot>/) from a template (the shipped templates are rakuda2 and piper-pika).
roboloom init <robot> [--root DIR] [--template PACKAGE_OR_DIR] [--update]
| Option | Type | Default | Description |
|---|---|---|---|
robot |
str | required | Robot name; the project is named after it |
--root DIR |
path | .roboloom |
Parent directory of the project |
--template PACKAGE_OR_DIR |
package or path | the shipped template | Make it from a template roboloom does not ship: a package holding template/ (my_lab.robots.arm) or a directory (From your own package) |
--update |
flag | off | Bring an existing project up to the installed template: add missing files, replace files still as they were copied, and leave edited and measured files alone, listing the keys and options only the template has |
uv run roboloom init rakuda2
roboloom skills
Copy the Agent Skill for coding agents into your project's .agents/skills/ and .claude/skills/ (install), check that the copies match this version (check; exit status 1 otherwise), or print where the packaged skill is (path). Opens no device ("Use with coding agents" in Installation).
roboloom skills install|check|path [--agent all|agents|claude] [--root DIR] [--force]
| Option | Type | Default | Description |
|---|---|---|---|
action |
install, check, path |
required | What to do |
--agent |
all, agents, claude |
all |
Which agents' skills directory (agents: .agents/skills, claude: .claude/skills) |
--root DIR |
path | . |
The project root |
--force |
flag | off | Replace a copy that differs |
uv run roboloom skills install
roboloom validate
Validate the configuration and dataflow without opening devices. Prints the enabled options, the dataset name and the video codec.
roboloom validate [robot] [COMMON_OPTIONS]
| Option | Type | Default | Description |
|---|---|---|---|
robot |
robot name or path | the only robot | The configuration to validate |
| Common options | — | — | Common options (including --experiment) |
uv run roboloom validate --with digit
roboloom run
Start the dataflow and keep collecting with the operator screen (run operations).
roboloom run [robot] [--plain] [COMMON_OPTIONS]
| Option | Type | Default | Description |
|---|---|---|---|
robot |
robot name or path | the only robot | The configuration to start |
--plain |
flag | off | A line-by-line prompt instead of the fixed screen (no launcher either) |
| Common options | — | — | Common options |
uv run roboloom run --with gravity # start without the launcher
uv run roboloom run --mock # mock devices
roboloom record
Collect episodes of a fixed length, then exit. Select Start for each episode once ready (Operator screen).
roboloom record [robot] --task TEXT --seconds N [--episodes N] [--home] [--plain] [COMMON_OPTIONS]
| Option | Type | Default | Description |
|---|---|---|---|
robot |
robot name or path | the only robot | The configuration to start |
--task TEXT |
str | required (or task: in the experiment file) |
Task text stored with every frame |
--seconds N |
float | required (or seconds: in the experiment file) |
Length of an episode, in seconds |
--episodes N |
int | 1 | Number of episodes |
--home |
flag | off | Move to the controller's initial pose before every episode |
--plain |
flag | off | Collect without key input |
| Common options | — | — | Common options |
When the experiment file gives steps:, pass --seconds (steps count a policy's actions and do not apply to record).
uv run roboloom record --task "pick up the cup" --seconds 30 --home
roboloom infer
Run episodes with a policy. Enables the option policy automatically. Saves only with --task (Running a policy).
roboloom infer [robot] (--seconds N | --steps N) [--episodes N] [--home] [--policy MODULE:CALLABLE] [--policy-kwargs JSON] [--task TEXT] [--plain] [COMMON_OPTIONS]
| Option | Type | Default | Description |
|---|---|---|---|
robot |
robot name or path | the only robot | The configuration to start |
--seconds N |
float | this or --steps is required (or the experiment file) |
Length of an episode, in seconds |
--steps N |
int | — | End each episode after this many actions of the policy (at least 1; not together with --seconds) |
--episodes N |
int | 1 | Number of episodes |
--home |
flag | off | Move to the policy's initial pose before every episode (policy home) |
--policy MODULE:CALLABLE |
str | the YAML's factory |
The callable returning the policy |
--policy-kwargs JSON |
JSON | the YAML's kwargs |
Its arguments |
--task TEXT |
str | — | Task given to the policy; with it, runs are saved |
--plain |
flag | off | Run without key input |
| Common options | — | — | Common options |
uv run roboloom infer --seconds 20 --policy my_lab.policies:load
uv run roboloom infer --experiment drawer # configs/roboloom/drawer.yaml
roboloom session
Send one operation to a running run.
roboloom session [robot] <operation> [task]
| Option | Type | Default | Description |
|---|---|---|---|
robot |
robot name or path | the only robot | The configuration of the running run (whatever its options) |
operation |
one of below | required | start, stop, save, discard, home, estop, release, quit; with teleop: in the policy also teleop, policy, stop_teleop (teleoperation and interventions) |
task |
str | — | For start the task; for save the verdict (success or failure) |
uv run roboloom session home
uv run roboloom session save success # from another terminal: save with the verdict
roboloom serve-policy
Mock only
Serve a policy from this environment to a policy node with backend: server (another process). Reads no robot configuration.
roboloom serve-policy (<module:callable> | --from POLICY_YAML | --experiment EXPERIMENT_YAML) [--kwargs JSON] [--address HOST:PORT] [--authkey-env NAME]
| Option | Type | Default | Description |
|---|---|---|---|
policy |
module:callable |
— | The callable returning the policy (exactly one of this, --from, --experiment) |
--from POLICY_YAML |
path | — | Use the factory, kwargs and server.address of this policy node file (e.g. .roboloom/<robot>/nodes/policy.yaml) |
--experiment EXPERIMENT_YAML |
path | — | Use the factory, kwargs and server.address this experiment file (e.g. configs/roboloom/<name>.yaml) gives the policy |
--kwargs JSON |
JSON | the file's kwargs |
Arguments of the callable (replace the file's) |
--address HOST:PORT |
str | the file's server.address, else 127.0.0.1:18765 |
Where to listen |
--authkey-env NAME |
str | the file's server.authkey_env, else ROBOLOOM_POLICY_AUTHKEY |
Environment variable holding the shared secret |
uv run roboloom serve-policy --from .roboloom/rakuda2/nodes/policy.yaml
roboloom check-dataset
Check a recorded dataset by reading it only: episode counts against the files, video length against the rows, the share of rows whose valid is 0, the count of verdicts. Exit code 1 when something is wrong (Checking the data).
roboloom check-dataset [robot | DATASET_DIR] [--recover] [COMMON_OPTIONS]
| Option | Type | Default | Description |
|---|---|---|---|
robot |
robot name or path, or a dataset directory | the only robot's dataset | The dataset to check; select a dataset whose name an option changes with --with |
--recover |
flag | off | First remove an episode whose save was interrupted (Saved episodes) |
| Common options | — | — | Common options (--with, --without and --experiment decide the dataset name) |
uv run roboloom check-dataset --with digit
roboloom label
Give a saved episode its evaluation verdict, or change it. Appends to the dataset's meta/roboloom_episodes.jsonl and prints the count of verdicts (Episode records).
roboloom label [robot | DATASET_DIR] <episode> success|failure [--note TEXT] [COMMON_OPTIONS]
| Option | Type | Default | Description |
|---|---|---|---|
robot |
robot name or path, or a dataset directory | the only robot's dataset | The dataset; select a dataset whose name an option changes with --with |
episode |
int | required | The episode's index in the dataset |
verdict |
success, failure |
required | The verdict |
--note TEXT |
str | — | Free text kept with the verdict |
| Common options | — | — | Common options (--with, --without and --experiment decide the dataset name) |
uv run roboloom label --with policy 3 failure # episode 3 of the evaluation dataset
roboloom convert-handheld
In development
Turn a hand-held recording (a configuration without followers) into a training dataset whose actions are relative poses (Hand-held collection).
roboloom convert-handheld [robot] [--action delta|relative-chunk] [--horizon N] [--hands A,B] [--max-gap N] [--output DIR] [--repo-id ID]
| Option | Type | Default | Description |
|---|---|---|---|
robot |
robot name or path | the only robot | The configuration that recorded (its dataset is read) |
--action |
delta, relative-chunk |
delta |
delta: one step inv(P[t]) P[t+1]; relative-chunk: inv(P[t]) P[t+k], k=1..horizon, in one row (train with chunk_size 1) |
--horizon N |
int | 16 | Steps of relative-chunk |
--hands A,B |
list of names | every pose | The pose inputs to convert |
--max-gap N |
int | 3 | Untracked rows filled per gap |
--output DIR |
path | <output>-<action> of the recording |
Where to write |
--repo-id ID |
str | <repo_id>-<action> |
Repo id of the result |
uv run roboloom convert-handheld --action relative-chunk --horizon 16
roboloom setup
In development Find which CAN interface, serial port and tracker is which PiPER, Pika Gripper and Pika Sense in the configuration, and write them to the node files. Devices are only read: nothing is enabled, moved, or zeroed. The steps are in PiPER + Pika: robot setup.
roboloom setup [robot] [--step check,can,arms,senses,trackers,grippers,validate]
| Option | Type | Default | Description |
|---|---|---|---|
robot |
str | the only one in .roboloom/ |
Robot configuration |
--step A,B |
list of steps | all (in this order) | Steps to run |
- Arms are found by turning the named arm's joint1 by hand, Senses by opening and closing them, trackers by moving the Sense, and Grippers by unplugging and replugging their USB. A device is assigned only when exactly one thing changed.
- Values already set are shown first; Enter keeps them and
rfinds the device again. - When a CAN interface is not up, the
sudo ip link ...commands to run are shown (not run). - It stops if any PiPER has its motors enabled (disabling makes the arm drop, so setup does not disable it).
uv run roboloom setup piper-pika
uv run roboloom setup piper-pika --step grippers
roboloom probe
Inspect a Dynamixel bus read-only: IDs, models, registers, and read times (a rough rate limit). Given a CAN interface such as can0 (a name without /), read the PiPER (in development) there: firmware, joint angles, state, enabling, temperatures and faults (enables and moves nothing). With --device pika, read the Pika Gripper (in development) on a serial port: version, angle, status bits, temperatures and feedback rates. With --device pika_sense, read a Pika Sense's (in development) serial link: version, jaw angle, Command and feedback rates.
roboloom probe <port> [--device dynamixel|pika|pika_sense] [--ids 1,2,3] [--baudrate N]
| Option | Type | Default | Description |
|---|---|---|---|
port |
str | required | Serial port (Dynamixel, Pika) or CAN interface (PiPER) |
--device |
dynamixel, pika, pika_sense |
dynamixel |
What is on a serial port (a CAN interface is a PiPER) |
--ids 1,2,3 |
list of integers | the IDs a broadcast ping finds | Dynamixel IDs to read |
--baudrate N |
int | 1000000 | Baud rate |
uv run roboloom probe /dev/ttyUSB0
roboloom calibrate-joints
Save measured counts at the URDF zero pose to the calibration. It does not write to the bus, but it saves local YAML. The arm torque must be off.
roboloom calibrate-joints <calibration> [--joints A,B]
| Option | Type | Default | Description |
|---|---|---|---|
calibration |
path | required | The calibration YAML |
--joints A,B |
list of names | every joint | Joints to record |
uv run roboloom calibrate-joints .roboloom/rakuda2/calibration/leader_right.yaml
roboloom measure-travel
Save the range of motion moved by hand. It does not write to the bus, but it saves local YAML. The arm torque must be off.
roboloom measure-travel <calibration> --out PATH
| Option | Type | Default | Description |
|---|---|---|---|
calibration |
path | required | The calibration YAML |
--out PATH |
path | required | Where to save the travel |
uv run roboloom measure-travel .roboloom/rakuda2/calibration/leader_right.yaml --out .roboloom/rakuda2/calibration/travel_right.yaml
roboloom identify-gravity
Measure holding current and identify the gravity model (leader gravity compensation, the follower model_residual estimator). --collect energizes the motors, so it asks the operator first.
roboloom identify-gravity <calibration> --out PATH [--collect] [--data NPZ] [--delta N] [--max-rms-mA X]
| Option | Type | Default | Description |
|---|---|---|---|
calibration |
path | required | The calibration YAML |
--out PATH |
path | required | Where to save the gravity model |
--collect |
flag | off | Collect new poses first (energizes the arm) |
--data NPZ |
path | next to --out |
npz of holding currents |
--delta N |
int | 30 | Approach offset, in counts |
--max-rms-mA X |
float | 15.0 | Largest RMS residual of the fit, in mA; above it the model is not saved |
uv run roboloom identify-gravity .roboloom/rakuda2/calibration/leader_right.yaml --out .roboloom/rakuda2/calibration/gravity_right.yaml --collect
roboloom capture-pose
Save a follower's current pose as poses/<follower>/<name>.yaml (moves nothing), for home.
roboloom capture-pose [robot] [follower] <name> [--force] [COMMON_OPTIONS]
| Option | Type | Default | Description |
|---|---|---|---|
robot |
robot name or path | the only robot | The configuration |
follower |
str | the only follower | The follower to read (may be omitted when there is one) |
name |
str | required | The pose name |
--force |
flag | off | Replace an existing pose |
| Common options | — | — | Common options |
uv run roboloom capture-pose ready
roboloom commission
Read a node's EEPROM (Operating Mode, Current Limit), compare it with the configuration, write after a diff and operator confirmation, then read it back.
roboloom commission [robot] <node> [COMMON_OPTIONS]
| Option | Type | Default | Description |
|---|---|---|---|
robot |
robot name or path | the only robot | The configuration |
node |
str | required | The Dynamixel node |
| Common options | — | — | Common options (options change the expected values) |
uv run roboloom commission leader --with gravity
roboloom watchdog-test
Bench test: check that the Bus Watchdog stops a current-mode motor (energizes it). The node needs bus_watchdog_ms.
roboloom watchdog-test [robot] <node> <joint> [--current-mA X] [COMMON_OPTIONS]
| Option | Type | Default | Description |
|---|---|---|---|
robot |
robot name or path | the only robot | The configuration |
node |
str | required | The Dynamixel node |
joint |
str | required | The joint to push |
--current-mA X |
float | 30.0 | Current to push with, in mA |
| Common options | — | — | Common options |
uv run roboloom watchdog-test leader r_arm_sh_pitch1 --with gravity
roboloom check-hold
Bench test: measure whether a follower keeps its pose once commands stop, and after confirmation write unattended: to its YAML (energizes it). Only for models that declare unattended unknown (Behaviour without torque and when left alone).
roboloom check-hold [robot] <follower> --tolerance X [--seconds N] [COMMON_OPTIONS]
| Option | Type | Default | Description |
|---|---|---|---|
robot |
robot name or path | the only robot | The configuration |
follower |
str | required | The follower to test |
--tolerance X |
float | required | Largest change still counted as holding, in the follower's unit |
--seconds N |
float | 10.0 | How long to watch after the commands stop, in seconds |
| Common options | — | — | Common options |
uv run roboloom check-hold left --tolerance 0.02 # PiPER's left
roboloom tune-gravity
Tune the leader's gravity compensation gain and hold joint by joint (energizes the arm). Requires a TTY before opening any device. Stop the dataflow that opens the same bus first. For the keys, see Gravity tuning.
roboloom tune-gravity [robot] <node> <group> [COMMON_OPTIONS]
| Option | Type | Default | Description |
|---|---|---|---|
robot |
robot name or path | the only robot | The configuration |
node |
str | required | The Dynamixel leader node |
group |
str | required | The gravity_comp group (e.g. right_arm) |
| Common options | — | — | Common options (--with gravity selects the gravity-compensated configuration) |
uv run roboloom tune-gravity leader right_arm --with gravity
roboloom gravity-check
At the same pose, release the arm once per multiple of the configured gains and measure the change in pose with and without compensation (energizes the arm).
roboloom gravity-check [robot] <node> <group> [--poses N] [--scales 1,0] [COMMON_OPTIONS]
| Option | Type | Default | Description |
|---|---|---|---|
robot |
robot name or path | the only robot | The configuration |
node |
str | required | The Dynamixel leader node |
group |
str | required | The control group (e.g. right_arm) |
--poses N |
int | 3 | Number of poses to try |
--scales 1,0 |
list of numbers | 1,0 |
Multiples of the configured gains to try at each pose (e.g. 1,0,2,-2) |
| Common options | — | — | Common options (--with gravity) |
uv run roboloom gravity-check leader right_arm --with gravity