Command Reference

Command Reference

caeruleus --help prints the full grouped command map, and caeruleus <command> --help is the authoritative, current list of a command's flags. The tables below are a curated summary.

Handles. Every handle argument (-a, listen -a, and the shell/batch char-read-hnd / char-write-* verbs) is an ATT value handle. enumerate's char_handle is already the value handle, so pass it straight to -a. characteristics prints both the declaration handle and the value_handle (they differ, usually by one); use the value_handle.

Discovery

Command	Purpose
scan [-d secs]	LE discovery; shows address, type, RSSI, inferred device type (from GAP Appearance + service UUIDs), and name. --include-cached also shows devices BlueZ cached earlier (default is active-only). --live shows a self-updating, indexed table until Ctrl-C (unless -d given). -o jsonl streams found/update events.
enumerate -b A [--values] [--compact] [--raw]	Full GATT tree; --values reads each characteristic; --compact is one line/char. --max-len N truncates displayed values. --raw (root) discovers directly over ATT for a host/BlueZ-independent view with the device's true handles, incl. GAP/GATT services older BlueZ hides.
primary -b A / characteristics -b A	gatttool-style service / characteristic listing.

GATT operations

Command	Purpose
read -b A (-a 0xHND | -u UUID) [--watch --every D] [--extract] [--raw]	Read a characteristic; --extract emits bare hex for piping. --raw (root) reads the exact handle over raw ATT, bypassing BlueZ, to reach handles BlueZ doesn't expose (hidden GAP chars on old BlueZ); pair with enumerate --raw.
write -b A (-a 0xHND | -u UUID) (-n HEX | -s STR) [--req] [--each-line]	Write; --req forces write-with-response; --each-line reads one payload per stdin line.
raw-write -b A -a 0xHND (-n HEX | --length N --pattern HH)	Single-PDU ATT Write Request over raw L2CAP (oversized, bypasses BlueZ fragmentation; root).
listen -b A -a 0xHND [--trigger-value HEX] [--trigger-handle 0xHND] [--duration D] [--count N]	Subscribe to notifications/indications; trigger-then-capture in one step.
cccd -b A (--char UUID | --handle 0xHND) --enable notify|indicate|off [--raw]	Manipulate the CCCD directly (--raw = root).
mtu -b A --show	Show negotiated ATT MTU. --set N reconfigures bluetoothd (root, global).

Connection management

Command	Purpose
pair -b A / unpair -b A	Establish / drop a bond. Pairing rejection is recorded, not treated as an error. pair --passkey NNNNNN for Passkey Entry.
conn-params -b A	Connection interval / peripheral latency / supervision timeout + ATT MTU (root).
disconnect -b A / forget -b A	Drop the link / purge BlueZ cache (clears a stuck Connected=true).

Scripting & automation

Command	Purpose
shell -b A	Interactive REPL. -b optional: scan, then connect <#> by index. gatttool-style verbs.
batch -b A	Run shell commands from stdin over one persistent connection.
serve -b A + send "..."	Long-lived daemon holding one warm GATT link; clients dispatch over a Unix socket.

Shell/batch verbs are positional and do not accept the top-level -s/-n/--req flags. Write hex with char-write-req 0xHND HEX (or char-write-cmd); write ASCII with write-string-req 0xHND "STR" (or write-string); read with char-read-hnd 0xHND. Run help inside shell for the full verb list.

Security assessment

All emit {address, test, summary, findings[]}; findings carry severity (info/low/medium/high/critical), handle, uuid, evidence, detail. They exit 0 even when issues are found — findings are data.

Command	What it tests
recon -b A	Fingerprint + audit: DFU presence, exposed serial, custom services, hidden-readable characteristics.
assess check-auth -b A [--probe-write]	Read-only by default. What an unpaired attacker can read; values scanned with Titus (a secret match escalates to high). --probe-write also tests unauthenticated writes (safe same-value write-back).
assess encryption -b A	Unauthenticated baseline → pair → re-test: no-pairing exposure, enforcement, legacy fallback after unpair.
assess pairing -b A	SMP pairing feature exchange + downgrade resistance (root; takes over the adapter).
assess dfu -b A [--probe-entry]	Detect 0xFE59 DFU + unauthenticated buttonless entry. --probe-entry is destructive (reboots target).
assess wwr -b A [--sizes ...] [--burst N]	Write-without-response overflow sweep + rapid-fire burst with a liveness probe (can crash a fragile target).

Fuzzing

Command	Purpose
fuzz write -b A -a 0xHND [--type req|cmd|both] [--max-iter N] [--max-time D] [--seed HEX]	Fuzz writes with an on-disk corpus and crash/hang triage. Output dir fuzz-out-<ts>/.
fuzz write … --raw [--include prep,exec]	Drive raw L2CAP (oversized single-PDU + multi-part writes); root.
fuzz write … --target-reset "CMD"	Run a recovery shell command when the target locks up.
fuzz replay DIR/file	Re-send a saved corpus/crash input to reproduce.

Adapter & diagnostics

Command	Purpose
doctor	One-shot health check (bluetoothd, power, scan, MTU, address); exit 2 on FAIL, with a fix per finding.
adapter power on|off|cycle / adapter info	Soft adapter recovery / state.
bdaddr --show / --set MAC	Read / spoof adapter BD_ADDR (root; vendor-specific).
monitor -b A [--handle 0xHND]	Passive HCI decode of notifications BlueZ hides (root).

Global flags

-b/--bdaddr target · -i/--adapter hciN (default hci0) · --addr-type public\|random (force if a connect fails) · -t/--timeout N seconds (default 45) · -o/--format text\|json\|jsonl · -v/--verbose · -q/--quiet.