{
  "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": {
    "downloadMode": "redirect",
    "downloadUrl": "/downloads/beeper-api-cli",
    "sourceDownloadUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=beeper-api-cli",
    "sourcePlatform": "tencent",
    "targetPlatform": "OpenClaw",
    "installMethod": "Manual import",
    "extraction": "Extract archive",
    "prerequisites": [
      "OpenClaw"
    ],
    "packageFormat": "ZIP package",
    "includedAssets": [
      "SKILL.md",
      "beeper.sh"
    ],
    "primaryDoc": "SKILL.md",
    "quickSetup": [
      "Download the package from Yavira.",
      "Extract the archive and review SKILL.md first.",
      "Import or place the package into your OpenClaw setup."
    ],
    "agentAssist": {
      "summary": "Hand the extracted package to your coding agent with a concrete install brief instead of figuring it out manually.",
      "steps": [
        "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."
      ],
      "prompts": [
        {
          "label": "New install",
          "body": "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."
        },
        {
          "label": "Upgrade existing",
          "body": "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."
        }
      ]
    },
    "sourceHealth": {
      "source": "tencent",
      "status": "healthy",
      "reason": "direct_download_ok",
      "recommendedAction": "download",
      "checkedAt": "2026-04-23T16:43:11.935Z",
      "expiresAt": "2026-04-30T16:43:11.935Z",
      "httpStatus": 200,
      "finalUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=4claw-imageboard",
      "contentType": "application/zip",
      "probeMethod": "head",
      "details": {
        "probeUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=4claw-imageboard",
        "contentDisposition": "attachment; filename=\"4claw-imageboard-1.0.1.zip\"",
        "redirectLocation": null,
        "bodySnippet": null
      },
      "scope": "source",
      "summary": "Source download looks usable.",
      "detail": "Yavira can redirect you to the upstream package for this source.",
      "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."
      ]
    },
    "downloadPageUrl": "https://openagent3.xyz/downloads/beeper-api-cli",
    "agentPageUrl": "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"
  },
  "agentAssist": {
    "summary": "Hand the extracted package to your coding agent with a concrete install brief instead of figuring it out manually.",
    "steps": [
      "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."
    ],
    "prompts": [
      {
        "label": "New install",
        "body": "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."
      },
      {
        "label": "Upgrade existing",
        "body": "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."
      }
    ]
  },
  "documentation": {
    "source": "clawhub",
    "primaryDoc": "SKILL.md",
    "sections": [
      {
        "title": "beeper-api-cli",
        "body": "LLM-friendly wrapper around the Beeper CLI for reading and sending messages across all connected chat networks."
      },
      {
        "title": "⚠️ CRITICAL: Message Sending Policy",
        "body": "🚨 NEVER SEND ANY MESSAGE WITHOUT EXPLICIT USER APPROVAL 🚨\n\nMANDATORY PROTOCOL FOR ALL MESSAGING:\n\nALWAYS show the complete message draft first - display full content\nWAIT for explicit verbal approval - \"send it\", \"looks good\", \"go ahead\", etc.\nNEVER assume permission to send - even if user says \"draft a message\"\nApply to ALL platforms: WhatsApp, Telegram, Signal, Instagram, Twitter, Facebook, LinkedIn, etc.\nNO EXCEPTIONS EVER - This applies to new messages, replies, and forwards\n\nThis rule is NON-NEGOTIABLE and applies to ALL beeper send commands."
      },
      {
        "title": "Step 1: Get Your Token from Beeper Desktop",
        "body": "1. Open Beeper Desktop\n2. Settings → Advanced → API\n3. Enable API access\n4. Copy the Bearer token"
      },
      {
        "title": "Step 2: Set Environment Variables",
        "body": "# REQUIRED: Set your token\nexport BEEPER_TOKEN=\"paste-your-token-here\"\n\n# OPTIONAL: Override default localhost URL\nexport BEEPER_API_URL=\"http://[::1]:23373\"  # Default"
      },
      {
        "title": "Step 3: Use the CLI",
        "body": "# Use the skill wrapper (recommended)\n~/clawd/skills/beeper-api-cli/beeper.sh chats list --output json\n\n# Or use the binary directly\n/Users/ashrafali/clawd/beeper-api-cli/beeper chats list --output json\n\n⚠️ Important: Without setting BEEPER_TOKEN, all commands will fail with \"Unauthorized\" errors."
      },
      {
        "title": "1. Beeper Desktop Must Be Running",
        "body": "The CLI connects to Beeper Desktop's local API server."
      },
      {
        "title": "2. Enable API Access in Beeper Desktop",
        "body": "⚠️ REQUIRED: You must configure the API token in Beeper Desktop first!\n\nOpen Beeper Desktop\nGo to Settings → Advanced → API\nEnable API access\nGenerate and copy the Bearer token\n(Optional) Configure allowed IP addresses\n\nDefault: Only localhost (127.0.0.1 / ::1) is allowed\nIf running CLI from remote machine, add its IP address in Beeper settings"
      },
      {
        "title": "3. Set Environment Variables",
        "body": "You must set the token before the CLI will work:\n\n# REQUIRED: Set your token from Beeper Desktop\nexport BEEPER_TOKEN=\"your-token-from-beeper-settings\"\n\n# OPTIONAL: Override API URL (default: http://[::1]:23373)\nexport BEEPER_API_URL=\"http://[::1]:23373\"\n\nWhere to get the token:\n\nBeeper Desktop → Settings → Advanced → API → Copy Bearer Token\n\nImportant:\n\n❌ The CLI will NOT work without setting BEEPER_TOKEN\n⚠️ Default API URL is localhost (http://[::1]:23373)\n🔒 If accessing from another machine, you must:\n\nAdd that machine's IP in Beeper Desktop API settings\nUpdate BEEPER_API_URL to use the correct host IP"
      },
      {
        "title": "List All Chats",
        "body": "# JSON output (LLM-friendly)\n~/clawd/skills/beeper-api-cli/beeper.sh chats list --output json\n\n# Human-readable text\n~/clawd/skills/beeper-api-cli/beeper.sh chats list --output text\n\n# Markdown format\n~/clawd/skills/beeper-api-cli/beeper.sh chats list --output markdown\n\nExample JSON output:\n\n[\n  {\n    \"id\": \"!wcn4YMCOtKUEtxYXYAq1:beeper.local\",\n    \"title\": \"beeper-api-cli - Lion Bot\",\n    \"type\": \"group\",\n    \"network\": \"Telegram\",\n    \"unreadCount\": 15\n  }\n]"
      },
      {
        "title": "Get Specific Chat",
        "body": "~/clawd/skills/beeper-api-cli/beeper.sh chats get <chat-id> --output json"
      },
      {
        "title": "List Messages from Chat",
        "body": "# Get last 50 messages (default)\n~/clawd/skills/beeper-api-cli/beeper.sh messages list --chat-id <chat-id>\n\n# Get specific number of messages\n~/clawd/skills/beeper-api-cli/beeper.sh messages list --chat-id <chat-id> --limit 20 --output json\n\nExample JSON output:\n\n[\n  {\n    \"id\": \"42113\",\n    \"chatID\": \"!wcn4YMCOtKUEtxYXYAq1:beeper.local\",\n    \"senderName\": \"ClawdBot\",\n    \"text\": \"Hello world!\",\n    \"timestamp\": \"2026-01-19T22:17:38.000Z\",\n    \"isSender\": true\n  }\n]"
      },
      {
        "title": "Send a Message",
        "body": "# ⚠️ REQUIRES USER APPROVAL FIRST - see Message Sending Policy above\n~/clawd/skills/beeper-api-cli/beeper.sh send --chat-id <chat-id> --message \"Your message here\"\n\nExample output:\n\n{\n  \"success\": true,\n  \"message_id\": \"msg_123\",\n  \"chat_id\": \"!wcn4YMCOtKUEtxYXYAq1:beeper.local\"\n}"
      },
      {
        "title": "Search Messages",
        "body": "# Search across all chats\n~/clawd/skills/beeper-api-cli/beeper.sh search --query \"keyword\" --limit 10 --output json"
      },
      {
        "title": "Auto-Discover API URL",
        "body": "~/clawd/skills/beeper-api-cli/beeper.sh discover"
      },
      {
        "title": "Find Chat and Send Message",
        "body": "# 1. List chats to find the right one\nCHATS=$(~/clawd/skills/beeper-api-cli/beeper.sh chats list --output json)\n\n# 2. Extract chat ID (using jq)\nCHAT_ID=$(echo \"$CHATS\" | jq -r '.[] | select(.title | contains(\"Project\")) | .id')\n\n# 3. Send message\n~/clawd/skills/beeper-api-cli/beeper.sh send --chat-id \"$CHAT_ID\" --message \"Update ready!\""
      },
      {
        "title": "Get Conversation Context",
        "body": "# Get recent messages for context\n~/clawd/skills/beeper-api-cli/beeper.sh messages list --chat-id <chat-id> --limit 20 --output json | jq"
      },
      {
        "title": "Monitor Unread Messages",
        "body": "# Get all chats with unread count\n~/clawd/skills/beeper-api-cli/beeper.sh chats list --output json | jq '.[] | select(.unreadCount > 0) | {title, network, unread: .unreadCount}'"
      },
      {
        "title": "JSON (Default - LLM-Optimized)",
        "body": "Structured data ready for parsing\nPerfect for programmatic use\nPipe to jq for filtering"
      },
      {
        "title": "Text (Human-Readable)",
        "body": "ID: !wcn4YMCOtKUEtxYXYAq1:beeper.local\nTitle: beeper-api-cli - Lion Bot\nType: group\nNetwork: Telegram\nUnread: 15"
      },
      {
        "title": "Markdown (Documentation)",
        "body": "## beeper-api-cli - Lion Bot\n\n- **ID**: !wcn4YMCOtKUEtxYXYAq1:beeper.local\n- **Type**: group\n- **Network**: Telegram\n- **Unread**: 15"
      },
      {
        "title": "Chat ID Formats",
        "body": "Different networks use different ID formats:\n\nTelegram: !wcn4YMCOtKUEtxYXYAq1:beeper.local\nWhatsApp: Phone number format (e.g., 15551234567@s.whatsapp.net)\nSignal: Phone number (e.g., +15551234567)\nInstagram/Twitter: Platform-specific IDs\n\nUse chats list to discover the exact format for your chats."
      },
      {
        "title": "Required Configuration",
        "body": "You MUST set these environment variables before using the CLI:\n\nBEEPER_TOKEN (Required)\n\nexport BEEPER_TOKEN=\"your-bearer-token-from-beeper-desktop\"\n\nHow to get your token:\n\nOpen Beeper Desktop\nSettings → Advanced → API\nEnable API access\nCopy the Bearer token shown in the settings\nSet it as an environment variable\n\nWithout this token, the CLI will return \"Unauthorized\" errors.\n\nBEEPER_API_URL (Optional)\n\nexport BEEPER_API_URL=\"http://[::1]:23373\"  # Default value\n\nDefault behavior:\n\nUses http://[::1]:23373 (localhost on IPv6)\nThis works when running CLI on the same machine as Beeper Desktop\n\nWhen to change:\n\nRunning CLI from a remote machine\nBeeper Desktop is on a different host\nUsing a custom port\n\nIf running remotely:\n\nFind the IP address of the machine running Beeper Desktop\nIn Beeper Desktop → Settings → Advanced → API → Add the remote machine's IP to allowed list\nSet BEEPER_API_URL to: http://<beeper-host-ip>:23373\n\nExample for remote access:\n\nexport BEEPER_API_URL=\"http://192.168.1.100:23373\"\nexport BEEPER_TOKEN=\"your-token-here\""
      },
      {
        "title": "Skill Wrapper Behavior",
        "body": "The skill wrapper (beeper.sh) will:\n\n✅ Use $BEEPER_TOKEN from environment (you must set this!)\n✅ Default $BEEPER_API_URL to http://[::1]:23373 if not set\n❌ Fail with error if BEEPER_TOKEN is not set"
      },
      {
        "title": "\"Connection refused\"",
        "body": "# Check if Beeper Desktop is running\nps aux | grep -i beeper\n\n# Start Beeper Desktop\nopen -a \"Beeper Desktop\"  # macOS"
      },
      {
        "title": "\"Unauthorized\" or \"Invalid or missing token\"",
        "body": "This means you haven't set BEEPER_TOKEN or it's invalid.\n\nFix:\n\n# 1. Check if token is set\necho $BEEPER_TOKEN\n\n# If empty or wrong, get a new token from Beeper Desktop:\n# - Open Beeper Desktop\n# - Settings → Advanced → API\n# - Enable API if not already enabled\n# - Copy the Bearer token shown\n# - Set it in your environment:\n\nexport BEEPER_TOKEN=\"paste-the-token-here\"\n\n# Test it works:\n~/clawd/skills/beeper-api-cli/beeper.sh chats list\n\nImportant Notes:\n\nThe token is generated in Beeper Desktop settings, not in this CLI\nYou must copy it exactly from Settings → Advanced → API\nWithout a valid token, no commands will work\nTokens don't expire unless you regenerate them in Beeper settings"
      },
      {
        "title": "\"Chat not found\"",
        "body": "# List all chats to find correct ID\n~/clawd/skills/beeper-api-cli/beeper.sh chats list --output text | grep -i \"search-term\""
      },
      {
        "title": "Remote Access (CLI on different machine than Beeper Desktop)",
        "body": "If you want to run the CLI from a different computer:\n\n1. Configure Beeper Desktop to allow remote access:\n\n- Open Beeper Desktop (on the machine running Beeper)\n- Settings → Advanced → API\n- Find the \"Allowed IP Addresses\" section\n- Add the IP address of the machine running the CLI\n- Example: 192.168.1.50\n\n2. Set BEEPER_API_URL to point to the remote machine:\n\n# On the machine running the CLI:\nexport BEEPER_API_URL=\"http://<beeper-desktop-ip>:23373\"\nexport BEEPER_TOKEN=\"your-token\"\n\n# Example:\nexport BEEPER_API_URL=\"http://192.168.1.100:23373\"\n\nDefault behavior (localhost only):\n\nDefault URL: http://[::1]:23373 (IPv6 localhost)\nOnly works when CLI is on same machine as Beeper Desktop\nNo remote access unless you configure allowed IPs in Beeper settings"
      },
      {
        "title": "Example 1: Check Unread Messages",
        "body": "#!/bin/bash\nBEEPER=\"$HOME/clawd/skills/beeper-api-cli/beeper.sh\"\n\n# Get chats with unread messages\n$BEEPER chats list --output json | \\\n  jq -r '.[] | select(.unreadCount > 0) | \"\\(.title) (\\(.network)): \\(.unreadCount) unread\"'"
      },
      {
        "title": "Example 2: Read Recent Messages",
        "body": "#!/bin/bash\nBEEPER=\"$HOME/clawd/skills/beeper-api-cli/beeper.sh\"\nCHAT_ID=\"!wcn4YMCOtKUEtxYXYAq1:beeper.local\"\n\n# Get last 10 messages in readable format\n$BEEPER messages list --chat-id \"$CHAT_ID\" --limit 10 --output text"
      },
      {
        "title": "Example 3: Search and Respond",
        "body": "#!/bin/bash\nBEEPER=\"$HOME/clawd/skills/beeper-api-cli/beeper.sh\"\n\n# Search for mentions\nRESULTS=$($BEEPER search --query \"@clawdbot\" --limit 5 --output json)\n\n# Process results and respond (LLM integration point)\necho \"$RESULTS\" | jq"
      },
      {
        "title": "Integration with Clawdbot",
        "body": "When using from Clawdbot tools, the environment variables are already configured:\n\n# Direct usage from exec tool\n~/clawd/skills/beeper-api-cli/beeper.sh chats list --output json\n\nThe skill wrapper handles:\n\n✅ Auto-configuration of BEEPER_API_URL and BEEPER_TOKEN\n✅ Error checking for required environment variables\n✅ Clean passthrough of all CLI arguments"
      },
      {
        "title": "Binary Location",
        "body": "Skill wrapper: ~/clawd/skills/beeper-api-cli/beeper.sh\nBeeper CLI binary: /Users/ashrafali/clawd/beeper-api-cli/beeper\nSource code: https://github.com/nerveband/beeper-api-cli"
      },
      {
        "title": "Features",
        "body": "✅ Read-only and write operations (unlike other tools)\n✅ LLM-optimized JSON output\n✅ Human-readable text and markdown formats\n✅ Auto-discovery of Beeper Desktop API\n✅ Cross-platform binaries (macOS, Linux, Windows)\n✅ Environment variable configuration\n✅ Comprehensive error messages\n✅ Unix pipeline friendly"
      },
      {
        "title": "Notes",
        "body": "The skill requires Beeper Desktop to be running\nAPI access must be enabled in Beeper Desktop settings\nToken is stored in Clawdbot config (already configured)\nAll networks connected to Beeper are accessible (WhatsApp, Telegram, Signal, etc.)\nUse JSON output for LLM processing, text for human reading"
      },
      {
        "title": "Version",
        "body": "Latest (dev build from source)"
      }
    ],
    "body": "beeper-api-cli\n\nLLM-friendly wrapper around the Beeper CLI for reading and sending messages across all connected chat networks.\n\n⚠️ CRITICAL: Message Sending Policy\n\n🚨 NEVER SEND ANY MESSAGE WITHOUT EXPLICIT USER APPROVAL 🚨\n\nMANDATORY PROTOCOL FOR ALL MESSAGING:\n\nALWAYS show the complete message draft first - display full content\nWAIT for explicit verbal approval - \"send it\", \"looks good\", \"go ahead\", etc.\nNEVER assume permission to send - even if user says \"draft a message\"\nApply to ALL platforms: WhatsApp, Telegram, Signal, Instagram, Twitter, Facebook, LinkedIn, etc.\nNO EXCEPTIONS EVER - This applies to new messages, replies, and forwards\n\nThis rule is NON-NEGOTIABLE and applies to ALL beeper send commands.\n\nQuick Start\nStep 1: Get Your Token from Beeper Desktop\n1. Open Beeper Desktop\n2. Settings → Advanced → API\n3. Enable API access\n4. Copy the Bearer token\n\nStep 2: Set Environment Variables\n# REQUIRED: Set your token\nexport BEEPER_TOKEN=\"paste-your-token-here\"\n\n# OPTIONAL: Override default localhost URL\nexport BEEPER_API_URL=\"http://[::1]:23373\"  # Default\n\nStep 3: Use the CLI\n# Use the skill wrapper (recommended)\n~/clawd/skills/beeper-api-cli/beeper.sh chats list --output json\n\n# Or use the binary directly\n/Users/ashrafali/clawd/beeper-api-cli/beeper chats list --output json\n\n\n⚠️ Important: Without setting BEEPER_TOKEN, all commands will fail with \"Unauthorized\" errors.\n\nPrerequisites\n1. Beeper Desktop Must Be Running\n\nThe CLI connects to Beeper Desktop's local API server.\n\n2. Enable API Access in Beeper Desktop\n\n⚠️ REQUIRED: You must configure the API token in Beeper Desktop first!\n\nOpen Beeper Desktop\nGo to Settings → Advanced → API\nEnable API access\nGenerate and copy the Bearer token\n(Optional) Configure allowed IP addresses\nDefault: Only localhost (127.0.0.1 / ::1) is allowed\nIf running CLI from remote machine, add its IP address in Beeper settings\n3. Set Environment Variables\n\nYou must set the token before the CLI will work:\n\n# REQUIRED: Set your token from Beeper Desktop\nexport BEEPER_TOKEN=\"your-token-from-beeper-settings\"\n\n# OPTIONAL: Override API URL (default: http://[::1]:23373)\nexport BEEPER_API_URL=\"http://[::1]:23373\"\n\n\nWhere to get the token:\n\nBeeper Desktop → Settings → Advanced → API → Copy Bearer Token\n\nImportant:\n\n❌ The CLI will NOT work without setting BEEPER_TOKEN\n⚠️ Default API URL is localhost (http://[::1]:23373)\n🔒 If accessing from another machine, you must:\nAdd that machine's IP in Beeper Desktop API settings\nUpdate BEEPER_API_URL to use the correct host IP\nCommands\nList All Chats\n# JSON output (LLM-friendly)\n~/clawd/skills/beeper-api-cli/beeper.sh chats list --output json\n\n# Human-readable text\n~/clawd/skills/beeper-api-cli/beeper.sh chats list --output text\n\n# Markdown format\n~/clawd/skills/beeper-api-cli/beeper.sh chats list --output markdown\n\n\nExample JSON output:\n\n[\n  {\n    \"id\": \"!wcn4YMCOtKUEtxYXYAq1:beeper.local\",\n    \"title\": \"beeper-api-cli - Lion Bot\",\n    \"type\": \"group\",\n    \"network\": \"Telegram\",\n    \"unreadCount\": 15\n  }\n]\n\nGet Specific Chat\n~/clawd/skills/beeper-api-cli/beeper.sh chats get <chat-id> --output json\n\nList Messages from Chat\n# Get last 50 messages (default)\n~/clawd/skills/beeper-api-cli/beeper.sh messages list --chat-id <chat-id>\n\n# Get specific number of messages\n~/clawd/skills/beeper-api-cli/beeper.sh messages list --chat-id <chat-id> --limit 20 --output json\n\n\nExample JSON output:\n\n[\n  {\n    \"id\": \"42113\",\n    \"chatID\": \"!wcn4YMCOtKUEtxYXYAq1:beeper.local\",\n    \"senderName\": \"ClawdBot\",\n    \"text\": \"Hello world!\",\n    \"timestamp\": \"2026-01-19T22:17:38.000Z\",\n    \"isSender\": true\n  }\n]\n\nSend a Message\n# ⚠️ REQUIRES USER APPROVAL FIRST - see Message Sending Policy above\n~/clawd/skills/beeper-api-cli/beeper.sh send --chat-id <chat-id> --message \"Your message here\"\n\n\nExample output:\n\n{\n  \"success\": true,\n  \"message_id\": \"msg_123\",\n  \"chat_id\": \"!wcn4YMCOtKUEtxYXYAq1:beeper.local\"\n}\n\nSearch Messages\n# Search across all chats\n~/clawd/skills/beeper-api-cli/beeper.sh search --query \"keyword\" --limit 10 --output json\n\nAuto-Discover API URL\n~/clawd/skills/beeper-api-cli/beeper.sh discover\n\nLLM Workflows\nFind Chat and Send Message\n# 1. List chats to find the right one\nCHATS=$(~/clawd/skills/beeper-api-cli/beeper.sh chats list --output json)\n\n# 2. Extract chat ID (using jq)\nCHAT_ID=$(echo \"$CHATS\" | jq -r '.[] | select(.title | contains(\"Project\")) | .id')\n\n# 3. Send message\n~/clawd/skills/beeper-api-cli/beeper.sh send --chat-id \"$CHAT_ID\" --message \"Update ready!\"\n\nGet Conversation Context\n# Get recent messages for context\n~/clawd/skills/beeper-api-cli/beeper.sh messages list --chat-id <chat-id> --limit 20 --output json | jq\n\nMonitor Unread Messages\n# Get all chats with unread count\n~/clawd/skills/beeper-api-cli/beeper.sh chats list --output json | jq '.[] | select(.unreadCount > 0) | {title, network, unread: .unreadCount}'\n\nOutput Formats\nJSON (Default - LLM-Optimized)\nStructured data ready for parsing\nPerfect for programmatic use\nPipe to jq for filtering\nText (Human-Readable)\nID: !wcn4YMCOtKUEtxYXYAq1:beeper.local\nTitle: beeper-api-cli - Lion Bot\nType: group\nNetwork: Telegram\nUnread: 15\n\nMarkdown (Documentation)\n## beeper-api-cli - Lion Bot\n\n- **ID**: !wcn4YMCOtKUEtxYXYAq1:beeper.local\n- **Type**: group\n- **Network**: Telegram\n- **Unread**: 15\n\nChat ID Formats\n\nDifferent networks use different ID formats:\n\nTelegram: !wcn4YMCOtKUEtxYXYAq1:beeper.local\nWhatsApp: Phone number format (e.g., 15551234567@s.whatsapp.net)\nSignal: Phone number (e.g., +15551234567)\nInstagram/Twitter: Platform-specific IDs\n\nUse chats list to discover the exact format for your chats.\n\nEnvironment Variables\nRequired Configuration\n\nYou MUST set these environment variables before using the CLI:\n\nBEEPER_TOKEN (Required)\nexport BEEPER_TOKEN=\"your-bearer-token-from-beeper-desktop\"\n\n\nHow to get your token:\n\nOpen Beeper Desktop\nSettings → Advanced → API\nEnable API access\nCopy the Bearer token shown in the settings\nSet it as an environment variable\n\nWithout this token, the CLI will return \"Unauthorized\" errors.\n\nBEEPER_API_URL (Optional)\nexport BEEPER_API_URL=\"http://[::1]:23373\"  # Default value\n\n\nDefault behavior:\n\nUses http://[::1]:23373 (localhost on IPv6)\nThis works when running CLI on the same machine as Beeper Desktop\n\nWhen to change:\n\nRunning CLI from a remote machine\nBeeper Desktop is on a different host\nUsing a custom port\n\nIf running remotely:\n\nFind the IP address of the machine running Beeper Desktop\nIn Beeper Desktop → Settings → Advanced → API → Add the remote machine's IP to allowed list\nSet BEEPER_API_URL to: http://<beeper-host-ip>:23373\n\nExample for remote access:\n\nexport BEEPER_API_URL=\"http://192.168.1.100:23373\"\nexport BEEPER_TOKEN=\"your-token-here\"\n\nSkill Wrapper Behavior\n\nThe skill wrapper (beeper.sh) will:\n\n✅ Use $BEEPER_TOKEN from environment (you must set this!)\n✅ Default $BEEPER_API_URL to http://[::1]:23373 if not set\n❌ Fail with error if BEEPER_TOKEN is not set\nTroubleshooting\n\"Connection refused\"\n# Check if Beeper Desktop is running\nps aux | grep -i beeper\n\n# Start Beeper Desktop\nopen -a \"Beeper Desktop\"  # macOS\n\n\"Unauthorized\" or \"Invalid or missing token\"\n\nThis means you haven't set BEEPER_TOKEN or it's invalid.\n\nFix:\n\n# 1. Check if token is set\necho $BEEPER_TOKEN\n\n# If empty or wrong, get a new token from Beeper Desktop:\n# - Open Beeper Desktop\n# - Settings → Advanced → API\n# - Enable API if not already enabled\n# - Copy the Bearer token shown\n# - Set it in your environment:\n\nexport BEEPER_TOKEN=\"paste-the-token-here\"\n\n# Test it works:\n~/clawd/skills/beeper-api-cli/beeper.sh chats list\n\n\nImportant Notes:\n\nThe token is generated in Beeper Desktop settings, not in this CLI\nYou must copy it exactly from Settings → Advanced → API\nWithout a valid token, no commands will work\nTokens don't expire unless you regenerate them in Beeper settings\n\"Chat not found\"\n# List all chats to find correct ID\n~/clawd/skills/beeper-api-cli/beeper.sh chats list --output text | grep -i \"search-term\"\n\nRemote Access (CLI on different machine than Beeper Desktop)\n\nIf you want to run the CLI from a different computer:\n\n1. Configure Beeper Desktop to allow remote access:\n\n- Open Beeper Desktop (on the machine running Beeper)\n- Settings → Advanced → API\n- Find the \"Allowed IP Addresses\" section\n- Add the IP address of the machine running the CLI\n- Example: 192.168.1.50\n\n\n2. Set BEEPER_API_URL to point to the remote machine:\n\n# On the machine running the CLI:\nexport BEEPER_API_URL=\"http://<beeper-desktop-ip>:23373\"\nexport BEEPER_TOKEN=\"your-token\"\n\n# Example:\nexport BEEPER_API_URL=\"http://192.168.1.100:23373\"\n\n\nDefault behavior (localhost only):\n\nDefault URL: http://[::1]:23373 (IPv6 localhost)\nOnly works when CLI is on same machine as Beeper Desktop\nNo remote access unless you configure allowed IPs in Beeper settings\nExamples\nExample 1: Check Unread Messages\n#!/bin/bash\nBEEPER=\"$HOME/clawd/skills/beeper-api-cli/beeper.sh\"\n\n# Get chats with unread messages\n$BEEPER chats list --output json | \\\n  jq -r '.[] | select(.unreadCount > 0) | \"\\(.title) (\\(.network)): \\(.unreadCount) unread\"'\n\nExample 2: Read Recent Messages\n#!/bin/bash\nBEEPER=\"$HOME/clawd/skills/beeper-api-cli/beeper.sh\"\nCHAT_ID=\"!wcn4YMCOtKUEtxYXYAq1:beeper.local\"\n\n# Get last 10 messages in readable format\n$BEEPER messages list --chat-id \"$CHAT_ID\" --limit 10 --output text\n\nExample 3: Search and Respond\n#!/bin/bash\nBEEPER=\"$HOME/clawd/skills/beeper-api-cli/beeper.sh\"\n\n# Search for mentions\nRESULTS=$($BEEPER search --query \"@clawdbot\" --limit 5 --output json)\n\n# Process results and respond (LLM integration point)\necho \"$RESULTS\" | jq\n\nIntegration with Clawdbot\n\nWhen using from Clawdbot tools, the environment variables are already configured:\n\n# Direct usage from exec tool\n~/clawd/skills/beeper-api-cli/beeper.sh chats list --output json\n\n\nThe skill wrapper handles:\n\n✅ Auto-configuration of BEEPER_API_URL and BEEPER_TOKEN\n✅ Error checking for required environment variables\n✅ Clean passthrough of all CLI arguments\nBinary Location\nSkill wrapper: ~/clawd/skills/beeper-api-cli/beeper.sh\nBeeper CLI binary: /Users/ashrafali/clawd/beeper-api-cli/beeper\nSource code: https://github.com/nerveband/beeper-api-cli\nFeatures\n\n✅ Read-only and write operations (unlike other tools)\n✅ LLM-optimized JSON output\n✅ Human-readable text and markdown formats\n✅ Auto-discovery of Beeper Desktop API\n✅ Cross-platform binaries (macOS, Linux, Windows)\n✅ Environment variable configuration\n✅ Comprehensive error messages\n✅ Unix pipeline friendly\n\nNotes\nThe skill requires Beeper Desktop to be running\nAPI access must be enabled in Beeper Desktop settings\nToken is stored in Clawdbot config (already configured)\nAll networks connected to Beeper are accessible (WhatsApp, Telegram, Signal, etc.)\nUse JSON output for LLM processing, text for human reading\nVersion\n\nLatest (dev build from source)"
  },
  "trust": {
    "sourceLabel": "tencent",
    "provenanceUrl": "https://clawhub.ai/nerveband/beeper-api-cli",
    "publisherUrl": "https://clawhub.ai/nerveband/beeper-api-cli",
    "owner": "nerveband",
    "version": "1.0.0",
    "license": null,
    "verificationStatus": "Indexed source record"
  },
  "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"
  }
}