A cross-platform command-line interface for the Beeper Desktop API. Built for programmatic access to Beeper conversations with LLM-friendly output formats.

🚀 Quick Start Guide | 📚 API Documentation | 🔧 Examples

While existing tools read the Beeper SQLite database directly, this CLI interfaces with the Beeper Desktop HTTP API to provide both read and write capabilities. This enables sending messages, managing conversations, and full bidirectional communication through Beeper's unified chat platform.

• Full API Coverage: Read and write operations across all Beeper-supported chat networks
• LLM-Friendly Output: JSON, plain text, and markdown formats optimized for AI agent consumption
• Auto-Discovery: Automatically detect Beeper Desktop API endpoint when available
• Cross-Platform: Single binary for Linux, macOS, and Windows
• Self-Upgrade: Built-in upgrade command to update to the latest version
• Pipeable: Unix-friendly design for scripting and tool composition

# Download latest release for your platform
# macOS (arm64)
curl -L https://github.com/nerveband/beeper-api-cli/releases/latest/download/beeper-api-darwin-arm64 -o beeper
chmod +x beeper
sudo mv beeper /usr/local/bin/

# Linux (amd64)
curl -L https://github.com/nerveband/beeper-api-cli/releases/latest/download/beeper-api-linux-amd64 -o beeper
chmod +x beeper
sudo mv beeper /usr/local/bin/

# Or build from source
go install github.com/nerveband/beeper-api-cli@latest

# Auto-discover Beeper Desktop API
beeper discover

# Or manually configure
beeper config set-url http://localhost:23373

# List all chats
beeper chats list

# Get messages from a chat
beeper messages list --chat-id CHAT_ID

# Send a message
beeper send --chat-id CHAT_ID --message "Hello from CLI"

# Search messages
beeper search --query "important meeting"

The CLI stores configuration in ~/.beeper-api-cli/config.yaml:

api_url: http://localhost:23373
output_format: json  # json, text, markdown

Environment variables override config file settings:

Generate an API token in Beeper Desktop settings and set it as an environment variable:

export BEEPER_TOKEN="your-token-here"

Token permissions:

• read: Access messages, chats, and accounts
• write: Send messages, archive chats, set reminders

• chats list - List all conversations
• chats get - Get chat details
• messages list - Retrieve messages from a chat
• messages get - Get specific message details
• search - Search across all messages
• users get - Get user information

• send - Send new message
• react - Add reaction to message
• edit - Edit existing message
• delete - Delete message
• read - Mark messages as read

• version - Display version and build information
• upgrade - Self-upgrade to the latest release from GitHub

All commands support multiple output formats via --output flag:

# JSON (default, ideal for LLM parsing)
beeper chats list --output json

# Plain text (human-readable)
beeper chats list --output text

# Markdown (formatted for documentation)
beeper chats list --output markdown

beeper chats list | jq '.[] | {name, participants, last_message}'

MESSAGE_ID=$(beeper send --chat-id CHAT --message "Status update" --output json | jq -r '.message_id')

beeper search --query "invoice" --output markdown > invoices.md

Built with Go for:

• Fast execution
• Easy cross-compilation
• Minimal dependencies
• Single binary distribution

Uses Cobra for CLI framework and Viper for configuration management.

beeper-api-cli is designed for simplicity and minimal dependencies:

• Pure API approach - No SQLite dependencies, no keyring requirements
• Simple authentication - Manual token configuration (no OAuth flow)
• Focused feature set - Core read/write operations for programmatic access
• LLM-friendly - JSON/text/markdown output optimized for AI agents
• Single binary - Easy cross-compilation and distribution

This makes it ideal for:

• CI/CD pipelines and automation scripts
• LLM/AI agent integrations
• Environments where you want minimal dependencies
• Quick setup without browser auth flows

Different Beeper CLI tools have different strengths. Use the best tool for your use case!

Full-featured terminal client with desktop integration

• OAuth browser authentication with keyring storage
• Real-time message streaming (tail/follow mode)
• Desktop control (focus window, navigate chats, pre-fill drafts)
• Advanced features: reminders, bulk archive, inbox view
• DB backend for faster local search
• Template output and JQ integration

Best for: Interactive terminal use, power users, desktop integration

Read-only SQLite access (original inspiration for this project)

• Direct database queries
• No API dependencies

Best for: Quick local reads, offline access

Lightweight API client for automation

• Pure HTTP API (no SQLite, no keyring)
• Write operations (send, edit, react, delete)
• Simple manual token auth
• LLM-optimized JSON output
• Minimal dependencies

Best for: Automation, CI/CD, LLM integration, simple deployments

# Clone repository
git clone https://github.com/nerveband/beeper-api-cli
cd beeper-api-cli

# Install dependencies
go mod download

# Build
go build -o beeper

# Run tests
go test ./...

# Cross-compile
./build.sh

This CLI is designed for programmatic access by LLMs and automation tools.

1. Check connectivity: beeper info to verify API is reachable
2. Test permissions: beeper info --test-permissions to verify token works
3. List chats: beeper chats list -o json to get available chat IDs
4. Read messages: beeper messages list --chat-id <ID> -o json
5. Send messages: beeper send --chat-id <ID> --message "text"

Use --json-errors for machine-readable error output:

beeper chats list --json-errors 2>&1

Error JSON format:

{
  "error": "error message",
  "code": "error_code",
  "category": "auth|config|permission|not_found|network|validation|server|unknown",
  "operation": "operation_name",
  "hint": "actionable suggestion"
}

The CLI checks for updates automatically and notifies when a new version is available. To upgrade:

beeper upgrade

Use --quiet to suppress update notifications in automated environments.

Run beeper info for diagnostic information.

• Beeper Desktop application installed and running
• API server enabled (default: http://localhost:23373)

MIT

Contributions welcome. Please open an issue before starting major work.