CLI Quick Reference
A structured reference of all aria_gen2 CLI commands. For full details, see the Technical Specs CLI Reference.
Prerequisites
- Client SDK installed and virtual environment activated
- Device connected via USB and authenticated
Before using any device control commands (recording, streaming, etc.), you must authenticate your device by running aria_gen2 auth pair (see Device Authentication). This only needs to be done once per device-PC combination, but all subsequent SDK operations will fail without it. You can verify your authentication status at any time with aria_gen2 auth check.
Global Options
These go before the subcommand, not after it.
--ble* flags are experimentalThey work on macOS and have only been exercised on Fedora among Linux distributions; they are not supported on Ubuntu. See BLE Device Control.
| Flag | Description |
|---|---|
--serial <serial> | Target a specific device by ADB serial. Mandatory when several devices are plugged in over USB |
--device-ip <ipv4> | Target a device by IP address instead of USB |
--ble | Connect over BLE instead of USB/Wi-Fi. Uses the only BLE-paired device; add --serial when several are paired. Recording and streaming are not available over BLE. The CLI also falls back to BLE on its own when a device is not found over USB/Wi-Fi — see BLE Device Control |
--ble-scan | In device list, scan to report which BLE-paired devices are in range. Off by default because it costs a few seconds |
--ble-scan-timeout <sec> | How long --ble-scan runs (default 12). BLE discovery latency is irregular, so shorter windows report present devices as missing |
-v / --version | Print the installed SDK version and exit |
aria_gen2 --serial 1M0YDB5H7B0020 device status
System Setup
aria_doctor
Purpose: Configure your PC for device communication (ports, USB networking, internet access).
aria_doctor
When to use: After installing the SDK, after a system restart, or when the device is not detected.
Device Commands
aria_gen2 device list
Purpose: List all connected Aria Gen 2 devices.
aria_gen2 device list
Expected Output:
[AriaGen2Cli:App][INFO]: 1M0YDB5H7B0020
aria_gen2 device status
Purpose: Report battery, charging state, Wi-Fi, thermals, the device's default recording profile, and device mode.
aria_gen2 device status
aria_gen2 device data-quality-stats
Purpose: Report per-sensor data quality statistics — drop counts, quality score, sequential drops, timestamp errors — during an active recording or streaming session.
aria_gen2 device data-quality-stats
aria_gen2 device wifi connect
Purpose: Connect the device to a Wi-Fi network.
| Flag | Required | Description |
|---|---|---|
--ssid | Yes | Wi-Fi network name |
--password | Yes | Wi-Fi password |
aria_gen2 device wifi connect --ssid "MyNetwork" --password "MyPassword"
aria_gen2 device hotspot start
Purpose: Enable the on-device Wi-Fi hotspot for direct wireless streaming.
aria_gen2 device hotspot start
Profile Commands
aria_gen2 device profile list
Purpose: List all available recording and streaming profiles on the device, including pre-defined and custom profiles.
aria_gen2 device profile list
aria_gen2 device profile add
Purpose: Add a custom profile JSON file to the device for use with recording or streaming. Non-destructive — existing profiles are left in place.
| Argument | Required | Description |
|---|---|---|
<profile> | Yes | Path to a JSON file containing a single custom profile (positional) |
aria_gen2 device profile add /path/to/custom_profile.json
For details on creating custom profile JSON files, see Custom Profile Example.
aria_gen2 device profile remove
Purpose: Remove a custom profile from the device by name.
| Argument | Required | Description |
|---|---|---|
<name> | Yes | Name of the profile to remove (positional) |
aria_gen2 device profile remove my_custom_profile
aria_gen2 device profile pull
Purpose: Download a profile's JSON from the device by name.
| Flag | Required | Description |
|---|---|---|
<name> | Yes | Name of the profile to pull (positional) |
-o / --output | No | Output file path for the profile JSON |
aria_gen2 device profile pull my_custom_profile -o ./my_custom_profile.json
Authentication Commands
aria_gen2 auth pair
Purpose: Authenticate the device with your PC. Requires approval in the Companion App.
Prerequisites: Device detected (aria_gen2 device list)
aria_gen2 auth pair
Expected Output:
[AriaGen2SDK:DeviceClient][INFO]: Client hash is: f30a36a9f3842bd3fc16c75b525...
[AriaGen2Cli:App][INFO]: Waiting for authentication approval on your mobile Companion App...
[AriaGen2Cli:App][INFO]: Successfully authenticated the device
aria_gen2 auth check
Purpose: Verify the device is authenticated.
aria_gen2 auth check
Expected Output:
[AriaGen2Cli:App][INFO]: Device 1M0YDB5H7B0020 is successfully authenticated.
aria_gen2 auth unpair
Purpose: Unpair this PC from the device.
| Flag | Required | Description |
|---|---|---|
--ble | No | Remove only the locally stored BLE credentials for the selected device |
aria_gen2 auth unpair
aria_gen2 auth remove-certs / aria_gen2 auth remove-ble-creds
Purpose: Clear locally stored credentials. Neither needs a connected device.
remove-certs— remove any locally stored SDK authentication certificatesremove-ble-creds— remove all locally stored BLE credentials, for every paired device
aria_gen2 auth remove-certs
aria_gen2 auth remove-ble-creds
Account Commands
aria_gen2 user login / verify / logout
Purpose: Log in to a Project Aria account. No device required — this group is served by Project Aria Login, not the device CLI.
| Command | Flags | Description |
|---|---|---|
user login | --username (required) | Log in to Project Aria |
user verify | — | Verify the stored authentication token |
user logout | — | Log out and discard the stored token |
aria_gen2 user login --username user@example.com
aria_gen2 user verify
Recording Commands
aria_gen2 recording start
Purpose: Start a recording on the device.
Prerequisites: Device authenticated (aria_gen2 auth check)
| Flag | Required | Default | Description |
|---|---|---|---|
--profile | No | device default | Recording profile (e.g. profile8, profile9, profile10). When omitted, the device's default recording profile is used — read it from aria_gen2 device status |
--recording-name | No | timestamp | Custom name for the recording |
--json-profile | No | — | Path to a custom JSON profile file |
--cross-device-camera-sync | No | — | Multi-device: receivers align their CV camera triggers to the broadcaster's trigger timing |
--cross-device-camera-sync-offset-us <N> | No | 0 | Multi-device: microsecond offset for cross-device camera sync. Positive = after the broadcaster, negative = before. Receivers only |
--all | No | — | Multi-device: orchestrate all connected devices. See Multi-Device Recording & Streaming |
--broadcaster <serial> | No | smallest serial | Multi-device: serial of the TDM broadcaster (requires --all) |
--disable-time-domain-mapping | No | — | Multi-device: skip TDM, coordinate start/stop only (requires --all) |
--time-domain-mapping-channel <N> | No | auto | TDM radio channel. Allowed values depend on the device's country code (read from wifi_country_code): ETSI permits 0–2; FCC permits 10–40. Auto-picked for the resolved region when omitted. |
--time-domain-mapping-broadcaster-id <N> | No | 0 | TDM broadcaster identifier |
--time-domain-mapping-rate-hz <N> | No | 2.0 | TDM signal rate in Hz |
aria_gen2 recording start --profile profile8 --recording-name my_experiment
aria_gen2 recording stop
Purpose: Stop the currently active recording.
| Flag | Required | Default | Description |
|---|---|---|---|
--all | No | — | Multi-device: stop recording on all connected devices |
To target one device out of several, pass the global --serial before the subcommand: aria_gen2 --serial <serial> recording stop.
aria_gen2 recording stop
aria_gen2 recording list
Purpose: List all recordings stored on the device (UUID, name, timestamp, size).
aria_gen2 recording list
Expected Output:
[RecordingClientWrapper][INFO]: Start time Recording uuid Size (bytes) Type
[RecordingClientWrapper][INFO]: 2025-10-12 16:51:16 PDT 4b5d47d4-f1e4-46d6-b852-670adae9d848 11724800 prototype
aria_gen2 recording info
Purpose: Get detailed information about a specific recording.
| Flag | Required | Description |
|---|---|---|
-u / --uuid | Yes | Recording UUID |
aria_gen2 recording info -u <uuid>
aria_gen2 recording download
Purpose: Download a specific recording from the device in VRS format, or every recording in a multi-device session.
| Flag | Required | Description |
|---|---|---|
-u / --uuid | Conditional | Recording UUID. Required unless --session is given |
-o / --output | No | Output directory |
--session <id> | Conditional | Multi-device session ID. Downloads every device's recording into per-device subdirectories. Mutually exclusive with --uuid. See Multi-Device Recording & Streaming. |
aria_gen2 recording download -u <uuid> -o ~/Downloads/
aria_gen2 recording download-all
Purpose: Download all recordings from the device.
| Flag | Required | Description |
|---|---|---|
-o / --output | No | Output directory |
aria_gen2 recording download-all -o ~/Downloads/
aria_gen2 recording delete
Purpose: Delete a specific recording from the device.
| Flag | Required | Description |
|---|---|---|
-u / --uuid | Yes | Recording UUID |
aria_gen2 recording delete -u <uuid>
aria_gen2 recording delete-all
Purpose: Delete all recordings from the device.
aria_gen2 recording delete-all
Streaming Commands
aria_gen2 streaming start
Purpose: Start streaming sensor data from the device.
Prerequisites: Device authenticated (aria_gen2 auth check)
| Flag | Required | Default | Description |
|---|---|---|---|
--interface | No | usb | usb, wifi_sta, or wifi_sap |
--batch-period-ms | No | — | Message batching period (required for wireless) |
--profile | No | mp_streaming_demo | Streaming profile |
--url | No | — | Remote server URL for remote streaming |
--streaming-cert-name | No | — | Use the named certificate already installed by install-certs instead of generating and installing a new pair. See Start Order and Streaming Certificates |
--no-verify-server-certs | No | — | Skip server certificate verification |
--use-ephemeral-certs | No | — | Use ephemeral certs on device and host instead of the persistent pair |
--local-certs-dir | No | — | Local streaming certificates directory |
--keep-streaming-on-disconnection | No | — | Keep streaming after Wi-Fi disconnection |
--header "name:value" | No | — | Extra HTTP headers to send with streaming requests. Accepts multiple values |
--cross-device-camera-sync | No | — | Multi-device: receivers align their CV camera triggers to the broadcaster's trigger timing |
--cross-device-camera-sync-offset-us <N> | No | 0 | Multi-device: microsecond offset for cross-device camera sync. Receivers only |
--all | No | — | Multi-device: orchestrate all connected devices. See Multi-Device Recording & Streaming |
--broadcaster <serial> | No | smallest serial | Multi-device: serial of the TDM broadcaster (requires --all) |
--disable-time-domain-mapping | No | — | Multi-device: skip TDM, coordinate start/stop only (requires --all) |
--time-domain-mapping-channel <N> | No | auto | TDM radio channel. Allowed values depend on the device's country code (read from wifi_country_code): ETSI permits 0–2; FCC permits 10–40. Auto-picked for the resolved region when omitted. |
--time-domain-mapping-broadcaster-id <N> | No | 0 | TDM broadcaster identifier |
--time-domain-mapping-rate-hz <N> | No | 2.0 | TDM signal rate in Hz |
# USB streaming
aria_gen2 streaming start
# WiFi router streaming
aria_gen2 streaming start --interface wifi_sta --batch-period-ms 200
# On-device hotspot streaming
aria_gen2 streaming start --interface wifi_sap --batch-period-ms 800
# Remote server streaming
aria_gen2 streaming start --url "https://server:6768" --interface wifi_sta --batch-period-ms 200
Expected Output:
[AriaGen2Cli:App][INFO]: Streaming started successfully
aria_gen2 streaming webrtc start
Purpose: Start a WebRTC streaming session instead of HTTP. See WebRTC Streaming for the two supported topologies.
Prerequisites: Device authenticated (aria_gen2 auth check). No streaming certificates to install. A TLS (https://) signaling URL is the exception: the device accepts one only when the signaling server's certificate chains to a trust anchor built into the device — see Trusting a TLS signaling server.
| Flag | Required | Default | Description |
|---|---|---|---|
--signaling-url | Yes | — | Signaling server URL, e.g. tcp://<host>:<port>. https:// selects TLS signaling, which the device can use only against a server certificate chaining to its built-in trust anchor — there is no trust-anchor option here, unlike the receiver's --ca-root |
--interface | No | wifi_sta | wifi_sta or wifi_sap (WebRTC is Wi-Fi only) |
--profile | No | mp_streaming_demo | Streaming profile name |
--json-profile | No | — | Streaming profile JSON file. Takes precedence over --profile when both are given |
--room | No | default | Signaling room to join |
--room-password | No | — | Shared secret required to join the room. Must match the receiver's aria_streaming_viewer --room-password |
--auth-token | No | — | Auth token presented to the signaling server |
--stun | No | — | STUN server URL. Repeatable |
--turn | No | — | TURN server as url,username,credential. Repeatable |
--ntp-sync | No | — | Sync the device clock against an NTP server before starting the session. See below |
--pcie-batch-period-ms | No | 10 | PCIe batch period in ms (minimum 10) |
-r, --record | No | — | Also record to VRS on-device during the session. WebRTC only — see below |
--recording-profile | No | — | Recording profile name to use (requires --record) |
--recording-json-profile | No | — | Recording profile JSON file to use (requires --record). Takes precedence over --recording-profile |
# Same-network direct peer-to-peer
aria_gen2 streaming webrtc start --signaling-url tcp://<host-ip>:9000 \
--profile low_latency_streaming --interface wifi_sta
# Cross-network through a signaling server, syncing the device clock first
aria_gen2 streaming webrtc start \
--signaling-url tcp://example.com:8443 \
--profile low_latency_streaming \
--room my-room --auth-token "$AUTH_TOKEN" \
--stun stun:example.com:3478 \
--turn turn:example.com:3478,aria,"$TURN_PASSWORD" \
--interface wifi_sta \
--ntp-sync
Replace example.com with your own host.
--ntp-sync: a signaling server may refuse a device whose clock has drifted, because the
authentication handshake is timestamped and stale handshakes are rejected. --ntp-sync makes
the device sync its clock against an NTP server before the session starts. The device must be
able to reach that server over Wi-Fi, and the sync is a precondition rather than best-effort:
if it fails the session does not start. Without the flag no clock sync is performed and the
device starts the session on its default time source.
-r / --record: records to VRS on the device for the duration of the streaming session,
so you get a full-rate on-device capture alongside the live stream. --recording-profile or
--recording-json-profile selects the recording profile — both require --record, and they
are independent of --profile, which selects the streaming profile. One
aria_gen2 streaming webrtc stop ends both the stream and the recording. See
Recording While Streaming.
aria_gen2 streaming start (HTTP) has no --record flag. In Python,
device.start_streaming(record=True) fails with OperationNotAllowed unless a WebRTC config
was set first via set_webrtc_streaming_config().
Expected Output:
[AriaGen2Cli:App][INFO]: Streaming started successfully
aria_gen2 streaming webrtc stop
Purpose: Stop the active WebRTC streaming session.
aria_gen2 streaming webrtc stop
aria_gen2 streaming stop
Purpose: Stop the active streaming session.
| Flag | Required | Default | Description |
|---|---|---|---|
--all | No | — | Multi-device: stop streaming on all connected devices |
--remove-ephemeral-certs | No | — | Also remove ephemeral streaming certs from the local host |
--local-certs-dir <path> | No | — | Local streaming certificates directory |
To target one device out of several, pass the global --serial before the subcommand: aria_gen2 --serial <serial> streaming stop.
aria_gen2 streaming stop
aria_gen2 streaming install-certs
Purpose: Generate and install streaming certificates for remote streaming.
| Flag | Required | Default | Description |
|---|---|---|---|
--device <serial> | No (repeatable) | — | Pass repeatedly to install the same cert across multiple devices, e.g. --device A --device B, for multi-device streaming. See Multi-Device Streaming Certs. |
aria_gen2 streaming install-certs
Output includes a cert name (e.g., cert_1769712774692532015) needed for --streaming-cert-name. Pinning that name on streaming start also makes the start order irrelevant — see Start Order and Streaming Certificates.
aria_gen2 streaming uninstall-certs
Purpose: Remove streaming certificates from both the device and the local host.
aria_gen2 streaming uninstall-certs
aria_gen2 streaming profiles
Purpose: List the streaming profiles the device supports.
aria_gen2 streaming profiles
Multi-Device Sessions
Multi-device sessions are tracked on disk at ~/.aria/multi-device-session/<id>.json. Use these commands to inspect and manage them. See Multi-Device Recording & Streaming for the full conceptual guide.
aria_gen2 recording sessions list
Purpose: List all multi-device recording sessions on disk.
aria_gen2 recording sessions list
aria_gen2 recording sessions info
Purpose: Show details of a specific recording session — roles (broadcaster/receiver), per-device recording UUIDs, TDM config, active/stopped status.
| Flag | Required | Description |
|---|---|---|
<session-id> | Yes | Session UUID (positional) |
aria_gen2 recording sessions info <session-id>
aria_gen2 streaming sessions list
Purpose: List all multi-device streaming sessions on disk.
aria_gen2 streaming sessions list
aria_gen2 streaming sessions info
Purpose: Show details of a specific streaming session — roles, profile, TDM config, streaming cert name, active/stopped status.
| Flag | Required | Description |
|---|---|---|
<session-id> | Yes | Session UUID (positional) |
aria_gen2 streaming sessions info <session-id>
Visualization Commands
aria_streaming_viewer
Purpose: Open the real-time streaming viewer (run in a separate terminal while streaming is active).
On HTTP, run aria_gen2 streaming start first and aria_streaming_viewer second, in two terminals. Pinning an already-installed certificate with --streaming-cert-name lets you run them in either order — see Start Order and Streaming Certificates for more details. WebRTC installs no streaming certificates, so the order never matters there — including when the signaling channel runs over TLS, which involves the signaling server's certificate rather than a per-device one.
aria_streaming_viewer --real-time --interpolate --rerun-memory-limit 4GB
WebRTC transport: add --transport webrtc to stream over WebRTC instead of HTTP — use --listen <port> for a same-network direct peer-to-peer connection, or --signaling-url (or the older --signaling-host / --signaling-port), plus --room, --room-password, --auth-token, --stun, --turn, --turn-username, --turn-password, for cross-network streaming through a signaling server. An https:// signaling URL puts the signaling channel behind TLS; --ca-root picks the trust anchor, see Trusting a TLS signaling server. See WebRTC Streaming and TLS on the signaling channel.
# Same-network direct peer-to-peer over WebRTC
aria_streaming_viewer --transport webrtc --listen 9000
On WebRTC the viewer also shows terminal audio controls — press m to mute/unmute the microphone, and watch the incoming audio level meter. Add --no-audio-controls to turn them off; they are skipped automatically when the terminal is not interactive. See Terminal Audio Controls.
Custom layout: --blueprint <path.rbl> replaces the auto-generated Rerun layout with a saved Rerun blueprint. The SDK ships aria_video_focused_rerun_0.33.rbl with the example code; a blueprint can also be dragged onto the Rerun window or opened from its menu. The viewer exits with an error if the path does not exist. See Custom Layout with a Rerun Blueprint.
aria_streaming_viewer --real-time --interpolate \
--blueprint ~/Downloads/projectaria_client_sdk_samples_gen2/aria_video_focused_rerun_0.33.rbl
aria_multi_device_streaming_viewer
Purpose: Live Rerun visualization for two or more Aria Gen 2 devices streaming simultaneously, with TDM-corrected timestamps for synchronized cross-device replay. Installed as a console script by the Client SDK — no sample export needed.
aria_streaming_viewer)This tool is the HTTPS server that devices push to, so launching it before aria_gen2 streaming start --all lets frames land from the first push attempt. Reverse order also works — devices retry on connection-refused. Hard prerequisite: a streaming cert must already be installed via aria_gen2 streaming install-certs (this viewer never auto-generates one, unlike aria_streaming_viewer). Recommended sequence:
aria_gen2 streaming install-certs --device <SERIAL> [--device <SERIAL>](one-time, REQUIRED)aria_multi_device_streaming_viewer(terminal 1)aria_gen2 streaming start --profile profile9 --all(terminal 2)
| Flag | Default | Description |
|---|---|---|
--broadcaster <serial> | lowest-sorted serial | Explicit broadcaster serial. Use only if you passed --broadcaster to streaming start |
--expected-device-count <N> | passive | Strict mode: hard-error if fewer than N devices connect within the wait window |
--skip-tdm-validation | — | Proceed even when a receiver fails TDM validation. Logically impossible cases still hard-error |
--port <port> | 6768 | HTTP server port. Override only when running alongside aria_streaming_viewer on the same host |
--streaming-cert-name <name> | installed cert | Verify the installed cert's name up front, turning a silent TLS-handshake failure into a clear startup error |
--jpeg-quality <q> | 50 | JPEG decode quality |
--rerun-memory-limit <limit> | 4GB | Buffering scales as N devices × per-frame size; use e.g. 16GB for long sessions |
aria_multi_device_streaming_viewer --expected-device-count 2
See Multi-Device Recording & Streaming → Live Visualization for the full workflow and validation behavior.
aria_rerun_viewer
Purpose: Visualize a downloaded VRS recording.
| Flag | Required | Description |
|---|---|---|
--vrs | Yes | Path to VRS file |
aria_rerun_viewer --vrs ~/Downloads/recording.vrs
Diagnostic Commands
aria_diagnostics
Purpose: Collect diagnostic information and error logs for troubleshooting.
aria_diagnostics
If aria_diagnostics fails to run, you may need to install net-tools:
sudo apt install net-tools