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:

1. ALWAYS show the complete message draft first - display full content
2. WAIT for explicit verbal approval - "send it", "looks good", "go ahead", etc.
3. NEVER assume permission to send - even if user says "draft a message"
4. Apply to ALL platforms: WhatsApp, Telegram, Signal, Instagram, Twitter, Facebook, LinkedIn, etc.
5. NO EXCEPTIONS EVER - This applies to new messages, replies, and forwards

This rule is NON-NEGOTIABLE and applies to ALL beeper send commands.

Quick Start

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.

Prerequisites

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!

1. Open Beeper Desktop
2. Go to Settings → Advanced → API
3. Enable API access
4. Generate and copy the Bearer token
5. (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:
  1. Add that machine's IP in Beeper Desktop API settings
  2. Update BEEPER_API_URL to use the correct host IP

Commands

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 \x3Cchat-id> --output json

List Messages from Chat

# Get last 50 messages (default)
~/clawd/skills/beeper-api-cli/beeper.sh messages list --chat-id \x3Cchat-id>

# Get specific number of messages
~/clawd/skills/beeper-api-cli/beeper.sh messages list --chat-id \x3Cchat-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 \x3Cchat-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

LLM Workflows

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 \x3Cchat-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}'

Output Formats

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., [email protected])
• Signal: Phone number (e.g., +15551234567)
• Instagram/Twitter: Platform-specific IDs

Use chats list to discover the exact format for your chats.

Environment Variables

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:

1. Open Beeper Desktop
2. Settings → Advanced → API
3. Enable API access
4. Copy the Bearer token shown in the settings
5. 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:

1. Find the IP address of the machine running Beeper Desktop
2. In Beeper Desktop → Settings → Advanced → API → Add the remote machine's IP to allowed list
3. Set BEEPER_API_URL to: http://\x3Cbeeper-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

Troubleshooting

"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://\x3Cbeeper-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

Examples

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)