roadrunner (rr)

Use rr when the user explicitly wants to operate Beeper Desktop via the local API (send, search, list chats/messages, reminders, focus).
Prefer --agent for agent use (forces JSON, envelope, no-input, readonly).

Safety

• - Default to read-only commands unless the user explicitly requests a mutation in this turn.
• Require explicit recipient (chat ID) and message text before sending.
• Confirm or ask a clarifying question if the chat ID is ambiguous.
• Never paste raw rr command output (JSON dumps, chat lists, etc.) into outgoing messages. Treat tool output as private; summarize or extract only what the user needs.
• Use --agent for safe agent defaults: INLINECODE3
• Use --readonly to block writes: INLINECODE5
• Use --enable-commands to allowlist: INLINECODE7
• Use --envelope for structured errors: INLINECODE9
• Envelope errors may include error.hint with next-step guidance for safe retries.
• Never request, paste, or store raw auth tokens in chat. If auth is missing, ask the user to configure it locally.
• If sending message text through a shell, avoid interpolation/expansion (e.g. $100/month or !). Prefer --stdin <<'EOF' ... EOF for safe literals.

Setup (once)

• - rr auth set --stdin (recommended; token saved to ~/.config/beeper/config.json)
• INLINECODE16
• INLINECODE17

Common commands

• - List accounts: INLINECODE18
• Capabilities: INLINECODE19
• Describe command/flags: INLINECODE20
• Connect metadata: INLINECODE21
• Live websocket events (experimental): INLINECODE22
• List contacts: INLINECODE23
• Search contacts: INLINECODE24
• Search contacts (flag): INLINECODE25
• Resolve contact: INLINECODE26
• Resolve contact (flag): INLINECODE27
• List chats: INLINECODE28
• List chats (JSON Lines): INLINECODE29
• Search chats: INLINECODE30
• Search chats (filters): INLINECODE31
• Search chats (activity): INLINECODE32
• Search by participant name: INLINECODE33
• Resolve chat: INLINECODE34
• Get chat: INLINECODE35
• Get chat (bounded participants): INLINECODE36
• Start/resolve DM from merged contact hints: INLINECODE37
• Default account for commands: INLINECODE38
• List messages: INLINECODE39
• List messages (all pages): INLINECODE40
• List messages (download media): INLINECODE41
• Search messages: INLINECODE42
• Search messages (JSON Lines): INLINECODE43
• Search messages (all pages): INLINECODE44
• Search messages (filters): INLINECODE45
• Add/remove reaction: rr messages react "!chatid:beeper.com" "<message-id>" "👍" --json / INLINECODE47
• Tail messages (polling): INLINECODE48
• Wait for message: INLINECODE49
• Message context: INLINECODE50
• Draft message (pre-fill without sending): INLINECODE51
• Draft message from file: INLINECODE52
• Draft with attachment: INLINECODE53
• Download attachment: INLINECODE54
• Stream attachment bytes: INLINECODE55
• Focus app: INLINECODE56
• Global search: INLINECODE57
• Global search messages auto-page: INLINECODE58
• Status summary: INLINECODE59
• Status by account: INLINECODE60
• Unread rollup: INLINECODE61
• Global search includes in_groups for participant matches.

Mutations (explicit user request only)

• - Message send: INLINECODE63
• Message edit: INLINECODE64
• Message react/unreact: rr messages react "!chatid:beeper.com" "<message-id>" "👍" / INLINECODE66
• Upload + send file: INLINECODE67
• Create chat: INLINECODE68
• Start chat from merged contact hints: INLINECODE69
• Archive/unarchive: rr chats archive "!chatid:beeper.com" / INLINECODE71
• Reminder mutations: rr reminders set "!chatid:beeper.com" "2h" / INLINECODE73
• Asset uploads: rr assets upload ./photo.jpg / INLINECODE75
• For retries on non-idempotent writes, use --request-id and prefer --dedupe-window.
• Use --dry-run to validate mutating requests without API write side effects.

Pagination

• - Auto-page chats list/search: rr chats list --all --max-items=1000 --json / INLINECODE80
• Auto-page messages list/search: rr messages list "!chatid:beeper.com" --all --max-items=1000 --json / INLINECODE82
• Chats: INLINECODE83
• Messages list: INLINECODE84
• Messages search (max 20): INLINECODE85
• Messages search page: INLINECODE86
• Global search message paging (max 20): INLINECODE87
• Global search message page: INLINECODE88

Notes

• - Requires Beeper Desktop running; token from app settings.
• Token is stored in ~/.config/beeper/config.json via rr auth set (recommended). BEEPER_TOKEN overrides the config file.
• INLINECODE92 sets the default account ID (aliases supported).
• INLINECODE93 prefers OAuth introspection (/oauth/introspect) when available and falls back to account-list validation on older builds.
• Message search is literal word match (not semantic).
• INLINECODE95 is strict and fails on ambiguous names; resolve by ID after contacts search when needed.
• If a DM title shows your own Matrix ID, use --scope=participants to find by name.
• JSON output includes display_name for single chats (derived from participants).
• Message JSON includes message_type, linked_message_id, is_sender, is_unread, attachments, and reactions.
• INLINECODE105 is only populated when --download-media is used.
• INLINECODE107 returns pending_message_id (temporary ID).
• Account network may be missing in newer API builds; rr falls back to "unknown" in summaries/search output.
• INLINECODE112 writes raw bytes to stdout unless --dest is provided.
• INLINECODE114 does exact matching and fails on ambiguous matches.
• Attachment overrides require --attachment-upload-id; set --attachment-width and --attachment-height together.
• INLINECODE118 has a safety cap (default 500 items, max 5000); use --max-items to tune it.
• Prefer --json or --jsonl (and --no-input) for automation.
• INLINECODE123 emits one JSON object per line and is supported on high-volume list/search commands.
• INLINECODE124/BEEPER_DRY_RUN validates mutating command inputs and prints preview output without sending write API requests.
• INLINECODE126 overrides API base URL; BEEPER_TIMEOUT sets timeout in seconds.
• JSON/Plain output goes to stdout; errors/hints go to stderr.
• Destructive commands prompt unless --force; --no-input/BEEPER_NO_INPUT fails without --force.
• Use --fail-if-empty on list/search commands to exit with code 1 if no results.
• Use --fields with --plain to select columns (comma-separated).
• In bash/zsh, ! triggers history expansion. Prefer single quotes, or disable history expansion (set +H in bash, setopt NO_HIST_EXPAND in zsh).
• INLINECODE138 returns features array for capability discovery.
• INLINECODE140 returns full CLI capability metadata.
• INLINECODE141 depends on experimental /v1/ws support in Beeper Desktop; fall back to rr messages tail when unavailable.
• Envelope error codes: AUTH_ERROR, NOT_FOUND, VALIDATION_ERROR, CONNECTION_ERROR, INTERNAL_ERROR.
• Retry policy: retry CONNECTION_ERROR with backoff; do not blind-retry AUTH_ERROR/VALIDATION_ERROR; refresh IDs before retrying NOT_FOUND.
• Non-idempotent writes: messages send, messages send-file, chats create, chats start, assets upload, assets upload-base64.
• Use --request-id/BEEPER_REQUEST_ID to tag envelope metadata for cross-retry attempt tracing.
• Use --dedupe-window/BEEPER_DEDUPE_WINDOW to block duplicate non-idempotent writes with repeated request IDs.
• Local smoke check: make test-agent-smoke.