beeper-cli-skill.sh

---
name: beeper
description: >
  Manage messaging across platforms (WhatsApp, Telegram, Twitter/X, etc.) using the Beeper Desktop CLI.
  Use when the user wants to send messages, check messages, search chats, list accounts, manage reactions,
  upload attachments, or interact with any messaging platform through Beeper.
triggers:
  - send message
  - beeper
  - check messages
  - search chats
  - search messages
  - list accounts
  - messaging
---

# Beeper Desktop CLI

CLI for managing unified messaging across WhatsApp, Telegram, Twitter/X, and other platforms via Beeper Desktop.

**Binary:** `beeper-desktop-cli`
**Auth:** Set `$BEEPER_ACCESS_TOKEN` env var (Bearer token from OAuth2 PKCE or created in-app).

## Safety Guidelines

- **Always confirm before sending messages.** Show the user the chat name, recipient, and message text before executing `messages send`.
- **Use `--format json` for programmatic use** when parsing output in scripts or pipelines.
- **Use `--format pretty` (default) for human-readable display** in normal conversation.

## Known Issues

### Chat IDs containing `!` get backslash-escaped by the CLI

Beeper chat IDs start with `!` (e.g., `!Qp_ial72qHIHdGhZfrRUQrT-DJA:...`). When passed directly via `--chat-id`, the CLI backslash-escapes the `!`, causing 404 "Chat not found" errors.

**Workaround:** Use `printf` with `xargs -0` to pass the chat ID without shell or CLI escaping:

```bash
printf '%s' '!CHAT_ID_HERE' | xargs -0 -I{} beeper-desktop-cli messages list --chat-id {} --format json
printf '%s' '!CHAT_ID_HERE' | xargs -0 -I{} beeper-desktop-cli messages send --chat-id {} --text "Hello"
```

This applies to all commands that accept `--chat-id`: `messages list`, `messages send`, `messages search`, `chats retrieve`, `chats archive`, `chats:reminders create/delete`, `chats:messages:reactions add/delete`, and `focus`.

## Global Options

All commands accept these options:

| Option | Description |
|--------|-------------|
| `--debug` | Enable debug logging |
| `--format <fmt>` | Output format: `auto`, `explore`, `json`, `jsonl`, `pretty`, `raw`, `yaml` (default: `pretty`) |
| `--format-error <fmt>` | Error output format (same options) |
| `--transform <gjson>` | GJSON transformation for output |
| `--transform-error <gjson>` | GJSON transformation for errors |
| `--access-token <token>` | Bearer token (or use `$BEEPER_ACCESS_TOKEN`) |
| `--base-url <url>` | Override API base URL |

## Commands Reference

### Top-Level Commands

#### `focus`
Focus Beeper Desktop window, optionally navigate to a chat/message or pre-fill draft.

```
beeper-desktop-cli focus [options]
  --chat-id <id>                 Chat ID to navigate to
  --message-id <id>              Message ID to jump to
  --draft-text <text>            Pre-fill message input
  --draft-attachment-path <path> Pre-fill attachment
```

#### `search`
Universal search across chats, participants, and messages in one call.

```
beeper-desktop-cli search --query <text>
```

### accounts

#### `accounts list`
List all connected messaging accounts (WhatsApp, Telegram, Twitter/X, etc.).

```
beeper-desktop-cli accounts list
```

### accounts:contacts

#### `accounts:contacts list`
List merged contacts for a specific account with cursor-based pagination.

```
beeper-desktop-cli accounts:contacts list [options]
  --account-id <id>   Account ID (required)
  --cursor <cursor>    Pagination cursor
  --direction <dir>    'before' (older) or 'after' (newer)
  --limit <n>          Max contacts per page
  --query <text>       Optional search query
```

#### `accounts:contacts search`
Search contacts on a specific account.

```
beeper-desktop-cli accounts:contacts search [options]
  --account-id <id>   Account ID (required)
  --query <text>       Search text (network-specific behavior)
```

### chats

#### `chats create`
Create a new single/group chat or start a direct chat from merged user data.

```
beeper-desktop-cli chats create [options]
  --account-id <id>              Account to create chat on
  --mode <mode>                  'create' (default) or 'start'
  --type <type>                  'single' or 'group' (mode=create)
  --participant-id <id>          User IDs to include (repeatable, mode=create)
  --title <title>                Group chat title (mode=create)
  --user <key>=<val>             Merged user payload (repeatable, mode=start)
  --allow-invite                 Allow invite-based DM creation (mode=start)
  --message-text <text>          Optional first message
```

#### `chats retrieve`
Get chat details including metadata, participants, and latest message.

```
beeper-desktop-cli chats retrieve [options]
  --chat-id <id>                  Chat ID (required)
  --max-participant-count <n>     Max participants to return (-1 for all, default)
```

#### `chats list`
List all chats sorted by last activity (most recent first).

```
beeper-desktop-cli chats list [options]
  --account-id <id>   Filter by account (repeatable)
  --cursor <cursor>    Pagination cursor
  --direction <dir>    'before' or 'after'
```

#### `chats archive`
Archive or unarchive a chat.

```
beeper-desktop-cli chats archive [options]
  --chat-id <id>   Chat ID (required)
  --archived        true to archive, false to unarchive
```

#### `chats search`
Search chats by title/network or participants.

```
beeper-desktop-cli chats search [options]
  --query <text>                  Literal token search (case-insensitive, all words must match)
  --scope <scope>                 'titles' or 'participants'
  --account-id <id>               Filter by account (repeatable)
  --type <type>                   'single', 'group', or 'any'
  --inbox <inbox>                 'primary', 'low-priority', or 'archive'
  --unread-only <bool>            Only unread chats
  --include-muted <bool>          Include muted chats (default: true)
  --last-activity-after <iso>     ISO datetime filter
  --last-activity-before <iso>    ISO datetime filter
  --limit <n>                     Max results 1-200 (default: 50)
  --cursor <cursor>               Pagination cursor
  --direction <dir>               'before' or 'after'
```

### messages

#### `messages send`
Send a text message to a chat. Supports replies and attachments.

```
beeper-desktop-cli messages send [options]
  --chat-id <id>                  Chat ID (required)
  --text <text>                   Message text (supports markdown)
  --reply-to-message-id <id>     Reply to specific message
  --attachment <key>=<val>        Attachment data (repeatable)
```

#### `messages list`
List messages in a chat with cursor-based pagination.

```
beeper-desktop-cli messages list [options]
  --chat-id <id>     Chat ID (required)
  --cursor <cursor>   Pagination cursor
  --direction <dir>   'before' or 'after'
```

#### `messages search`
Search messages across chats.

```
beeper-desktop-cli messages search [options]
  --query <text>                  Literal word search (use single words, not phrases)
  --chat-id <id>                  Filter by chat (repeatable)
  --account-id <id>               Filter by account (repeatable)
  --chat-type <type>              'group' or 'single'
  --sender <sender>               'me', 'others', or a user ID
  --date-after <iso>              ISO 8601 datetime
  --date-before <iso>             ISO 8601 datetime
  --media-type <type>             Filter by media: 'any', 'video', 'image' (repeatable)
  --include-muted <bool>          Include muted chats (default: true)
  --exclude-low-priority <bool>   Exclude low priority (default: true)
  --limit <n>                     Max results
  --cursor <cursor>               Pagination cursor
  --direction <dir>               'before' or 'after'
```

#### `messages update`
Edit an existing text message (cannot edit messages with attachments).

```
beeper-desktop-cli messages update [options]
  --chat-id <id>       Chat ID (required)
  --message-id <id>    Message ID (required)
  --text <text>        New message text
```

### chats:reminders

#### `chats:reminders create`
Set a reminder for a chat.

```
beeper-desktop-cli chats:reminders create [options]
  --chat-id <id>                    Chat ID (required)
  --reminder <key>=<val>            Reminder config (repeatable)
```

#### `chats:reminders delete`
Clear an existing reminder from a chat.

```
beeper-desktop-cli chats:reminders delete --chat-id <id>
```

### chats:messages:reactions

#### `chats:messages:reactions add`
Add a reaction to a message.

```
beeper-desktop-cli chats:messages:reactions add [options]
  --chat-id <id>           Chat ID (required)
  --message-id <id>        Message ID (required)
  --reaction-key <emoji>   Emoji or shortcode
  --transaction-id <id>    Optional dedup ID
```

#### `chats:messages:reactions delete`
Remove your reaction from a message.

```
beeper-desktop-cli chats:messages:reactions delete [options]
  --chat-id <id>           Chat ID (required)
  --message-id <id>        Message ID (required)
  --reaction-key <emoji>   Reaction to remove
```

### assets

#### `assets upload`
Upload a file via multipart/form-data. Returns an uploadID for use with `messages send`.

```
beeper-desktop-cli assets upload [options]
  --file <path>        File to upload (max 500 MB)
  --file-name <name>   Original filename (defaults to file name)
  --mime-type <type>   MIME type (auto-detected if omitted)
```

#### `assets upload-base64`
Upload a file via base64-encoded JSON body.

```
beeper-desktop-cli assets upload-base64 [options]
  --content <base64>   Base64-encoded file content
  --file-name <name>   Filename (generated if omitted)
  --mime-type <type>   MIME type (auto-detected if omitted)
```

#### `assets download`
Download an asset to local disk.

```
beeper-desktop-cli assets download --url <mxc://...>
```

#### `assets serve`
Stream a file (downloads first if not cached). Supports Range requests.

```
beeper-desktop-cli assets serve --url <mxc://|localmxc://|file://>
```

### info

#### `info retrieve`
Get app, platform, server, and endpoint metadata for this Beeper Desktop instance.

```
beeper-desktop-cli info retrieve
```

## Common Workflows

### List connected accounts
```bash
beeper-desktop-cli accounts list
```

### Find a chat by name
```bash
beeper-desktop-cli chats search --query "John" --scope titles
```

### Read recent messages in a chat
```bash
beeper-desktop-cli messages list --chat-id <CHAT_ID> --format json
```

### Send a message (always confirm with user first)
```bash
beeper-desktop-cli messages send --chat-id <CHAT_ID> --text "Hello!"
```

### Search messages across all chats
```bash
beeper-desktop-cli messages search --query "meeting" --date-after "2026-03-01T00:00:00Z"
```

### Upload and send an attachment
```bash
# Step 1: Upload the file
beeper-desktop-cli assets upload --file /path/to/photo.jpg --format json
# Step 2: Send with the returned uploadID
beeper-desktop-cli messages send --chat-id <CHAT_ID> --text "Check this out" --attachment upload_id=<UPLOAD_ID>
```

### Search for unread chats
```bash
beeper-desktop-cli chats search --unread-only true --inbox primary
```

### React to a message
```bash
beeper-desktop-cli chats:messages:reactions add --chat-id <CHAT_ID> --message-id <MSG_ID> --reaction-key "thumbsup"
```

### Focus Beeper on a specific chat with pre-filled text
```bash
beeper-desktop-cli focus --chat-id <CHAT_ID> --draft-text "Draft message here"
```