Beeper CLI

---

name: beeper description: Search chats, list/read messages, and send messages via Beeper Desktop using the beeper-cli. metadata: {"clawdbot":{"requires":{"bins":["beeper"]}}}

---

beeper

Use this skill when you need to search chats, list/read messages, or send messages via Beeper Desktop.

What this is

A CLI wrapper around the Beeper Desktop API. No MCP, no curl — just beeper commands.

Requires beeper-cli.

Prereqs

Beeper Desktop running with API enabled: Settings > Developers

beeper-cli installed

Env var: BEEPER_ACCESS_TOKEN set (get from Beeper Desktop: Settings > Developers > API Access Token)

Install beeper-cli

Download from releases, or build:

go install github.com/foeken/beeper-cli@latest

Commands

Accounts

beeper accounts list
beeper accounts list -o table

Chats

# List all chats (sorted by last activity)
beeper chats list
Search chats
beeper chats search --query "John"
beeper chats search --query "project" --type group
Get specific chat
beeper chats get ""
Archive
beeper chats archive ""
Create
beeper chats create --account-id "telegram:123" --participant "user1" --type dm
Reminders
beeper chats reminders create "" --time "2025-01-26T10:00:00Z"
beeper chats reminders delete ""

Messages

# List messages in a chat
beeper messages list ""
Search messages
beeper messages search --query "dinner"
beeper messages search --query "dinner" --limit 10
beeper messages search --query "meeting" --sender me
beeper messages search --query "budget" --after "2025-01-01T00:00:00Z"
beeper messages search --chat-ids "" --media-type image
Send a message
beeper messages send "" "Hello!"
Send with reply
beeper messages send "" "Thanks!" --reply-to ""
Edit a message
beeper messages edit "" "" "Corrected text"

Assets (attachments)

# Upload a file
beeper assets upload /path/to/image.png
Download an asset
beeper assets download "mxc://beeper.local/abc123" --output /path/to/save.jpg
Send with attachment (upload first)
beeper assets upload /path/to/photo.jpg  # returns uploadID
beeper messages send "" "Check this!" --upload-id ""

Other

# Focus Beeper window
beeper focus
beeper focus --chat-id ""
Global search
beeper search "important"

Output formats

beeper chats list -o json   # default
beeper chats list -o table  # human-readable

Workflow

1. Find the chat: beeper chats search --query "Name" 2. Read messages: beeper messages list "" 3. Search content: beeper messages search --query "phrase" 4. Send: beeper messages send "" "message"

Safety

Store BEEPER_ACCESS_TOKEN securely (e.g., in a password manager)

When quoting messages, include only what's needed

Confirm message text before sending unless explicit