Develop

Install Meta VR CLI for Android apps

Updated: Aug 31, 2026

Overview

Meta VR CLI (metavr) is a single developer tool with two interfaces: a command line you run directly from your terminal, and a Model Context Protocol (MCP) server that your AI coding agent drives on your behalf. This guide installs the metavr command, verifies the install, and connects the tool to an AI agent so it can search documentation, manage connected devices, and automate other development tasks for you. For background on how the command line and the MCP server relate, see the Meta VR CLI overview.

Prerequisites

A terminal on macOS or Linux, or PowerShell on Windows

Node.js 18 or later, if you plan to install with npm instead of the native installer

An AI coding agent already installed, if you want to connect one during setup

Steps

1. Install the CLI

Install the CLI with the native installer. The installer detects your operating system and architecture, downloads the matching binary, and adds it to your PATH.

macOS / Linux

Windows

curl -fsSL https://developers.meta.com/horizon/install-cli/ | sh

By default, the macOS and Linux script installs to ~/.metavr/bin, and the Windows script installs to %USERPROFILE%\.metavr\bin. Set METAVR_HOME before running the installer to choose a different location, or METAVR_NO_PATH to skip the PATH changes.

When the installer finishes, it prints metavr init as the next step.

If you have Node.js, you can run the CLI through npm instead. Running it with npx picks up the current release every time, so it is the option to prefer:

npx metavr@latest init

Any command works this way, for example npx metavr@latest device list.

To install it globally instead:

npm install -g metavr

The package downloads a binary for your platform the first time you run it, verifies it, and caches it locally.

Note: A global npm install does not update itself. Run npm update -g metavr to move to a newer release.

2. Verify the installation

Confirm the CLI installed correctly:

metavr --version

A version number prints to confirm the install. Then run the diagnostic report to see what developer software metavr found on your machine:

metavr doctor

metavr doctor reports installed developer software only: Meta developer tools, Android Studio and the Meta Horizon plugin, the Android SDK, the Java JDK/JRE, and installed Unity editors. It does not test device connectivity, sign-in, or MCP setup. The report ends by pointing you to metavr init or metavr tools install <name> for anything missing.

3. Connect your AI agent

Run the guided setup to connect metavr to your AI agent:

metavr init

metavr init walks through seven steps in order: it installs the metavr skill for AI agents, configures the MCP server, installs agent plugins, offers an optional Meta sign-in, asks for telemetry consent, checks developer tools, and shows next steps at the end.

Pass flags to skip the prompts:

metavr init --cursor --no-auth

Available flags: -y/--no-prompt, --all-agents, --no-auth, --claude-code, --cursor, --gemini, --copilot, --codex, and --opencode. Without a flag, metavr init uses --all-agents, falls back to an interactive multi-select, or detects agents already on your PATH.

To configure a single agent instead, use metavr mcp install <target>:

metavr mcp install cursor

Valid targets: android-studio, cursor, claude-desktop, claude-code, vscode, vscode-insiders, codex, zed, windsurf, antigravity, gemini-cli, open-code, lm-studio, and project. The project target writes a project-scoped configuration in your current directory instead of a global one. If you use the Meta Horizon Android Studio plugin, use the android-studio target.

The metavr MCP server communicates over stdio. To start it directly, run metavr mcp server.

Note: metavr init offers to sign you in, and signing in is worth doing. It unlocks Meta Horizon Store commands and other account-backed features, and more will depend on it over time. You can sign in at any point with metavr auth login, which opens your browser.

4. Keep the CLI up to date

Update the CLI when a new version ships:

metavr update

Add --version <V> to install a specific version, --dry-run to preview the update, or --force to reinstall the current version.

This works for a binary from the native installer, which updates itself in place. If you installed through a package manager, update through that instead, and metavr update tells you so rather than changing anything:

npm update -g metavr

Run your first command

You can run metavr directly from your terminal, without going through your AI agent, to explore what it can do.

metavr --version: confirms your installed version. No device or sign-in needed.

metavr doctor: lists the developer software metavr found on your machine. No device or sign-in needed.

metavr docs search "passthrough rendering": searches Meta Quest documentation and API references. No device or sign-in needed.

metavr asset search "office chair": searches the 3D asset catalog, returning five results by default and up to ten. No device or sign-in needed.

metavr device list: lists connected devices. Needs a device.

metavr capture screenshot: captures a screenshot from a connected device, saving a 1024x1024 image named screenshot_<timestamp>.png by default. Needs a device.

To inspect a specific device, run metavr device list first to get a device ID, then pass it to metavr device info <device_id>.

Common flags work across every command:

-d, --device <DEVICE>: targets a specific device.

--format <table|json|plain>, or --json as a shortcut, sets the output format.

--color <auto|always|never>: controls colored output.

-v, -vv, -vvv, and -q: control log verbosity.

With more than one headset attached, pick a target with --device, or set a default once:

metavr config set default-device 1WMHH000X00000

--device overrides the default. The HZDB_DEVICE environment variable sets it too. For automation, set METAVR_TOKEN so scripts do not need an interactive sign-in.

These commands are a small sample. metavr also covers:

Device management, plus app and build installation

File transfer, device logs, and shell access

Screenshots and user interface automation

Performance capture and trace analysis

Documentation, application programming interface (API) reference, and 3D asset search

Meta Horizon Store distribution

Managed developer-tool installs and simulators

Run metavr --help for the full list, or let your AI agent discover these capabilities through the MCP server you configured in the previous step.

Troubleshooting

npm reports an unsupported platform

Symptom:npm install -g metavr fails with metavr: unsupported platform, followed by your platform name and the list of platforms the package covers.

Solution: The npm package downloads a prebuilt binary, and it has none for your platform. The native installer covers macOS, Linux, and Windows, so use that instead.

On macOS and Linux:

curl -fsSL https://developers.meta.com/horizon/install-cli/ | sh

In PowerShell on Windows:

iwr -useb https://developers.meta.com/horizon/install-cli/windows/ | iex

The metavr command is not found after install

Symptom: The installer finishes, but a new terminal session reports command not found: metavr (or metavr is not recognized on Windows).

Solution: The installer adds its install directory to your shell profile: ~/.bash_profile or ~/.bashrc for bash, ~/.zshrc for zsh, ~/.config/fish/conf.d/metavr.fish for fish, and ~/.profile for anything else. On Windows, it updates your user Path. Open a new terminal window so the change takes effect. If you set METAVR_NO_PATH before installing, add the install directory to your PATH manually.

The installer reports a webpage instead of a binary

Symptom: On macOS or Linux, the installer prints an error saying it received an HTML page instead of the metavr binary. The Windows installer does not make this check, so the same cause surfaces there as a failure to extract the download.

Solution: The download request did not reach the release server. A proxy, firewall, or captive portal can rewrite the response before it arrives. Check your network connection and any proxy settings, then run the installer again.