Beeper CLI

A command-line interface for the Beeper Desktop API.

Requirements

• Beeper Desktop v4.1.169 or later
• API enabled in Beeper Desktop: Settings > Developers

Installation

Download Binary

Download the latest release from the releases page.

Build from Source

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

Or clone and build:

git clone https://github.com/foeken/beeper-cli.git
cd beeper-cli
go build -o beeper .

Configuration

Set your access token as an environment variable:

export BEEPER_ACCESS_TOKEN="your-token-here"

Or pass it with each command using --token.

Get your access token from Beeper Desktop: Settings > Developers > API Access Token

Usage

# List all connected accounts
beeper accounts list

# List chats
beeper chats list

# Search chats
beeper chats search --query "project"

# Get a specific chat
beeper chats get "!abc123:beeper.local"

# Send a message
beeper messages send "!abc123:beeper.local" "Hello, world!"

# Search messages
beeper messages search --query "meeting" --sender me

# Focus Beeper Desktop on a chat
beeper focus --chat-id "!abc123:beeper.local"

# Global search
beeper search "important"

Output Formats

Use --output or -o to change the output format:

# JSON (default)
beeper accounts list --output json

# Table format
beeper accounts list --output table

Commands

Client Operations

Command	Description
beeper focus	Focus Beeper Desktop window, optionally open a chat
beeper search <query>	Global search across chats, participants, and messages

Accounts

Command	Description
beeper accounts list	List connected messaging accounts
beeper accounts contacts search <account-id> <query>	Search contacts on an account

Chats

Command	Description
beeper chats list	List all chats sorted by last activity
beeper chats get <chat-id>	Get details for a specific chat
beeper chats search	Search chats with filters
beeper chats create	Create a new chat
beeper chats archive <chat-id>	Archive a chat
beeper chats reminders create <chat-id>	Set a reminder for a chat
beeper chats reminders delete <chat-id>	Delete a reminder

Messages

Command	Description
beeper messages list <chat-id>	List messages in a chat
beeper messages search	Search messages with filters
beeper messages send <chat-id> <text>	Send a message
beeper messages edit <chat-id> <msg-id> <text>	Edit a message

Assets

Command	Description
beeper assets download <url>	Download a Matrix asset
beeper assets upload <file>	Upload a file
beeper assets upload-base64 <data>	Upload base64-encoded data

Examples

Send a Message with Reply

beeper messages send "!abc123:beeper.local" "Thanks for the info!" --reply-to "msg456"

Search Messages from a Specific Time

beeper messages search --query "budget" --after "2025-01-01T00:00:00Z"

Search for Images in a Chat

beeper messages search --chat-ids "!abc123:beeper.local" --media-type image

Create a Group Chat

beeper chats create \
  --account-id "telegram:123" \
  --participant "user1" \
  --participant "user2" \
  --type group \
  --title "Project Team"

Set a Reminder

beeper chats reminders create "!abc123:beeper.local" \
  --time "2025-01-26T10:00:00Z" \
  --dismiss-on-message

License

MIT