beeper-cli

README

💬 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
• Local-first - everything stays on your device via Beeper Desktop’s local API
• Multi-network support - WhatsApp, Signal, Telegram, Discord, Google Messages, Google Chat, Google Voice, Slack, X (Twitter DMs), LinkedIn, Instagram, Messenger (Facebook Messenger)
• Upcoming networks - LINE, Hinge, Snapchat (coming soon)
• Reminders - set and clear chat reminders

Supported Networks

Currently supported chat networks:

• WhatsApp
• Signal
• Telegram
• Discord
• Google Messages
• Google Chat
• Google Voice
• Slack
• X (Twitter DMs)
• LinkedIn
• Instagram
• Messenger (Facebook Messenger)

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), json, json-pretty, or jsonl
• 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)
• BEEPER_SOURCE - Backend source: api (default), db, or auto
• BEEPER_DB - Path to Beeper index.db (implies --source db)

DB Backend (Read-Only)

For faster local search, you can use the DB backend which reads Beeper’s local SQLite database directly. This is read-only and does not support sending or modifying data.

Requirements

• CGO-enabled Go toolchain
• SQLite3 library available on your system

Usage

# Use DB backend explicitly
beeper --source db messages search "invoice"

# Or point directly at the database (implies db backend)
beeper --db ~/Library/Application\ Support/BeeperTexts/index.db messages search "invoice"

# Include context around search hits
beeper --source db messages search "invoice" --context 2 --window 30m

# Auto mode (API first, DB fallback for search)
beeper --source auto messages search "invoice"

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 login            # Authenticate via browser (opens browser)
beeper auth add              # Add a token (interactive or --token)
beeper auth add --token "<token>"
beeper auth add work         # Add a token with a profile name
beeper auth list             # List configured tokens
beeper auth remove <name>    # Remove a token
beeper auth test             # Test current token
beeper auth test work        # Test a named 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 --source db chats list               # List chats via local DB (read-only)
beeper chats get <chat-id>                  # Get chat details
beeper chats search <query>                 # Search for chats by name
beeper chats search <query> --limit 50      # Limit search results
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
beeper chats archive-read --yes             # Skip confirmation prompt

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 list --unread               # Only unread messages
beeper messages list --cursor <cursor>      # Paginate from cursor
beeper messages list --direction before     # Paginate direction
beeper messages search <query>              # Search all messages
beeper messages search "invoice" --account telegram
beeper messages search "invoice" --after 2024-01-01
beeper messages search "invoice" --chat <chat-id>
beeper messages search "invoice" --limit 50
beeper messages send <chat-id> --text "Hello!"
beeper messages send --to "John" --text "Meeting at 3pm"
beeper messages send --to "John" --stdin
beeper messages send --to "John" --file ./message.txt
beeper messages send --to "John" --reply-to <message-id>
beeper messages tail <chat-id>              # Follow new messages
beeper messages tail --chat "John"          # Follow by chat name
beeper messages tail --interval 2s          # Polling interval
beeper messages tail --limit 20             # Show last N before following
beeper messages delete <message-id> --chat "John"
beeper messages delete <message-id> --chat-id <chat-id> --yes
beeper messages read --chat "John"
beeper messages read --chat-id <chat-id>
beeper messages react <message-id> --chat "John" --emoji "👍"
beeper messages react <message-id> --chat-id <chat-id> --emoji "👍"
beeper messages get <message-id> --chat "John" --context 3
beeper messages get <message-id> --chat-id <chat-id>

DB backend search options:

beeper --source db messages search "invoice" --days 7
beeper --source db messages search "invoice" --context 2 --window 30m
beeper --source db messages search "invoice" --message-format plain

Contacts

beeper contacts list                         # List DM contacts
beeper contacts list --limit 50              # Limit results
beeper contacts search <query>               # Search contacts by name
beeper contacts search <query> --limit 50    # Limit search results

Inbox

beeper inbox                                 # Show unread messages
beeper inbox --limit 10                      # Limit chats shown
beeper inbox --dm                            # Only DM conversations
beeper inbox --since 1h                      # Messages since duration
beeper inbox --watch --interval 3s           # Stream new messages

Reminders

beeper reminders set <chat-id> --at "2024-12-25 10:00"
beeper reminders set --chat "John" --at "2024-12-25 10:00"
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
beeper focus --chat "John" --message <id>   # Jump to a message
beeper focus --chat "John" --attachment /path/to/file

Version

beeper version                              # Print version info
beeper version --check                      # Check for updates

Completion

beeper completion [bash|zsh|fish|powershell]

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.

Pretty JSON

Readable JSON formatting:

beeper chats list -o json-pretty

Template Output

Customize text output with Go templates (applies per item for list commands):

beeper chats list --format '{{.Title}}\t{{.Network}}'

JSON Lines (JSONL)

Streaming commands emit one JSON object per line when -o json or -o jsonl is set. For list outputs, -o jsonl emits one object per line:

# Follow a chat and stream JSON events
beeper messages tail --chat "Team" -o jsonl | jq -c .

# Watch inbox updates as JSON lines
beeper inbox --watch -o jsonl

# List chats as JSON lines
beeper chats list -o jsonl

Sample event payloads:

{"chatID":"!abc123:beeper.com","chatTitle":"Team","network":"Slack","chatType":"group","message":"Standup in 5","sender":"Alex","timestamp":"2025-01-12T10:15:00Z"}

{"id":"$event:1","chatID":"!abc123:beeper.com","accountID":"acct1","senderID":"@alex:beeper.com","sender":"Alex","senderName":"Alex","text":"Hello","timestamp":"2025-01-12T10:15:00Z","isMe":false}

Fields by stream:

• beeper inbox --watch -o json
  • chatID, chatTitle, network, chatType, message, sender, timestamp
• beeper messages tail -o json
  • id, chatID, accountID, senderID, sender, senderName, text, timestamp, isMe, attachments, reactions, replyTo

Streaming filters:

# Print only message text from a live stream
beeper messages tail --chat "Team" -o json | jq -r '.text'

# Print inbox sender + message
beeper inbox --watch -o json | jq -r '"\(.sender): \(.message)"'

List output schema (JSON):

• beeper chats list -o json
  • id, title, network, unreadCount, lastActivity, type, accountID, isArchived, isMuted, isPinned, preview
• beeper messages list -o json
  • items[] with message fields (id, chatID, accountID, senderID, sender, senderName, text, timestamp, isMe, attachments, reactions, replyTo)
• beeper messages search -o json
  • messages[] with message fields, chats{} lookup, hasMore
• beeper inbox -o json
  • chatID, chatTitle, network, chatType, message, sender, timestamp
• beeper contacts list -o json
  • id, title, network, lastActivity
• beeper accounts -o json
  • id, network, user
• beeper reminders set/clear -o json
  • status, chat_id, reminder_at (for set)
• beeper focus -o json
  • status, chat_id, draft

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 --to "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
beeper reminders set --chat "Alex" --dm --at "2024-12-25 10:00"

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, json, json-pretty, or jsonl (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
• --format <template> - Go template for text output (applies per item for lists)
• --source <api|db|auto> - Backend source (db is read-only)
• --db <path> - Path to Beeper index.db (implies db backend)
• --help - Show help for any command
• --version - Show version information

API Limitations

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

• Muting, pinning, or renaming chats
• Editing messages
• 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