metavr-cli

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

metavr CLI Reference

metavr CLI参考指南

What metavr Does

metavr的功能

metavr (Meta VR CLI) is a CLI for Meta Quest and Horizon OS development. It wraps ADB and Meta developer APIs into higher-level commands for device management, app lifecycle, documentation lookup, screenshots, audio control, test-device preparation, MCP integration, and Perfetto performance analysis.

Keep this

SKILL.md

as the routing layer. For exact flags and complete command syntax, use the generated full CLI reference in

docs/hzdb.md

or run:

bash

npx -y metavr --markdown-help

metavr（Meta VR CLI）是一款用于Meta Quest和Horizon OS开发的CLI工具。它将ADB和Meta开发者API封装为更高级的命令，可用于设备管理、应用生命周期管理、文档查询、截图、音频控制、测试设备准备、MCP集成以及Perfetto性能分析。

请将此

SKILL.md

作为路由层。如需精确的参数和完整的命令语法，请使用

docs/hzdb.md

中生成的完整CLI参考文档，或运行：

bash

npx -y metavr --markdown-help

Installation

安装

Requires Node.js 20 or newer.

Invoke via

npx

bash

npx -y metavr --help
npx -y metavr --version

npx

is the recommended path: it always pulls the latest published version, so you don't end up running an outdated global install. Examples in the rest of the documentation use the bare

metavr

command for brevity — substitute

npx -y metavr

for any of them.

Alternatively, install metavr globally using:

bash

npm install -g metavr

If you install globally, update regularly with

npm update -g metavr

. Use

npx -y metavr

when you want the latest published version without depending on a global install.

需要Node.js 20或更高版本。

通过

npx

调用：

bash

npx -y metavr --help
npx -y metavr --version

推荐使用

npx

：它始终拉取最新发布的版本，因此你不会运行过时的全局安装版本。文档其余部分的示例为简洁起见使用裸

metavr

命令——你可以将它们替换为

npx -y metavr

。

或者，使用以下命令全局安装metavr：

bash

npm install -g metavr

如果全局安装，请定期使用

npm update -g metavr

更新。当你想要使用最新发布版本而不依赖全局安装时，请使用

npx -y metavr

。

Device Connection

设备连接

Before using on-device commands:

Enable Developer Mode on your Quest (Settings > System > Developer)
Enable USB Debugging when prompted
Connect your Quest to your computer via USB-C

Verify the connection:

bash

metavr device list

If no devices appear: try a different USB cable (data-capable, not charge-only), accept the USB debugging prompt on the headset, or connect wirelessly with

metavr device connect <ip>

使用设备端命令之前：

在你的Quest上启用开发者模式（设置 > 系统 > 开发者）
出现提示时启用USB调试
通过USB-C将你的Quest连接到电脑

验证连接：

bash

metavr device list

如果未显示设备：尝试更换USB线缆（需支持数据传输，而非仅充电），在头显上接受USB调试提示，或使用

metavr device connect <ip>

进行无线连接。

Command Discovery

命令查找

Use progressive disclosure:

Start with this skill for command groups and common workflows.
Open a focused reference file when the user is working in that area.
Use
```
docs/hzdb.md
```
or
```
metavr --markdown-help
```
for exact flags, arguments, and less common subcommands.

Current top-level command groups:

Group	Use for
`adb` / `shell`	Low-level ADB-compatible commands and direct device shell access
`app`	Install, list, launch, stop, clear, inspect, and detect the foreground app
`asset`	Search Meta's 3D asset library
`audio`	Read volume, set volume, mute, and unmute device audio
`capture`	Capture screenshots from a connected headset
`config`	Read, write, reset, and list metavr configuration
`device`	List/connect devices, wait for ADB state, inspect controllers, configure test devices, run health checks, and manage proximity
`docs`	Search/fetch Meta Quest docs and API reference entries
`files`	List, pull, push, remove, and create directories on the device
`log`	View recent device logs; use `adb logcat` for advanced filters and streaming
`mcp`	Start or install the metavr MCP server for AI tools
`perf`	Capture, open, analyze, query, compare, and manage Perfetto traces

使用渐进式披露方式：

从本技能开始了解命令组和常见工作流。
当用户在特定领域工作时，打开针对性的参考文件。
使用
```
docs/hzdb.md
```
或
```
metavr --markdown-help
```
获取精确的参数、参数值和较不常用的子命令。

当前顶级命令组：

组	用途
`adb` / `shell`	兼容ADB的低级命令和直接设备shell访问
`app`	安装、列出、启动、停止、清除、检查和检测前台应用
`asset`	搜索Meta的3D资源库
`audio`	读取音量、设置音量、静音和取消设备音频静音
`capture`	从已连接的头显捕获截图
`config`	读取、写入、重置和列出metavr配置
`device`	列出/连接设备、等待ADB状态、检查控制器、配置测试设备、运行健康检查以及管理接近感应
`docs`	搜索/获取Meta Quest文档和API参考条目
`files`	在设备上列出、拉取、推送、删除和创建目录
`log`	查看近期设备日志；使用 `adb logcat` 进行高级过滤和流式传输
`mcp`	启动或安装用于AI工具的metavr MCP服务器
`perf`	捕获、打开、分析、查询、比较和管理Perfetto跟踪数据

MCP Server Mode

MCP服务器模式

metavr includes a built-in MCP (Model Context Protocol) server with ~40 tools that enable AI agents to interact with Quest devices programmatically.

Add this command to any MCP configuration to use the MCP server:

bash

metavr mcp server

The server exposes tools for device management, app lifecycle, performance trace analysis, documentation search, file operations, and 3D asset search.

Install MCP configuration into other AI tools:

bash

metavr mcp install cursor
metavr mcp install claude-desktop
metavr mcp install vscode

For project-local agent setup, install the MCP config into the current repository:

bash

cd your-project
metavr mcp install project

This is the best default when a coding agent already has repository access on the host machine and should be able to call metavr tools from that project.

metavr包含一个内置的MCP（Model Context Protocol）服务器，带有约40个工具，可让AI Agent以编程方式与Quest设备交互。

将以下命令添加到任何MCP配置中以使用MCP服务器：

bash

metavr mcp server

该服务器提供用于设备管理、应用生命周期、性能跟踪分析、文档搜索、文件操作和3D资源搜索的工具。

将MCP配置安装到其他AI工具中：

bash

metavr mcp install cursor
metavr mcp install claude-desktop
metavr mcp install vscode

对于项目本地Agent设置，将MCP配置安装到当前仓库：

bash

cd your-project
metavr mcp install project

当编码Agent已拥有主机上的仓库访问权限，并且应该能够从该项目调用metavr工具时，这是最佳默认选项。

Common Agent Workflow

常见Agent工作流

If you are building a Quest-native developer tool or pairing a Quest headset UI with a host-side coding agent, keep the architecture simple:

Let the host-side coding agent own repository access, file edits, builds, tests, and metavr tool calls
Let the headset app or browser experience act as a thin client for preview, prompt capture, status, and approval
Prefer project-local MCP installation with
```
metavr mcp install project
```
so the integration is explicit and travels with the repository

bash

undefined

如果你正在构建Quest原生开发者工具，或将Quest头显UI与主机端编码Agent配对，请保持架构简洁：

让主机端编码Agent负责仓库访问、文件编辑、构建、测试和metavr工具调用
让头显应用或浏览器体验充当预览、提示捕获、状态显示和审批的瘦客户端
优先使用
```
metavr mcp install project
```
进行项目本地MCP安装，这样集成是明确的，并且随仓库一起迁移

bash

undefined

1. Verify the current docs before coding against an API or workflow

1. 在针对API或工作流编码之前，验证当前文档

metavr docs search "spatial sdk panel" metavr docs fetch https://developers.meta.com/horizon/documentation/...

2. Build and deploy your app

2. 构建并部署你的应用

./gradlew assembleDebug metavr app install app/build/outputs/apk/debug/app-debug.apk metavr app launch com.example.app

3. Observe on-device behavior

3. 观察设备端行为

metavr log --tag MyApp metavr capture screenshot -o latest.png

4. Prepare a stable test device when running repeatable tests

4. 运行可重复测试时，准备稳定的测试设备

metavr device health-check metavr device configure-testing setup

...run tests...

...运行测试...

metavr device configure-testing restore

undefined

metavr device configure-testing restore

undefined

Relationship to ADB

与ADB的关系

metavr wraps ADB and provides higher-level commands. You do not need to use

adb

directly for most Quest development tasks. metavr handles device selection, provides structured output, and adds Quest-specific functionality (screenshots via metacam, Perfetto trace analysis, doc search) that raw ADB does not support.

If you need raw shell access to the device, use

metavr shell

metavr adb shell

metavr封装了ADB并提供更高级的命令。大多数Quest开发任务你不需要直接使用

adb

。metavr处理设备选择，提供结构化输出，并添加了原始ADB不支持的Quest特定功能（通过metacam截图、Perfetto跟踪分析、文档搜索）。

如果你需要对设备进行原始shell访问，请使用

metavr shell

或

metavr adb shell

。

Full Command Reference

完整命令参考

Use

docs/hzdb.md

for generated command details. Regenerate it with:

bash

npx -y metavr --markdown-help > docs/hzdb.md

如需生成的命令详细信息，请使用

docs/hzdb.md

。使用以下命令重新生成它：

bash

npx -y metavr --markdown-help > docs/hzdb.md

References

参考资料

For detailed usage guides with workflows, examples, and troubleshooting:

Device Management — device commands, audio, screenshots, logs, test setup, health checks, shell access
App Management — app lifecycle, foreground app detection, crash debugging, common log tags
Agent Workflows — project-local MCP install, docs verification, safety, thin-client architecture
Performance Tools — trace capture, guided analysis, Perfetto UI, SQL queries, comparisons, GPU counters
Documentation Search — doc search, API search, category filtering

如需包含工作流、示例和故障排除的详细使用指南：

设备管理 —— 设备命令、音频、截图、日志、测试设置、健康检查、shell访问
应用管理 —— 应用生命周期、前台应用检测、崩溃调试、常见日志标签
Agent工作流 —— 项目本地MCP安装、文档验证、安全性、瘦客户端架构
性能工具 —— 跟踪捕获、引导式分析、Perfetto UI、SQL查询、比较、GPU计数器
文档搜索 —— 文档搜索、API搜索、类别过滤