roadrunnerBeeper Desktop CLI for chats, messages, contacts, connect info, websocket events, search, and reminders.
Install via ClawdBot CLI:
clawdbot install johntheyoung/roadrunnerUse 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
--agent for safe agent defaults: rr --agent --enable-commands=chats,messages,status chats list--readonly to block writes: rr --readonly chats list --json--enable-commands to allowlist: rr --enable-commands=chats,messages chats list --json--envelope for structured errors: rr --json --envelope chats get "!chatid"error.hint with next-step guidance for safe retries.$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 --checkrr doctorCommon commands
rr accounts list --jsonrr capabilities --jsonrr contacts search "" "Alice" --json rr contacts search "Alice" --account-id="" --json rr contacts resolve "" "Alice" --json rr contacts resolve "Alice" --account-id="" --json rr chats list --jsonrr chats search "John" --jsonrr chats search --inbox=primary --unread-only --jsonrr chats search --last-activity-after="2024-07-01T00:00:00Z" --jsonrr chats search "Jamie" --scope=participants --jsonrr chats resolve "Jamie" --jsonrr chats get "!chatid:beeper.com" --jsonrr chats get "!chatid:beeper.com" --max-participant-count=50 --jsonrr --account="imessage:+123" chats list --jsonrr messages list "!chatid:beeper.com" --jsonrr messages list "!chatid:beeper.com" --all --max-items=1000 --jsonrr messages list "!chatid:beeper.com" --download-media --download-dir ./media --jsonrr messages search "dinner" --jsonrr messages search "dinner" --all --max-items=1000 --jsonrr messages search --sender=me --date-after="2024-07-01T00:00:00Z" --media-types=image --jsonrr messages tail "!chatid:beeper.com" --interval 2s --stop-after 30s --jsonrr messages wait --chat-id="!chatid:beeper.com" --contains "deploy" --wait-timeout 2m --jsonrr messages context "!chatid:beeper.com" "" --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.txtrr 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" --jsonrr focusrr search "dinner" --jsonrr search "dinner" --messages-all --messages-max-items=500 --messages-limit=20 --jsonrr status --jsonrr status --by-account --jsonrr unread --jsonin_groups for participant matches.Mutations (explicit user request only)
rr messages send "!chatid:beeper.com" "Hello!"rr messages edit "!chatid:beeper.com" "" "Updated text" rr messages send-file "!chatid:beeper.com" ./photo.jpg "See attached"rr chats create "" --participant "" rr chats archive "!chatid:beeper.com" / rr chats archive "!chatid:beeper.com" --unarchiverr 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 and prefer --dedupe-window.Pagination
rr chats list --all --max-items=1000 --json / rr chats search "alice" --all --max-items=1000 --jsonrr messages list "!chatid:beeper.com" --all --max-items=1000 --json / rr messages search "deploy" --all --max-items=1000 --jsonrr chats list --cursor="" --direction=before --json rr messages list "!chatid:beeper.com" --cursor="" --direction=before --json rr messages search "project" --limit=20 --jsonrr messages search "project" --cursor="" --direction=before --json rr search "dinner" --messages-limit=20 --jsonrr search "dinner" --messages-cursor="" --messages-direction=before --json Notes
~/.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 contacts resolve is strict and fails on ambiguous names; resolve by ID after contacts search when needed.--scope=participants to find by name.display_name for single chats (derived from participants).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-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.--json (and --no-input) for automation.BEEPER_URL overrides API base URL; BEEPER_TIMEOUT sets timeout in seconds.--force; --no-input/BEEPER_NO_INPUT fails without --force.--fail-if-empty on list/search commands to exit with code 1 if no results.--fields with --plain to select columns (comma-separated).! 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.AUTH_ERROR, NOT_FOUND, VALIDATION_ERROR, CONNECTION_ERROR, INTERNAL_ERROR.CONNECTION_ERROR with backoff; do not blind-retry AUTH_ERROR/VALIDATION_ERROR; refresh IDs before retrying NOT_FOUND.messages send, messages send-file, chats create, assets upload, assets upload-base64.--request-id/BEEPER_REQUEST_ID to tag envelope metadata for cross-retry attempt tracing.--dedupe-window/BEEPER_DEDUPE_WINDOW to block duplicate non-idempotent writes with repeated request IDs.make test-agent-smoke.Generated Mar 1, 2026
Use roadrunner to monitor support chat channels for specific keywords like 'issue' or 'help', automatically alerting agents when a user needs assistance. It can search messages across chats to identify unresolved tickets and draft responses for agent review, ensuring timely support without manual monitoring.
Integrate roadrunner into project workflows to send automated reminders for deadlines via Beeper, search for past discussions on tasks, and list chat participants to keep teams aligned. It helps track activity in project-related chats and can notify users of updates without manual intervention.
Leverage roadrunner to search for leads in Beeper chats by name or keywords, list recent messages to gauge interest, and set reminders for follow-ups. Sales teams can automate initial outreach drafts and monitor engagement across multiple accounts, streamlining lead management processes.
Individuals use roadrunner to manage personal chats, set reminders for important events, and search for old messages or contacts quickly. It automates routine tasks like drafting messages or archiving chats, enhancing daily communication efficiency without complex setups.
Offer roadrunner as part of a subscription-based platform that integrates Beeper Desktop with other business tools like CRM or helpdesk software. Revenue comes from monthly fees for enhanced automation features, API access, and premium support, targeting small to medium enterprises.
Provide consulting services to businesses for custom roadrunner setups, including tailored scripts for specific use cases like customer support or project management. Revenue is generated through one-time project fees and ongoing maintenance contracts, focusing on industries with high communication needs.
Distribute roadrunner as a free CLI tool with basic read-only functions, monetizing through premium features like advanced search, bulk messaging, or analytics dashboards. Revenue streams include in-app purchases for power users and enterprise licenses with additional security and support options.
💬 Integration Tip
Always use the --agent flag for safe, JSON-only output in automated workflows, and configure auth tokens locally to avoid security risks in chat logs.
iMessage/SMS CLI for listing chats, history, watch, and sending.
Use when you need to control Discord from Clawdbot via the discord tool: send messages, react, post or upload stickers, upload emojis, run polls, manage threads/pins/search, fetch permissions or member/role/channel info, or handle moderation actions in Discord DMs or channels.
Use when you need to control Slack from Clawdbot via the slack tool, including reacting to messages or pinning/unpinning items in Slack channels or DMs.
Send WhatsApp messages to other people or search/sync WhatsApp history via the wacli CLI (not for normal user chats).
Build or update the BlueBubbles external channel plugin for Clawdbot (extension package, REST send/probe, webhook inbound).
OpenClaw skill for designing Telegram Bot API workflows and command-driven conversations using direct HTTPS requests (no SDKs).