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.

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 "<chatID>"

# Archive
beeper chats archive "<chatID>"

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

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

Messages

# List messages in a chat
beeper messages list "<chatID>"

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

# Send a message
beeper messages send "<chatID>" "Hello!"

# Send with reply
beeper messages send "<chatID>" "Thanks!" --reply-to "<messageID>"

# Edit a message
beeper messages edit "<chatID>" "<messageID>" "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 "<chatID>" "Check this!" --upload-id "<uploadID>"

Other

# Focus Beeper window
beeper focus
beeper focus --chat-id "<chatID>"

# Global search
beeper search "important"

Output formats

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

Workflow

Find the chat: beeper chats search --query "Name"
Read messages: beeper messages list "<chatID>"
Search content: beeper messages search --query "phrase"
Send: beeper messages send "<chatID>" "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