beepctl

Use when sending messages, searching chats, or managing conversations across messaging platforms (Telegram, WhatsApp, Slack, iMessage, etc.) via Beeper Desktop API.

Security Scan

The skill's requirements and runtime instructions match its stated purpose (invoking the beepctl CLI to manage messages) and there are no unexplained credential requests or risky installers, though you should verify the beepctl binary and be mindful of file-access and message-sending actions.

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.

Assessment

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.

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 <chat-id> "Hello!"     # Send a message

Commands

Auth Management

beepctl auth show           # Check auth status and token
beepctl auth set <token>    # 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 <chat-id>              # Detailed chat info with participants
beepctl chats create <account> <users...> # Create new chat

Inbox filters: primary (default), archive, low-priority, all

List Messages

beepctl messages <chat-id>              # Recent messages from a chat
beepctl messages <chat-id> --limit 10   # Limit results
beepctl messages work --after "1d ago"  # Use alias + time filter
beepctl messages <chat-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 <id>       # 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 <chat-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 <chat-id>              # Archive a chat
beepctl archive <chat-id> --unarchive  # Unarchive
beepctl archive work                   # Use alias
beepctl archive <chat-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 <chat-id> "Hello!"                    # Send message
beepctl send myself "Quick note"                   # Send to self
beepctl send <chat-id> "Reply" --reply-to <msg-id> # Reply to message
beepctl send <chat-id> "msg" --quiet               # No confirmation output

Focus (Bring to Foreground)

beepctl focus                           # Bring Beeper to foreground
beepctl focus <chat-id>                 # Open a specific chat
beepctl focus <chat-id> -m <msg-id>     # Jump to specific message
beepctl focus <chat-id> -d "draft"      # Pre-fill draft text
beepctl focus <chat-id> -a /path/file   # Pre-fill draft attachment

Send Media

beepctl send only supports text. To send media, use focus with draft:

beepctl focus <chat-id> -a /path/to/image.png -d "Caption"
# Then press Enter in Beeper to send

Contacts

beepctl contacts search <account> <query>  # Search contacts on an account

Download Attachments

beepctl download <mxc-url>              # Download attachment (mxc:// URLs)
beepctl download <mxc-url> -o /path     # Save to specific path

Reminders

beepctl reminders set <chat> 30m       # Remind in 30 minutes
beepctl reminders set <chat> 1h        # Remind in 1 hour
beepctl reminders set <chat> 2d        # Remind in 2 days
beepctl reminders set <chat> tomorrow  # Remind tomorrow
beepctl reminders clear <chat>         # Clear reminder

Tips

• Chat IDs look like: !gZ42vWzDxl8V0sZXWBgO:beeper.local
• Use aliases to avoid typing long chat IDs
• The special alias myself sends to your own chat