Use it

CLI reference

Every ring-cli command with its options — generated from the CLI's own --help.

• people holding the ring
• 2 min read
• 343 words

In 10 seconds

ring-cli is the driver's command line: 21 verbs, JSON on stdout, every frame logged to a JSONL. You will mostly run six of them: scan · battery · hr · sync · audio-pull · bridge. ring-cli battery -a <uuid|mac> | jq .battery_percent

Options every command takes

option	meaning
-a, --address	CoreBluetooth UUID (macOS) or MAC (Linux). Omit it → the macOS-held ring, else the first ring found by scan
-e, --evidence	JSONL that receives every frame sent and received, hex + decoded · default evidence/raw.jsonl

Every command below is one ??? box — its exact --help, generated by tools/gen_cli_docs.py. Edit the docstrings in ring/cli.py, not this file. Verbs talking to tiny need ~/.tiny/device.json (npx tiny-tech).

Verbs

group	verbs
discover	scan · gatt · info · listen
vitals	battery · steps · hr · spo2 · temp · sleep · sync
settings	settime · find · alarms · handshake
audio	audio-state · audio-pull · audio-post · audio-record
daemon · raw	bridge · raw (refuses 39/67 without --i-own-this-ring)

scan — List ring-like advertisers with decoded manufacturer data

ring-cli scan [OPTIONS]

option	meaning
--seconds	<float> · [default: 20]

gatt — Connect and dump the full GATT table (reads every readable characteristic)

ring-cli gatt [OPTIONS]

info — Device info + features + battery (JY cmds 37/55/6 + BAS 2A19)

ring-cli info [OPTIONS]

option	meaning
--bas	--no-bas · also read GATT Battery Service 0x2A19 (may trigger a macOS pairing → the ring becomes a bonded 'Mouse' and stops advertising for everyone else) · [default: no-bas]

audio-state — 0x2F queryAudioState + 0x3D offline file count

ring-cli audio-state [OPTIONS]

audio-pull — Download the on-ring voice memo(s): 0x40 → 0x34 stream → .opus (+ .wav via ffmpeg) → 0x36 clear

ring-cli audio-pull [OPTIONS]

option	meaning
--out	<str> · [default: captures/memo.opus]
--no-clear	--no-no-clear · [default: no-no-clear]
--max-s	<float> · [default: 300.0]

audio-post — POST an already-pulled .opus memo to tiny (/api/health/media). Idempotent server-side (sha256)

ring-cli audio-post [OPTIONS] {path}

option	meaning
*	path · <str> · [required]
--name	<str> · [default: JY-Y3-011A]
--ble-address	<str> · [default: 73:01:06:00:01:1A]

audio-record — Phone-style live recording: 0x30 controlAudioMode(mode) → 0x32/0x33 frames → .opus/.wav → 0x30 stop

ring-cli audio-record [OPTIONS]

option	meaning
--seconds	<float> · [default: 10.0]
--out	<str> · [default: captures/live.opus]
--mode	<int> · [default: 1]

bridge — Stay connected: handshake → history sync → live HR/battery/SpO2/temp/button → POST to tiny health; auto-reconnect. Refuses to start when the pidfile names a live bridge (two bridges = every frame posted twice)

ring-cli bridge [OPTIONS]

option	meaning
--days	<int> · [default: 2]
--flush-s	<float> · [default: 30.0]
--resync-s	<float> · [default: 900.0]
--post	--no-post · [default: post]
--auto-hr-min	<int> · [default: 5]
--pidfile	<str> · [default: ~/.tiny/ring/bridge.pid]

handshake — LoraFit's post-connect sequence (time, app-info, auto-HR, features, info, battery)

ring-cli handshake [OPTIONS]

battery

ring-cli battery [OPTIONS]

steps

ring-cli steps [OPTIONS]

settime

ring-cli settime [OPTIONS]

find — vibrateLED(mode)

ring-cli find [OPTIONS]

option	meaning
--mode	<int> · [default: 1]

alarms

ring-cli alarms [OPTIONS]

hr — Live heart rate for N seconds (cmd 7 → cmd 11 stream → cmd 8)

ring-cli hr [OPTIONS]

option	meaning
--seconds	<float> · [default: 30]

spo2

ring-cli spo2 [OPTIONS]

option	meaning
--seconds	<float> · [default: 40]

temp

ring-cli temp [OPTIONS]

option	meaning
--seconds	<float> · [default: 30]

sleep

ring-cli sleep [OPTIONS]

option	meaning
--days	<int> · [default: 1]

sync — History: step buckets, sleep, health records for the last N days

ring-cli sync [OPTIONS]

option	meaning
--days	<int> · [default: 1]

raw — Send an arbitrary JY command; reply=-1 → wait for same cmd id. cmd 39 (reboot/factory reset) and 67 (unbind) need --i-own-this-ring

ring-cli raw [OPTIONS] {cmd}

option	meaning
*	cmd · <int> · [required]
--payload-hex	<str>
--reply	<int> · [default: -1]
--i-own-this-ring	--no-i-own-this-ring · [default: no-i-own-this-ring]

listen — Just subscribe and print every notification (button events, auto-measurements)

ring-cli listen [OPTIONS]

option	meaning
--seconds	<float> · [default: 60]