Living notes for apps/relay-cli (binary relay). Terminal only: no WebView dependencies.
| Path | Role |
|---|---|
src/main.rs |
Calls relay_cli::main_exit(); nothing else |
src/host.rs |
Process setup: plain tokio runtime, or (for hotkey/tui) main thread that starts the hotkey backend and services the platform loop while tokio runs on a worker thread |
src/hotkey/ |
start_with (probe and register), HotkeyReport (honest state), supervise (keeps the shared relay_client::ptt::PttWorker on the right call) |
src/secret.rs |
Secret (redacted Debug, zeroed on drop), hidden-prompt and stdin sources |
src/cli/ |
clap definitions (args), CliError, exit codes, endpoint resolution |
src/client/ |
Control (request/response), Manage (channels, privacy, avatar, connection info) and Subscribe (streams) traits; RealClient over relay_api::RelayClient; resyncing feeds |
src/commands/ |
One module per command family; views (JSON/text), resolve (names to ids), names; messages/ for relay messages (target, send, read, files, manage, watch, view) |
src/client/messaging.rs, session_feed.rs |
The Messaging trait (session RPCs over the messages capability) and the TUI's reopening session feed |
src/tui/ |
model (pure state), keys (key to TuiCommand), exec, view/ (Ratatui), app (event loop), messages/ (the Messages tab: state, keys, render, view, exec) |
tests/ |
Fake Control, in-process engine over a real Unix socket, TestBackend snapshots, binary exit codes |
Commands are generic over Control/Manage, so they run unchanged against a scripted fake. commands::execute is the seam tests use; commands::run adds connecting.
relay daemon start [--log-file P] [--wait S] [-- relayd args]
relay daemon restart [--force] [same options] refuses while a call is in progress unless --force
relay daemon stop | status | logs [-n N]
relay daemon run [-- relayd args] run the daemon in this terminal
relay status | peers
relay call <peer|ip:port> never enables the microphone
relay accept|decline|end [call]
relay mute|deafen [on|off] [--call C] global unless --call
relay gain mic|playback|receive <v> [--call C]
relay talk muted|unmuted|ptt [--call C]
relay devices list | select [--input X] [--output Y]
relay profile set --name <n>
relay trust list | verify <peer> --fingerprint <hex> | forget <fingerprint-prefix|name>
relay favorites [list | add <peer> | remove <peer> | move <peer> <position>]
relay auto-answer [list | on <peer> | off <peer>]
relay mic-test [--seconds N] [--local-playback --accept-feedback]
relay doctor [--bundle FILE]
relay address [--copy] connection string others use to call you
relay connect --trust <relay://...> dial a scanned connection string; trust the device as verified when its key matches
relay call relay://ip:port#fp call by pasted connection string
relay privacy set [--inbound anyone|shared-channel|nobody] [--advert visible|hidden]
relay channel create <name> [--hidden] [--invite-only] [--password|--password-stdin]
relay channel join <name|id> [--password|--password-stdin|--invite|--invite-stdin]
relay channel leave|invite|revoke <channel> ... (invite: --ttl-seconds, --uses; revoke: <fingerprint>)
relay channel list
relay channel nearby channels other devices list on your network (not joined); password ones are marked, invite-only ones are never listed
relay config get [key] | set <key> <value> | export [file] | import <file>
relay avatar set <file> | clear png, jpg, webp, gif, bmp or tiff
relay history [--limit N] past calls, newest first (default 20, at most 200)
relay history clear delete the call history on this device
relay completions <shell> bash, zsh, fish, elvish, powershell
relay man [--dir DIR] man page to stdout, or one page per command into DIR
relay messages send <text|-> [--call C] text into a call session ('-' reads stdin)
relay messages watch | log [--since N] [--limit N] | search <q>
relay messages pin|unpin <msg> | clear [--yes] | export [--out FILE] [--embed-images]
relay messages copy <msg> | copy code-block <N> [--print]
relay messages perms [--messages on|off] [--files on|off]
relay messages image send <file> | offer <path> | offers
relay messages accept <offer> [--dest DIR] [--name NAME] | reject|cancel <offer>
relay messages preview request|approve <offer> [--deny]
relay hotkey [--binding KEYS] run the global push-to-talk key
relay hotkey status | set <keys>
# An empty hotkeys.push_to_talk means no key is registered.
relay tui [--no-hotkey | --binding KEYS]
Global flags (accepted anywhere): --json, --socket PATH, --tcp-profile PATH, --takeover, --timeout-ms N. Environment: RELAY_SOCKET, RELAY_TCP_PROFILE (flags win). Default endpoint is the per-user engine socket from relay_api::default_socket_path.
Targets: a peer is matched by exact id, exact name (any case), then a unique id/name prefix. An ambiguous prefix is an error listing candidates, never a guess. A call is an id prefix or a peer name; with no argument the only live call is used, and several live calls are an error.
relay callslists the live calls: id, peer, state,TIME(connected time, measured from the call'sconnected_at_unix_msso both ends agree), mode and microphone.relay statusshows the same table. With--jsoneach call carriesconnected_at_unix_ms,duration_ms(null until connected) and, for connected calls,diagnostics(the firstCallStatssample, best effort: path, packet counters, rtt, jitter, loss, buffers, latency estimate).relay stats [CALL] [--watch]prints the live statistics of a call (WatchCallStats): the path and why it waits or failed, sending and receiving, packets, rtt with min and max, jitter, loss over 5 s and total, jitter buffer, mouth-to-ear estimate, codec, drift and device buffers.--watchprints one sample per second; with--jsonone JSON object per line.callis the dial command, so statistics live understats. Sourcecommands/stats.rs, teststests/stats_cmd.rs.
- The mode is the consent:
talk unmutedandtalk pttare the explicit consent to send the microphone to that call, in one request;talk mutedwithdraws it. There is no--consentflag. New calls start incalls.default_transmit_mode(relay config set calls.default_transmit_mode unmuted). mic-test --accept-feedbackrequires--local-playback.favoriteslists, adds, removes or moves the quick-call favorites (up to 6 trusted peers;<peer>is a name or id prefix as forcall). Positions are 1-based, the order of the Calls page grid;--jsonprints[{position, id, name, fingerprint_short, reachable}]. It sends the whole new list withSetFavorites; a seventh favorite is refused withYou can have up to 6 favorites. Sourcecommands/favorites.rs, teststests/favorites_cmd.rs.auto-answerlists the contacts whose calls the engine answers by itself, or switches one on or off (SetPeerAutoAnswer).onneeds a verified contact (relay trust verifyfirst); the CLI refuses a contact that is not shown as verified before sending, and the engine checks again. The list notes when the global switchcalls.auto_answer_enabledis off;--jsonprints{enabled, contacts: [{id, name, fingerprint_short, reachable}]}.relay statusalso showsbackground(background.available),alert(calls.alert) andauto-answer(the global switch), and its JSON hasbackground_available,call_alert,auto_answer_enabled. Change those withrelay config set background.available false,calls.alert silent,calls.auto_answer_enabled false(live when the daemon runs). The TUI status line says "answered automatically: " on theAutoAnsweredevent. Sourcecommands/auto_answer.rs, teststests/auto_answer_cmd.rs.trust verifyneeds the 64-hex SHA-256 the user compared out of band (:and-separators are fine); it sendsout_of_band_verified = true.forgetusesForgetPeer: the argument is a hex fingerprint prefix (at least 8 digits;:,-, spaces and case are ignored, so the short form fromtrust listor its first groups work) or an exact, case-insensitive display name, tried in that order. An unknown or ambiguous argument is exit 5; ambiguity prints the candidates with their short fingerprints and changes nothing.trust replace <peer> --fingerprint <64 hex>(ReplacePinnedKey) trusts the new key of a peer whose key changed, after the full fingerprint was compared with the other device's Connect a device > Details; it keeps the name and favorite and is refused (exit 2 for a peer without a key change or a short fingerprint, otherwise the engine's reason) unless the fingerprint is exactly the new key's.forgetalso accepts the prefix of the key-changed device's new key.relay peersandtrust listmark such a deviceKEY CHANGED, blocked (was <short>)(key_changedin JSON).trust listandpeersshow each peer's short fingerprint (A1B2-C3D4-E5F6-0718-293A, a hint to tell devices apart, never a verification string).- Call-scoped mutations first acquire the controller lease (
--takeoversetsrequest_explicit_takeover) and send its generation. Leases are not released explicitly; they expire.
relay addressprints only the engine's connection string (pipeable);--jsonadds addresses, port and fingerprint.--copyusesarboard(text only, no image codecs). If the clipboard is unavailable the string is still printed and the command exits 1 with the reason; on X11 clipboard text may vanish whenrelayexits unless a clipboard manager runs.relay connect --trust <string>sendsConnectAndTrust: the string (fromrelay addresson the other device, or a QR code) carries the full fingerprint, so pasting it is an out-of-band exchange. A device with another key, an unreachable address or a malformed string fails with the engine codeCONNECT_FINGERPRINT_MISMATCH,CONNECT_UNREACHABLEorCONNECT_STRING_INVALIDand trusts nothing.--trustis required.relay call relay://...is checked locally withrelay_net::connect::ConnectionString(scheme, 64-hex fingerprint, literal LAN address, no credentials or path) before anything is sent; failures exit 2. The local check admits overlay (100.64.0.0/10) addresses because the engine holds the opt-in and decides.- Channel passwords and invite tokens are never argv: flags are booleans that select a hidden terminal prompt (
rpassword) or one line of stdin.create --passwordasks twice. Secrets have a redactedDebug, are zeroed on drop, never appear in output, errors or logs; the only secret printed is a freshly minted invite (bare token in text mode), which is the command's purpose. Channels are matched by exact name, id or unique prefix;joinalso accepts a 32-hex id. avatar setaccepts PNG, JPEG, WebP, GIF, BMP or TIFF up to 1 MiB and 2048x2048, recognised from the file's bytes (the extension is ignored), and refuses locally (exit 2) with the engine's own wording (avatar must be 1 byte to 1 MiB (PNG, JPEG, WebP, GIF, BMP or TIFF),avatar rejected: unsupported or unrecognised image format ...,avatar rejected: avatar dimensions WxH exceed the 2048 pixel limit); the engine stays the authority.avatar clearcallsClearAvatar(idempotent; trusted peers are sent an empty avatar hash).
relay history [--limit N] lists the newest past calls (ListCallHistory): a table with the local time (the system zone), peer name, short fingerprint, direction, outcome and, for completed calls, the length as m:ss or h:mm:ss; no call history when empty. --json prints an array with one object per call: id, call_id (hex, names the chat session), peer_name, peer_id (hex, full fingerprint), peer_fingerprint_short, direction (incoming/outgoing), outcome (completed, missed, declined, failed, cancelled), started_at_unix_ms, duration_ms. relay history clear deletes everything (ClearCallHistory, no prompt: the list is local metadata). Recording is the preference history.enabled (relay config set history.enabled false). Source: commands/history.rs; tests tests/history_cmd.rs. The list stays on this machine (docs/config.md, "Call history").
With a daemon running, set and import send every key through SetSettings and print one line per key (--json: an array of {key, outcome, reason}): applied live, saved, needs restart (reason) (read at the next start, for example network.*, hotkeys.*, audio.input_*), or rejected: <reason> (unknown key, bad value, out of range). Valid keys are saved even when others are rejected; any rejected key makes the command exit 4 after the report. Only the security-sensitive keys (identity.*, diagnostics.record_raw_audio, network.allow_wan, network.allow_overlay_manual) need the daemon stopped: the daemon refuses them over the API, the CLI reports them as rejected: security-sensitive: change it with the daemon stopped and still sends the rest (a sensitive key given its current value is a no-op). import parses and validates the file locally, then sends only the keys that differ from the daemon's GetSettings. With no daemon, set and import take the writer lock themselves (a held lock is reported as "locked by another process") and set prints the stored value.
get and export ask a running daemon for the live values (GetSettings) and otherwise read the database without the settings lock. export is the same TOML either way and without a file prints TOML even with --json.
relay limits prints every storage and retention limit (docs/limits.md): key, current value, default, range and, when a daemon runs and knows it, what is in use. --json prints an array of {key, current, default, min, max, unit, used_bytes?}. Values come from the running daemon (GetSettings) and otherwise from the settings database without a lock. limits.messages_retained_calls (default 3) is the number of ended chats kept in memory. Change one with relay config set limits.avatar_cache_mib 256; config get, export and import include the limits.* keys like any other, and an out-of-range value is refused with the key named. Source commands/limits.rs; tests tests/limits_cmd.rs.
relay completions <shell> prints a completion script (bash, zsh, fish, elvish, powershell; clap_complete). relay man prints the relay(1) page to stdout; relay man --dir DIR writes relay.1 and one page per subcommand (relay-trust.1, ...) into DIR (clap_mangen). Neither connects to the daemon.
Text, inline images and file offers inside a call session (docs/api.md, docs/session-messages.md). The daemon owns the transcripts, so the desktop app and the CLI see the same session. Messages exist only for the life of a call and in the daemon's RAM; the only thing that ever persists is an explicit export.
- Least privilege. These commands (and the TUI's messages connection) register with the
messagescapability and nothing else; every other command never asks for it, so a daemon refuses messaging to them. Auto-start works as for other commands (--no-autostart,RELAY_NO_AUTOSTART). - Targeting.
--call <id|name>takes a call id prefix, session id prefix or peer name (exact before prefix, any case). Without it the only active session is used; none, or several, is an error listing the candidates (exit 5), never a guess. A retained (ended) transcript is readable (log,search,copy,export,clear) but must be named with--call. send <text|->sends exactly the text (-reads stdin, one trailing newline removed). Empty text and text over 4096 bytes are refused locally (exit 2).- Message numbers.
logprints each entry as#<n>(the session ordinal, never reused, surviving a clear), time (local,HH:MM:SS), direction, delivery state (sending,delivered,failed (reason)) and[pinned].pin,unpinandcopytake that number. Times use the system time zone (TZ,/etc/localtime; daylight saving applied per message) throughrelay_io::localtime::LocalZone, whichOut::with_zoneandMessagesState::zonelet tests replace.--jsonis unchanged: it carriestime_unix_ms(UTC milliseconds) and no local field. The header says(local times). - Code blocks and links. Fenced blocks in received text are listed under their message as
[code <N>: <language>, <lines> lines];Ncounts blocks across the whole session in transcript order, so it is the same inlog,watchandcopy code-block N. Links are parsed with the daemon's own safe parser and never opened: each is printed with its ASCII host, and a lookalike host (internationalised, mixed-script or invalid punycode) adds aWARNING. Control characters in received text are replaced before printing. copyuses the clipboard helper ofrelay address --copy(arboard);--printalso prints the text (and with a clipboard failure the text is still printed and the command exits 1).watchprints new entries, delivery changes, offer progress, permission changes, pins and session start/end as lines (--json: one object per line with aneventtag). History islog's job. When the daemon answersSessionResync, or a gap, overflow or new incarnation is detected, it prints-- resync: <reason>, opens a fresh watch and reads each transcript from the last ordinal printed, so nothing repeats and nothing is lost; the engine closing the stream is an error (exit 1). Ctrl-C stops.log --limit Nis the firstNentries from--since; when more remain it says how to continue.clearasks first ([y/N]on stderr, stdin) unless--yes; an active session is emptied, an ended one removed; local only.exportprints the export JSON (always JSON);--out FILEmakes the path absolute against the current directory (./..folded) and has the daemon create it, owner-only. An existing file is refused locally and by the daemon. Over about 960 KiB the daemon requires--out.image sendaccepts a regular file of at most 15 KiB (PNG,JPEG,WebP,GIF; the daemon validates the header); larger images are refused with a pointer tooffer.- File offers.
offer <path>makes the path absolute locally; the daemon opens the file (same user, same machine) and nothing moves until the peer accepts.offerslists each offer with id prefix, message number, direction, name, size, state, progress (50% of 10.0 MiB) and notes (executable-looking name, preview pending, saved name, failure).accept <offer>saves into--dest DIR(an existing directory, default the current one) with an optional suggested--name; the daemon sanitizes the name and never overwrites (name (1).ext).reject,cancelandpreview request|approve [--deny]take the same id prefix; an ambiguous prefix lists candidates. - Permissions and budget.
permsshows the session'smessages/filesswitches, message count and transcript budget; with flags it changes them (the host's choice is pushed to the guest, the guest's stays local). A full budget is stated with the way out (export, thenclear). - Problem codes (
MESSAGES_DISABLED,SESSION_PERMISSION_OFF,HISTORY_FULL,FILE_REFUSED, ...) becomeerror.codewith exit 4; some carry a hint (what to run next). Message text, file names and paths are never logged at any level and never appear in an error.
Text by default. With --json, stdout is exactly one JSON value per command (arrays for peers, devices list, trust list); errors go to stderr as {"error":{"code","message"}}. error.code is the engine's Problem.code for rejections, otherwise one of engine_unreachable, timeout, api_error, target, usage, io, json, failure. Mutations print {operation_id, state, revision, call_id}.
| Code | Meaning |
|---|---|
| 0 | success |
| 1 | other failure (I/O, a failed doctor check, hosted engine error) |
| 2 | bad usage or a request refused locally (clap errors, bad gain or fingerprint) |
| 3 | engine unreachable: auto-start is disabled (--no-autostart, RELAY_NO_AUTOSTART) or failed (the reason and the log tail are printed), or the command never starts one (below), or daemon stop ran earlier in this process |
| 4 | engine rejected the request (failed operation, gRPC error other than below) |
| 5 | target not found or ambiguous (peer, call, device, gRPC NOT_FOUND) |
| 6 | timed out waiting for an operation |
If a daemon answers but is still opening the system's secure storage (a keychain password prompt), a command waits for it (up to five minutes), printing relay: waiting for permission to use secure storage; answer the system prompt to continue... on stderr; it never starts a second daemon or restarts that one. If the keychain refuses, the command fails with the plain reason (Relay needs access to your keychain to keep your identity safe. Allow it, or choose the file store in settings) and the daemon stays up: relay daemon status shows starting or failed, relay daemon retry reads the keychain again, relay daemon use-file-store --yes chooses the less secure file store (without --yes it only explains), and relay identity reset --yes deletes the stored identity (without --yes it warns that every contact will see a new key and must verify this device again). Only the daemon ever opens the keychain; the CLI asks it.
Every command that needs the engine starts the daemon (this executable, see below) when none answers (relay_client::daemon::ensure_running, which holds a cross-process start lock so concurrent commands start one daemon), prints one line on stderr (never stdout, so --json stays clean) and goes on. The line says that the daemon opens no microphone and that the device advertises on the LAN while a client is attached or background availability is on, by default with its name (privacy default visible; relay privacy hides it). --no-autostart or RELAY_NO_AUTOSTART=1 turns it off, as does the stored clients.autostart_daemon preference (changed in the desktop Settings; the CLI has no setter); then an unreachable daemon is exit 3. Never started: daemon stop|status|logs, hotkey status, config get|export (they use a daemon only if one already answers), doctor, completions, man. After daemon stop the same process never starts one again. A running daemon with another API revision (daemon status shows both builds and warns "out of date") is replaced when it is idle: the command prints one line (relay: restarted relayd (it was build X, this is Y)) and goes on; with a call in progress it prints one warning line and leaves the daemon alone (relay daemon restart when done). --no-autostart/RELAY_NO_AUTOSTART switch this off too. Headless: on desktop background.available is off by default, so a relayd only rings while an app or the tray holds it (a client is attached) and a command-started daemon exits after 300 s unused; enable it with relay config set background.available true. On Android it is on by default. With background.available on a relayd with no attached client, however it was started (a command, relay daemon start, a service unit), is itself home: it advertises on the LAN (by default with its name; privacy.advert_mode hidden stops that), listens, accepts invitations, rings the engine ringtone per calls.alert and auto-answers verified flagged contacts (the engine owns that call; the first client that attaches can control it, push-to-talk and mic state follow calls.default_transmit_mode). An unanswered call follows the ring timeout and is in the history. relayd itself shows no notification (it has no shell): the sound rings and the log says what happened; a notification needs the desktop app in the tray (docs/desktop.md). With background on the daemon never idle-exits, so a command that autostarts it leaves it running; relay config set background.available false (live), the desktop default, gives the rules: no advert, no ring, invitations declined as busy without a client, and an exit after 300 s with no attached client and no call (--idle-exit, RELAY_IDLE_EXIT_SECS). relay daemon start has no idle exit.
A daemon with no attached client (no open WatchState stream) neither advertises nor rings: a short-lived command such as relay peers attaches, so it counts for the second or so it lives (the engine debounces presence by 2 s).
A call belongs to the client that holds its controller lease. When that client detaches, the call ends after a 3 s grace, unless it re-attaches or another attached client takes over. So relay call and relay accept stay in the foreground holding a watch; Ctrl-C or q hangs up. relay end implies takeover. mute, deafen, gain and talk on a call another client owns still need --takeover; a taken-over call then belongs to the CLI process, so when that command exits the call ends after the grace. Use the desktop app, or relay call, to keep a call going.
Checks, in order: endpoint, engine reachability and version, input and output device availability, engine warnings, preferences readability. It reads the preferences database read-only (PreferenceStore::read_only) without taking the writer lock, so it works while the engine runs. --bundle FILE writes relay_config::diagnostics::build_bundle output (redacted, size capped) with mode 0600, even if the engine is down. Any failed check exits 1.
relay tui opens registered connections: one for commands, one for the state watch, one for telemetry (plus two messages-only ones, below). The state feed (client::run_state_feed) reopens the watch, which begins with a snapshot, on revision gaps, stale revisions, incarnation changes, subscription overflow, an engine Resync, or a closed stream; the header shows live, resyncing (...) or offline (...) meanwhile. Telemetry is best-effort and reopens after errors.
Screens: Peers, Calls (cards), Devices, Settings, Messages. Header: link state, revision, microphone meter, mute/deafen, noise suppression. Call cards show peer, state, speaking indicator, mode, the engine's effective_transmitting ("TRANSMITTING" or "mic closed"), blocked_reason, receive meter and transport stats.
Keys: tab/1-5 screens, j/k move, enter call or select, c call, a/x/e accept/decline/end, t cycle the mode (muted, push-to-talk, unmuted; applied at once), space push-to-talk, m/d mute/deafen, +/- gain on Settings (and the PTT release delay row, in 50 ms steps from 0 to 2000), q quit.
relay tui opens two more registered connections for messaging, with the messages capability only: one for commands and one for the session watch. If it cannot be opened (or the daemon refuses the capability) the rest of the UI works and the tab says Messages are unavailable: <reason>. The session feed (client::run_session_feed) opens WatchSession, loads each session's transcript (at most 8 pages), and on SessionResync, a gap, an overflow, a new incarnation or a closed stream reopens it and reloads, with the header showing live, resyncing (...) or offline (...). The pane keeps at most 1000 rows per session and 16 sessions; bursts of events are applied between two redraws.
One pane per call, [ and ] switch (ended calls stay as read-only transcripts). Rows show time (local, HH:MM:SS), who, delivery state (sending, delivered, FAILED (reason)), [pinned], text with bold/italic/inline code, numbered code blocks (+- code N: lang), links (underlined, never opened, lookalike hosts flagged in red with the real host), images as a one-line summary, and file offers with a progress bar and warnings. Header lines state messages on/off files on/off, counts and the transcript budget; honest states: permissions off ("turned off for this call"), budget full (e export, X clear), call ended (read-only), no call, link lost.
Browse keys (the compose box and prompts take every key while open, so tab switching and q only apply while browsing): i/enter write (Enter sends, Ctrl-J new line, Esc leaves; the draft is dropped only after the daemon accepted it), j/k move, g/G first/newest, / search then n/N jump between matches, p pin, b choose a code block in the selected message, Ctrl-Y or y copy it, o offer a file (path prompt), a accept the selected incoming offer (directory prompt, default the current directory), r reject, c cancel, v request a preview (or approve the peer's request), e export to a new file (path prompt), X empty the transcript (y confirms). These keys shadow the global a/c/e/m/d/... only on this tab.
The Settings tab lists the microphone and playback gain, mute, deafen and the PTT release delay (how long the gate stays open after the key is released, 0 to 2000 ms; relay config set ptt.release_delay_ms 300 does the same). While the delay runs the call shows the engine's releasing state; nothing is assumed locally.
Push-to-talk in the TUI has two paths:
- Global hotkey (
hotkeys.push_to_talk, defaultCtrl+Alt+Space):relay tuistarts the platform backend on the main thread and presses the sharedPttWorker(docs/client.md) with its edges, exactly likerelay hotkey; the worker opens its ownInputControlstream as this client. The header's third line says what is true:active via <backend>plusptt: idle|transmitting|held, engine not transmitting|blocked: no controlled call|rejected|failedand the controlled call, orneeds Input Monitoring: ...,unsupported: <reason>,failed: <reason>,off (...). Nothing is claimed when the backend refused. - Terminal key: terminals do not report key release, so
spacelatches (press, renew every 100 ms tick, release on the nextspace). It needs the call already in push-to-talk mode with consent. The engine's effective state is what is displayed.
The platform backend (relay-platform) must be created on the process main thread on macOS, and the run loop must be serviced there, so main starts the backend, then runs tokio on a worker thread and calls hotkey::run_main_loop until the command ends (host.rs). The daemon is unaffected. relay hotkey prints one line per change (--json: one object per line with an event tag) until Ctrl-C, which releases transmission.
relay hotkey statusprobes without starting: backend state, saved binding, lock-detection coverage, and on macOS Accessibility and Input Monitoring status. JSON hasstate=active|disabled|needs_permission|unsupported|failed.relay hotkey set <keys>validates with the platform parser and saveshotkeys.push_to_talk(empty disables). With a daemon running it goes throughSetSettingsand printssaved, needs restart(the key is read whenrelay hotkeyor the desktop app starts;--binding KEYSis for a single run). With none running it takes the settings lock itself; a lock held by another process is reported.- The key controls the one
Connectedcall: once a second the supervisor takes that call's controller lease (--takeoverto take it from another client) and rebinds the driver when the call or its route generation changes. No connected call: the key is blocked. Several connected calls: it will not guess (several calls). Muting, missing consent and gating still decide whether audio flows; the driver showsheld, engine not transmitting. - Permissions on macOS attach to the terminal app that runs
relay, not the binary.
cargo test -p relay-cli. FakeControl (scripted, records calls; implements Control, Subscribe, Manage) covers command logic, secrets and the TUI drive loop; EngineHarness serves a fake Engine over a Unix socket for wire-level behavior (lease generation, consent bits, secrets on the wire, rejection mapping, live config set); tests/real_engine.rs runs against the real service layer with recording adapters; tests/messages_*.rs cover the relay messages commands against the scripted fake (tests/common/chat.rs holds the messaging semantics shared with the socket engine), tests/messages_wire.rs the capability and a TRACE-level log capture proving text and file names never reach a log, tests/tui_messages.rs the Messages tab on a TestBackend, tests/messages_feed.rs the feed, and tests/real_chat.rs two real daemons in a call (text both ways, a file offer accepted and verified byte for byte; it includes the engine's own harness by path); tests/daemon_cmd.rs builds relayd and runs start, status, restart and stop against it; tests/hotkey.rs drives supervise with relay_platform::testing fakes; TUI snapshots use ratatui TestBackend; binary tests check exit codes and hotkey status.
relay never runs the engine in its own process. relay daemon start launches the engine as a
separate detached process: relay itself, started with the hidden first argument --run-daemon
(relay_daemon::exit_if_requested, called first in main; docs/decisions.md). No relayd file is
searched for, so a cargo run -p relay-cli from a clean checkout works. The hidden global
--daemon-bin PATH runs another program as relayd instead (tests). It waits until the endpoint
accepts connections; it prints already running instead of starting a second one. stop and
restart register a short-lived client with the admin capability and call Shutdown; no other
command requests it. status exits 3 when nothing serves the endpoint, like every other command
(daemon not running at ...; try relay daemon start). --socket and
--tcp-profile choose the endpoint and are passed on to the daemon. The engine comes in through the
relay-daemon library (the daemon entry only); relay-engine is also a dev-dependency (for
tests/real_engine.rs).
- Real key delivery is a manual gate (see
docs/platform.md):relay hotkey statuswas only exercised on macOS here, and press/release through the OS was not. hotkeys.push_to_talkcan be set while the engine runs, but it is read whenrelay hotkeyor the desktop app starts (saved, needs restart). Channel and privacy RPCs depend on the engine; anUNIMPLEMENTEDanswer is reported as a rejection (exit 4).relay-clientis being extended with channel and privacy commands by another change; this app calls the generated RPCs for them inclient/manage.rsand should move to the shared vocabulary once that lands.trust verifyrequires the user to supply the full fingerprint:Peercarries only the short form, which is a hint and not enough to verify.- No Windows named-pipe endpoint (API gate); on Windows only
--tcp-profileworks. doctorcannot report preference-recovery notices (needs the writer lock) and passes no log lines or counters beyond peer/call counts.