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 "alice@example.com" --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 "alice@example.com" --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
```
.

Roadrunner

AI Skill Market Insights

Quick Start

Manual Installation

TEAR & SHARE

Tags

typesafe-mcp

Be Part of the 0+ Developer Community

roadrunner (rr)

Upgrade Stripe

README

MCP Apps Builder

jev-mcp (jkudish)

Channels

Learn

Compare

Company

Agents