roadrunner

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

roadrunner (rr)

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
```

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

Get chat (bounded participants):

rr chats get "!chatid:beeper.com" --max-participant-count=50 --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 (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

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"

Upload + send file:

rr messages send-file "!chatid:beeper.com" ./photo.jpg "See attached"

Create chat:

rr chats create "<account-id>" --participant "<user-id>"

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
```
.

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).
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).
```
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
```
(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

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

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
```
.

当用户明确希望通过本地API操作Beeper Desktop时（发送消息、搜索、列出聊天/消息、设置提醒、聚焦窗口），请使用

rr

命令。对于Agent使用场景，优先使用

--agent

参数（强制输出JSON格式、使用信封结构、无交互输入、只读模式）。

安全注意事项

默认使用只读命令，除非用户在本次请求中明确要求执行修改操作。
发送消息前必须明确指定接收方（聊天ID）和消息文本。
如果聊天ID存在歧义，请确认或提出澄清问题。
切勿将rr命令的原始输出（JSON数据、聊天列表等）粘贴到外发消息中。将工具输出视为私密内容；仅总结或提取用户需要的信息。

对于安全的Agent默认配置，使用

--agent

参数：

rr --agent --enable-commands=chats,messages,status chats list

使用

--readonly

参数阻止写入操作：

rr --readonly chats list --json

使用

--enable-commands

参数设置允许的命令白名单：

rr --enable-commands=chats,messages chats list --json

使用

--envelope

参数获取结构化错误信息：

rr --json --envelope chats get "!chatid"

信封格式的错误信息可能包含
```
error.hint
```
字段，提供安全重试的下一步指导。
切勿请求、粘贴或存储原始认证令牌到聊天中。如果缺少认证信息，请让用户在本地配置。
如果通过Shell发送消息文本，避免变量插值/扩展（例如
```
$100/month
```
或
```
!
```
）。对于安全的文本内容，优先使用
```
--stdin <<'EOF' ... EOF
```
方式。

首次设置

rr auth set --stdin

（推荐；令牌将保存到

~/.config/beeper/config.json

）

```
rr auth status --check
```
```
rr doctor
```

常用命令

列出账户：
```
rr accounts list --json
```
查看功能支持：
```
rr capabilities --json
```

搜索联系人：

rr contacts search "<account-id>" "Alice" --json

搜索联系人（使用参数）：

rr contacts search "Alice" --account-id="<account-id>" --json

解析联系人：

rr contacts resolve "<account-id>" "Alice" --json

解析联系人（使用参数）：

rr contacts resolve "Alice" --account-id="<account-id>" --json

列出聊天：
```
rr chats list --json
```
搜索聊天：
```
rr chats search "John" --json
```

搜索聊天（筛选条件）：

rr chats search --inbox=primary --unread-only --json

搜索聊天（按活动时间）：

rr chats search --last-activity-after="2024-07-01T00:00:00Z" --json

按参与者名称搜索聊天：

rr chats search "Jamie" --scope=participants --json

解析聊天：
```
rr chats resolve "Jamie" --json
```

获取聊天详情：

rr chats get "!chatid:beeper.com" --json

获取聊天详情（限制参与者数量）：

rr chats get "!chatid:beeper.com" --max-participant-count=50 --json

指定命令的默认账户：

rr --account="imessage:+123" chats list --json

列出消息：

rr messages list "!chatid:beeper.com" --json

列出所有消息（自动分页）：

rr messages list "!chatid:beeper.com" --all --max-items=1000 --json

列出消息并下载媒体文件：

rr messages list "!chatid:beeper.com" --download-media --download-dir ./media --json

搜索消息：
```
rr messages search "dinner" --json
```

搜索所有消息（自动分页）：

rr messages search "dinner" --all --max-items=1000 --json

搜索消息（筛选条件）：

rr messages search --sender=me --date-after="2024-07-01T00:00:00Z" --media-types=image --json

实时监听消息（轮询）：

rr messages tail "!chatid:beeper.com" --interval 2s --stop-after 30s --json

等待指定消息：

rr messages wait --chat-id="!chatid:beeper.com" --contains "deploy" --wait-timeout 2m --json

获取消息上下文：

rr messages context "!chatid:beeper.com" "<sortKey>" --before 5 --after 2 --json

草稿消息（预填充不发送）：

rr focus --chat-id="!chatid:beeper.com" --draft-text="Hello!"

从文件加载草稿消息：

rr focus --chat-id="!chatid:beeper.com" --draft-text-file ./draft.txt

带附件的草稿：

rr focus --chat-id="!chatid:beeper.com" --draft-attachment="/path/to/file.jpg"

下载附件：

rr assets download "mxc://example.org/abc123" --dest "./attachment.jpg"

流式传输附件字节：

rr assets serve "mxc://example.org/abc123" --dest "./attachment.jpg" --json

聚焦应用窗口：
```
rr focus
```
全局搜索：
```
rr search "dinner" --json
```

全局搜索消息自动分页：

rr search "dinner" --messages-all --messages-max-items=500 --messages-limit=20 --json

状态汇总：
```
rr status --json
```
按账户查看状态：
```
rr status --by-account --json
```
未读消息汇总：
```
rr unread --json
```
全局搜索包含
```
in_groups
```
参数用于匹配参与者。

修改操作（仅在用户明确请求时执行）

发送消息：

rr messages send "!chatid:beeper.com" "Hello!"

编辑消息：

rr messages edit "!chatid:beeper.com" "<message-id>" "Updated text"

上传并发送文件：

rr messages send-file "!chatid:beeper.com" ./photo.jpg "See attached"

创建聊天：

rr chats create "<account-id>" --participant "<user-id>"

归档/取消归档：

rr chats archive "!chatid:beeper.com"

rr chats archive "!chatid:beeper.com" --unarchive

提醒修改：

rr reminders set "!chatid:beeper.com" "2h"

rr reminders clear "!chatid:beeper.com"

资产上传：

rr assets upload ./photo.jpg

rr assets upload-base64 --content-file ./photo.b64

对于非幂等写入操作的重试，使用
```
--request-id
```
参数，并优先配合
```
--dedupe-window
```
参数。

分页

聊天列表/搜索自动分页：

rr chats list --all --max-items=1000 --json

rr chats search "alice" --all --max-items=1000 --json

消息列表/搜索自动分页：

rr messages list "!chatid:beeper.com" --all --max-items=1000 --json

rr messages search "deploy" --all --max-items=1000 --json

聊天分页：

rr chats list --cursor="<oldestCursor>" --direction=before --json

消息列表分页：

rr messages list "!chatid:beeper.com" --cursor="<sortKey>" --direction=before --json

消息搜索（最多20条）：

rr messages search "project" --limit=20 --json

消息搜索分页：

rr messages search "project" --cursor="<cursor>" --direction=before --json

全局搜索消息分页（最多20条）：

rr search "dinner" --messages-limit=20 --json

全局搜索消息分页：

rr search "dinner" --messages-cursor="<cursor>" --messages-direction=before --json

注意事项

需要Beeper Desktop处于运行状态；令牌可从应用设置中获取。
令牌通过
```
rr auth set
```
命令保存到
```
~/.config/beeper/config.json
```
（推荐方式）。环境变量
```
BEEPER_TOKEN
```
会覆盖配置文件中的设置。
环境变量
```
BEEPER_ACCOUNT
```
用于设置默认账户ID（支持别名）。
消息搜索为字面单词匹配（非语义匹配）。
```
rr contacts resolve
```
命令为严格匹配，名称存在歧义时会执行失败；必要时可先通过
```
contacts search
```
获取ID再进行解析。
如果私聊会话标题显示您自己的Matrix ID，可使用
```
--scope=participants
```
参数按名称查找。
JSON输出包含单聊的
```
display_name
```
字段（从参与者信息推导）。
消息JSON包含
```
is_sender
```
、
```
is_unread
```
、
```
attachments
```
和
```
reactions
```
字段。
仅当使用
```
--download-media
```
参数时，才会填充
```
downloaded_attachments
```
字段。
```
rr messages send
```
命令返回
```
pending_message_id
```
（临时ID）。
除非指定
```
--dest
```
参数，否则
```
rr assets serve
```
命令会将原始字节写入标准输出。
```
--chat
```
参数为精确匹配，存在歧义匹配时会执行失败。
附件覆盖需要使用
```
--attachment-upload-id
```
参数；
```
--attachment-width
```
和
```
--attachment-height
```
参数需同时设置。
```
--all
```
参数有安全上限（默认500条，最大5000条）；可使用
```
--max-items
```
参数调整。
自动化场景优先使用
```
--json
```
（配合
```
--no-input
```
）参数。
环境变量
```
BEEPER_URL
```
用于覆盖API基础URL；
```
BEEPER_TIMEOUT
```
用于设置超时时间（秒）。
JSON/纯文本输出写入标准输出；错误/提示信息写入标准错误输出。
破坏性命令会触发确认提示，除非使用
```
--force
```
参数；如果未使用
```
--force
```
，
```
--no-input
```
/
```
BEEPER_NO_INPUT
```
会导致命令执行失败。
在列表/搜索命令中使用
```
--fail-if-empty
```
参数，当无结果时会以代码1退出。
配合
```
--plain
```
参数使用
```
--fields
```
参数选择要显示的列（逗号分隔）。
在bash/zsh中，
```
!
```
会触发历史扩展。优先使用单引号，或禁用历史扩展（bash中执行
```
set +H
```
，zsh中执行
```
setopt NO_HIST_EXPAND
```
）。
```
rr version --json
```
命令返回
```
features
```
数组用于功能发现。
```
rr capabilities --json
```
命令返回完整的CLI功能元数据。

信封格式错误码：

AUTH_ERROR

、

NOT_FOUND

、

VALIDATION_ERROR

、

CONNECTION_ERROR

、

INTERNAL_ERROR

。

重试策略：对
```
CONNECTION_ERROR
```
错误进行退避重试；不要盲目重试
```
AUTH_ERROR
```
/
```
VALIDATION_ERROR
```
错误；重试
```
NOT_FOUND
```
错误前先刷新ID。

非幂等写入操作：

messages send

、

messages send-file

、

chats create

、

assets upload

、

assets upload-base64

。

使用
```
--request-id
```
/
```
BEEPER_REQUEST_ID
```
参数标记信封元数据，用于跨重试尝试的追踪。
使用
```
--dedupe-window
```
/
```
BEEPER_DEDUPE_WINDOW
```
参数阻止重复请求ID的非幂等写入操作重复执行。
本地冒烟测试：
```
make test-agent-smoke
```
。