ZeroTrace AirLeak
CLI Reference
Every firmware command, what it does, what it returns
The AirLeak firmware accepts text commands over USB. The desktop app's AirLeak → Settings → Command tab is the easiest way to send them — type, press Enter, see the response.
Every command starts with airleak-. Commands are case-sensitive and lowercase. Arguments are space-separated.
Quick reference
| Command | Purpose |
|---|---|
airleak-info | Firmware version, build, MAC, uptime |
airleak-mode | Show or change capture mode |
airleak-active-scan | Show or set BLE active-scan flag |
airleak-scan-window | Show or set BLE scan window (ms) |
airleak-scan-interval | Show or set BLE scan interval (ms) |
airleak-throttle | Show or set event throttle window (ms) |
airleak-channels | Show or set WiFi channel-hop list |
airleak-dwell | Show or set per-channel dwell time (ms) |
airleak-snapshot | Force a DEV: device-list dump |
airleak-clear-aggregator | Clear the live device aggregator |
airleak-alerts-replay | Replay the alert ring |
airleak-alert-list | Show every rule and enabled state |
airleak-alert-enable | Enable a specific alert rule |
airleak-alert-disable | Disable a specific alert rule |
airleak-fingerprint-reset | Clear in-RAM fingerprint cache |
airleak-status | One-shot heartbeat-equivalent status print |
airleak-heap | Detailed heap report |
airleak-tasks | RTOS task summary (CPU usage per task) |
airleak-uptime | Print uptime |
airleak-restart | Soft restart |
airleak-factory-reset | Wipe NVS, reset to defaults, restart |
Commands
airleak-info
Prints firmware identity.
> airleak-info
firmware: airleak-v1.4.2
build: 2026-04-29-stable
slot: 0
mac: 9C:3D:CF:54:8F:88
boot_count: 47
uptime: 3h 14m 22s
| Field | Meaning |
|---|---|
firmware | Version string + channel (stable / beta / dev) |
build | Build date and tag |
slot | Active OTA slot (0 or 1) |
mac | The unit's primary BLE MAC (also used as USB device ID) |
boot_count | Total successful boots since factory reset |
uptime | Time since last boot |
airleak-mode
Show or change capture mode.
> airleak-mode
mode: monitor
> airleak-mode setup
ok mode: setup
> airleak-mode monitor
ok mode: monitor
Accepted values: setup, monitor. The mode is persisted to NVS — survives reboot.
Legacy aliases (still accepted, all map to monitor): room_scan, self_test, mdns_audit, travel, recon, stalker_hunt.
airleak-active-scan
Show or set the BLE active-scan flag.
> airleak-active-scan
active_scan: on
> airleak-active-scan off
ok active_scan: off
> airleak-active-scan on
ok active_scan: on
on (default) — the unit transmits SCAN_REQs and captures friendly device names from SCAN_RSPs.
off — passive only, no SCAN_REQ transmissions, but most BLE peers' friendly names are unavailable.
Persists to NVS. See Active scan for tradeoffs.
airleak-scan-window
Show or set the BLE scan window in milliseconds.
> airleak-scan-window
scan_window_ms: 75
> airleak-scan-window 100
ok scan_window_ms: 100
Range: 20–10240 ms (BLE spec limits). Must be ≤ scan-interval. Default: 75 ms.
Higher values increase the chance of catching scannable advertisements, at the cost of duty cycle. Setting scan_window equal to scan_interval gives 100 % duty cycle (continuous reception).
airleak-scan-interval
Show or set the BLE scan interval in milliseconds.
> airleak-scan-interval
scan_interval_ms: 100
> airleak-scan-interval 100
ok scan_interval_ms: 100
Range: 20–10240 ms. Must be ≥ scan-window. Default: 100 ms.
airleak-throttle
Show or set the per-(device, event-type) USB-stream throttle window, in ms.
> airleak-throttle
throttle_ms: 1000
> airleak-throttle 2000
ok throttle_ms: 2000
> airleak-throttle 0
ok throttle_ms: 0 (firehose mode — every event streamed)
Default: 1000 ms (1 s).
The throttle gates only the USB stream — every event still updates the device aggregator and runs through the alert engine. See Throttle for capacity numbers and tuning advice.
airleak-channels
Show or set the WiFi channel-hop list.
> airleak-channels
channels: 1,2,3,4,5,6,7,8,9,10,11,12,13
> airleak-channels 1,6,11
ok channels: 1,6,11
> airleak-channels default
ok channels: 1,2,3,4,5,6,7,8,9,10,11,12,13
Comma-separated list of channels in the 2.4 GHz band (1–13). Use a shorter list to dwell longer per channel and catch more frames per AP, at the cost of missing APs on excluded channels.
default resets to the full sweep.
Persisted to NVS.
airleak-dwell
Show or set per-channel dwell time, in milliseconds.
> airleak-dwell
dwell_ms: 150
> airleak-dwell 250
ok dwell_ms: 250
Range: 50–2000 ms. Default: 150 ms.
A typical AP beacon is ~102 ms apart. Dwelling 150 ms guarantees one beacon capture per visit. Going below 100 ms risks missing beacons; above 300 ms slows the full sweep.
Persisted to NVS.
airleak-snapshot
Forces the firmware to emit a DEV: line containing every device currently in the aggregator. Useful to backfill the desktop after late-connecting.
> airleak-snapshot
ok snapshot dispatched (87 devices)
The desktop uses this automatically on connect.
airleak-clear-aggregator
Clears the in-RAM device list. Doesn't affect the desktop's library or session records — just empties what's currently in firmware RAM.
> airleak-clear-aggregator
ok cleared (was 87 entries)
Useful for "I want to see what's nearby right now from a clean slate."
airleak-alerts-replay
Pushes every alert in the ring buffer over the USB stream. The desktop calls this on connect to backfill alerts that fired before it attached.
> airleak-alerts-replay
ok replayed 124 alerts
The ring holds the last 1024 alerts. Older alerts are evicted when the ring fills.
airleak-alert-list
Lists every alert rule and whether it's enabled.
> airleak-alert-list
airdrop_discoverable enabled
findmy_separated enabled
multi_hour_follower enabled
pii_ssid_in_probe enabled
corp_ssid_in_probe enabled
airport_ssid_in_probe enabled
hotel_ssid_in_probe enabled
cafe_ssid_in_probe disabled
open_network_near enabled
wep_network_near enabled
wpa_personal_only enabled
wps_enabled enabled
mfp_required_off enabled
deauth_burst enabled
tile_tracker enabled
samsung_smarttag_near enabled
unknown_tracker_near enabled
random_mac_no_name disabled
mac_rotation_detected enabled
See Alert Rules for what each rule means.
airleak-alert-enable / airleak-alert-disable
Enable or disable a specific rule by name.
> airleak-alert-disable cafe_ssid_in_probe
ok cafe_ssid_in_probe: disabled
> airleak-alert-enable cafe_ssid_in_probe
ok cafe_ssid_in_probe: enabled
Disabled rules don't fire and don't consume cycles. State is persisted to NVS.
airleak-fingerprint-reset
Clears the in-RAM fingerprint cache. Forces all currently-known devices to re-build their fingerprint from the next observation.
> airleak-fingerprint-reset
ok cache cleared (213 entries dropped)
Useful after changing scan settings or to force re-evaluation of merged-MAC groups.
airleak-status
Prints a one-shot equivalent of the heartbeat — useful for scripted polling.
> airleak-status
mode=monitor
devices=87 events=4421 wifi=18 ble=69
alerts=23 drop=0.2% throttled=8902
heap_free=43620 (12%) heap_min=29840
ble_active_scan=on scan_window=75 scan_interval=100 throttle=1000
uptime=3h 14m 22s
See Heartbeat fields for what each field means.
airleak-heap
Detailed heap report. Useful when investigating heap pressure.
> airleak-heap
internal:
total: 327 KB
free: 43620 (13%)
min_free: 29840 (9%)
largest_block: 24 KB
psram:
total: 8192 KB
free: 7740 KB (94%)
min_free: 7510 KB
largest_block: 4096 KB
If largest_block shrinks below 8 KB on internal heap, the unit may struggle to allocate large queues — consider increasing the throttle window.
airleak-tasks
Per-task CPU usage summary (sampled over the last second).
> airleak-tasks
task cpu% stack-high-water
parser 41% 8.4 KB
usb_stream 18% 5.2 KB
nimble_host 14% 11 KB
wifi_capture 9% 3.8 KB
heap_monitor 1% 1.4 KB
serial_cli 0% 14 KB
idle (core 0) 24% -
idle (core 1) 35% -
Useful for diagnosing "why is the unit dropping events." Saturated parser → bump throttle. Saturated USB stream → check the desktop isn't backlogged.
airleak-uptime
> airleak-uptime
uptime: 3h 14m 22s
Simple uptime print. Same value as in airleak-info.
airleak-restart
Soft-resets the firmware. Equivalent to pressing the RST button.
> airleak-restart
ok restarting in 1s...
Persistent settings survive. Live state (aggregator, alert ring, heap stats) does not.
airleak-factory-reset
Wipes the NVS partition (all settings) and restarts. After factory reset:
- Capture mode →
setup(default) - Active scan →
on - Throttle → 1000 ms
- All alert rules → enabled
- Boot count → 1
> airleak-factory-reset
ok wiping NVS and restarting...
Factory reset is irreversible. The unit reboots immediately and you lose all customized settings. Use only when troubleshooting or before transferring the unit to someone else.
Unrecognized commands
If you send a command the firmware doesn't recognize, it responds with a list of known commands:
> hello
unknown command. try: airleak-info, airleak-mode, airleak-active-scan, ...