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

• Require explicit recipient (chat ID) and message text before sending.
• Confirm or ask a clarifying question if the chat ID is ambiguous.
• Use --agent for safe agent defaults: rr --agent --enable-commands=chats,messages,status chats list
• Use --readonly to block writes: rr --readonly chats list --json
• Use --enable-commands to allowlist: rr --enable-commands=chats,messages chats list --json
• Use --envelope for structured errors: rr --json --envelope chats get "!chatid"

Setup (once)

• rr auth set <token>
• rr auth status --check
• rr doctor

Common commands

• List accounts: rr accounts list --json
• Capabilities: rr capabilities --json
• Search contacts: rr contacts search "<account-id>" "Alice" --json
• Search contacts (flag): rr contacts search "Alice" --account-id="<account-id>" --json
• Resolve contact: rr contacts resolve "<account-id>" "Alice" --json
• Resolve contact (flag): rr contacts resolve "Alice" --account-id="<account-id>" --json
• List chats: rr chats list --json
• Search chats: rr chats search "John" --json
• Search chats (filters): rr chats search --inbox=primary --unread-only --json
• Search chats (activity): rr chats search --last-activity-after="2024-07-01T00:00:00Z" --json
• Search by participant name: rr chats search "Jamie" --scope=participants --json
• Resolve chat: rr chats resolve "Jamie" --json
• Get chat: rr chats get "!chatid:beeper.com" --json
• Create chat (single): rr chats create "<account-id>" --participant "<user-id>"
• Create chat (group): rr chats create "<account-id>" --participant "<user-a>" --participant "<user-b>" --type group --title "Project Chat" --message "Welcome!"
• Default account for commands: rr --account="imessage:+123" chats list --json
• Account aliases: rr accounts alias set work "slack:T123"
• List messages: rr messages list "!chatid:beeper.com" --json
• List messages (download media): rr messages list "!chatid:beeper.com" --download-media --download-dir ./media --json
• Search messages: rr messages search "dinner" --json
• Search messages (filters): rr messages search --sender=me --date-after="2024-07-01T00:00:00Z" --media-types=image --json
• Send message: rr messages send "!chatid:beeper.com" "Hello!"
• Reply to message: rr messages send "!chatid:beeper.com" "Thanks!" --reply-to "<message-id>"
• Send message from file: rr messages send "!chatid:beeper.com" --text-file ./message.txt
• Send message from stdin: cat message.txt | rr messages send "!chatid:beeper.com" --stdin
• Tail messages (polling): rr messages tail "!chatid:beeper.com" --interval 2s --stop-after 30s --json
• Wait for message: rr messages wait --chat-id="!chatid:beeper.com" --contains "deploy" --wait-timeout 2m --json
• Message context: rr messages context "!chatid:beeper.com" "<sortKey>" --before 5 --after 2 --json
• Draft message (pre-fill without sending): rr focus --chat-id="!chatid:beeper.com" --draft-text="Hello!"
• Draft message from file: rr focus --chat-id="!chatid:beeper.com" --draft-text-file ./draft.txt
• Draft with attachment: rr focus --chat-id="!chatid:beeper.com" --draft-attachment="/path/to/file.jpg"
• Download attachment: rr assets download "mxc://example.org/abc123" --dest "./attachment.jpg"
• Reminders: rr reminders set "!chatid:beeper.com" "2h" / rr reminders clear "!chatid:beeper.com"
• Archive chat: rr chats archive "!chatid:beeper.com" / rr chats archive "!chatid:beeper.com" --unarchive
• Focus app: rr focus
• Global search: rr search "dinner" --json
• Status summary: rr status --json
• Status by account: rr status --by-account --json
• Unread rollup: rr unread --json
• Global search includes in_groups for participant matches.

Pagination

• Chats: rr chats list --cursor="<oldestCursor>" --direction=before --json
• Messages list: rr messages list "!chatid:beeper.com" --cursor="<sortKey>" --direction=before --json
• Messages search (max 20): rr messages search "project" --limit=20 --json
• Messages search page: rr messages search "project" --cursor="<cursor>" --direction=before --json
• Global search message paging (max 20): rr search "dinner" --messages-limit=20 --json
• Global search message page: rr search "dinner" --messages-cursor="<cursor>" --messages-direction=before --json

Notes

• Requires Beeper Desktop running; token from app settings.
• Token stored at ~/.config/beeper/config.json. BEEPER_TOKEN overrides.
• BEEPER_ACCOUNT sets the default account ID (aliases supported).
• Message search is literal word match (not semantic).
• rr contacts resolve 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 is_sender, is_unread, attachments, and reactions.
• downloaded_attachments is only populated when --download-media is used.
• rr messages send returns pending_message_id (temporary ID).
• Prefer --json (and --no-input) for automation.
• BEEPER_URL 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).
• rr version --json returns features array for capability discovery.
• rr capabilities --json returns full CLI capability metadata.
• Envelope error codes: AUTH_ERROR, NOT_FOUND, VALIDATION_ERROR, CONNECTION_ERROR, INTERNAL_ERROR.