Roadrunner

Beeper Desktop CLI for chats, messages, contacts, connect info, websocket events, search, and reminders.

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: 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"
• 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)
• rr auth status --check
• rr doctor

Common commands

• List accounts: rr accounts list --json
• Capabilities: rr capabilities --json
• Describe command/flags: rr describe messages send --json
• Connect metadata: rr connect info --json
• Live websocket events (experimental): rr events tail --all --stop-after 30s --json
• List contacts: rr contacts list "<account-id>" --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
• List chats (JSON Lines): rr chats list --jsonl
• 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
• Get chat (bounded participants): rr chats get "!chatid:beeper.com" --max-participant-count=50 --json
• Start/resolve DM from merged contact hints: rr chats start "<account-id>" --email "[e-mail]" --full-name "Alice" --json
• Default account for commands: rr --account="imessage:+123" chats list --json
• List messages: rr messages list "!chatid:beeper.com" --json
• List messages (all pages): rr messages list "!chatid:beeper.com" --all --max-items=1000 --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 (JSON Lines): rr messages search "dinner" --jsonl
• Search messages (all pages): rr messages search "dinner" --all --max-items=1000 --json
• Search messages (filters): rr messages search --sender=me --date-after="2024-07-01T00:00:00Z" --media-types=image --json
• Add/remove reaction: rr messages react "!chatid:beeper.com" "<message-id>" "👍" --json / rr messages unreact "!chatid:beeper.com" "<message-id>" "👍" --json
• 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"
• Stream attachment bytes: rr assets serve "mxc://example.org/abc123" --dest "./attachment.jpg" --json
• Focus app: rr focus
• Global search: rr search "dinner" --json
• Global search messages auto-page: rr search "dinner" --messages-all --messages-max-items=500 --messages-limit=20 --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.

Mutations (explicit user request only)

• Message send: rr messages send "!chatid:beeper.com" "Hello!"
• Message edit: rr messages edit "!chatid:beeper.com" "<message-id>" "Updated text"
• Message react/unreact: rr messages react "!chatid:beeper.com" "<message-id>" "👍" / rr messages unreact "!chatid:beeper.com" "<message-id>" "👍"
• Upload + send file: rr messages send-file "!chatid:beeper.com" ./photo.jpg "See attached"
• Create chat: rr chats create "<account-id>" --participant "<user-id>"
• Start chat from merged contact hints: rr chats start "<account-id>" --email "[e-mail]" --full-name "Alice"
• Archive/unarchive: rr chats archive "!chatid:beeper.com" / rr chats archive "!chatid:beeper.com" --unarchive
• Reminder mutations: rr reminders set "!chatid:beeper.com" "2h" / rr reminders clear "!chatid:beeper.com"
• Asset uploads: rr assets upload ./photo.jpg / rr assets upload-base64 --content-file ./photo.b64
• 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 / rr chats search "alice" --all --max-items=1000 --json
• Auto-page messages list/search: rr messages list "!chatid:beeper.com" --all --max-items=1000 --json / rr messages search "deploy" --all --max-items=1000 --json
• 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 is stored in ~/.config/beeper/config.json via rr auth set (recommended). BEEPER_TOKEN overrides the config file.
• BEEPER_ACCOUNT sets the default account ID (aliases supported).
• rr auth status --check 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).
• 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 message_type, linked_message_id, 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).
• Account network may be missing in newer API builds; rr falls back to "unknown" in summaries/search output.
• rr assets serve writes raw bytes to stdout unless --dest is provided.
• --chat does exact matching and fails on ambiguous matches.
• Attachment overrides require --attachment-upload-id; set --attachment-width and --attachment-height together.
• --all has a safety cap (default 500 items, max 5000); use --max-items to tune it.
• Prefer --json or --jsonl (and --no-input) for automation.
• --jsonl emits one JSON object per line and is supported on high-volume list/search commands.
• --dry-run/BEEPER_DRY_RUN validates mutating command inputs and prints preview output without sending write API requests.
• 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.
• rr events tail 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.