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 "\x3CchatID>"

# Archive
beeper chats archive "\x3CchatID>"

# Create
beeper chats create --account-id "telegram:123" --participant "user1" --type dm

# Reminders
beeper chats reminders create "\x3CchatID>" --time "2025-01-26T10:00:00Z"
beeper chats reminders delete "\x3CchatID>"

Messages

# List messages in a chat
beeper messages list "\x3CchatID>"

# 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 "\x3CchatID>" --media-type image

# Send a message
beeper messages send "\x3CchatID>" "Hello!"

# Send with reply
beeper messages send "\x3CchatID>" "Thanks!" --reply-to "\x3CmessageID>"

# Edit a message
beeper messages edit "\x3CchatID>" "\x3CmessageID>" "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 "\x3CchatID>" "Check this!" --upload-id "\x3CuploadID>"

Other

# Focus Beeper window
beeper focus
beeper focus --chat-id "\x3CchatID>"

# 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 "\x3CchatID>"
3. Search content: beeper messages search --query "phrase"
4. Send: beeper messages send "\x3CchatID>" "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