quest-tooling

The Quest toolchain: one CLI, two interfaces, one channel per agent

metavr (Meta VR CLI) is a single tool with two faces: a command line, and a stdio MCP server an agent drives on its own. Everything below is available through both — the CLI names are given because they are also the fallback when no MCP server is configured.

Read references/research-navigation.md when planning research, choosing a capture/automation path, handling conflicting sources or working without a tool. Resolve the executable and inspect that version's help before using this dated command map; generated companion instructions may describe a different version.

For a whole-product roadmap or stage audit, use quest-lifecycle; a single technical task stays with this owner. If absent, identify the current stage, its evidence and the next prerequisite inline.

Read references/source-research.md for current-source discovery, unavailable Markdown, conflicting requirements, versioned API indexes and existing CLI/MCP registrations.

Install it once, through one channel

Channel	Command	Updates
Native installer (preferred)	curl -fsSL https://developers.meta.com/horizon/install-cli/ | sh → ~/.metavr/bin	metavr update, in place
npx, no install	npx -y metavr@latest <cmd>	always current
npm global	npm install -g metavr	never on its own — needs npm update -g metavr

Two of these installed at once is a version split waiting to be read as a bug: on one measured machine ~/.metavr/bin/metavr (1.3.2.2.2) and /opt/homebrew/bin/metavr (npm 1.3.2) both answered to metavr, and PATH order decided which. Check with which -a metavr and keep one.

Sign in — metavr auth login, verify with metavr auth status. It unlocks the Store commands; METAVR_TOKEN covers unattended automation.

metavr init is the trap, not the setup

init installs skills, configures MCP servers and installs agent plugins. With no target flag it means --all-agents, and "all agents" is its own fixed list, not the agents you have. Run inside a project directory it writes one skills/ tree per agent into that directory.

Measured 2026-09-20 in a game repository: 29 skills × 25 directories = 4129 files, 47 MB, untracked, uncovered by .gitignore — and the next git add -A committed the lot into the product.

Before setup, check whether metavr's MCP server is already registered, by Meta's plugin or in the agent host's own MCP config. If it is not, register it once in the selected host's MCP config; metavr mcp install writes host configs, so read its --help for which ones first. If a selected host installation is needed, inspect metavr init --help and the target paths first. Do not ignore project-owned .agents or other existing files broadly.

The command map

Job	Command
What is attached	metavr device list / device info <id> / device battery
Pair over Wi-Fi	metavr device connect (USB first), device wait, device health-check
Make a device test-stable	metavr device configure-testing (animations off, stay awake)
Install / launch / stop a build	metavr app install <apk> / app launch <pkg> / app stop <pkg>
Logs	metavr log (logcat), metavr shell <cmd>
Screens	metavr capture screenshot
Files on device	metavr files push / pull / ls / rm
UI automation	metavr ui dump / tap / type / swipe / wait
Performance	metavr perf capture / start / stop / analyze-trace / compare / simpleperf
Docs and API reference	metavr docs search / fetch / api-search
3D assets	metavr asset search "<thing>"
Store distribution	metavr store dist apps / channels / upload / copy-build; store test-user
Emulator	metavr ssim (SpatialSim)
Managed tools	metavr tools list / install <name>
Setup report	metavr doctor

metavr doctor reports installed software only — it does not test device connectivity, sign-in or MCP wiring. A green doctor with no headset attached is still a machine that cannot run anything.

The MCP server, and how it ends up registered twice

metavr mcp server is the stdio server. Meta's plugin may own its registration; otherwise it is declared in the agent host's own MCP config (user or project scope). Inspect both before adding anything and never register it twice: plugin-managed MCP stays with the plugin, and OAuth protected-resource servers authenticate at the host. A project .mcp.json is one host-config option, not a universal project setup recipe.

metavr xroperator status shows whether the XR Operator proxy is installed and federated into metavr's own MCP server — when it is, a running XR app can be inspected through the same connection; no second server to register.

Meta's 29 skills, and what this pack adds

Meta publishes them at github.com/meta-quest/agentic-tools (plugin meta-vr@meta-quest, also on npx skills, gh skill, Cursor, Codex, Gemini). The split is worth knowing before wondering which one to reach for:

Meta's skills	Count	Owner of the lane
hz-unity-*	12	Unity — this pack does not duplicate them
hz-quest-verify-first, metavr-cli, portal	3	doc verification and CLI reference
hz-perfetto-debug, hz-simpleperf-debug, hz-vr-debug	3	driving a specific profiler
hz-store-submit, hz-store-pwa	2	store mechanics
hz-spatial-sdk, hz-iwsdk-webxr, hz-android-2d-porting, hz-platform-sdk, hz-psdk-integration, others	9	other build paths

This pack answers the questions that sit above a tool: which lane a project is on, which number to read, what to measure, what the Store will reject. Where a Meta skill drives the tool, use it — and say which one did the work.

No headset on the desk

• xrsim (Meta XR Simulator) and spatialsim (metavr ssim) run app logic on the machine. They check supported simulated behavior and integration.
• They cannot answer a performance question: no real GPU, no thermals, no compositor. See quest-perf.
• metavr device browser <url> and the Store test accounts (metavr store test-user) need a real device and an organization.

Managed developer tools

metavr tools install <name> fetches and installs; metavr tools list shows versions and what is present. What each is for — including which need a headset — is in references/tool-matrix.md.

Hygiene, because the estate pays for it later

1. One channel per agent. A plain copy under ~/.claude/skills/<name> beats the plugin of the same name and serves its frozen version forever.
2. Never vendor skills into a product repository. They are installed on the machine; a repo copy is 47 MB of a third party's text your CI now lints.
3. Skills and plugins load at session start — restart the agent after changing either, or it keeps the old set.
4. After any install or removal, the check that must print nothing:

for d in ~/.claude/skills/*/; do n=$(basename "$d"); \
  [ -e ~/.claude/plugins/marketplaces/"$n" ] && echo "SHADOW: $n"; done

CLI surface read from metavr --help at 1.3.2.2.2 on 2026-09-20; the install and init behaviour was measured on this machine the same day.

Triggers

More phrases that route here: "adb to Quest" / "adb к шлему", "XR Simulator" / "симулятор", "no headset" / "нет шлема", "metavr init", "Meta VR CLI", "Quest MCP" / "MCP для Quest", "install the APK" / "поставить apk на шлем", "developer mode" / "режим разработчика", "which Quest tools are installed" / "что установлено для Quest", "hz- skills" / "скилы Meta".

Moved here from the description in 0.4.4: "connect the headset".

Qualified forms that name the headset, added in 0.4.5 (hub B-298): "Meta XR Simulator" / "симулятор Quest", "install the APK on Quest" / "поставить apk на Quest", "Quest developer mode" / "режим разработчика на Quest".