Skill: nerveband/beeper-api-cli (version 1.0.0)

--- name: beeper-api-cli description: Read and send messages via Beeper CLI. Supports WhatsApp, Telegram, Signal, Instagram, Twitter/X, LinkedIn, Facebook Messenger and more. metadata: {"clawdbot":{"emoji":"💬","os":["darwin","linux"]}} --- # 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 ```bash # 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 ```bash # 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: ```bash # 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 ```bash # 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:** ```json [ { "id": "!wcn4YMCOtKUEtxYXYAq1:beeper.local", "title": "beeper-api-cli - Lion Bot", "type": "group", "network": "Telegram", "unreadCount": 15 } ] ``` ### Get Specific Chat ```bash ~/clawd/skills/beeper-api-cli/beeper.sh chats get <chat-id> --output json ``` ### List Messages from Chat ```bash # 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:** ```json [ { "id": "42113", "chatID": "!wcn4YMCOtKUEtxYXYAq1:beeper.local", "senderName": "ClawdBot", "text": "Hello world!", "timestamp": "2026-01-19T22:17:38.000Z", "isSender": true } ] ``` ### Send a Message ```bash # ⚠️ 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:** ```json { "success": true, "message_id": "msg_123", "chat_id": "!wcn4YMCOtKUEtxYXYAq1:beeper.local" } ``` ### Search Messages ```bash # Search across all chats ~/clawd/skills/beeper-api-cli/beeper.sh search --query "keyword" --limit 10 --output json ``` ### Auto-Discover API URL ```bash ~/clawd/skills/beeper-api-cli/beeper.sh discover ``` ## LLM Workflows ### Find Chat and Send Message ```bash # 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 ```bash # 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 ```bash # 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) ```markdown ## 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., `[REDACTED_SECRET]`) - **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) ```bash export BEEPER_TOKEN=[REDACTED_SECRET] ``` **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) ```bash 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://<beeper-host-ip>:23373` Example for remote access: ```bash 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" ```bash # 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:** ```bash # 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" ```bash # 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:** ```bash # 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 ## Examples ### Example 1: Check Unread Messages ```bash #!/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 ```bash #!/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 ```bash #!/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: ```bash # 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)

path: beeper.sh
content: #!/bin/bash
# Beeper API CLI wrapper skill for Clawdbot
# Provides easy access to Beeper CLI commands with environment variables auto-configured
# Auto-starts Beeper Desktop if not running

set -e

# Beeper CLI binary location
BEEPER_CLI="/Users/ashrafali/clawd/skills/beeper-api-cli/beeper"

# Ensure environment variables are set
: ${BEEPER_API_URL:="http://[::1]:23373"}
: ${BEEPER_TOKEN:?"BEEPER_TOKEN must be set in environment"}

export BEEPER_API_URL
export BEEPER_TOKEN

# Function to check if Beeper Desktop is running
is_beeper_running() {
    pgrep -x "Beeper Desktop" > /dev/null 2>&1
}

# Function to check if Beeper API is responding
is_beeper_api_ready() {
    curl -s -f -H "Authorization: Bearer ${BEEPER_TOKEN}" \
        "${BEEPER_API_URL}/api/whoami" > /dev/null 2>&1
}

# Auto-start Beeper Desktop if not running
if ! is_beeper_running; then
    echo "⚠️  Beeper Desktop is not running. Starting it..." >&2
    open -a "Beeper Desktop"
    
    # Wait for Beeper to start (max 30 seconds)
    MAX_WAIT=30
    WAITED=0
    while [ $WAITED -lt $MAX_WAIT ]; do
        if is_beeper_running; then
            echo "✅ Beeper Desktop started. Waiting for API..." >&2
            break
        fi
        sleep 1
        WAITED=$((WAITED + 1))
    done
    
    if [ $WAITED -ge $MAX_WAIT ]; then
        echo "❌ Beeper Desktop failed to start within ${MAX_WAIT} seconds" >&2
        exit 1
    fi
fi

# Wait for API to be ready (max 15 seconds)
if ! is_beeper_api_ready; then
    echo "⏳ Waiting for Beeper API to be ready..." >&2
    MAX_API_WAIT=15
    API_WAITED=0
    while [ $API_WAITED -lt $MAX_API_WAIT ]; do
        if is_beeper_api_ready; then
            echo "✅ Beeper API is ready" >&2
            break
        fi
        sleep 1
        API_WAITED=$((API_WAITED + 1))
    done
    
    if [ $API_WAITED -ge $MAX_API_WAIT ]; then
        echo "❌ Beeper API not responding after ${MAX_API_WAIT} seconds" >&2
        echo "   Make sure API is enabled in Beeper Desktop settings" >&2
        exit 1
    fi
fi

# Execute the beeper CLI with all arguments passed through
exec "$BEEPER_CLI" "$@"


Security scan verdicts — ClawScan: suspicious | static analysis: clean | VirusTotal: clean | SkillSpector: suspicious (MEDIUM)