# Beepctl > Use when sending messages, searching chats, or managing conversations across messaging platforms (Telegram, WhatsApp, Slack, iMessage, etc.) via Beeper Desktop API. - Skill: `tomevault-io/beepctl` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add tomevault-io/beepctl` - Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/beepctl/raw - Safety review: pending (external: skill-scanner PASS, skillspector PASS) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Integrations & APIs - Author: tomevault-io (https://skillmd.com/u/tomevault-io) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/tomevault-io/beepctl --- # beepctl CLI for [Beeper Desktop API](https://developers.beeper.com/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](https://github.com/blqke/beepctl) ## Quick Start ```bash 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 "Hello!" # Send a message ``` ## Commands ### Auth Management ```bash beepctl auth show # Check auth status and token beepctl auth set # Set API token beepctl auth clear # Clear saved token ``` ### Accounts ```bash beepctl accounts # List all connected accounts ``` ### Browse Chats ```bash 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 # Detailed chat info with participants beepctl chats create # Create new chat ``` **Inbox filters:** `primary` (default), `archive`, `low-priority`, `all` ### List Messages ```bash beepctl messages # Recent messages from a chat beepctl messages --limit 10 # Limit results beepctl messages work --after "1d ago" # Use alias + time filter beepctl messages --before "1h ago" # Messages before a time ``` ### Search Messages ```bash 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 # Filter by account beepctl search "todo" --include-low-priority # Include low-priority chats beepctl search "important" --exclude-muted # Exclude muted chats ``` **Combine filters:** ```bash 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: ```bash beepctl alias list # List all aliases beepctl alias add work # 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 ```bash beepctl archive # Archive a chat beepctl archive --unarchive # Unarchive beepctl archive work # Use alias beepctl archive --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. ```bash beepctl send "Hello!" # Send message beepctl send myself "Quick note" # Send to self beepctl send "Reply" --reply-to # Reply to message beepctl send "msg" --quiet # No confirmation output ``` ### Focus (Bring to Foreground) ```bash beepctl focus # Bring Beeper to foreground beepctl focus # Open a specific chat beepctl focus -m # Jump to specific message beepctl focus -d "draft" # Pre-fill draft text beepctl focus -a /path/file # Pre-fill draft attachment ``` ### Send Media `beepctl send` only supports text. To send media, use focus with draft: ```bash beepctl focus -a /path/to/image.png -d "Caption" # Then press Enter in Beeper to send ``` ### Contacts ```bash beepctl contacts search # Search contacts on an account ``` ### Download Attachments ```bash beepctl download # Download attachment (mxc:// URLs) beepctl download -o /path # Save to specific path ``` ### Reminders ```bash beepctl reminders set 30m # Remind in 30 minutes beepctl reminders set 1h # Remind in 1 hour beepctl reminders set 2d # Remind in 2 days beepctl reminders set tomorrow # Remind tomorrow beepctl reminders clear # Clear reminder ``` ### React to Messages ```bash beepctl react 👍 # React with emoji beepctl react thumbsup # React with shortcode beepctl react custom_emoji_key # React with custom emoji key beepctl react 👍 --remove # Remove your reaction beepctl react work ❤️ # Use alias ``` `` accepts an emoji, shortcode, or custom emoji key. `--remove` removes the authenticated user's reaction only — it cannot remove other users' reactions. ## 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 --- > Source: [blqke/beepctl](https://github.com/blqke/beepctl) — distributed by [TomeVault](https://tomevault.io).