Essentials

Set up your environment and tools

Updated: Aug 31, 2026

Overview

Meta VR CLI (metavr) sets up and manages your development environment for Meta Quest. Use it to check what you have installed, add developer tools and a simulator, and configure the CLI itself. This guide covers each of those in turn, then 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 headset 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

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 headset, 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.

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.

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.

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.