Beeper API CLI

beeper-api-cli

LLM-friendly wrapper around the Beeper CLI for reading and sending messages across all connected chat networks.

⚠️ CRITICAL: Message Sending Policy

🚨 NEVER SEND ANY MESSAGE WITHOUT EXPLICIT USER APPROVAL 🚨 MANDATORY PROTOCOL FOR ALL MESSAGING: ALWAYS show the complete message draft first - display full content WAIT for explicit verbal approval - "send it", "looks good", "go ahead", etc. NEVER assume permission to send - even if user says "draft a message" Apply to ALL platforms: WhatsApp, Telegram, Signal, Instagram, Twitter, Facebook, LinkedIn, etc. NO EXCEPTIONS EVER - This applies to new messages, replies, and forwards This rule is NON-NEGOTIABLE and applies to ALL beeper send commands.

Step 1: Get Your Token from Beeper Desktop

1. Open Beeper Desktop 2. Settings → Advanced → API 3. Enable API access 4. Copy the Bearer token

Step 2: Set Environment Variables

# REQUIRED: Set your token export BEEPER_TOKEN="paste-your-token-here" # OPTIONAL: Override default localhost URL export BEEPER_API_URL="http://[::1]:23373" # Default

Step 3: Use the CLI

# Use the skill wrapper (recommended) ~/clawd/skills/beeper-api-cli/beeper.sh chats list --output json # Or use the binary directly /Users/ashrafali/clawd/beeper-api-cli/beeper chats list --output json ⚠️ Important: Without setting BEEPER_TOKEN, all commands will fail with "Unauthorized" errors.

1. Beeper Desktop Must Be Running

The CLI connects to Beeper Desktop's local API server.

2. Enable API Access in Beeper Desktop

⚠️ REQUIRED: You must configure the API token in Beeper Desktop first! Open Beeper Desktop Go to Settings → Advanced → API Enable API access Generate and copy the Bearer token (Optional) Configure allowed IP addresses Default: Only localhost (127.0.0.1 / ::1) is allowed If running CLI from remote machine, add its IP address in Beeper settings

3. Set Environment Variables

You must set the token before the CLI will work: # REQUIRED: Set your token from Beeper Desktop export BEEPER_TOKEN="your-token-from-beeper-settings" # OPTIONAL: Override API URL (default: http://[::1]:23373) export BEEPER_API_URL="http://[::1]:23373" Where to get the token: Beeper Desktop → Settings → Advanced → API → Copy Bearer Token Important: ❌ The CLI will NOT work without setting BEEPER_TOKEN ⚠️ Default API URL is localhost (http://[::1]:23373) 🔒 If accessing from another machine, you must: Add that machine's IP in Beeper Desktop API settings Update BEEPER_API_URL to use the correct host IP

List All Chats

# JSON output (LLM-friendly) ~/clawd/skills/beeper-api-cli/beeper.sh chats list --output json # Human-readable text ~/clawd/skills/beeper-api-cli/beeper.sh chats list --output text # Markdown format ~/clawd/skills/beeper-api-cli/beeper.sh chats list --output markdown Example JSON output: [ { "id": "!wcn4YMCOtKUEtxYXYAq1:beeper.local", "title": "beeper-api-cli - Lion Bot", "type": "group", "network": "Telegram", "unreadCount": 15 } ]

Get Specific Chat

~/clawd/skills/beeper-api-cli/beeper.sh chats get <chat-id> --output json

List Messages from Chat

# Get last 50 messages (default) ~/clawd/skills/beeper-api-cli/beeper.sh messages list --chat-id <chat-id> # Get specific number of messages ~/clawd/skills/beeper-api-cli/beeper.sh messages list --chat-id <chat-id> --limit 20 --output json Example JSON output: [ { "id": "42113", "chatID": "!wcn4YMCOtKUEtxYXYAq1:beeper.local", "senderName": "ClawdBot", "text": "Hello world!", "timestamp": "2026-01-19T22:17:38.000Z", "isSender": true } ]

Send a Message

# ⚠️ REQUIRES USER APPROVAL FIRST - see Message Sending Policy above ~/clawd/skills/beeper-api-cli/beeper.sh send --chat-id <chat-id> --message "Your message here" Example output: { "success": true, "message_id": "msg_123", "chat_id": "!wcn4YMCOtKUEtxYXYAq1:beeper.local" }

Search Messages

# Search across all chats ~/clawd/skills/beeper-api-cli/beeper.sh search --query "keyword" --limit 10 --output json

Auto-Discover API URL

~/clawd/skills/beeper-api-cli/beeper.sh discover

Find Chat and Send Message

# 1. List chats to find the right one CHATS=$(~/clawd/skills/beeper-api-cli/beeper.sh chats list --output json) # 2. Extract chat ID (using jq) CHAT_ID=$(echo "$CHATS" | jq -r '.[] | select(.title | contains("Project")) | .id') # 3. Send message ~/clawd/skills/beeper-api-cli/beeper.sh send --chat-id "$CHAT_ID" --message "Update ready!"

Get Conversation Context

# Get recent messages for context ~/clawd/skills/beeper-api-cli/beeper.sh messages list --chat-id <chat-id> --limit 20 --output json | jq

Monitor Unread Messages

# Get all chats with unread count ~/clawd/skills/beeper-api-cli/beeper.sh chats list --output json | jq '.[] | select(.unreadCount > 0) | {title, network, unread: .unreadCount}'

JSON (Default - LLM-Optimized)

Structured data ready for parsing Perfect for programmatic use Pipe to jq for filtering

Text (Human-Readable)

ID: !wcn4YMCOtKUEtxYXYAq1:beeper.local Title: beeper-api-cli - Lion Bot Type: group Network: Telegram Unread: 15

Markdown (Documentation)

• ## beeper-api-cli - Lion Bot
• **ID**: !wcn4YMCOtKUEtxYXYAq1:beeper.local
• **Type**: group
• **Network**: Telegram
• **Unread**: 15

Chat ID Formats

Different networks use different ID formats: Telegram: !wcn4YMCOtKUEtxYXYAq1:beeper.local WhatsApp: Phone number format (e.g., 15551234567@s.whatsapp.net) Signal: Phone number (e.g., +15551234567) Instagram/Twitter: Platform-specific IDs Use chats list to discover the exact format for your chats.

Required Configuration

You MUST set these environment variables before using the CLI: BEEPER_TOKEN (Required) export BEEPER_TOKEN="your-bearer-token-from-beeper-desktop" How to get your token: Open Beeper Desktop Settings → Advanced → API Enable API access Copy the Bearer token shown in the settings Set it as an environment variable Without this token, the CLI will return "Unauthorized" errors. BEEPER_API_URL (Optional) export BEEPER_API_URL="http://[::1]:23373" # Default value Default behavior: Uses http://[::1]:23373 (localhost on IPv6) This works when running CLI on the same machine as Beeper Desktop When to change: Running CLI from a remote machine Beeper Desktop is on a different host Using a custom port If running remotely: Find the IP address of the machine running Beeper Desktop In Beeper Desktop → Settings → Advanced → API → Add the remote machine's IP to allowed list Set BEEPER_API_URL to: http://<beeper-host-ip>:23373 Example for remote access: export BEEPER_API_URL="http://192.168.1.100:23373" export BEEPER_TOKEN="your-token-here"

Skill Wrapper Behavior

The skill wrapper (beeper.sh) will: ✅ Use $BEEPER_TOKEN from environment (you must set this!) ✅ Default $BEEPER_API_URL to http://[::1]:23373 if not set ❌ Fail with error if BEEPER_TOKEN is not set

"Connection refused"

# Check if Beeper Desktop is running ps aux | grep -i beeper # Start Beeper Desktop open -a "Beeper Desktop" # macOS

"Unauthorized" or "Invalid or missing token"

This means you haven't set BEEPER_TOKEN or it's invalid. Fix: # 1. Check if token is set echo $BEEPER_TOKEN # If empty or wrong, get a new token from Beeper Desktop: # - Open Beeper Desktop # - Settings → Advanced → API # - Enable API if not already enabled # - Copy the Bearer token shown # - Set it in your environment: export BEEPER_TOKEN="paste-the-token-here" # Test it works: ~/clawd/skills/beeper-api-cli/beeper.sh chats list Important Notes: The token is generated in Beeper Desktop settings, not in this CLI You must copy it exactly from Settings → Advanced → API Without a valid token, no commands will work Tokens don't expire unless you regenerate them in Beeper settings

"Chat not found"

# List all chats to find correct ID ~/clawd/skills/beeper-api-cli/beeper.sh chats list --output text | grep -i "search-term"

Remote Access (CLI on different machine than Beeper Desktop)

• If you want to run the CLI from a different computer:
• 1. Configure Beeper Desktop to allow remote access:
• Open Beeper Desktop (on the machine running Beeper)
• Settings → Advanced → API
• Find the "Allowed IP Addresses" section
• Add the IP address of the machine running the CLI
• Example: 192.168.1.50
• 2. Set BEEPER_API_URL to point to the remote machine:
• # On the machine running the CLI:
• export BEEPER_API_URL="http://<beeper-desktop-ip>:23373"
• export BEEPER_TOKEN="your-token"
• # Example:
• export BEEPER_API_URL="http://192.168.1.100:23373"
• Default behavior (localhost only):
• Default URL: http://[::1]:23373 (IPv6 localhost)
• Only works when CLI is on same machine as Beeper Desktop
• No remote access unless you configure allowed IPs in Beeper settings

Example 1: Check Unread Messages

#!/bin/bash BEEPER="$HOME/clawd/skills/beeper-api-cli/beeper.sh" # Get chats with unread messages $BEEPER chats list --output json | \ jq -r '.[] | select(.unreadCount > 0) | "\(.title) (\(.network)): \(.unreadCount) unread"'

Example 2: Read Recent Messages

#!/bin/bash BEEPER="$HOME/clawd/skills/beeper-api-cli/beeper.sh" CHAT_ID="!wcn4YMCOtKUEtxYXYAq1:beeper.local" # Get last 10 messages in readable format $BEEPER messages list --chat-id "$CHAT_ID" --limit 10 --output text

Example 3: Search and Respond

#!/bin/bash BEEPER="$HOME/clawd/skills/beeper-api-cli/beeper.sh" # Search for mentions RESULTS=$($BEEPER search --query "@clawdbot" --limit 5 --output json) # Process results and respond (LLM integration point) echo "$RESULTS" | jq

Integration with Clawdbot

When using from Clawdbot tools, the environment variables are already configured: # Direct usage from exec tool ~/clawd/skills/beeper-api-cli/beeper.sh chats list --output json The skill wrapper handles: ✅ Auto-configuration of BEEPER_API_URL and BEEPER_TOKEN ✅ Error checking for required environment variables ✅ Clean passthrough of all CLI arguments

Binary Location

Skill wrapper: ~/clawd/skills/beeper-api-cli/beeper.sh Beeper CLI binary: /Users/ashrafali/clawd/beeper-api-cli/beeper Source code: https://github.com/nerveband/beeper-api-cli

Features

✅ Read-only and write operations (unlike other tools) ✅ LLM-optimized JSON output ✅ Human-readable text and markdown formats ✅ Auto-discovery of Beeper Desktop API ✅ Cross-platform binaries (macOS, Linux, Windows) ✅ Environment variable configuration ✅ Comprehensive error messages ✅ Unix pipeline friendly

Notes

The skill requires Beeper Desktop to be running API access must be enabled in Beeper Desktop settings Token is stored in Clawdbot config (already configured) All networks connected to Beeper are accessible (WhatsApp, Telegram, Signal, etc.) Use JSON output for LLM processing, text for human reading

Version

Latest (dev build from source)