beepctl 🐝


CLI for Beeper Desktop API - unified messaging from your terminal. Give your AI agents the power to chat across all your messaging platforms.

> Disclaimer: This is an unofficial project. Not affiliated with, endorsed by, or sponsored by Beeper. The Beeper Desktop API is still in beta — expect breaking changes.

Requirements

- Beeper Desktop v4.1.169+
- Beeper Desktop API enabled (Settings → Developers → Enable)
- Node.js 20+ or Bun

Installation

``bash


From npm

npm install -g beepctl

Or use directly with npx

npx beepctl

From source

pnpm install
pnpm build
pnpm link --global
`

Setup

1. Open Beeper Desktop
2. Go to Settings → Developers
3. Enable Beeper Desktop API
4. Click "+" next to "Approved connections" to create a token
5. (Optional) Enable "Allow sensitive actions" on the token to send messages
6. Configure the CLI:

`bash
beepctl auth set


Or use environment variable


export BEEPER_TOKEN=
`

Configuration

Config stored at ~/.config/beepctl/config.json with token, base URL, and aliases.

Precedence: Environment variables (BEEPER_TOKEN, BEEPER_URL) override config file.

Usage

$3

`bash
beepctl auth show # Check auth status
beepctl auth set # Set API token
beepctl auth clear # Clear stored token
`

$3

`bash
beepctl accounts # List all connected accounts
`

$3

`bash


List chats

beepctl chats list # List inbox (non-archived)
beepctl chats list --limit 50 # 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 (including archived)
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

Chat details

beepctl chats show # Detailed info with participants

Create chat

beepctl chats create # Create new single/group chat
`

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

$3

Browse messages in a specific chat:

`bash
beepctl messages # List recent messages
beepctl messages --limit 20 # Limit results
beepctl messages --after "1d ago" # Messages after a time
beepctl messages --before "1h ago" # Messages before a time
beepctl messages work # Use alias
`

$3

Search messages across all chats:

`bash
beepctl search "meeting tomorrow"
beepctl search "deadline" --limit 10
beepctl search "deadline" --chat work --sender me --after "1d ago"
beepctl search "photo" --media image video
beepctl search "discussion" --chat-type group --before "yesterday"
`

#### Search Filters

`bash


Filter by chat (supports aliases, space or comma-separated)

beepctl search "hello" --chat work family
beepctl search "test" --chat id1,id2,id3

Filter by time range (relative dates)

beepctl search "meeting" --after "1d ago" --before "1h ago"
beepctl search "report" --after "yesterday"

Filter by sender

beepctl search "question" --sender me # Only my messages
beepctl search "update" --sender others # Messages from others

Filter by media type

beepctl search "screenshot" --media image
beepctl search "files" --media file link

Filter by chat type

beepctl search "announcement" --chat-type group
beepctl search "dm" --chat-type single

Filter by account

beepctl search "slack message" --account

Combine filters

beepctl search "deploy" --chat work --sender others --after "1d ago" --media link

Include/exclude options

beepctl search "todo" --include-low-priority
beepctl search "important" --exclude-muted
`

Time formats: 1h ago, 2d ago, 3w ago, 1mo ago, yesterday, today

Media types: any, video, image, link, file

$3

`bash
beepctl send "Hello!" # Send message
beepctl send myself "Quick note" # Send to yourself
beepctl send "Thanks!" --reply-to # Reply to message
beepctl send "msg" --quiet # No confirmation output
`

$3

Bring Beeper Desktop to foreground and optionally open a chat:

`bash
beepctl focus # Bring Beeper to foreground
beepctl focus # Open a specific chat
beepctl focus work # Use alias
beepctl focus -m # Jump to specific message
beepctl focus -d "draft text" # Pre-fill draft text
beepctl focus -a /path/to/file # Pre-fill draft attachment
`

Tip: Use focus with -a to send media (images, files) since send only supports text:

`bash
beepctl focus -a /path/to/image.png -d "Check this out!"


Then press Enter in Beeper to send


`

$3

`bash
beepctl archive # Archive a chat
beepctl archive --unarchive # Unarchive a chat
beepctl archive work # Use alias
beepctl archive --quiet # No confirmation message
`

$3

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
`

$3

`bash
beepctl contacts search # Search contacts on an account
`

$3

Download message attachments (mxc:// URLs):

`bash
beepctl download # Download to current directory
beepctl download -o /path # Save to specific path
`

$3

Set reminders to follow up on chats:

`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
`

Development

`bash


Run in dev mode

pnpm dev -- accounts

Run tests

pnpm test

Lint

pnpm lint
pnpm lint:fix

Build

pnpm build

Create standalone binary

pnpm binary
`

Project Structure

`
src/
├── cli.ts # Entry point - command registration
├── index.ts # Library exports
├── version.ts # Version info
├── commands/ # CLI commands
│ ├── auth.ts # Token management
│ ├── accounts.ts # List accounts
│ ├── alias.ts # Alias management
│ ├── archive.ts # Archive/unarchive chats
│ ├── chats.ts # Browse chats
│ ├── contacts.ts # Search contacts
│ ├── download.ts # Download attachments
│ ├── focus.ts # Bring Beeper to foreground
│ ├── messages.ts # List messages in a chat
│ ├── reminders.ts # Chat reminders
│ ├── search.ts # Search messages/chats
│ └── send.ts # Send messages
└── lib/ # Core logic
├── client.ts # Beeper API client wrapper
├── config.ts # Config file management (~/.config/beepctl/)
├── aliases.ts # Alias resolution utilities
└── dates.ts # Relative date parsing
`

Stack

- TypeScript with plain tsc
- Commander for CLI framework
- Kleur for colors/styling
- Vitest for testing
- Biome + oxlint for linting/formatting
- Bun for standalone binary compilation
- @beeper/desktop-api SDK

AI Agent Integration

beepctl includes an Agent Skill for AI coding assistants.

Supported agents: Claude Code, Cursor, VS Code, GitHub Copilot, OpenAI Codex, Gemini CLI, Goose, Amp, and 25+ more.

$3

`bash
npx skills add blqke/beepctl
`

$3

`bash
cp -r skills/beepctl ~/.claude/skills/
`

$3

`bash
cp -r skills/beepctl ~/.cursor/skills/
``

Acknowledgments

Inspired by beeper-cli by @krausefx.

The author uses beepctl alongside clawdbot.

License

MIT