beepctl

Overview

beepctl is an OpenClaw skill that provides a command line interface to the Beeper Desktop API. It lets you interact with Beeper accounts, chats, and messages from a terminal or script. The skill is designed to make Beeper automation possible without writing a full application. It includes commands for logging in, listing accounts, browsing chats, searching messages, sending new messages, and managing chat state such as read status, archive, mute, and pin.

What This Skill Is Good For

Use beepctl when you want fast access to Beeper from a shell, or when you want to automate routine messaging tasks. It is useful for triage, monitoring, and operational workflows such as searching for a message by keyword, sending a status update to a chat, or exporting a list of recent chats. Because it is a CLI wrapper around the Desktop API, it is best suited for workflows where the desktop client is available and the local API is enabled.

Requirements and Setup

The skill requires Beeper Desktop with the local API enabled. You must turn on the desktop API access in Beeper settings, and the API must be reachable from the machine running the CLI. The tool supports authentication via Beeper credentials and stores tokens to allow subsequent calls.

The OpenClaw documentation highlights the following setup steps:

• Install beepctl locally or use the provided binary.
• Enable the Beeper Desktop API in the desktop client.
• Log in through the CLI and verify the connection with a status command.

Because this is a local API, the desktop app must be running. If the app is closed or the API is disabled, commands will fail.

Core Command Groups

beepctl is organized into command groups that map directly to Beeper concepts such as accounts, chats, and messages.

Authentication and Status

• status: Confirms the CLI can reach the desktop API.
• auth login: Logs in with your Beeper credentials and saves tokens.
• auth refresh: Refreshes authentication tokens.
• auth logout: Clears the stored tokens.

These commands are used to establish and maintain access to the API. The status check is a useful health probe for automation.

Accounts

• accounts list: Lists connected accounts that Beeper manages.
• accounts status: Shows status information for accounts.

These commands help you see which networks are connected and whether any account requires attention.

Chats

• chats list: Lists chats with optional filters.
• chats info: Returns details for a specific chat.
• chats search: Searches chats by name or keyword.
• chats rename: Renames a chat.
• chats mute and chats unmute: Control notifications for a chat.
• chats pin and chats unpin: Control chat priority in the list.
• chats archive and chats unarchive: Moves chats in and out of archive.
• chats sync: Syncs chat state with the server.
• chats delete: Removes a chat.

These commands allow you to manage chat state and metadata. They are useful for automation that needs to clean up chats, organize conversations, or keep a focused chat list.

Messages

• messages list: Lists messages in a chat with optional limits.
• messages recent: Shows recent messages across chats.
• messages search: Finds messages by keyword.
• messages send: Sends a new message to a chat.
• messages react: Adds a reaction to a message.
• messages read: Marks messages as read.
• messages delete: Removes a message.
• messages download: Downloads attachments.

The messages group is the heart of automation. You can search for context, send a reply, or download attachments as part of a workflow. For example, a script can search for messages containing an incident ID and then post an update back into the same chat.

Streaming and Events

The skill also supports streaming events from Beeper, which can be useful for real time automation. By subscribing to events, you can trigger actions when new messages arrive or when chat state changes.

Typical Workflows

A common workflow is to start with status and accounts list to verify connectivity. Then list chats, find a target by name, and send a message. For triage, use messages search with a keyword or incident ID, review the matching messages, and then post a summary to the relevant chat.

Another workflow is chat maintenance. List chats and identify inactive conversations, then archive or mute them. For high priority chats, pin them and ensure they remain visible in the desktop client. If you are moving between projects, rename chats or adjust metadata to keep organization consistent.

For attachment management, use messages list to find a message with an attachment and then download it. This is useful when an automation needs to ingest files that arrive through a chat.

Data Handling and Safety

The tool interacts with real user messages. It should be used with care because it can send, delete, or archive conversations. Keep authentication tokens secure, and avoid running automated scripts on shared machines. When deleting messages or chats, verify the target identifiers first.

Because Beeper aggregates multiple networks, chat visibility depends on account permissions. If a command fails, it may be because the account is not connected or the chat is not accessible through the local API.

Troubleshooting Tips

• If status fails, confirm that the desktop app is running and the API is enabled.
• If login fails, re enter credentials and verify network connectivity.
• If a chat cannot be found, use chats list and verify names or IDs.
• If message send fails, check that the chat is writable and not archived.
• If search returns no results, broaden the query or confirm that the chat is synced.

Summary

beepctl is a CLI focused integration for Beeper Desktop API. It provides commands for authentication, accounts, chats, and messages, along with the ability to send messages, search history, manage chat state, and download attachments. When used carefully with the local API enabled, it is a powerful tool for command line messaging workflows and automation.