Hz Xr Simulator Control

XR Simulator Control

metavr is overwhelmingly a physical Quest or Glasses CLI: device, app, capture, input, log, files and ui all talk to a headset over ADB. xrsim is one group among them and drives a simulated headset instead. Choosing the wrong group is the most common failure here, and it is quiet: metavr device list prints No devices connected and exits 0, so the wrong answer looks healthier than the right one.

This skill drives a simulator that already exists. Installing one, or wiring it into a project, belongs to hz-xr-simulator-install-and-configure.

Which Command Group

Read the Use column as the right tool for that goal and Not as the one you might reach for by mistake. The last two rows are in this table because they are the mistakes, not because they are this skill's job.

Three are worth stating outright, because a plausible command exists on both sides:

• "Record an OpenXR session" is the most confusable intent in the CLI. xrsim record captures the simulator's compositor output to MP4; tapedeck captures and replays an app's OpenXR call stream on a physical device. They are not substitutes.
• "The simulator" is ambiguous inside this binary. ssim is the SpatialSim emulator, xrsim is the Meta XR Simulator.
• device, app and input exist both at the top level and under xrsim, so the same verb means different things depending on the group. capture does not: there is no xrsim capture, and the simulator equivalent is xrsim record.

The Three Connection Tiers

Once you are inside xrsim, what a command needs decides which error you get.

device list and device refresh-rates read like static catalogs but come from the live runtime. input sources prints a fixed list yet still needs a connection, because the input group opens one before it dispatches.

Two that a reasonable guess gets wrong in the other direction:

• The app group is how you fix a down frontend, not something blocked by one. app launch and app ensure-running start it if it is absent. app quit asks the frontend on --port to close; --force terminates that same process instead, and --all is the explicit escape hatch for stopping every MetaXRSimulator on the host. Treating lifecycle commands as frontend-tier rules out the recovery.
• Bare record is local on Linux. Without --runtime-addr it never connects — it captures the framebuffer through ffmpeg, so it needs ffmpeg on PATH but neither tier. The record start / stop / status subcommands are runtime-tier and additionally refuse to run on Linux without --runtime-addr.

Each error names exactly one hop, so do not retry blindly.

Check liveness with a frontend-tier command before asking runtime-tier questions. A refused connection returns XR Simulator is not running immediately, and --timeout is the total connection budget rather than a fresh budget for every retry. runtime list also distinguishes a reachable frontend with no attached app from a missing frontend, while runtime status requires an attached runtime.

So diagnose in tier order — cheapest first, stopping at the first failure:

metavr xrsim runtime logs                             # local: paths resolve with nothing running
metavr xrsim runtime list --format json --timeout 2   # frontend reachable? how many runtimes?
metavr xrsim runtime status --format json             # only once a runtime is attached

runtime logs goes first precisely because it is the one that still answers when everything else is down: when runtime list fails, the log paths are what say why the frontend will not come up, and the XR Simulator is not running row above cannot tell you that.

runtime list returning [] is the frontend being up with no app connected — a different failure from the frontend being down, needing a different fix. More than one entry is its own trap: the runtime-tier groups follow the frontend's current endpoint, so pin one with --runtime-addr rather than guessing which answered.