核心用法
roadrunner（rr）是 Beeper Desktop 的命令行接口，允许用户在不打开 GUI 的情况下完成聊天操作、消息管理、联系人搜索与提醒设置。核心工作流围绕「认证 → 查询 → 操作」展开：首次使用需通过 rr auth set <token> 配置 Beeper 令牌，随后即可调用 rr chats list、rr messages send、rr search 等子命令完成操作。工具支持 JSON 输出（--json）、结构化错误包装（--envelope）和只读模式（--readonly），便于脚本集成与自动化场景。
显著优点
- 功能覆盖面广：涵盖聊天列表、消息收发、附件上传下载、全局搜索、提醒设置等 20+ 操作场景
- 自动化友好：
--agent模式专为 AI agent 设计，强制 JSON 输出、禁用交互、提供错误封装；--enable-commands允许细粒度权限控制 - 安全设计：
--readonly完全阻止写操作，--force与--no-input组合防止意外破坏性操作，历史命令中的!字符也有明确风险提示 - 分页与流式：支持
--all自动分页、--tail轮询监听、--wait条件阻塞，满足批处理与实时性需求
潜在缺点与局限
- 依赖 Beeper Desktop：必须保持桌面客户端运行，CLI 本身不独立连接云端，这限制了纯服务器/无头环境的使用
- Token 管理负担：需手动从 Beeper 设置中提取令牌，且存储在本地明文 JSON，多设备同步或 CI 场景下需额外安全管控
- 搜索语义局限：消息搜索为字面词匹配，非语义/向量检索；联系人
resolve对模糊名称严格失败，需先search再resolve - 生态成熟度：由个人开发者维护（johntheyoung），非 Beeper 官方项目，长期维护与兼容性存在不确定性
适合人群
- Beeper 重度用户，希望用键盘工作流替代 GUI 操作
- 需要批量导出聊天记录、自动化消息发送的开发者/运营人员
- 构建 Beeper 集成 bot 或内部工具的工程师
- 熟悉 CLI 与 JSON 处理、具备基本 Matrix/Beeper 概念的技术用户
常规风险
- 认证凭证泄露：
BEEPER_TOKEN拥有完整账号权限，环境变量或配置文件泄露将导致消息被读取/发送、附件被下载 - 消息误发风险：CLI 无二次确认（除非未指定
--force），脚本错误或参数错位可能导致消息发往错误聊天 - 本地文件权限：
~/.config/beeper/config.json及下载的附件目录需严格限制访问权限 - API 变更兼容：Beeper Desktop 的本地 API 非公开契约，版本升级可能破坏 CLI 功能