This page is ora --help and every command's --help, generated from the
parser (ora/app/main.py and one module per command group in ora/app/). The
command guide explains what each command writes and
when to use it. A command that hands the rest of its line to an operator tool
lists the tool here; ora COMMAND ... --help prints the tool's own arguments.
ora --help
ora — Open Robot-Use Agents
Run an episode
setup install the local environment or one simulator
doctor check the host, credentials, simulators and services
run compose, preflight, launch and seal one episode
play free play in one scene
replay replay a finished run in the browser, export a video, or check its replay program
web a live run in the browser
cameras a run's cameras in the terminal, beside its conversation
interactive run ORA in Pi's terminal UI and steer it
attach show a running run's terminal UI here
sessions list runs with Pi sessions, or export one
local the local CPU MuJoCo task picker
Formal runs and evidence
plan validate, show, preview or preflight one RunSpec
launch preflight and launch one confirmed run
retry retry an unsealed, action-free incomplete run
status one run, or every run on this workspace
stop stop one active run
watch follow a live run, or replay a finished one, as a transcript
workspace the shared evidence and state roots
task resolve, run or submit a task file (ora.task.v1)
evaluate official verdict and evidence checks of one run
seal make an evaluated run immutable
revalidate review completed runs into separate reports
export archive one sealed run for transfer
export-sft export a run's model calls as tool-call JSONL
report stop-reason and cost report of runs
metadata one run's context and environment manifest
state one run's public policy state
metrics one run's Runtime metrics
ownership one run's behavioral-ownership audit
trace-validate one run's agent trace and artifact graph
Environment qualification and suites
spec compose tasks and RunSpecs per environment
qualify environment, lane and seed qualification
suite the official-suite queue
play audit audit free-play scenes
Configuration
providers model API keys and profiles
services the resident perception services
cell set up, watch and recover a real robot cell
baselines the default composition and how it resolves
lock policy.lock, the hash of every policy asset
Developer
toolkit try toolkit code at a recorded tool call
dev authoring tools (embodiment, prompt bundle, task contract, CLI reference)
help ora help COMMAND, or a topic: runs, evidence, play, remote, safety, rl-interface
ora <command> --help shows one command; ora help topics lists the topic pages.
Run an episode
ora setup
usage: ora setup [-h] [--json] [--root ROOT] [--python PYTHON]
[--graphics {auto,cgl,glfw,egl,osmesa}]
[--env {libero,robotwin,robodojo,perception}] [--prefix PREFIX]
[--cuda-home CUDA_HOME] [--cuda-arch CUDA_ARCH] [--env-file ENV_FILE] [--dry-run]
``ora setup``: install the local CPU simulator, or with ``--env`` the single-GPU stacks.
ora setup [--root DIR] [--python PY] [--graphics MODE] [--json]
the locked Harness, the agent core's Pi packages and terminal UI, pinned CPU
LIBERO sources and assets and a separate simulator runtime (``local_setup``)
ora setup --env libero|robotwin|robodojo|perception [--env ...] [--prefix DIR] [--cuda-home DIR]
[--cuda-arch X.Y] [--env-file .env] [--dry-run] [--json]
the pinned single-GPU simulator, CuRobo and perception stacks and their .env keys
(``gpu_setup`` with ``gpu_recipes``)
Both are idempotent and start no simulator, service or Provider call.
options:
-h, --help show this help message and exit
--json print the report as JSON
the local CPU installation (without --env):
--root ROOT local setup root (default: ORA_LOCAL_ROOT or the user data directory)
--python PYTHON existing Python 3.11 interpreter
--graphics {auto,cgl,glfw,egl,osmesa}
auto (the default): CGL on macOS; on Linux EGL when an NVIDIA EGL vendor
file exists, else OSMesa
the single-GPU stacks (--env):
--env {libero,robotwin,robodojo,perception}
libero, robotwin and robodojo include the perception services (repeatable)
--prefix PREFIX persistent install directory (default: ORA_GPU_PREFIX from the environment
or .env, else ~/.local/share/ora/gpu)
--cuda-home CUDA_HOME
CUDA 12.8 toolkit for the CuRobo build (default: CUDA_HOME,
/usr/local/cuda-12.8, /usr/local/cuda)
--cuda-arch CUDA_ARCH
TORCH_CUDA_ARCH_LIST base for CuRobo, e.g. 12.0 (default: nvidia-smi
--query-gpu=compute_cap)
--env-file ENV_FILE the .env to update (default: the checkout's .env)
--dry-run list each step as done or pending; change nothing
ora doctor
usage: ora doctor [-h] [--env {synthetic,robotwin,libero_pro,robodojo,local}] [--root ROOT] [--json]
``ora doctor``: read-only setup checks; never display credential values or start a simulator.
ora doctor [--env synthetic|robotwin|libero_pro|robodojo] [--json]
ora doctor --env local [--root DIR] [--json] the local CPU setup (``local.doctor``)
A simulator backend says what to discover (``backends.registry.DoctorProbe``).
The ``agent_core`` check reports the Node.js and ora-pi package readiness of the
default Pi agent core (``episode/agent_core.py``); it runs ``node --version`` only.
Where the environment's default policy runs code mode (RoboDojo), the code-mode
sandbox's host prerequisites are checked too: ``bwrap``, unprivileged user
namespaces and the sandbox interpreter against its lock.
options:
-h, --help show this help message and exit
--env {synthetic,robotwin,libero_pro,robodojo,local}
--root ROOT with --env local: the local setup root
--json machine-readable readiness report
ora run
usage: ora run [-h] [--env {synthetic,libero,robotwin,robodojo}] [--provider-profile ID]
[--task TASK] [--seed SEED] [--task-config {demo_randomized,demo_clean}]
[--candidates CANDIDATES] [--gpu N] [--requalify] [--yes] [--confirm-launch]
[--prepare-only] [--env-file ENV_FILE] [--emit {jsonl}] [--poll POLL]
[--world-view {auto,off}] [--world-port WORLD_PORT] [--world-browser {auto,off}]
[--world-public-url WORLD_PUBLIC_URL]
Run the bounded Synthetic quickstart episode, or prepare one GPU task on the single-gpu host and
open ORA on it.
options:
-h, --help show this help message and exit
--env {synthetic,libero,robotwin,robodojo}
synthetic (the default) or a GPU environment
--provider-profile ID
the model's Provider profile (ora providers lists them; its key from the
environment or ora providers key). Synthetic: instead of ORA_API_KEY and the
ORA_* variables. GPU task: default deepseek_flash_openai_low_16k_v1, e.g.
muse_spark_open_openrouter_high_16k_v1
a GPU task (--env libero|robotwin|robodojo):
--task TASK LIBERO: <suite>/<task id> (base or LIBERO-Pro core suite); RoboTwin and
RoboDojo: the task name (required)
--seed SEED LIBERO initial state 0-49 (default 0); RoboTwin: an admitted seed (default:
the first seed the qualification accepted)
--task-config {demo_randomized,demo_clean}
RoboTwin scene configuration (default demo_randomized)
--candidates CANDIDATES
RoboTwin seeds a new scan may try (default 4)
--gpu N this machine's CUDA device index to run on, 0-7 (default 0): the simulator's
slot and the perception services ora run starts
--requalify run the qualification even if a record is reusable
--yes confirm qualification simulator episodes without asking
--confirm-launch authorize launching the selected task after its normal preflight passes
--prepare-only stop after composing the RunSpec and print its path
--env-file ENV_FILE GPU task only: the .env with its simulator, service and key settings
(default: the checkout's .env); Synthetic reads only the environment
--emit {jsonl} JSON-lines interactive backend instead of the Pi UI
--poll POLL event polling interval in seconds (default 0.2)
--world-view {auto,off}
automatically show the exact live run's cameras (default: human terminal
only)
--world-port WORLD_PORT
loopback world-view port; 0 chooses a free port
--world-browser {auto,off}
open the local world view after its server is ready
--world-public-url WORLD_PUBLIC_URL
browser-facing /live URL, for example a local SSH-forwarded URL
Examples: ora run; ora run --provider-profile deepseek_flash_openai_low_16k_v1; ora run --env libero
--task libero_goal/0 --confirm-launch; ora run --env robotwin --task click_bell --confirm-launch;
ora run --env robodojo --task general_pickup --confirm-launch
ora play
usage: ora play [-h] [--env {synthetic,libero,robotwin,robodojo,yam}] [--spec SPEC]
[--provider PROFILE] [--host HOST] [--resource-profile SLOT]
[--service-report SERVICE_REPORT] [--scene-set SET] [--scene NAME] [--scenes SCENES]
[--rig-mode {sim,read,on}] [--operator-present] [--auto-approve] [--setup]
[--cell CELL.json] [--no-perception] [--scripted-moves] [--reach-query]
[--motion-timing] [--smooth-commands] [--motion-planner] [--code-mode]
[--latency-profile {sim_benchmark,realtime}] [--pipeline-predict]
[--request-priority JSON] [--draw-seed DRAW_SEED] [--prepare-only]
[--confirm-launch] [--no-attach] [--world-view {auto,off}] [--world-port WORLD_PORT]
[--world-browser {auto,off}] [--world-public-url WORLD_PUBLIC_URL]
audit ...
Free play: a random qualified scene, no task; type instructions in turn.
positional arguments:
audit
audit audit ORA's own free-play scenes on this host
options:
-h, --help show this help message and exit
--env {synthetic,libero,robotwin,robodojo,yam}
the environment (required)
--spec SPEC launch this free-play RunSpec (from --prepare-only) as it is
--provider PROFILE provider profile (`ora providers`), or env for
ORA_BASE_URL/ORA_MODEL/ORA_API_KEY
--host HOST execution host of a real environment (default: ORA_EXECUTION_HOST)
--resource-profile SLOT
the host's simulator slot to run on (default: its first), e.g. the slot a
router allocation leased
--service-report SERVICE_REPORT
a real environment's perception readiness report (`ora services qualify`)
--scene-set SET draw among the audited scenes of one of ORA's scene sets: RoboTwin's
tabletop-v1 (instead of the official tasks) or RoboDojo's isaac-tabletop-v1
(its default)
--scene NAME the task or scene to play (a LIBERO or RoboTwin task, or a scene of a scene
set); its seeds or initial states are still drawn
--scenes SCENES scenes drawn for /reset (1-32, default 8)
--rig-mode {sim,read,on}
YAM: the station model (sim), the real cell read only (read), or the real
arms with each motion approved by the operator (on); required with --env yam
--operator-present YAM --rig-mode on: a person stands beside the cell with a hand on the stop
--auto-approve YAM --rig-mode on: motions run without asking; the operator still approves
enabling the arms once
--setup YAM --rig-mode on: first finish the cell's setup (ora cell setup), its
questions answered in the play terminal, then start the arms
--cell CELL.json YAM: the real cell's config (ora.cell-config.v1), read by the worker
--no-perception YAM: run yam_direct_v1, which has no SAM3 or Contact-GraspNet tools, instead
of the default yam_perception_v1 and its --service-report
--scripted-moves YAM: the model runs a pick and place it can already plan as one checked
codemode script instead of a turn per move (off by default)
--reach-query YAM: an unreachable target's refusal names the nearest position that solves
at its height, and the model is told to read it rather than search a grid
(off by default)
--motion-timing YAM: ORA's shared timing worker (TOPP-RA + Ruckig, ORA_TIMING_PYTHON) times
the arm paths under the station's speed caps, with acceleration limits and a
start and stop at rest, instead of the station's fixed-speed timing (off by
default)
--smooth-commands YAM --rig-mode on/read: stream each control tick's arm target along a line
at 250 Hz with its velocity feed-forward instead of one position step per
tick (off by default)
--motion-planner YAM: ORA's shared cuRobo V2 planner (CUROBO_V2_PYTHON, CUROBO_V2_ROOT) plans
the arm paths in the public-depth world, a free-space move collision-free,
instead of the station's own IK lines (off by default)
--code-mode the agent works in ORA's code mode (bash and the robot library in ORA's
sandbox, the environment baseline's policy.code_mode) instead of Pi's own
tools and codemode
--latency-profile {sim_benchmark,realtime}
what the run keeps on its control path (docs/reference/latency-profile.md):
realtime turns execution capture and preview pictures off (default: realtime
on --env yam, sim_benchmark elsewhere)
--pipeline-predict while a motion runs, predict the next step and use it only when the receipt
confirms the motion (off by default; not with --code-mode)
--request-priority JSON
the priority field each model request carries, for a self-hosted server's
priority scheduling: '{"correction": -1, "default": 0}' (correction: the
call that first reads an operator message joined to the running instruction;
default: none sent)
--draw-seed DRAW_SEED
seed of the random draw (default: fresh)
--prepare-only write the free-play RunSpec and stop
--confirm-launch authorize launching a real environment after its normal preflight passes
--no-attach launch and print the `ora attach` command
--world-view {auto,off}
automatically show the exact live run's cameras (default: human terminal
only)
--world-port WORLD_PORT
loopback world-view port; 0 chooses a free port
--world-browser {auto,off}
open the local world view after its server is ready
--world-public-url WORLD_PUBLIC_URL
browser-facing /live URL, for example a local SSH-forwarded URL
Keys in the session: Enter sends an instruction, Esc stops the running one, /reset loads another
scene, /quit ends and seals the session, Ctrl+D detaches.
ora play audit
Qualify ORA's own free-play scenes on this host.
ora play audit --env robotwin --scene-set tabletop-v1 [--scene NAME ...] ...
ora play audit --env robodojo [--scene-set isaac-tabletop-v1] ...
The backend's play-scene audit (``play_audit`` in ``orchestrator.backends.registry``)
gets the rest of the line (``ora play audit --env robotwin --help``).
Runs ora.app.play:audit on the rest of the line.
ora replay
usage: ora replay [-h] [--speed SPEED] [--motion-speed X|same] [--view {compact,detailed}]
[--expand-thinking] [--lang {en,zh}] [--publish] [--from S] [--port PORT]
[--no-browser] [--export OUT.mp4] [--fps FPS] [--size SIZE] [--scale SCALE]
[--zoom ZOOM] [--to S] [--workers WORKERS] [--crf CRF] [--ffmpeg FFMPEG]
[--chromium CHROMIUM] [--export-python EXPORT_PYTHON] [--program DIR]
[--check OUT] [--resource-profile RESOURCE_PROFILE] [--scene] [--scene-traces DIR]
[--incident N] [--report OUT] [--stack-run RUN] [--branch {both,recorded,current}]
[--preview]
run
`ora replay`: a finished run in the browser, replayed from its evidence, or made into a video.
ora replay RUN [--speed 16] [--motion-speed 1|same] [--from S] [--port N] [--no-browser]
[--view compact|detailed] [--expand-thinking] [--lang en|zh] [--publish]
ora replay RUN --program DIR | --check OUT [--resource-profile P]
ora replay RUN --scene [--scene-traces DIR] [--resource-profile P]
ora replay RUN --incident N --report OUT [--stack-run RUN] [--branch both|recorded|current] [--preview]
[--resource-profile P]
ora replay RUN --export OUT.mp4 [--speed 16] [--motion-speed 1|same] [--fps 30] [--size 1920x1080] [--scale 2] [--zoom 1]
[--from S] [--to S] [--workers N] [--publish] [--ffmpeg PATH] [--chromium PATH]
[--export-python PY]
The page is `ora web`'s own (ora-pi/web), shown at a clock over the run's recorded
time: its web server rebuilds what the live page showed from the run's evidence
(Pi's session, the Supervisor's events, the execution capture and the operator
views: ora-pi/web/server/replay.ts) and attaches to nothing. The gateway in front
is `ora web`'s (launch token, cookie, loopback Host), passing the page and its one
route, GET /api/replay. Nothing in the run is written, and a live run is refused
(`ora web` shows it).
The replay has two rates: the waiting and thinking between the robot's actions play at
`--speed` (16x by default), and each action, from its start to its end with any settling
frames, plays its execution capture by the frames' simulated time at `--motion-speed` (1x by
default: real simulated time, never shorter than the action at `--speed`). Only captured frames
are shown, each held until the next; nothing is interpolated. `--motion-speed same` keeps one
speed throughout. The page has the same switches. `--export` draws the replay into a video at
those rates: a headless Chromium opens the page, the page's playback is set to each frame's
moment in turn (a virtual clock, so the video keeps the replay's rates whatever the machine's
speed and is the same every time), each frame is a screenshot drawn at `--scale` device pixels
per CSS pixel and scaled down to `--size`, and ffmpeg encodes H.264 (yuv420p, CRF 16). A corner
of the page says what plays and how fast ("robot motion · real time", "thinking · 16×"); the
report beside the video lists every stretch with its rate and times. `--publish` leaves the
run's ID and absolute paths out of the page.
`--program` and `--check` work on the run's replay program: its agent actions as code
that reproduces the run (`environment/replay_program.py`). Every run sealed with this
version carries it in `replay-program/`; `--program DIR` writes it for any run, outside
the run. `--check OUT` re-executes it on the run's simulator (the plan's interpreter,
the caller's CUDA_VISIBLE_DEVICES first), compares every action's end pose with its
receipt bit for bit and the official verdict with the run's, and writes
OUT/replay-program-check.json. A RoboCasa365 check also compares the base's end pose and a
hash of the whole scene at every action. A RoboDojo check runs the qualification control
replay on `--resource-profile` and needs the run's host marker. A RoboLab check runs in the
environment worker a run uses, on one card. A run that records no per-tick controls (a
RoboCasa365 or RoboLab run sealed before they were recorded) has no program, so `--check`
refuses it and `--program DIR` writes DIR/unavailable.json.
`--scene` runs the same check on a RoboTwin, LIBERO-Pro, RoboCasa365, RoboDojo or RoboLab run and, when it passes,
keeps the scene of that re-execution for the run dashboard's 3D replay: every body's world pose (about 50 Hz on
RoboTwin and LIBERO-Pro, every fifth SAPIEN step and every tenth MuJoCo step, every native action on
RoboDojo, 25 Hz, RoboCasa365, 20 Hz, and RoboLab, 15 Hz, plus each action's last step) and each body's visual mesh,
in `scene-trace/<run_id>/` beside the run's `runs/` directory or under `--scene-traces DIR` (`environment/scene_trace.py`). A
RoboDojo run needs `--resource-profile`, as its `--check` does. The run itself is not written. A run
whose re-execution diverges gets no trace; the report beside the traces says why. A re-execution that matches
the run bit for bit keeps its trace even if its verdict reads differently: the result and the report say
`verdict_differs`. Scene poses are
private simulator state: the trace is for a developer and reaches no policy.
`--incident N` replays the run up to action N and runs N again with no model, to see what
this checkout does with a move that once went wrong (`orchestrator/evaluation/incident_replay.py`).
On RoboTwin and LIBERO-Pro the `recorded` branch runs the recorded controls and the `current`
branch submits the recorded target to the motion stack of `--stack-run`, a run sealed on this
checkout such as a merge smoke; `--stack-run` must share the source run's simulator revisions.
On RoboDojo `--resource-profile` names a slot on the run's host and the run must be a toolkit
run: only `current` runs, through `ora toolkit replay --live --execute-action`, on the default
baseline's tool surface, planner and timing, and it needs a clean checkout.
OUT/incident-replay.json says whether the prefix matched bit for bit, each branch's receipt or
refusal, the stack it ran on, and which bodies moved. Scene poses are private simulator state:
the report is for a developer and reaches no policy.
The export needs Playwright for Python with its Chromium (`pip install
playwright==1.56.0 && playwright install chromium`, or `uv` on PATH, which runs it
as `uv run --no-project --with playwright==1.56.0`) and ffmpeg (on PATH,
ORA_FFMPEG or --ffmpeg). Neither is a dependency of ORA.
positional arguments:
run the finished run's ID or directory
options:
-h, --help show this help message and exit
--speed SPEED the speed of the waiting and thinking between the robot's actions (default
16)
--motion-speed X|same
the speed of each action's motion against its simulated time (default 1:
real time); `same`: --speed throughout
--view {compact,detailed}
how the conversation is drawn (default compact)
--expand-thinking every thought open
--lang {en,zh} the page's language (default: the browser's)
--publish leave the run's ID and absolute paths out of the page
--from S start S seconds into the run's recorded time
the page:
--port PORT loopback port (default: a free one)
--no-browser print the link instead of opening it
a video (--export):
--export OUT.mp4 draw the replay into this H.264 video and exit
--fps FPS frames per second (default 30)
--size SIZE the video's WIDTHxHEIGHT (default 1920x1080)
--scale SCALE device pixels per CSS pixel the page is drawn at before scaling to --size
(default 2)
--zoom ZOOM the page's zoom: its layout is --size / zoom CSS pixels (default 1)
--to S end S seconds into the run's recorded time (default: its end)
--workers WORKERS pages drawing frames side by side (default 4)
--crf CRF H.264 quality, lower is better (default 16)
--ffmpeg FFMPEG ffmpeg to encode with (default: ORA_FFMPEG, then PATH)
--chromium CHROMIUM Chromium to draw with (default: Playwright's)
--export-python EXPORT_PYTHON
a Python with Playwright (default: this one, else uv)
the replay program (--program, --check):
--program DIR write the run's replay program (program.json, program.py) to DIR outside the
run and exit; a sealed run already carries it in replay-program/
--check OUT re-execute the replay program on the run's simulator, check every action's
end pose against its receipt bit for bit and the verdict, write OUT/replay-
program-check.json
--resource-profile RESOURCE_PROFILE
RoboDojo --check, --scene or --incident: the qualified slot to replay on
the scene trace (--scene):
--scene re-execute the run as --check does on RoboTwin, LIBERO-Pro, RoboCasa365,
RoboDojo or RoboLab and, if it passes, write its scene trace for the run
dashboard: every body's pose per step and visual mesh
--scene-traces DIR --scene: write DIR/<run_id>/ (default: scene-trace/<run_id>/ beside the
run's runs/)
one bad action (--incident):
--incident N replay the run up to action N, then run N again on this checkout's motion
stack; needs --report, and --stack-run or --resource-profile
--report OUT --incident: an empty directory for the report
--stack-run RUN --incident on RoboTwin or LIBERO-Pro: a run sealed on this checkout, whose
motion stack the action runs on
--branch {both,recorded,current}
--incident: which branches to run (default both)
--preview --incident on RoboDojo: what a dry run of the action shows at that state,
written to OUT/preview.png, instead of running it
ora web
usage: ora web [-h] [--last] [--port PORT] [--socket SOCKET] [--token-file TOKEN_FILE]
[--no-browser]
[run]
`ora web`: a live run in the browser, ORA's own page over the run's Pi RPC.
ora web setup install and build the page (ora-pi/web: npm ci, then vite build)
ora web [RUN] [--last] [--port N | --socket PATH] [--token-file PATH] [--no-browser]
The run's agent core serves Pi's RPC protocol (ora-pi/src/rpc/host.ts). ORA's
web server (ora-pi/web/server, Node; its page seeded from Watercol/pi-web-ui,
MIT) attaches to it through `ora-rpc-attach` as one controlling client and
serves the page: the conversation, the robot's cameras and each step's images
on one screen. In front of it the gateway (web_gateway.py) adds a one-time
launch token exchanged for a cookie, loopback Host and same-origin checks, the
routes the page uses and nothing else, the run's stored images and its world
view (world_view.py), and on a real robot cell the cell's controls
(web_cell.py).
The page is built once by `ora web setup`; the build records a digest of the
sources it was built from (dist/ora-build.json), and `ora web` refuses a page
built from other sources. Nothing in ora-pi/web is patched after install, so
`npm ci` there changes nothing `ora web` relies on; a changed page is rebuilt
by `ora web setup`.
`--socket` serves the gateway on a unix socket for `ssh -L` (ora-remote);
otherwise it listens on 127.0.0.1 and prints the link with the token. A run
that is not live is refused: no Pi of ours opens a finished run's session.
A finished run is replayed from its evidence by `ora replay` (replay.py),
on the same page and gateway with no Pi RPC.
positional arguments:
run run ID or directory, or `setup` (default: the live run)
options:
-h, --help show this help message and exit
--last the most recent live run when several are
--port PORT loopback port (default: a free one)
--socket SOCKET serve on this unix socket (0600) instead, for `ssh -L` (ora-remote)
--token-file TOKEN_FILE
the launch token, in a file this command removes (ora-remote)
--no-browser print the link instead of opening it
ora cameras
usage: ora cameras [-h] [--last] [--protocol {auto,kitty,iterm2}] [--interval INTERVAL] [--once]
[run]
``ora cameras``: a run's cameras in the terminal, beside its conversation.
ora cameras [RUN] [--last] [--protocol auto|kitty|iterm2] [--interval S] [--once]
The page of ``ora web`` shows a run's cameras next to its conversation; a terminal
shows them in a pane of its own: run Pi's terminal (``ora play``, ``ora attach``) in
one pane and ``ora cameras`` in the pane beside it. It draws one picture, the run's
cameras two by two with their names, the capture's phase and action and how old it
is, and redraws it whenever the run captures a new frame
(``native/execution-capture/timeline.jsonl``: at every observation and every action's
end). The line under it says which observation step the agent last read
(``policy-observations``).
The picture goes to the terminal through its own image protocol: kitty's (kitty,
Ghostty) or iTerm2's (iTerm2, WezTerm). A terminal with neither (macOS Terminal) is
refused with that reason. Inside tmux the picture passes through to the terminal
outside, which needs ``set -g allow-passthrough on``; the command says so when it is
off. ``--protocol`` names the protocol when the terminal cannot be recognised (over
SSH, say). Nothing is written to the run; ``q`` or Ctrl-C ends the command.
positional arguments:
run run ID or directory (default: the live run)
options:
-h, --help show this help message and exit
--last the most recent live run when several are
--protocol {auto,kitty,iterm2}
the terminal's image protocol (default: recognised from the terminal)
--interval INTERVAL seconds between looks for a new frame
--once draw the latest frame once and end
ora interactive
usage: ora interactive [-h] [--spec SPEC] [--ui {pi,watch}] [--provider PROFILE] [--task TEXT]
[--actions ACTIONS] [--no-attach] [--confirm-launch] [--emit {jsonl}]
[--poll POLL] [--world-view {auto,off}] [--world-port WORLD_PORT]
[--world-browser {auto,off}] [--world-public-url WORLD_PUBLIC_URL]
options:
-h, --help show this help message and exit
--spec SPEC prepared Native benchmark RunSpec; repeat to populate the task picker
(without --spec: a Synthetic episode in Pi's terminal UI)
--ui {pi,watch} pi: the run's own Pi terminal UI on the Pi agent core (the default without
--spec); watch: the task picker and transcript (the default with --spec)
--provider PROFILE provider profile (`ora providers`), or env for
ORA_BASE_URL/ORA_MODEL/ORA_API_KEY; asked in a terminal when omitted
--task TEXT Synthetic task instruction (default: three moves)
--actions ACTIONS Synthetic robot decisions before the episode ends
--no-attach launch and print the `ora attach` command instead of attaching
--confirm-launch authorize launching a selected task after its normal preflight passes
--emit {jsonl} JSON-lines RPC backend instead of the Pi UI
--poll POLL event polling interval in seconds
--world-view {auto,off}
automatically show the exact live run's cameras (default: human terminal
only)
--world-port WORLD_PORT
loopback world-view port; 0 chooses a free port
--world-browser {auto,off}
open the local world view after its server is ready
--world-public-url WORLD_PUBLIC_URL
browser-facing /live URL, for example a local SSH-forwarded URL
ora attach
usage: ora attach [-h] [--last] [--world-view {auto,off}] [--world-port WORLD_PORT]
[--world-browser {auto,off}] [--world-public-url WORLD_PUBLIC_URL]
[run_id]
positional arguments:
run_id run ID or run directory (default: choose a running one)
options:
-h, --help show this help message and exit
--last the most recently active running run
--world-view {auto,off}
automatically show the exact live run's cameras (default: human terminal
only)
--world-port WORLD_PORT
loopback world-view port; 0 chooses a free port
--world-browser {auto,off}
open the local world view after its server is ready
--world-public-url WORLD_PUBLIC_URL
browser-facing /live URL, for example a local SSH-forwarded URL
ora sessions
usage: ora sessions [-h] [--output OUTPUT] [--json] [{list,export}] [run_id]
positional arguments:
{list,export}
run_id with export: run ID or run directory
options:
-h, --help show this help message and exit
--output OUTPUT, -o OUTPUT
with export: .html (Pi's viewer) or .jsonl (the raw Pi session)
--json
ora local
usage: ora local [-h] [--root ROOT] [--suite {libero_object,libero_goal,libero_spatial,libero_10}]
[--task-id TASK_ID] [--seed SEED] [--confirm-launch] [--emit {jsonl}] [--poll POLL]
[--world-view {auto,off}] [--world-port WORLD_PORT] [--world-browser {auto,off}]
[--world-public-url WORLD_PUBLIC_URL]
options:
-h, --help show this help message and exit
--root ROOT local setup root (default: ORA_LOCAL_ROOT or the user data directory)
--suite {libero_object,libero_goal,libero_spatial,libero_10}
--task-id TASK_ID source-bound task in the selected suite, 0 through 9 (default: 0)
--seed SEED official initial state, 0 through 49 (default: 0)
--confirm-launch authorize the manually selected task after its normal preflight passes
--emit {jsonl} JSON-lines interactive backend instead of the Pi UI
--poll POLL
--world-view {auto,off}
automatically show the exact live run's cameras (default: human terminal
only)
--world-port WORLD_PORT
loopback world-view port; 0 chooses a free port
--world-browser {auto,off}
open the local world view after its server is ready
--world-public-url WORLD_PUBLIC_URL
browser-facing /live URL, for example a local SSH-forwarded URL
Formal runs and evidence
ora plan
usage: ora plan [-h] <action> ...
``ora plan``: one RunSpec bound, shown, previewed or preflighted, never launched.
ora plan validate SPEC bind the RunSpec; print its plan id and sha256
ora plan show SPEC the resolved, content-addressed RunPlan
ora plan context SPEC the exact project-owned model context and tools
ora plan preflight SPEC the launch gates, without starting an episode
``display_plan`` is the summary ``ora plan show``, ``ora launch`` and
``ora retry`` print before the plan itself or the confirmation prompt.
positional arguments:
<action>
validate validate and bind one RunSpec without writing a run
show print the resolved, content-addressed RunPlan
context preview exact project-owned model context and tools
preflight
run launch gates without starting an episode
options:
-h, --help show this help message and exit
ora plan validate
usage: ora plan validate [-h] run_spec
validate and bind one RunSpec without writing a run
positional arguments:
run_spec
options:
-h, --help show this help message and exit
ora plan show
usage: ora plan show [-h] run_spec
print the resolved, content-addressed RunPlan
positional arguments:
run_spec
options:
-h, --help show this help message and exit
ora plan context
usage: ora plan context [-h] run_spec
preview exact project-owned model context and tools
positional arguments:
run_spec
options:
-h, --help show this help message and exit
ora plan preflight
usage: ora plan preflight [-h] run_spec
run launch gates without starting an episode
positional arguments:
run_spec
options:
-h, --help show this help message and exit
ora launch
usage: ora launch [-h] [--yes] run_spec
positional arguments:
run_spec
options:
-h, --help show this help message and exit
--yes
ora retry
usage: ora retry [-h] [--yes] run_id
positional arguments:
run_id
options:
-h, --help show this help message and exit
--yes
ora status
usage: ora status [-h] [run_id]
positional arguments:
run_id
options:
-h, --help show this help message and exit
ora stop
usage: ora stop [-h] run_id
positional arguments:
run_id
options:
-h, --help show this help message and exit
ora watch
usage: ora watch [-h] [--speed SPEED] [--max-gap MAX_GAP] [--plain] [--ui {auto,pi,ansi,plain}]
[--emit {jsonl}] [--poll POLL] [--world-view {auto,off}] [--world-port WORLD_PORT]
[--world-browser {auto,off}] [--world-public-url WORLD_PUBLIC_URL] [--raw]
run_id
Follow a live Native run, or replay a finished one, as ORA's terminal transcript. Read-only: writes
nothing under the run and takes no lease; Ctrl-C stops watching, not the run.
positional arguments:
run_id run ID or run directory
options:
-h, --help show this help message and exit
--speed SPEED replay speed of a finished run (default 10 in a terminal, 0 = print at once,
the default when not a terminal)
--max-gap MAX_GAP longest recorded pause replayed, in seconds (default 30)
--plain no colours and no live status region
--ui {auto,pi,ansi,plain}
front end: pi (pi-tui, needs Node.js >= 22.19 and `npm ci` in ora-pi/), ansi
(built in), plain; auto picks pi in a terminal when installed
--emit {jsonl} write UI operations as JSON lines instead of drawing (the pi front end reads
them)
--poll POLL seconds between reads of a live run's events (default 0.2)
--world-view {auto,off}
automatically show the exact live run's cameras (default: human terminal
only)
--world-port WORLD_PORT
loopback world-view port; 0 chooses a free port
--world-browser {auto,off}
open the local world view after its server is ready
--world-public-url WORLD_PUBLIC_URL
browser-facing /live URL, for example a local SSH-forwarded URL
--raw print the run's canonical causal events as JSON lines until it terminates
ora workspace
usage: ora workspace [-h]
options:
-h, --help show this help message and exit
ora task
usage: ora task [-h] {resolve,run,submit} ...
run a task file (ora.task.v1) many times, changing only what each run needs
positional arguments:
{resolve,run,submit}
resolve print the task after overrides
run run the task once on its binding and wait for it
submit send one run of the task to the scheduler
options:
-h, --help show this help message and exit
ora task resolve
usage: ora task resolve [-h] [--task CELL] [--seed SEED] [--layout LAYOUT] [--set KEY=VALUE] file
positional arguments:
file
options:
-h, --help show this help message and exit
--task CELL the task name
--seed SEED
--layout LAYOUT
--set KEY=VALUE any other task key (policy.*, budgets.* included); VALUE is YAML
ora task run
usage: ora task run [-h] [--resolved RESOLVED] [--task CELL] [--seed SEED] [--layout LAYOUT]
[--set KEY=VALUE] [--binding BINDING] [--summary SUMMARY] [--no-wait]
[file]
positional arguments:
file
options:
-h, --help show this help message and exit
--resolved RESOLVED the resolved task as JSON (what submit sends)
--task CELL the task name
--seed SEED
--layout LAYOUT
--set KEY=VALUE any other task key (policy.*, budgets.* included); VALUE is YAML
--binding BINDING an ora.run-binding.v1 or allocation file (default: ORA_ROUTER_ALLOCATION)
--summary SUMMARY also write the task record here
--no-wait return once the run is launched
ora task submit
usage: ora task submit [-h] [--task CELL] [--seed SEED] [--layout LAYOUT] [--set KEY=VALUE]
[--defaults DEFAULTS] [--scheduler-url SCHEDULER_URL] [--owner OWNER]
[--name NAME] [--priority PRIORITY] [--job-type JOB_TYPE] [--window WINDOW]
[--workspace WORKSPACE] [--pin PIN] [--cpu] [--env NAME=VALUE]
[--env-file NAME=FILE] [--summary SUMMARY] [--print]
file
positional arguments:
file
options:
-h, --help show this help message and exit
--task CELL the task name
--seed SEED
--layout LAYOUT
--set KEY=VALUE any other task key (policy.*, budgets.* included); VALUE is YAML
--defaults DEFAULTS standing request fields (YAML)
--scheduler-url SCHEDULER_URL
--owner OWNER
--name NAME
--priority PRIORITY
--job-type JOB_TYPE
--window WINDOW
--workspace WORKSPACE
--pin PIN
--cpu
--env NAME=VALUE
--env-file NAME=FILE
--summary SUMMARY the run also writes its task record here (shared storage)
--print print the request instead of sending it
ora evaluate
usage: ora evaluate [-h] run_id
positional arguments:
run_id
options:
-h, --help show this help message and exit
ora seal
usage: ora seal [-h] [--backfill] run_id
positional arguments:
run_id
options:
-h, --help show this help message and exit
--backfill seal an old unsealed run with today's evaluator, pinning its recorded source identity
and marking the seal as a backfill
ora revalidate
usage: ora revalidate [-h] [--run-list RUN_LIST] --output-dir OUTPUT_DIR [--workers WORKERS]
[run_dirs ...]
positional arguments:
run_dirs
options:
-h, --help show this help message and exit
--run-list RUN_LIST JSON list of absolute run directories
--output-dir OUTPUT_DIR
--workers WORKERS
ora export
usage: ora export [-h] [--destination DESTINATION] run_id
positional arguments:
run_id
options:
-h, --help show this help message and exit
--destination DESTINATION
ora export-sft
usage: ora export-sft [-h] [--destination DESTINATION] [--view {sft,wire,openai}] [--check]
[--tokenize-url URL] [--tokenize-key-env NAME]
run_id
positional arguments:
run_id
options:
-h, --help show this help message and exit
--destination DESTINATION
--view {sft,wire,openai}
sft: one training record per accepted call (default); wire: every call as
sent, each image once, rebuilt and checked against the archived requests;
openai: a self-contained package of standard OpenAI conversations with the
wire export, a README and a verify tool
--check with --view wire or openai: check an existing export at --destination
instead of writing one
--tokenize-url URL with --view wire or openai: the serving engine's tokenize endpoint (vLLM
<root>/tokenize, sglang <root>/v1/tokenize); each policy call's prompt token
ids are taken from it and checked against the call's usage
--tokenize-key-env NAME
with --tokenize-url: the environment variable holding the endpoint's bearer
key
ora report
``ora report``: the read-only stop-reason and cost report of runs (``orchestrator.reports.run_report``).
ora report RUN [RUN ...] [--json FILE] [--markdown FILE]
ora report --namespace NS --cohort ID [--cohort ID ...]
The rest of the line goes to the report's own parser (``ora report --help``).
Runs ora.orchestrator.reports.run_report:main on the rest of the line.
ora metadata
usage: ora metadata [-h] run_id
positional arguments:
run_id
options:
-h, --help show this help message and exit
ora state
usage: ora state [-h] [--step STEP] run_id
positional arguments:
run_id
options:
-h, --help show this help message and exit
--step STEP
ora metrics
usage: ora metrics [-h] run_id
positional arguments:
run_id
options:
-h, --help show this help message and exit
ora ownership
usage: ora ownership [-h] run_id
positional arguments:
run_id
options:
-h, --help show this help message and exit
ora trace-validate
usage: ora trace-validate [-h] run_id
positional arguments:
run_id
options:
-h, --help show this help message and exit
Environment qualification and suites
ora spec
``ora spec``: tasks and RunSpecs of one environment, from the RunSpec composer its backend declares.
ora spec robotwin {tasks,spec,compose} ... RoboTwin (orchestrator.spec.benchmark)
ora spec libero {tasks,spec,compose} ... a LIBERO base or LIBERO-Pro core suite cell, by its suite
ora spec robodojo {tasks,spec,compose} ... RoboDojo (backends.robodojo.spec)
ora spec robocasa {language,compose} ... RoboCasa365 (backends.robocasa.spec)
ora spec robolab {tasks,compose} ... RoboLab (backends.robolab.spec, task_catalog)
The backend's ``spec_tools`` (``orchestrator.backends.registry``) name each
tool; the rest of the line goes to its own parser
(``ora spec robotwin compose --help``). ``ora spec ENVIRONMENT`` lists them.
Runs ora.app.spec:main on the rest of the line.
| Environment | Tool | What it does | Runs |
|---|---|---|---|
| robotwin | tasks |
list the RoboTwin roster and its public instructions | ora.orchestrator.spec.benchmark:robotwin_main tasks |
| robotwin | spec |
print one task's RunSpec | ora.orchestrator.spec.benchmark:robotwin_main spec |
| robotwin | compose |
write one task's RunSpec and import the seed manifest that admits it | ora.orchestrator.spec.benchmark:robotwin_main compose |
| libero_pro, libero | tasks |
list the LIBERO base suites' and LIBERO-Pro core suites' task languages | ora.orchestrator.spec.benchmark:libero_main tasks |
| libero_pro, libero | spec |
print one suite task's RunSpec | ora.orchestrator.spec.benchmark:libero_main spec |
| libero_pro, libero | compose |
write one suite task's RunSpec | ora.orchestrator.spec.benchmark:libero_main compose |
| robodojo | tasks |
list the contracted tasks with their physics device and limits | ora.orchestrator.backends.robodojo.spec:main tasks |
| robodojo | spec |
print one task's RunSpec | ora.orchestrator.backends.robodojo.spec:main spec |
| robodojo | compose |
write one task's RunSpec | ora.orchestrator.backends.robodojo.spec:main compose |
| robocasa | language |
print the official instruction of one cell | ora.orchestrator.backends.robocasa.spec:main language |
| robocasa | compose |
write one cell's RunSpec | ora.orchestrator.backends.robocasa.spec:main compose |
| robolab | compose |
write one cell's RunSpec | ora.orchestrator.backends.robolab.spec:main |
| robolab | tasks |
list the roster with each task's contract and compatibility state | ora.orchestrator.backends.robolab.task_catalog:main tasks |
ora qualify
``ora qualify``: environment, lane and seed qualification, from the tools each backend declares.
ora qualify robotwin {configs,prepare,qualify,merge,seal} ... expert seed scans and their seed manifests
ora qualify robodojo {card,task,smoke,revalidate} TASK ... one lane for the composed RunSpecs
ora qualify robodojo {physics-probe,motion-replay,motion-metrics} ...
ora qualify libero motion --run RUN --output RECORD ... scripted sparse-motion record
ora qualify robocasa motion --output RECORD ... scripted sparse-motion record
ora qualify robolab motion --gpu N --output RECORD ... scripted sparse-motion record
ora qualify robolab contract-witness --task T --gpu N ... seed-0 task-contract witnesses
The backend's ``qualify_tools`` (``orchestrator.backends.registry``) name each
tool; the rest of the line goes to its own parser
(``ora qualify robotwin prepare --help``). ``ora qualify ENVIRONMENT`` lists
them. Free-play scene audits are ``ora play audit``.
Runs ora.app.qualify:main on the rest of the line.
| Environment | Tool | What it does | Runs |
|---|---|---|---|
| robotwin | configs |
print the evaluation protocol and the task roster | ora.orchestrator.backends.robotwin.evaluation_seeds:main configs |
| robotwin | prepare |
plan an expert seed scan of explicit tasks on explicit slots | ora.orchestrator.backends.robotwin.evaluation_seeds:main prepare |
| robotwin | qualify |
run a prepared seed scan (--plan, --confirm) and write its seed manifests | ora.orchestrator.backends.robotwin.evaluation_seeds:main qualify |
| robotwin | merge |
merge a task's scan segments into one first-N seed manifest | ora.orchestrator.backends.robotwin.evaluation_seeds:main merge |
| robotwin | seal |
write interim seed manifests from scans still running | ora.orchestrator.backends.robotwin.evaluation_seeds:main seal |
| libero_pro, libero | motion |
the scripted sparse-motion qualification record | ora.orchestrator.backends.libero_pro.qualification:main |
| robodojo | motion |
scripted sparse-motion qualification with host-owned execution state | ora.orchestrator.backends.robodojo.qualification:main |
| robodojo | card |
the lane's card record: two full-length episodes (35-56 min) | ora.orchestrator.backends.robodojo.lane_qualification:main card |
| robodojo | task |
the lane's round-0 task record on a card record | ora.orchestrator.backends.robodojo.lane_qualification:main task |
| robodojo | smoke |
the bounded scene smoke of one lane | ora.orchestrator.backends.robodojo.lane_qualification:main smoke |
| robodojo | revalidate |
the lane gate, offline | ora.orchestrator.backends.robodojo.lane_qualification:main revalidate |
| robodojo | physics-probe |
the physics scene probe of the CPU-physics lane | ora.orchestrator.backends.robodojo.physics_probe:main |
| robodojo | motion-replay |
control replay of a sealed run (layer L0) | ora.orchestrator.backends.robodojo.motion.replay:main |
| robodojo | motion-metrics |
pinned motion-quality metrics of sealed runs (layer L0) | ora.orchestrator.backends.robodojo.motion.metrics:main |
| robocasa | motion |
the scripted sparse-motion qualification record | ora.orchestrator.backends.robocasa.qualification:main |
| robolab | motion |
the scripted sparse-motion qualification record | ora.orchestrator.backends.robolab.qualification:main |
| robolab | contract-witness |
seed-0 task-contract witnesses; fills the reviews' witness checks | ora.orchestrator.backends.robolab.contract_witness:main |
| yam | motion |
the scripted sparse-motion qualification record (simulated station) | ora.orchestrator.backends.yam.qualification:main |
ora suite
``ora suite``: the official-suite queue (``orchestrator.suite.queue``).
ora suite run --cells CELLS.json --experiment EXP --cohort ID --group G --lanes PROFILE ...
--service-report REPORT --yes one single-attempt launch per listed cell
ora suite status|drain --experiment EXP --group G
The rest of the line goes to the queue's own parser (``ora suite --help``).
Runs ora.orchestrator.suite.queue:main on the rest of the line.
Configuration
ora providers
usage: ora providers [-h] [--json] {key,add,remove,test} ...
``ora providers``: provider profiles and their keys, configured in the terminal.
positional arguments:
{key,add,remove,test}
key enter a profile's key (not echoed) and store it outside the run
add add an OpenAI-compatible or Anthropic endpoint of your own
remove remove a profile added here
test probe a profile's provider with its key
options:
-h, --help show this help message and exit
--json
ora providers key
usage: ora providers key [-h] [--remove] [--stdin] [--no-test] PROFILE|VARIABLE
positional arguments:
PROFILE|VARIABLE
options:
-h, --help show this help message and exit
--remove remove the stored key instead
--stdin read the key from standard input
--no-test store it without probing the provider
ora providers add
usage: ora providers add [-h] --protocol {anthropic_messages,openai_compatible} --endpoint ENDPOINT
--model MODEL [--images] [--context-window N] [--max-output N]
[--reasoning-effort REASONING_EFFORT] [--request-options JSON]
[--recovery-window SECONDS] [--key-env KEY_ENV] [--no-key] [--stdin]
[--no-test]
ID
positional arguments:
ID
options:
-h, --help show this help message and exit
--protocol {anthropic_messages,openai_compatible}
--endpoint ENDPOINT https://..., or http://127.0.0.1:PORT/... on this machine
--model MODEL the model id the endpoint serves
--images the model reads images
--context-window N the model's context window in tokens (default 131072)
--max-output N the reply's token limit (default 8192)
--reasoning-effort REASONING_EFFORT
--request-options JSON
request fields every call adds (openai_compatible): temperature, top_p,
top_k, chat_template_kwargs, reasoning, provider, return_token_ids (vLLM);
e.g. '{"temperature":0.6,"chat_template_kwargs":{"enable_thinking":true}}'
--recovery-window SECONDS
how long each attempt may wait for its first token, and how long failures
before any content are retried before the call ends, 30..1800 s (default
180); raise it for a slow self-hosted model
--key-env KEY_ENV the key's variable (default ORA_<ID>_API_KEY)
--no-key add the profile without entering a key
--stdin read the key from standard input
--no-test add it without probing the provider
ora providers remove
usage: ora providers remove [-h] [--keep-key] ID
positional arguments:
ID
options:
-h, --help show this help message and exit
--keep-key keep its stored key
ora providers test
usage: ora providers test [-h] PROFILE
positional arguments:
PROFILE
options:
-h, --help show this help message and exit
ora services
usage: ora services [-h] [--state STATE] {start,status,stop,qualify}
``ora services``: operate the resident SAM3 and Contact-GraspNet services from the shared workspace.
ora services start|status|stop|qualify [--state DIR]
`start` reads the `ORA_SAM_*` / `ORA_GRASP_*` selectors and the `ORA_SAM_PORT` /
`ORA_GRASP_PORT` ports from the environment, `status` reports readiness,
`stop` refuses while Runtime leases exist (and exits 1 naming any service it
left running because it could not prove that process's identity), and `qualify` writes the
hash-named readiness report a launch binds. The host layer supplies the
workspace and Runtime state roots; the service module resolves no paths.
positional arguments:
{start,status,stop,qualify}
options:
-h, --help show this help message and exit
--state STATE service state and log directory (default: model-services under the
configured output storage; services started by the retired scripts/b2 used
b2-model-services)
ora cell
usage: ora cell [-h] ACTION ...
``ora cell``: set up, watch and recover a real robot cell (``ora/cell``, docs/usage/real-cells.md).
ora cell init [--example PATH] validate the cell config against its robot, list devices
ora cell check buses, other controllers, cameras and their depth
ora cell read | record-rest the arms, read without enabling anything
ora cell grippers [--orient] each gripper opens and closes once to find its limits;
then (or with --orient alone, nothing moving) you say which way each is
ora cell calibrate --method arm-poses|board-poses|board-relative|charuco|wrists [--square-mm N] [--pattern CxR] [--role R]
ora cell calibrate --method hand-eye [--square-mm N] [--pattern CxR] [--placements N] [--arms A,B]
[--records DIR ...] [--ask terminal|broker]
ora cell setup [--status] [--redo STEP ...] [--only STEP ...]
a new cell, step by step: devices, rest, grippers, fixed cameras,
hand-eye calibration, table, verify (what is not done yet)
ora cell board [--port 8765] the operator's page: state, live cloud, verbs
ora cell depth-service [...] the depth completion service (ora.cell.depth.service)
ora cell home | hold | float | release | estop | diagnose | stop | kill | cameras | can
ora cell pending | approve [--id ID] [--value V] | decline [--id ID] [--reason TEXT]
ora cell auto-approve [on|off|status] motions of the running play worker answer themselves
ora cell mode [ask|safe|auto|status] the permission mode: every motion asked, small ones not, or none
ora cell stop-motion the running motion ends where the arms are; they stay held there
ora cell sim init PATH | status | place X Y [--yaw DEG] | clear | operator [--seconds S]
a simulated cell (``robot.sim``): write one, compare its
calibration with the injected truth, move its board, answer
its questions as the person at the cell would
Every command reads the cell config (``--cell``, else ``$ORA_CELL``, else
``~/.config/ora/cell.yaml``). The operator verbs (home ... can) act at once, also while a
play session moves the arms; ``hold`` and ``float`` keep the arms held and so need a
running cell board, which they reach over HTTP; with a board running every verb goes
through it. ``--json`` prints ``{"ok": true, "result": ...}`` or ``{"ok": false,
"error": ...}`` (exit 1); ``--yes`` skips the confirmation of verbs that make arms limp
or move them by hand.
``calibrate --method hand-eye`` is the guided calibration of a new cell
(``ora/cell/operator/handeye.py``): the person places a checkerboard a few times, the arms
look at it, and one fit measures the fixed cameras, the wrist cameras' mounts, the arms'
bases and their joint zeros; it asks every step (place the board, each motion, the
measured square, writing the result) on this terminal, or through the approval broker
when it has none (``--ask broker``) and prints its progress on stderr (JSON lines with
``--json``). ``--records`` fits earlier captures again without moving anything.
``pending``, ``approve`` and ``decline`` answer the questions a robot's worker asks the
operator (enable the arms, run a motion, release arms that could not get home): they
read and write only the cell's approval files (``$ORA_CELL_APPROVALS``, else beside the
cell lock), never the lock or the hardware. An answer names the question's ``--id``
(``pending`` lists them); without one, on a terminal, the one waiting question is shown
and answered after a yes.
``auto-approve on`` (the operator's "YOLO" switch) makes the play worker that drives the
arms now (``rig_mode on``) answer its own motion questions; enabling the arms and releasing
them are still asked. ``off`` turns it off; ``status`` (the default) says whether it is on.
It too touches only the approval files: the switch lives for that worker only, and a new
worker clears it unless its run was started with ``ora play ... --auto-approve``.
A simulated cell (``robot.sim: true``, docs/usage/real-cells.md) runs every command above
with no hardware: the robot's simulated adapter renders its cameras and moves kinematic
arms. Its lock, approvals and alerts live in its state directory unless
``ORA_CELL_LOCK``, ``ORA_CELL_APPROVALS`` or ``ORA_CELL_ALERTS`` name others, so it never
shares them with a real cell. ``ora cell sim init PATH`` writes such a config;
``sim status`` compares the calibration with the errors the simulation injected (its
``world.json``), ``sim place`` and ``sim clear`` move the checkerboard, and ``sim operator``
is the person at the cell: it answers the broker's questions (board placements, motions,
square size, which way a gripper opens, writing) until stopped.
positional arguments:
ACTION
init validate the cell config, list devices
check buses, other controllers, cameras
read the arms, read without enabling
record-rest record the rest pose
grippers find each gripper's limits (opens and closes once)
calibrate place the fixed cameras
setup a new cell, step by step
board the operator's page
depth-service
the depth completion service
home arms back to rest, then released
hold hold the arms where they are (needs a board)
float float the arms for hand guiding (needs a board)
release the arms go limp
estop disable every motor, whoever holds the cell
diagnose who holds the cell, faults, rest
stop ask the holder to home and release
kill end the holder
cameras hardware-reset the cameras
can re-initialise the buses (sudo)
pending the worker's questions waiting for an answer
approve approve one waiting question (by --id)
decline decline one waiting question (by --id)
auto-approve
the running worker's motions answer themselves (on|off|status)
mode the permission mode (ask|safe|auto|status)
stop-motion end the running motion where the arms are, and hold there
sim a simulated cell: init, status, place, clear, operator
options:
-h, --help show this help message and exit
ora cell init
usage: ora cell init [-h] [--cell CELL] [--json] [--yes] [--board-port BOARD_PORT]
[--example EXAMPLE]
options:
-h, --help show this help message and exit
--cell CELL the cell config (default: $ORA_CELL, else ~/.config/ora/cell.yaml)
--json print one JSON object
--yes skip confirmations
--board-port BOARD_PORT
the port a running cell board serves on
--example EXAMPLE write an example cell config here and stop
ora cell check
usage: ora cell check [-h] [--cell CELL] [--json] [--yes] [--board-port BOARD_PORT]
options:
-h, --help show this help message and exit
--cell CELL the cell config (default: $ORA_CELL, else ~/.config/ora/cell.yaml)
--json print one JSON object
--yes skip confirmations
--board-port BOARD_PORT
the port a running cell board serves on
ora cell read
usage: ora cell read [-h] [--cell CELL] [--json] [--yes] [--board-port BOARD_PORT]
options:
-h, --help show this help message and exit
--cell CELL the cell config (default: $ORA_CELL, else ~/.config/ora/cell.yaml)
--json print one JSON object
--yes skip confirmations
--board-port BOARD_PORT
the port a running cell board serves on
ora cell record-rest
usage: ora cell record-rest [-h] [--cell CELL] [--json] [--yes] [--board-port BOARD_PORT]
options:
-h, --help show this help message and exit
--cell CELL the cell config (default: $ORA_CELL, else ~/.config/ora/cell.yaml)
--json print one JSON object
--yes skip confirmations
--board-port BOARD_PORT
the port a running cell board serves on
ora cell grippers
usage: ora cell grippers [-h] [--cell CELL] [--json] [--yes] [--board-port BOARD_PORT]
[--ask {terminal,broker}] [--orient] [--no-save]
options:
-h, --help show this help message and exit
--cell CELL the cell config (default: $ORA_CELL, else ~/.config/ora/cell.yaml)
--json print one JSON object
--yes skip confirmations
--board-port BOARD_PORT
the port a running cell board serves on
--ask {terminal,broker}
where to ask the person (default: the terminal when there is one)
--orient only check which way each gripper opens (nothing moves)
--no-save report without saving
ora cell calibrate
usage: ora cell calibrate [-h] [--cell CELL] [--json] [--yes] [--board-port BOARD_PORT] --method
{arm-poses,board-poses,board-relative,charuco,wrists,hand-eye}
[--reference REFERENCE] [--pattern PATTERN] [--role ROLE]
[--square-mm SQUARE_MM] [--placements PLACEMENTS] [--arms ARMS]
[--records RECORDS [RECORDS ...]] [--ask {terminal,broker}] [--no-save]
options:
-h, --help show this help message and exit
--cell CELL the cell config (default: $ORA_CELL, else ~/.config/ora/cell.yaml)
--json print one JSON object
--yes skip confirmations
--board-port BOARD_PORT
the port a running cell board serves on
--method {arm-poses,board-poses,board-relative,charuco,wrists,hand-eye}
--reference REFERENCE
--method board-relative: a placed fixed camera that also sees the board
--pattern PATTERN --method board-poses|board-relative|hand-eye: inner corners COLSxROWS of a
plain checkerboard
--role ROLE --method wrists: the fixed camera to place
--square-mm SQUARE_MM
--method charuco|board-*|hand-eye: one square, measured
--placements PLACEMENTS
--method hand-eye: how many board placements (default 5)
--arms ARMS --method hand-eye: the arms that look, comma-separated (default: every arm)
--records RECORDS [RECORDS ...]
--method hand-eye: fit these earlier placements again; nothing moves
--ask {terminal,broker}
where to ask the person (default: the terminal when there is one)
--no-save report without saving
ora cell setup
usage: ora cell setup [-h] [--cell CELL] [--json] [--yes] [--board-port BOARD_PORT] [--status]
[--redo STEP [STEP ...]] [--only STEP [STEP ...]] [--ask {terminal,broker}]
options:
-h, --help show this help message and exit
--cell CELL the cell config (default: $ORA_CELL, else ~/.config/ora/cell.yaml)
--json print one JSON object
--yes skip confirmations
--board-port BOARD_PORT
the port a running cell board serves on
--status only say what is done and what comes next
--redo STEP [STEP ...]
do these steps again
--only STEP [STEP ...]
do only these steps
--ask {terminal,broker}
where to ask the person (default: the terminal when there is one)
ora cell board
usage: ora cell board [-h] [--cell CELL] [--json] [--yes] [--board-port BOARD_PORT] [--port PORT]
[--host HOST] [--depth-service DEPTH_SERVICE]
options:
-h, --help show this help message and exit
--cell CELL the cell config (default: $ORA_CELL, else ~/.config/ora/cell.yaml)
--json print one JSON object
--yes skip confirmations
--board-port BOARD_PORT
the port a running cell board serves on
--port PORT the port to serve on (default 8765)
--host HOST the address to serve on
--depth-service DEPTH_SERVICE
a depth service URL (default: the cell config's)
ora cell depth-service
usage: ora cell depth-service ...
positional arguments:
rest arguments of ora.cell.depth.service
ora cell home
usage: ora cell home [-h] [--cell CELL] [--json] [--yes] [--board-port BOARD_PORT]
options:
-h, --help show this help message and exit
--cell CELL the cell config (default: $ORA_CELL, else ~/.config/ora/cell.yaml)
--json print one JSON object
--yes skip confirmations
--board-port BOARD_PORT
the port a running cell board serves on
ora cell hold
usage: ora cell hold [-h] [--cell CELL] [--json] [--yes] [--board-port BOARD_PORT]
options:
-h, --help show this help message and exit
--cell CELL the cell config (default: $ORA_CELL, else ~/.config/ora/cell.yaml)
--json print one JSON object
--yes skip confirmations
--board-port BOARD_PORT
the port a running cell board serves on
ora cell float
usage: ora cell float [-h] [--cell CELL] [--json] [--yes] [--board-port BOARD_PORT]
options:
-h, --help show this help message and exit
--cell CELL the cell config (default: $ORA_CELL, else ~/.config/ora/cell.yaml)
--json print one JSON object
--yes skip confirmations
--board-port BOARD_PORT
the port a running cell board serves on
ora cell release
usage: ora cell release [-h] [--cell CELL] [--json] [--yes] [--board-port BOARD_PORT]
options:
-h, --help show this help message and exit
--cell CELL the cell config (default: $ORA_CELL, else ~/.config/ora/cell.yaml)
--json print one JSON object
--yes skip confirmations
--board-port BOARD_PORT
the port a running cell board serves on
ora cell estop
usage: ora cell estop [-h] [--cell CELL] [--json] [--yes] [--board-port BOARD_PORT]
options:
-h, --help show this help message and exit
--cell CELL the cell config (default: $ORA_CELL, else ~/.config/ora/cell.yaml)
--json print one JSON object
--yes skip confirmations
--board-port BOARD_PORT
the port a running cell board serves on
ora cell diagnose
usage: ora cell diagnose [-h] [--cell CELL] [--json] [--yes] [--board-port BOARD_PORT]
options:
-h, --help show this help message and exit
--cell CELL the cell config (default: $ORA_CELL, else ~/.config/ora/cell.yaml)
--json print one JSON object
--yes skip confirmations
--board-port BOARD_PORT
the port a running cell board serves on
ora cell stop
usage: ora cell stop [-h] [--cell CELL] [--json] [--yes] [--board-port BOARD_PORT]
options:
-h, --help show this help message and exit
--cell CELL the cell config (default: $ORA_CELL, else ~/.config/ora/cell.yaml)
--json print one JSON object
--yes skip confirmations
--board-port BOARD_PORT
the port a running cell board serves on
ora cell kill
usage: ora cell kill [-h] [--cell CELL] [--json] [--yes] [--board-port BOARD_PORT]
options:
-h, --help show this help message and exit
--cell CELL the cell config (default: $ORA_CELL, else ~/.config/ora/cell.yaml)
--json print one JSON object
--yes skip confirmations
--board-port BOARD_PORT
the port a running cell board serves on
ora cell cameras
usage: ora cell cameras [-h] [--cell CELL] [--json] [--yes] [--board-port BOARD_PORT]
options:
-h, --help show this help message and exit
--cell CELL the cell config (default: $ORA_CELL, else ~/.config/ora/cell.yaml)
--json print one JSON object
--yes skip confirmations
--board-port BOARD_PORT
the port a running cell board serves on
ora cell can
usage: ora cell can [-h] [--cell CELL] [--json] [--yes] [--board-port BOARD_PORT]
options:
-h, --help show this help message and exit
--cell CELL the cell config (default: $ORA_CELL, else ~/.config/ora/cell.yaml)
--json print one JSON object
--yes skip confirmations
--board-port BOARD_PORT
the port a running cell board serves on
ora cell pending
usage: ora cell pending [-h] [--cell CELL] [--json] [--yes] [--board-port BOARD_PORT]
options:
-h, --help show this help message and exit
--cell CELL the cell config (default: $ORA_CELL, else ~/.config/ora/cell.yaml)
--json print one JSON object
--yes skip confirmations
--board-port BOARD_PORT
the port a running cell board serves on
ora cell approve
usage: ora cell approve [-h] [--cell CELL] [--json] [--yes] [--board-port BOARD_PORT] [--id ID]
[--by BY] [--value VALUE]
options:
-h, --help show this help message and exit
--cell CELL the cell config (default: $ORA_CELL, else ~/.config/ora/cell.yaml)
--json print one JSON object
--yes skip confirmations
--board-port BOARD_PORT
the port a running cell board serves on
--id ID the question's id (`ora cell pending`); required with --json or no terminal
--by BY who answers, kept with the answer
--value VALUE the answer to a value question (a measured length, ...)
ora cell decline
usage: ora cell decline [-h] [--cell CELL] [--json] [--yes] [--board-port BOARD_PORT] [--id ID]
[--by BY] [--reason REASON]
options:
-h, --help show this help message and exit
--cell CELL the cell config (default: $ORA_CELL, else ~/.config/ora/cell.yaml)
--json print one JSON object
--yes skip confirmations
--board-port BOARD_PORT
the port a running cell board serves on
--id ID the question's id (`ora cell pending`); required with --json or no terminal
--by BY who answers, kept with the answer
--reason REASON why not; a declined motion's reason reaches the agent
ora cell auto-approve
usage: ora cell auto-approve [-h] [--cell CELL] [--json] [--yes] [--board-port BOARD_PORT] [--by BY]
[{on,off,status}]
positional arguments:
{on,off,status} on: motions run without asking (enabling and releasing are still asked);
off; status (default)
options:
-h, --help show this help message and exit
--cell CELL the cell config (default: $ORA_CELL, else ~/.config/ora/cell.yaml)
--json print one JSON object
--yes skip confirmations
--board-port BOARD_PORT
the port a running cell board serves on
--by BY who turns it on, kept with every auto-approval
ora cell mode
usage: ora cell mode [-h] [--cell CELL] [--json] [--yes] [--board-port BOARD_PORT] [--by BY]
[{ask,safe,auto,status}]
positional arguments:
{ask,safe,auto,status}
ask: every motion waits for a person; safe: a motion inside the safe limits
runs without asking; auto: every motion of the running worker does; status
(default). Enabling and releasing the arms are always asked
options:
-h, --help show this help message and exit
--cell CELL the cell config (default: $ORA_CELL, else ~/.config/ora/cell.yaml)
--json print one JSON object
--yes skip confirmations
--board-port BOARD_PORT
the port a running cell board serves on
--by BY who sets it, kept with every self-answered motion
ora cell stop-motion
usage: ora cell stop-motion [-h] [--cell CELL] [--json] [--yes] [--board-port BOARD_PORT] [--by BY]
[--withdraw]
options:
-h, --help show this help message and exit
--cell CELL the cell config (default: $ORA_CELL, else ~/.config/ora/cell.yaml)
--json print one JSON object
--yes skip confirmations
--board-port BOARD_PORT
the port a running cell board serves on
--by BY who stops it, kept with the stop
--withdraw take back a stop nobody has read yet
ora cell sim
usage: ora cell sim [-h] [--cell CELL] [--json] [--yes] [--board-port BOARD_PORT] [--yaw YAW]
[--seconds SECONDS] [--python PYTHON]
{init,status,place,clear,operator} [values ...]
positional arguments:
{init,status,place,clear,operator}
init PATH: write a simulated cell config; status: the truth against the
calibration; place X Y: the board's middle at (X, Y) m on the table; clear:
the board off the table; operator: answer the cell's questions until stopped
values init: the config's path; place: X Y in metres
options:
-h, --help show this help message and exit
--cell CELL the cell config (default: $ORA_CELL, else ~/.config/ora/cell.yaml)
--json print one JSON object
--yes skip confirmations
--board-port BOARD_PORT
the port a running cell board serves on
--yaw YAW place: the board's turn, degrees
--seconds SECONDS operator: stop after this long (default: Ctrl-C)
--python PYTHON init: the interpreter with MuJoCo and i2rt (default: this one)
ora baselines
usage: ora baselines [-h] [--json] [--explain] [--environment KIND]
options:
-h, --help show this help message and exit
--json
--explain show how the default resolves and what each tool does
--environment KIND with --explain, show only this environment instance
ora lock
usage: ora lock [-h] [--check] [--strip-pins]
options:
-h, --help show this help message and exit
--check exit 1 and list drift instead of writing
--strip-pins rewrite composable assets to path-only references, then write policy.lock
Developer
ora toolkit
usage: ora toolkit [-h] {provider-replay,replay} ...
positional arguments:
{provider-replay,replay}
provider-replay serve recorded model replies or compare complete requests
replay run a script before a recorded parent tool call
options:
-h, --help show this help message and exit
ora toolkit provider-replay
usage: ora toolkit provider-replay [-h] {serve,compare} ...
positional arguments:
{serve,compare}
serve serve a read-only reply tape; does not start ORA
compare compare every request, with per-image PSNR
options:
-h, --help show this help message and exit
ora toolkit provider-replay serve
usage: ora toolkit provider-replay serve [-h] --output OUTPUT [--listen LISTEN] [--port PORT]
[--ready-file READY_FILE]
source
positional arguments:
source
options:
-h, --help show this help message and exit
--output OUTPUT
--listen LISTEN
--port PORT
--ready-file READY_FILE
atomically publish the bound endpoint (port 0 supported)
ora toolkit provider-replay compare
usage: ora toolkit provider-replay compare [-h] --output OUTPUT source candidate
positional arguments:
source
candidate
options:
-h, --help show this help message and exit
--output OUTPUT
ora toolkit replay
usage: ora toolkit replay [-h] [--at AT | --step STEP | --native-action NATIVE_ACTION] [--snapshot]
(--list | --script SCRIPT | --tool TOOL) [--args ARGS]
[--service-report SERVICE_REPORT] [--output OUTPUT] [--live]
[--resource-profile RESOURCE_PROFILE] [--execute-action] [--json]
run
positional arguments:
run source run directory (read-only)
options:
-h, --help show this help message and exit
--at AT parent tool_call_id or zero-based call ordinal; legacy diagnostic unless
--snapshot
--step STEP completed policy-state step; implies snapshot replay, no simulator/actions
--native-action NATIVE_ACTION
completed native tick count N: state at end of controller native_action=N;
N=0 is reset/before any native action; requires --resource-profile; implies
snapshot, forbids new actions
--snapshot phase-one snapshot path: original bytes and private tool state; planner
requires simulator
--list list parent calls and recording/gap availability
--script SCRIPT Python file defining run(api, args)
--tool TOOL run a migrated tool from the source surface, or check_task, at the selected
boundary
--args ARGS JSON object; required for a different tool, otherwise defaults to original
arguments
--service-report SERVICE_REPORT
qualified perception report, as for spec robodojo compose
--output OUTPUT new output directory; default workspace/toolkit-replay/run_id/UTC-random
outside runs
--live restore a simulator on an already allocated resource profile
--resource-profile RESOURCE_PROFILE
caller-allocated live simulator lane
--execute-action execute one live proposal after the tool returns
--json print machine-readable list or result including output path
ora dev
usage: ora dev [-h] <tool> ...
``ora dev``: authoring tools for embodiments, prompt bundles, task contracts and this CLI.
ora dev embodiment ... validate and compile embodiment descriptors into cards
ora dev prompt-bundle ... create or statically audit one modular prompt bundle
ora dev task-contracts ... the offline task-contract review inventory and rendering
ora dev robolab-tasks ... RoboLab-120's roster, contracts and review drafts from the pinned source
ora dev cli-reference ... docs/usage/cli-reference.md, generated from ora's parser
The rest of the line goes to the tool's own parser (``ora dev prompt-bundle --help``).
The Viewer's own build steps are ``ora-viewer compile previews|videos`` (``viewer/``).
positional arguments:
<tool>
embodiment validate and compile policy-safe embodiment descriptors into cards
prompt-bundle
create or statically audit one modular robot prompt bundle
task-contracts
offline task-contract review inventory, private template and public rendering
robolab-tasks
generate RoboLab-120's roster, completion contracts and review drafts; promote
witnessed ones
cli-reference
print, write or check docs/usage/cli-reference.md
options:
-h, --help show this help message and exit
ora dev embodiment
validate and compile policy-safe embodiment descriptors into cards
Runs ora.agent.composition.embodiment.descriptor:main on the rest of the line.
ora dev prompt-bundle
create or statically audit one modular robot prompt bundle
Runs ora.agent.composition.prompt.bundle:main on the rest of the line.
ora dev task-contracts
offline task-contract review inventory, private template and public rendering
Runs ora.agent.composition.task_contract.review:main on the rest of the line.
ora dev robolab-tasks
generate RoboLab-120's roster, completion contracts and review drafts; promote witnessed ones
Runs ora.orchestrator.backends.robolab.task_catalog:main on the rest of the line.
ora dev cli-reference
print, write or check docs/usage/cli-reference.md
Runs ora.app.cli_reference:main on the rest of the line.
ora help
usage: ora help [-h] [COMMAND|TOPIC|topics ...]
Print the overview, one command's help, or a topic page (ora help topics lists them). A topic comes
before the command of the same name: ora help play is the page, ora play --help the command's
options.
positional arguments:
COMMAND|TOPIC|topics a command (and its subcommands), a topic page, or `topics` to list them
options:
-h, --help show this help message and exit