# Send Beeper API CLI to your agent
Hand the extracted package to your coding agent with a concrete install brief instead of figuring it out manually.
## Fast path
- Download the package from Yavira.
- Extract it into a folder your agent can access.
- Paste one of the prompts below and point your agent at the extracted folder.
## Suggested prompts
### New install

```text
I downloaded a skill package from Yavira. Read SKILL.md from the extracted folder and install it by following the included instructions. Tell me what you changed and call out any manual steps you could not complete.
```
### Upgrade existing

```text
I downloaded an updated skill package from Yavira. Read SKILL.md from the extracted folder, compare it with my current installation, and upgrade it while preserving any custom configuration unless the package docs explicitly say otherwise. Summarize what changed and any follow-up checks I should run.
```
## Machine-readable fields
```json
{
  "schemaVersion": "1.0",
  "item": {
    "slug": "beeper-api-cli",
    "name": "Beeper API CLI",
    "source": "tencent",
    "type": "skill",
    "category": "开发工具",
    "sourceUrl": "https://clawhub.ai/nerveband/beeper-api-cli",
    "canonicalUrl": "https://clawhub.ai/nerveband/beeper-api-cli",
    "targetPlatform": "OpenClaw"
  },
  "install": {
    "downloadUrl": "/downloads/beeper-api-cli",
    "sourceDownloadUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=beeper-api-cli",
    "sourcePlatform": "tencent",
    "targetPlatform": "OpenClaw",
    "packageFormat": "ZIP package",
    "primaryDoc": "SKILL.md",
    "includedAssets": [
      "SKILL.md",
      "beeper.sh"
    ],
    "downloadMode": "redirect",
    "sourceHealth": {
      "source": "tencent",
      "slug": "beeper-api-cli",
      "status": "healthy",
      "reason": "direct_download_ok",
      "recommendedAction": "download",
      "checkedAt": "2026-04-30T12:00:30.576Z",
      "expiresAt": "2026-05-07T12:00:30.576Z",
      "httpStatus": 200,
      "finalUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=beeper-api-cli",
      "contentType": "application/zip",
      "probeMethod": "head",
      "details": {
        "probeUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=beeper-api-cli",
        "contentDisposition": "attachment; filename=\"beeper-api-cli-1.0.0.zip\"",
        "redirectLocation": null,
        "bodySnippet": null,
        "slug": "beeper-api-cli"
      },
      "scope": "item",
      "summary": "Item download looks usable.",
      "detail": "Yavira can redirect you to the upstream package for this item.",
      "primaryActionLabel": "Download for OpenClaw",
      "primaryActionHref": "/downloads/beeper-api-cli"
    },
    "validation": {
      "installChecklist": [
        "Use the Yavira download entry.",
        "Review SKILL.md after the package is downloaded.",
        "Confirm the extracted package contains the expected setup assets."
      ],
      "postInstallChecks": [
        "Confirm the extracted package includes the expected docs or setup files.",
        "Validate the skill or prompts are available in your target agent workspace.",
        "Capture any manual follow-up steps the agent could not complete."
      ]
    }
  },
  "links": {
    "detailUrl": "https://openagent3.xyz/skills/beeper-api-cli",
    "downloadUrl": "https://openagent3.xyz/downloads/beeper-api-cli",
    "agentUrl": "https://openagent3.xyz/skills/beeper-api-cli/agent",
    "manifestUrl": "https://openagent3.xyz/skills/beeper-api-cli/agent.json",
    "briefUrl": "https://openagent3.xyz/skills/beeper-api-cli/agent.md"
  }
}
```
## Documentation

### 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)
## Trust
- Source: tencent
- Verification: Indexed source record
- Publisher: nerveband
- Version: 1.0.0
## Source health
- Status: healthy
- Item download looks usable.
- Yavira can redirect you to the upstream package for this item.
- Health scope: item
- Reason: direct_download_ok
- Checked at: 2026-04-30T12:00:30.576Z
- Expires at: 2026-05-07T12:00:30.576Z
- Recommended action: Download for OpenClaw
## Links
- [Detail page](https://openagent3.xyz/skills/beeper-api-cli)
- [Send to Agent page](https://openagent3.xyz/skills/beeper-api-cli/agent)
- [JSON manifest](https://openagent3.xyz/skills/beeper-api-cli/agent.json)
- [Markdown brief](https://openagent3.xyz/skills/beeper-api-cli/agent.md)
- [Download page](https://openagent3.xyz/downloads/beeper-api-cli)