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

  .