Essentials

Set up your environment and tools

Updated: Sep 4, 2026

Overview

Meta VR CLI (metavr) sets up and manages your development environment for Meta VR devices. Use it to check what you have installed, add developer tools and a simulator, and configure the CLI itself. This guide also covers sign-in and telemetry.

Prerequisites

Meta VR CLI installed. See Install Meta VR CLI.
A terminal on macOS or Linux, or PowerShell on Windows.
A Meta account, if you plan to sign in. Nothing else here needs one.

Steps

1. See what you already have

metavr doctor

The command is read-only and takes no flags. It reports installed software in five groups:

Meta developer tools
Android Studio and the Meta Horizon plugin
The Android software development kit (SDK)
Java
Installed Unity editors

It does not test device connections, sign-in, or agent setup. It ends by pointing you at metavr init or at a specific metavr tools install command for anything missing.

2. Install a tool

metavr tools list

The list reflects your operating system and your account access, so treat what you see on your own machine as authoritative over any printed table.

metavr tools info spatialsim
metavr tools install spatialsim

install takes these flags:

--connections <N> sets parallel download connections, from 1 to 16.
--elevate requests elevation on Windows.
--status reports install progress instead of installing.

To manage what you have:

metavr tools update <TOOL>
metavr tools update --all
metavr tools uninstall <TOOL>
metavr tools launch <TOOL>

uninstall and launch only handle installs that metavr created. A copy you installed yourself is detected but left alone. launch passes anything after -- through to the tool.

Tools available on a public build include:

Tool	What it is	Platforms
`spatialsim` (alias `ssim`)	Meta Spatial Simulator, an Android emulator for spatial computing development	macOS arm64, Windows
`xrsim`	Meta XR Simulator	macOS arm64, Windows
`renderdoc`	Meta’s fork of the RenderDoc graphics debugger	macOS arm64, Windows
`perfetto`	Perfetto trace processor, used by the performance commands	all
`platform-utils` (alias `ovr-platform-util`)	Submits builds to the Meta Horizon Store	macOS, Windows, Linux
`haptics-studio`	Meta Haptics Studio, for designing controller haptics	macOS arm64, Windows
`spatial-editor`	Meta Spatial Editor, a 3D scene editor	macOS, Windows, Linux

Note: This is a sample, not the full registry. Run metavr tools list for what your build offers. That list can include entries needing access your account does not have, and installing one of those reports that the feature is not enabled.

3. Run a simulator

Meta VR CLI drives two different simulators. Choose the one that matches your app:

Meta Spatial Simulator runs 2D panel apps. Use metavr ssim.
Meta XR Simulator runs immersive OpenXR apps on macOS and Windows. Use metavr xrsim.

Meta Spatial Simulator

metavr ssim (alias emu) drives Meta Spatial Simulator:

metavr ssim download
metavr ssim start
metavr ssim status
metavr ssim stop

Spatial Simulator renders 2D panel apps. It has no VR (OpenXR) runtime, so a fully immersive app cannot run on it. Test immersive apps on a device, or with Meta XR Simulator. To build the 2D apps it does run, see Android apps.

download takes --force to re-download and reinstall over an existing install.

start takes --name <N>, --release-build, --force-sync, and --wipe-data. Keep it current with metavr ssim check-update and metavr ssim update. update takes -y/--yes to skip the confirmation prompt, for plugin and other non-interactive use.

Note: When you embed Meta VR CLI in another tool, start also takes --developer-platform <PLATFORM> and --developer-platform-session-id <ID>. Both attribute telemetry to the calling platform.

To manage the simulated account inside the emulator:

metavr ssim auth login
metavr ssim auth status
metavr ssim auth logout

All three take -s/--serial to name a target when more than one simulator is running. ssim auth login also takes --access-token, --user-id, --profile-token, and --profile-id.

Meta XR Simulator

metavr xrsim drives Meta XR Simulator on macOS and Windows, so you can test immersive OpenXR apps without a device. Connection flags: --port (default 33794), --runtime-addr, and --timeout (default 5.0). The root-level --format table|json|plain option selects the output form, as it does for every metavr command.

Its subcommands group by what they control:

Group	Subcommands
`runtime`	`activate`, `deactivate`, `ping`, `status`, `info`, `fps`, `logs`, `list`
`app`	`launch`, `quit`, `ensure-running`
`device`	`set`, `ipd`, `refresh-rate`, `list`, `refresh-rates`
`env`	`set`, `list`
`input`	`source`, `controller`, `headset`, `point-and-click`, `follow`, `speed`, `compatibility-mode`, `sync`, `sources`
`layer`	`toggle`, `list`

metavr xrsim runtime activate
metavr xrsim runtime status
metavr xrsim device list
metavr xrsim runtime logs --tail 50

What each command needs:

runtime logs reads local log files. Nothing has to be running. It takes --tail <N> to print the last N lines of each log.
runtime activate, runtime deactivate, runtime list, and the app and env groups act on the frontend or the system.
runtime ping, status, info, fps, and the device, input, and layer groups need the frontend running with your application connected. They report a no-runtime or no-app state when it is not.

runtime activate and runtime deactivate set the system-wide OpenXR runtime, so they can prompt for administrator access.

Note: Requires Meta VR CLI 1.7 or later.

For what the simulator itself does, see Meta XR Simulator for Native, Unity, or Unreal.

4. Change CLI settings

metavr config list
metavr config get output-format
metavr config set output-format json
metavr config reset output-format

There are four settable keys:

Key	Meaning	Values	Default
`adb-path`	Path to the Android Debug Bridge (ADB) executable. `set` verifies the path and refuses a broken one. `reset` returns to auto-detect.	a path	auto-detect
`default-device`	Device serial used when you omit `--device`	non-empty string	not set
`output-format`	Default output format	`table`, `json`, `plain`	`table`
`color`	Colored output	`true`, `false`	`true`

metavr config get also reports where a value came from. metavr config path prints the settings file, and metavr config path --auth prints the credential file.

Config lives in ~/.config/metavr/ on Linux, ~/Library/Application Support/metavr/ on macOS, and %APPDATA%\metavr\ on Windows. Override it with METAVR_CONFIG_DIR. If you used the CLI under its former name, your settings and credentials are copied forward once, automatically.

Manage Unity editors and projects

Note: Requires Meta VR CLI 1.7 or later.

metavr unity editors list
metavr unity editors releases
metavr unity editors install <VERSION> --modules android
metavr unity editors add-modules <VERSION> --modules android

--modules takes a comma-separated list. Add --cm to include child modules. Module names include android, android-sdk-ndk-tools, android-open-jdk, ios, linux, webgl, and visualstudio.

metavr unity projects list
metavr unity projects status
metavr unity projects open <PROJECT_PATH>
metavr unity projects close

projects list takes an optional search path, and --depth defaults to 3. projects open uses the editor version the project already targets, and waits up to 30 seconds unless you pass --no-wait.

metavr auth status
metavr auth login
metavr auth logout

auth status takes --quick to skip the network check, or --validate to probe the API. auth login opens your browser. auth logout takes --local-only to clear this machine while leaving the Meta-side session alone.

Tokens live in your operating system credential store under the service name Meta VR CLI. Only Meta Horizon Store commands require signing in.

Telemetry

metavr telemetry status
metavr telemetry enable
metavr telemetry disable
metavr telemetry about

There are two tiers. enable opts in to additional analytical telemetry, and disable returns to essential only. Essential data is collected either way, and disable says so.

When you are signed in, your preference syncs to your Meta account. When you are signed out it applies to this machine, and the CLI tells you it did not sync.

Record and replay a session

Note: Requires Meta VR CLI 1.7 or later.

TapeDeck is an OpenXR API layer. It records a session on a device, then replays it into a later run of the same app. Use it for repeatable performance runs, and to reproduce input-dependent bugs without wearing the device.

metavr tapedeck doctor
metavr tapedeck bundle-apk --in app.apk --out app-tapedeck.apk
metavr tapedeck record -p com.example.myapp
metavr tapedeck stop
metavr tapedeck replay -p com.example.myapp
metavr tapedeck list
metavr tapedeck pull

tapedeck doctor checks the host tools it needs. record takes --duration-ms, which defaults to five minutes.

Note: metavr tapedeck install and metavr tapedeck uninstall appear in the help output but need access that is off by default. Use bundle-apk instead, which needs none.

Distribute a build

Note: Requires Meta VR CLI 1.7 or later.

metavr store dist apps --org <ORG_ID>
metavr store dist channels --app-id <APP_ID>
metavr store dist upload --app-id <APP_ID> --channel BETA --apk app.apk --notes "Build notes"
metavr store dist copy-build --binary-id <BINARY_ID> --to-channel <CHANNEL_ID>

--channel takes ALPHA, BETA, RC, or LIVE. Add --obb <PATH> for an expansion file. Uploads create a draft; add --publish to publish straight away.

metavr store test-user list --org <ORG_ID>
metavr store test-user create --org <ORG_ID> --username-prefix testuser --email-prefix testuser --password <PASSWORD>

Every metavr store command requires signing in. upload also needs the platform-utils tool from step 2.

Troubleshooting

A tool will not install

Symptom: An entry from metavr tools list fails to install, reporting that the feature is not enabled.

Solution: That tool needs access your account does not have. The list shows more than your account can install.

metavr tools launch does nothing

Symptom:metavr tools launch <TOOL> does nothing for a tool you know is on the machine.

Solution:launch and uninstall only handle installs metavr created. A copy you installed yourself is detected but not managed. Install it through metavr tools install to manage it here.

Symptom: A metavr store command fails and tells you to sign in.

Solution: Run metavr auth login, then run the command again.