← Back to Skills Marketplace
2345
Downloads
1
Stars
2
Active Installs
2
Versions
Install in OpenClaw
/install beepctl
Description
Use when sending messages, searching chats, or managing conversations across messaging platforms (Telegram, WhatsApp, Slack, iMessage, etc.) via Beeper Desktop API.
README (SKILL.md)
beepctl
CLI for Beeper Desktop API — unified messaging from your terminal. Control all your messaging platforms (Telegram, WhatsApp, Slack, iMessage, etc.) through one interface.
📖 Setup & installation: see GitHub repo
Quick Start
beepctl accounts # List connected accounts
beepctl chats list # List recent chats
beepctl chats list --search "John" # Find a chat
beepctl search "meeting" --after "1d ago" # Search messages
beepctl send \x3Cchat-id> "Hello!" # Send a message
Commands
Auth Management
beepctl auth show # Check auth status and token
beepctl auth set \x3Ctoken> # Set API token
beepctl auth clear # Clear saved token
Accounts
beepctl accounts # List all connected accounts
Browse Chats
beepctl chats list # List inbox (non-archived)
beepctl chats list --limit 20 # Limit results
beepctl chats list --search "John" # Filter by name
beepctl chats list --inbox archive # Archived chats only
beepctl chats list --inbox low-priority # Low-priority chats
beepctl chats list --inbox all # All chats
beepctl chats list --type group # Filter by type (single/group/any)
beepctl chats list --unread-only # Unread chats only
beepctl chats list --activity-after "1d ago" # Recent activity filter
beepctl chats show \x3Cchat-id> # Detailed chat info with participants
beepctl chats create \x3Caccount> \x3Cusers...> # Create new chat
Inbox filters: primary (default), archive, low-priority, all
List Messages
beepctl messages \x3Cchat-id> # Recent messages from a chat
beepctl messages \x3Cchat-id> --limit 10 # Limit results
beepctl messages work --after "1d ago" # Use alias + time filter
beepctl messages \x3Cchat-id> --before "1h ago" # Messages before a time
Search Messages
beepctl search "query" # Search across all chats
beepctl search "query" --limit 10 # Limit results
beepctl search "meeting" --after "1d ago" # Time filter
beepctl search "hello" --chat work # Filter by chat/alias
beepctl search "files" --media file # Filter by media type
beepctl search "dm" --chat-type single # Filter by chat type
beepctl search "update" --sender others # Filter by sender (me/others)
beepctl search "msg" --account \x3Cid> # Filter by account
beepctl search "todo" --include-low-priority # Include low-priority chats
beepctl search "important" --exclude-muted # Exclude muted chats
Combine filters:
beepctl search "deploy" --chat work --sender others --after "1d ago" --media link
beepctl search "hello" --chat work family # Multiple chats (space-separated)
beepctl search "test" --chat id1,id2,id3 # Multiple chats (comma-separated)
Time formats: 1h ago, 2d ago, 3w ago, 1mo ago, yesterday, today
Media types: any, video, image, link, file
Aliases
Create shortcuts for frequently used chat IDs:
beepctl alias list # List all aliases
beepctl alias add work \x3Cchat-id> # Create alias
beepctl alias show work # Show alias value
beepctl alias remove work # Remove alias
beepctl send work "Using alias!" # Use alias in any command
Archive Chats
beepctl archive \x3Cchat-id> # Archive a chat
beepctl archive \x3Cchat-id> --unarchive # Unarchive
beepctl archive work # Use alias
beepctl archive \x3Cchat-id> --quiet # No confirmation message
Send Messages
⚠️ NEVER send messages without explicit user approval first! Always show the message content and recipient, then ask for confirmation.
beepctl send \x3Cchat-id> "Hello!" # Send message
beepctl send myself "Quick note" # Send to self
beepctl send \x3Cchat-id> "Reply" --reply-to \x3Cmsg-id> # Reply to message
beepctl send \x3Cchat-id> "msg" --quiet # No confirmation output
Focus (Bring to Foreground)
beepctl focus # Bring Beeper to foreground
beepctl focus \x3Cchat-id> # Open a specific chat
beepctl focus \x3Cchat-id> -m \x3Cmsg-id> # Jump to specific message
beepctl focus \x3Cchat-id> -d "draft" # Pre-fill draft text
beepctl focus \x3Cchat-id> -a /path/file # Pre-fill draft attachment
Send Media
beepctl send only supports text. To send media, use focus with draft:
beepctl focus \x3Cchat-id> -a /path/to/image.png -d "Caption"
# Then press Enter in Beeper to send
Contacts
beepctl contacts search \x3Caccount> \x3Cquery> # Search contacts on an account
Download Attachments
beepctl download \x3Cmxc-url> # Download attachment (mxc:// URLs)
beepctl download \x3Cmxc-url> -o /path # Save to specific path
Reminders
beepctl reminders set \x3Cchat> 30m # Remind in 30 minutes
beepctl reminders set \x3Cchat> 1h # Remind in 1 hour
beepctl reminders set \x3Cchat> 2d # Remind in 2 days
beepctl reminders set \x3Cchat> tomorrow # Remind tomorrow
beepctl reminders clear \x3Cchat> # Clear reminder
Tips
- Chat IDs look like:
!gZ42vWzDxl8V0sZXWBgO:beeper.local - Use aliases to avoid typing long chat IDs
- The special alias
myselfsends to your own chat
Usage Guidance
This skill is internally consistent with its purpose, but before installing or enabling it: 1) Confirm the 'beepctl' binary you install comes from the official project (review the GitHub repo and the npm package if you use npm). 2) Check how beepctl stores the API token (where on disk) and avoid supplying long-lived tokens unless you trust the host. 3) Be aware that commands can read and write local files (attachments, downloads) — don't allow the agent to run the skill autonomously if you won't review its actions. 4) If you want extra safety, require explicit user approval for any send/focus/download operations or disable autonomous invocation for this skill.
Capability Analysis
Type: OpenClaw Skill
Name: beepctl
Version: 0.1.4
The skill bundle is classified as suspicious due to its inherent capabilities that, if exploited via prompt injection against the AI agent, could lead to data exfiltration or arbitrary file writes. Specifically, the `beepctl focus -a /path/file` command allows reading arbitrary local files and preparing them as attachments, and `beepctl download <mxc-url> -o /path` allows writing downloaded files to arbitrary local paths. While the `SKILL.md` explicitly warns against sending messages without user approval, the underlying capabilities to access local files and send messages to external platforms (Telegram, WhatsApp, etc.) present a significant risk if the agent's instructions are overridden.
Capability Assessment
Purpose & Capability
Name/description align with the actual requirements: the skill only needs the 'beepctl' CLI and the SKILL.md documents CLI commands for Beeper Desktop API (sending/searching/managing chats). There are no unrelated env vars, credentials, or config paths requested.
Instruction Scope
The SKILL.md is strictly a command reference for invoking beepctl. It includes legitimate operations like auth management, listing/searching chats, downloading attachments, and pre-filling drafts. These instructions necessarily reference local file paths (for attachments/download targets) and stored auth tokens; that is expected for messaging, but it means the agent may read or write files when performing those actions. The documentation also explicitly instructs to get user confirmation before sending messages, which reduces risk.
Install Mechanism
This is an instruction-only skill (no install spec / no code files) so nothing will be written to disk by the skill itself. The SKILL.md metadata suggests installing 'beepctl' via npm globally, but the registry metadata lists no install spec — a minor inconsistency. The install suggestion references a public npm package; verify the package and source before installing.
Credentials
The skill declares no required environment variables or credentials. The CLI exposes an 'auth set <token>' command for configuring a token, but the skill does not demand secrets via env vars or other unrelated credentials, which is proportionate to its purpose.
Persistence & Privilege
always:false (no forced inclusion). The skill can be invoked autonomously by the agent (platform default). Because the skill can send messages and access local files, you should be careful about allowing autonomous runs — though the SKILL.md explicitly requires user confirmation before sending messages.
How to Use
- Make sure OpenClaw is installed (local or Docker)
- Run the install command in chat:
/install beepctl - After installation, invoke the skill by name or use
/beepctl - Provide required inputs per the skill's parameter spec and get structured output
Version History
v0.1.4
- Documentation was streamlined by moving setup and installation instructions to the GitHub repository and referencing it directly.
- No changes were made to functionality or commands; only SKILL.md documentation was affected.
- The skill is now quicker to scan, with a simpler Quick Start and a shorter intro.
v0.1.3
Initial release of beepctl SKILL — a unified CLI for managing all your messaging platforms via the Beeper Desktop API.
- Send messages, search chats, and manage conversations (Telegram, WhatsApp, Slack, iMessage, etc.) from the terminal.
- Supports listing accounts/chats, searching messages with flexible filters, and sending/archiving messages.
- Includes alias management for fast access to frequent chats.
- Enables focus and draft pre-fill actions in Beeper Desktop.
- Provides tools for downloading attachments, setting reminders, and searching contacts.
- Flexible install options: npm, npx, or from source.
- Clear setup and environment variable configuration for authentication.
https://github.com/blqke/beepctl
Metadata
Frequently Asked Questions
What is beepctl?
Use when sending messages, searching chats, or managing conversations across messaging platforms (Telegram, WhatsApp, Slack, iMessage, etc.) via Beeper Desktop API. It is an AI Agent Skill for Claude Code / OpenClaw, with 2345 downloads so far.
How do I install beepctl?
Run "/install beepctl" in the OpenClaw or Claude Code chat to install it in one step — no extra setup required.
Is beepctl free?
Yes, beepctl is completely free (open-source). You can download, install and use it at no cost.
Which platforms does beepctl support?
beepctl is cross-platform and runs anywhere OpenClaw / Claude Code is available (cross-platform).
Who created beepctl?
It is built and maintained by blqke (@blqke); the current version is v0.1.4.
More Skills