blqke/beepctl
Overview
This skill provides a TypeScript CLI wrapper to control Beeper Desktop API from the terminal. It centralizes messaging across platforms (Telegram, WhatsApp, Slack, iMessage, etc.) so you can list accounts and chats, search messages, send text, and manage conversation state without switching apps. Use it to automate or speed up everyday chat operations from scripts or interactive shells.
How this skill works
The CLI queries the Beeper Desktop API to enumerate connected accounts, list and filter chats, fetch and search messages, and invoke actions like send, archive, focus, and download attachments. It supports aliases for chat IDs, time and media filters for refined searches, and a focus command to prepare drafts or attach files when text send is not supported. Authentication is handled via a token you set or clear with the auth commands.
When to use it
- Send quick replies or notes from the terminal without opening multiple apps
- Search across all messaging platforms for keywords, attachments, or recent activity
- Script cross-platform notifications or batch queries in shell scripts or cron jobs
- Manage conversation state: archive/unarchive, set reminders, or focus a chat window
- Download attachments or prepare media drafts via command-line workflows
Best practices
- Always present message content and recipient and ask for explicit approval before sending text
- Use aliases for frequently used chat IDs to avoid long identifiers and reduce errors
- Combine time, chat, sender, and media filters to narrow search results and speed queries
- Use focus + draft/attachment to send media because beepctl send supports text only
- Keep an auth token securely stored; clear tokens when no longer needed
Example use cases
- Search for "invoice" across all chats from the last week and download matching attachments
- Send a status update to a team chat alias from a CI job after build completion
- Create an alias for a family group and quickly send a photo by preparing a draft with focus
- Archive low-priority chats in bulk or unarchive when activity resumes
- Set a reminder to follow up in a specific chat tomorrow
FAQ
No. beepctl send supports text only. To send media, use focus with a draft and attachment (-a) so Beeper Desktop can deliver the file when you confirm.
How do I avoid accidental messages from scripts?
Require explicit approval before sending by showing recipient and content. Use --quiet only when you intentionally suppress confirmations; otherwise keep confirmations enabled.
How do I authenticate the CLI?
Set your API token with auth set <token>. Check status with auth show and clear it with auth clear when you want to revoke local access.
