Essentials

Work with devices and apps

Updated: Aug 28, 2026

Overview

This guide shows you how to connect a Meta Quest headset to Meta VR CLI (metavr), install and manage apps, move files, read logs, and automate the interface. Use these tasks to set up a headset for development or testing.

Prerequisites

Meta VR CLI installed. See Install Meta VR CLI.

Developer Mode enabled on the headset.

A USB-C data cable. Charge-only cables do not carry data.

USB debugging authorized on the headset.

Note: You do not need a separate adb install. The CLI has its own embedded device-communication library and uses it by default.

Steps

1. Connect a device

Plug in the headset with a USB-C data cable, then put the headset on. The first time the CLI talks to it, the headset shows a USB debugging prompt. Accept it and choose “Always allow from this computer”.

Confirm the connection:

metavr device list

The output lists the ID of each attached device. You use that ID with other commands.

To work over Wi-Fi, turn on Android Debug Bridge (ADB) over Wi-Fi and connect by address:

metavr device wifi enable
metavr device connect 192.168.1.10

The port defaults to 5555 when you leave it off. Disconnect with metavr device disconnect <ADDRESS>, or leave the address off to disconnect every device.

2. Check device status

metavr device info <DEVICE_ID>

<DEVICE_ID> is required. Take it from metavr device list.

Other status commands:

metavr device battery shows the battery state.

metavr device os shows the version, build, branch, and lock state.

metavr device health-check checks connectivity, battery, storage, and the interface.

metavr device boundary shows the boundary status. Add --enable or --disable to change it.

3. Target a device when several are attached

Pick one with -d on any command:

metavr device battery -d <DEVICE>

Or set a default once:

metavr config set default-device <SERIAL>

The HZDB_DEVICE environment variable also selects a device.

Note: metavr files commands skip the default. Pass -d to those whenever more than one device is attached.

4. Install and launch an app

metavr app install my-app.apk

Useful flags:

-r/--replace reinstalls and keeps app data. There is no --reinstall flag.

-g/--grant-permissions grants runtime permissions on install.

-t/--allow-test allows test packages.

--downgrade allows installing an older version over a newer one.

Launch it:

metavr app launch com.example.myapp

--cold-start forces a fresh process.

--wait-for-idle waits for the app to settle before returning.

--verify checks the logs for a launch crash afterward, and exits non-zero if it finds one.

List what is installed with metavr app list, narrowing by package-name substring with -f/--filter <SUBSTR>. Get detail on one package with metavr app info <PACKAGE>.

5. Manage installed apps

metavr app stop com.example.myapp
metavr app clear com.example.myapp -y
metavr app uninstall com.example.myapp -y

-y/--yes is required when stdin is not a terminal, which covers continuous integration jobs. Add -k/--keep-data to uninstall but leave app data in place.

6. Move files and read logs

metavr files ls /sdcard/
metavr files pull /sdcard/report.txt
metavr files push report.txt /sdcard/report.txt

ls defaults to /sdcard/, and -a/--all shows hidden files. pull defaults to the current directory. Create directories with metavr files mkdir <PATH>, where -p/--parents defaults to true. Remove with metavr files rm <PATH> -y, adding -r/--recursive for a directory.

Read device logs:

metavr log -n 200 -l E

-n/--lines <N> defaults to 100.

-t/--tag <TAG> filters by tag.

-l/--level <V|D|I|W|E|F> filters by level.

-c/--clear clears the buffer.

Run a single command on the device:

metavr shell pwd

An interactive shell is not supported, so each call runs one command. For anything the shortcuts leave out, drop to the full ADB surface:

metavr adb logcat --pid <PID> --follow

7. Automate the interface

metavr capture screenshot -o screenshot.png

The default size is 1024x1024. Change it with --width and --height. Without -o/--output, the file saves as screenshot_<timestamp>.png.

Read the interface hierarchy, then act on it:

metavr ui dump
metavr ui tap --text "Continue"

--id, --text, and --content-desc match a case-insensitive substring. Add --exact to match the whole string. --id matches the short id, the part after :id/. Add --index <N> to choose among several matches. Coordinates are screen pixels, so a center read from ui dump feeds straight into --coords.

metavr ui type "hello" --submit
metavr ui wait --text "Loading" --absent --timeout 5000
metavr ui exists --id my_button

ui type takes --clear to empty the field first. ui wait uses milliseconds and defaults to 10000, and --absent waits for the element to go away. ui exists exits with code 1 when the element is missing, so scripts can branch on it.

Other interface commands: metavr ui actions, metavr ui list, metavr ui select, metavr ui swipe, and metavr ui scroll-to-find.

8. Control other device settings

metavr device wake
metavr device reboot
metavr audio set 8
metavr input key back

Volume runs from 0 to 15. metavr audio mute, metavr audio unmute, and metavr audio status cover the rest. input key takes a friendly name such as home, enter, volume_up, or power, or a raw Android key code, and --count <N> repeats it.

List windows with metavr window list, and see which one has focus with metavr window focus.

To prepare a headset for automated testing:

metavr device configure-testing setup

This adjusts the headset for test runs, for example by turning off animations and keeping the screen awake. Put it back with metavr device configure-testing restore.

9. Get machine-readable output

Add --json to any command:

metavr device battery --json

Troubleshooting

No devices found

Symptom:metavr device list returns an empty list.

Solution: Check that the headset is plugged in, that Developer Mode is on, and that the cable carries data. Charge-only cables fail here. Confirm the headset showed the USB debugging prompt and that you accepted it.