beeper-cli

💬 Beeper CLI — Messaging in your terminal.

Manage chats, send messages, and control Beeper Desktop from the command line.

Features

• Authentication - browser-based login with secure keyring storage
• Chat management - list, search, archive, and organize conversations
• Desktop control - focus Beeper window, navigate to chats, pre-fill drafts
• Messaging - send messages, search history, and view conversations
• Multi-network support - manage chats across all connected networks (iMessage, WhatsApp, Telegram, Signal, etc.)
• Reminders - set and clear chat reminders

Installation

Homebrew

brew install salmonumbrella/tap/beeper-cli

Go Install

go install github.com/salmonumbrella/beeper-cli/cmd/beeper@latest

Build from Source

git clone https://github.com/salmonumbrella/beeper-cli
cd beeper-cli
make build && make install

Quick Start

1. Enable Local API

Open Beeper Desktop → Settings → Developers → Enable Local API

2. Authenticate

beeper auth login

This opens your browser to authenticate with Beeper and securely stores the token in your system keyring.

Prefer to paste a token directly?

beeper auth add --token "<token>"

3. Test Connection

beeper auth test

4. Start Using

beeper accounts              # List connected networks
beeper chats list            # Show recent chats
beeper messages search "hi"  # Search message history

Configuration

Account Filtering

Filter commands by specific chat networks:

# Via flag
beeper chats list --account whatsapp

# Multiple networks
beeper messages search "invoice" --account whatsapp,telegram

Get account IDs from beeper accounts.

Profile Selection

If you have multiple auth tokens saved, select one with --profile:

beeper --profile personal chats list

You can set a default profile with BEEPER_PROFILE.

Environment Variables

• BEEPER_OUTPUT - Output format: text (default) or json
• BEEPER_COLOR - Color mode: auto (default), always, or never
• NO_COLOR - Set to any value to disable colors (standard convention)
• BEEPER_PROFILE - Default auth profile name
• BEEPER_BASE_URL - Override API base URL (default: http://localhost:23373)

Security

Credential Storage

Tokens are stored securely in your system's keychain:

• macOS: Keychain Access
• Linux: Secret Service (GNOME Keyring, KWallet)
• Windows: Credential Manager

Commands

Authentication

beeper auth add              # Authenticate via browser (opens browser)
beeper auth list             # List configured tokens
beeper auth remove <name>    # Remove a token
beeper auth test             # Test current token

Accounts

beeper accounts              # List connected chat networks

Chats

beeper chats list                           # List recent chats
beeper chats list --unread                  # Only unread chats
beeper chats list --all                     # List ALL chats (pagination via search)
beeper chats list --all --include-muted     # Include muted chats
beeper chats list --pinned                  # Only pinned chats
beeper chats list --muted                   # Only muted chats
beeper chats list --archived                # Only archived chats
beeper chats list --inbox primary           # Filter by inbox
beeper chats list --inbox archive           # Show archived chats
beeper chats list --account whatsapp        # Filter by network
beeper chats list --type dm                 # Filter by chat type (dm or group)
beeper chats list --cursor <cursor>         # Paginate (recent or all)
beeper chats list --direction before        # Paginate direction
beeper chats get <chat-id>                  # Get chat details
beeper chats search <query>                 # Search for chats by name
beeper chats archive <chat-id>              # Archive a chat
beeper chats archive --chat "John"          # Archive by name
beeper chats archive --unarchive <chat-id>  # Unarchive
beeper chats archive-read                   # Archive all read chats
beeper chats archive-read --dry-run         # Preview what would be archived

Messages

beeper messages list <chat-id>              # List messages in a chat
beeper messages list --chat "John"          # List by chat name
beeper messages list <chat-id> --limit 50   # Limit results
beeper messages search <query>              # Search all messages
beeper messages search "invoice" --account telegram
beeper messages send <chat-id> --text "Hello!"
beeper messages send --chat "John" --text "Meeting at 3pm"
beeper messages send --chat "John" --stdin
beeper messages send --chat "John" --file ./message.txt
beeper messages tail <chat-id>              # Follow new messages
beeper messages tail --chat "John"          # Follow by chat name

Reminders

beeper reminders set <chat-id> --at "2024-12-25 10:00"
beeper reminders set --chat "John" --at "tomorrow 9am"
beeper reminders clear <chat-id>

Focus (Desktop Control)

beeper focus                                # Bring Beeper to foreground
beeper focus --chat "John"                  # Open specific chat
beeper focus --chat "John" --draft "Hi!"    # Open with pre-filled draft

Version

beeper version --check                      # Check for updates

Output Formats

Text

Human-readable tables with colors and formatting:

$ beeper chats list
ID                    NAME              NETWORK     UNREAD  LAST ACTIVITY
!abc123...            John Smith        WhatsApp            3:42 PM
!def456...            Team Chat         Telegram    5       2:15 PM
!ghi789...            Mom               iMessage    2       Yesterday

JSON

Machine-readable output:

$ beeper chats list -o json
[
  {
    "id": "!abc123...",
    "title": "John Smith",
    "network": "WhatsApp",
    "unreadCount": 0,
    "lastActivity": "2024-12-25T15:42:00Z"
  }
]

Data goes to stdout, errors and progress to stderr for clean piping.

Examples

Archive all read chats

# Preview first
beeper chats archive-read --dry-run

# Then execute
beeper chats archive-read

Send a quick message

beeper messages send --chat "John" --text "Running 5 mins late!"

Follow a chat

beeper messages tail --chat "Team" --interval 2s

Search messages across networks

beeper messages search "pdf" --account whatsapp -o json | jq '.messages[]'

Focus chat with draft from clipboard

beeper focus --chat "Team" --draft "$(pbpaste)"

Disambiguate chat names

beeper messages send --to "Project" --exact --text "Shipping now"
beeper chats archive --chat "Family" --first

Automation

Use -o json for scripting and --dry-run to preview changes:

# Count unread chats
beeper chats list -o json | jq '[.[] | select(.unreadCount > 0)] | length'

# Get all Telegram chat IDs
beeper chats list --account telegram -o json --query '.[].id'

# Notify on unread count
unread=$(beeper chats list -o json | jq '[.[] | select(.unreadCount > 0)] | length')
[ "$unread" -gt 10 ] && osascript -e "display notification \"$unread unread\" with title \"Beeper\""

Debug Mode

Enable verbose output for troubleshooting:

beeper --debug chats list
# Shows: api request method=GET url=http://localhost:9988/...
# Shows: api response status=200 content_length=1234

JQ Filtering

Filter JSON output with JQ expressions:

# Get only unread chats
beeper chats list -o json --query '.[] | select(.unreadCount > 0)'

# Extract chat IDs
beeper chats list -o json --query '.[].id'

# Get chats from specific network
beeper chats list -o json --query '.[] | select(.network == "Telegram")'

Global Flags

All commands support these flags:

• --account <id> - Filter by account/network ID
• --profile <name> - Auth profile name (from beeper auth list)
• --base-url <url> - Override API base URL
• -o, --output <format> - Output format: text or json (default: text)
• --color <mode> - Color mode: auto, always, or never (default: auto)
• --debug - Enable debug output (shows API requests/responses)
• --query <expr> - JQ filter expression for JSON output
• --help - Show help for any command
• --version - Show version information

API Limitations

The Beeper Desktop local API does not currently expose endpoints for:

• Marking chats/messages read or unread
• Muting, pinning, or renaming chats
• Editing/deleting messages or managing reactions/receipts
• Real-time event streams (this CLI uses polling for messages tail)

If these endpoints are added in the future, the CLI can expand to support them.

Shell Completions

Generate shell completions for your preferred shell:

Bash

# macOS (Homebrew):
beeper completion bash > $(brew --prefix)/etc/bash_completion.d/beeper

# Linux:
beeper completion bash > /etc/bash_completion.d/beeper

# Or source directly:
source <(beeper completion bash)

Zsh

beeper completion zsh > "${fpath[1]}/_beeper"

Fish

beeper completion fish > ~/.config/fish/completions/beeper.fish

PowerShell

beeper completion powershell | Out-String | Invoke-Expression

Development

After cloning, install git hooks:

make setup

This installs lefthook pre-commit and pre-push hooks for linting and testing.

License

MIT

Links

• Beeper
• GitHub Repository