# beeper/cli architecture

> Architecture diagram of the GitHub repository beeper/cli, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/beeper/cli
- Repository: https://github.com/beeper/cli

## Overview

Beeper CLI connects a user or automation to a local or remote Beeper target, then exposes account, chat, message, contact, and media operations across bridged networks. Setup handles installation, target registration, and authorization; client creation resolves the selected target and credentials before commands use the Beeper API. The README also documents verification, export, and automation surfaces. Some of those implementations were not sampled, so their documented capabilities are shown without speculative internal wiring.

Main entry points: [`packages/cli/src/lib/client.ts`](https://github.com/beeper/cli/blob/main/packages/cli/src/lib/client.ts) (API client setup), [`packages/cli/src/commands/setup.ts`](https://github.com/beeper/cli/blob/main/packages/cli/src/commands/setup.ts) (Setup workflow), [`packages/cli/bin/cli.js`](https://github.com/beeper/cli/blob/main/packages/cli/bin/cli.js) (CLI launcher), [`packages/cli/src/lib/export/index.ts`](https://github.com/beeper/cli/blob/main/packages/cli/src/lib/export/index.ts) (Export engine)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["CLI interaction"]
  node_cli["CLI launcher<br/>[cli.js]"]
end

subgraph group_connection["Targets and auth"]
  node_setup["Setup workflow<br/>[setup.ts]"]
  node_install["Install targets<br/>[server.ts]"]
  node_target_cmd["Target management<br/>[server.ts]"]
  node_targets[("Target profiles<br/>[targets.ts]")]
  node_oauth["OAuth PKCE<br/>[oauth.ts]"]
  node_client["API client setup<br/>[client.ts]"]
  node_desktop_auth["Desktop credentials<br/>[desktop-auth.ts]"]
  node_verification["Device verification<br/>[start.ts]"]
end

subgraph group_messaging["Chat operations"]
  node_accounts["Accounts and bridges<br/>[add.ts]"]
  node_chats["Chat management<br/>[search.ts]"]
  node_messages["Message operations<br/>[search.ts]"]
  node_contacts["Contact search<br/>[search.ts]"]
  node_send["Send messages<br/>[text.ts]"]
end

subgraph group_automation["Automation and data"]
  node_export_cmd["Data export<br/>[export.ts]"]
  node_exporter["Export engine<br/>[index.ts]"]
  node_watch["Events and watch<br/>[watch.ts]"]
  node_rpc["Stdio RPC<br/>[rpc.ts]"]
  node_api_cmd["Raw API requests<br/>[request.ts]"]
  node_plugins["Plugin extensions<br/>[plugins.ts]"]
end

node_user(("User or agent"))
node_beeper{{"Beeper API target"}}
node_export_files["Export files"]
node_webhook{{"Signed webhooks"}}

node_user -->|"runs commands"| node_cli
node_cli -->|"dispatches setup"| node_setup
node_cli -->|"dispatches targets"| node_target_cmd
node_setup -->|"installs"| node_install
node_setup -->|"reads and writes"| node_targets
node_setup -->|"authorizes remote"| node_oauth
node_setup -->|"adopts session"| node_desktop_auth
node_target_cmd -->|"updates profiles"| node_targets
node_client -->|"resolves target"| node_targets
node_client -->|"obtains token"| node_desktop_auth
node_client -->|"creates API client"| node_beeper
node_accounts -->|"creates client"| node_client
node_chats -->|"creates client"| node_client
node_messages -->|"creates client"| node_client
node_contacts -->|"creates client"| node_client
node_send -->|"creates client"| node_client
node_verification -->|"uses target client"| node_client
node_export_cmd -->|"creates client"| node_client
node_export_cmd -->|"runs export"| node_exporter
node_exporter -->|"reads chat data"| node_beeper
node_exporter -->|"writes export"| node_export_files
node_watch -->|"connects to target"| node_client
node_watch -.->|"dispatches events"| node_webhook
node_rpc -->|"uses target client"| node_client
node_api_cmd -->|"creates client"| node_client
node_plugins -.->|"extends commands"| node_cli

click node_cli "https://github.com/beeper/cli/blob/main/packages/cli/bin/cli.js"
click node_setup "https://github.com/beeper/cli/blob/main/packages/cli/src/commands/setup.ts"
click node_install "https://github.com/beeper/cli/blob/main/packages/cli/src/commands/install/server.ts"
click node_target_cmd "https://github.com/beeper/cli/blob/main/packages/cli/src/commands/targets/add/server.ts"
click node_targets "https://github.com/beeper/cli/blob/main/packages/cli/src/lib/targets.ts"
click node_oauth "https://github.com/beeper/cli/blob/main/packages/cli/src/lib/oauth.ts"
click node_client "https://github.com/beeper/cli/blob/main/packages/cli/src/lib/client.ts"
click node_desktop_auth "https://github.com/beeper/cli/blob/main/packages/cli/src/lib/desktop-auth.ts"
click node_accounts "https://github.com/beeper/cli/blob/main/packages/cli/src/commands/accounts/add.ts"
click node_chats "https://github.com/beeper/cli/blob/main/packages/cli/src/commands/chats/search.ts"
click node_messages "https://github.com/beeper/cli/blob/main/packages/cli/src/commands/messages/search.ts"
click node_contacts "https://github.com/beeper/cli/blob/main/packages/cli/src/commands/contacts/search.ts"
click node_send "https://github.com/beeper/cli/blob/main/packages/cli/src/commands/send/text.ts"
click node_verification "https://github.com/beeper/cli/blob/main/packages/cli/src/commands/verify/start.ts"
click node_export_cmd "https://github.com/beeper/cli/blob/main/packages/cli/src/commands/export.ts"
click node_exporter "https://github.com/beeper/cli/blob/main/packages/cli/src/lib/export/index.ts"
click node_watch "https://github.com/beeper/cli/blob/main/packages/cli/src/commands/watch.ts"
click node_rpc "https://github.com/beeper/cli/blob/main/packages/cli/src/commands/rpc.ts"
click node_api_cmd "https://github.com/beeper/cli/blob/main/packages/cli/src/commands/api/request.ts"
click node_plugins "https://github.com/beeper/cli/blob/main/packages/cli/src/commands/plugins.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_user toneBlue
class node_setup,node_install,node_target_cmd,node_targets,node_oauth,node_client,node_desktop_auth,node_verification toneAmber
class node_accounts,node_chats,node_messages,node_contacts,node_send,node_beeper,node_webhook toneMint
class node_export_cmd,node_exporter,node_watch,node_rpc,node_api_cmd,node_plugins toneRose
class node_export_files toneIndigo
```

## Components

### CLI interaction

- [CLI launcher](https://github.com/beeper/cli/blob/main/packages/cli/bin/cli.js): `packages/cli/bin/cli.js`

### Targets and auth

- [Setup workflow](https://github.com/beeper/cli/blob/main/packages/cli/src/commands/setup.ts): `packages/cli/src/commands/setup.ts`
- [Install targets](https://github.com/beeper/cli/blob/main/packages/cli/src/commands/install/server.ts): `packages/cli/src/commands/install/server.ts`
- [Target management](https://github.com/beeper/cli/blob/main/packages/cli/src/commands/targets/add/server.ts): `packages/cli/src/commands/targets/add/server.ts`
- [Target profiles](https://github.com/beeper/cli/blob/main/packages/cli/src/lib/targets.ts): `packages/cli/src/lib/targets.ts`
- [OAuth PKCE](https://github.com/beeper/cli/blob/main/packages/cli/src/lib/oauth.ts): `packages/cli/src/lib/oauth.ts`
- [API client setup](https://github.com/beeper/cli/blob/main/packages/cli/src/lib/client.ts): `packages/cli/src/lib/client.ts`
- [Desktop credentials](https://github.com/beeper/cli/blob/main/packages/cli/src/lib/desktop-auth.ts): `packages/cli/src/lib/desktop-auth.ts`
- [Device verification](https://github.com/beeper/cli/blob/main/packages/cli/src/commands/verify/start.ts): `packages/cli/src/commands/verify/start.ts`

### Chat operations

- [Accounts and bridges](https://github.com/beeper/cli/blob/main/packages/cli/src/commands/accounts/add.ts): `packages/cli/src/commands/accounts/add.ts`
- [Chat management](https://github.com/beeper/cli/blob/main/packages/cli/src/commands/chats/search.ts): `packages/cli/src/commands/chats/search.ts`
- [Message operations](https://github.com/beeper/cli/blob/main/packages/cli/src/commands/messages/search.ts): `packages/cli/src/commands/messages/search.ts`
- [Contact search](https://github.com/beeper/cli/blob/main/packages/cli/src/commands/contacts/search.ts): `packages/cli/src/commands/contacts/search.ts`
- [Send messages](https://github.com/beeper/cli/blob/main/packages/cli/src/commands/send/text.ts): `packages/cli/src/commands/send/text.ts`

### Automation and data

- [Data export](https://github.com/beeper/cli/blob/main/packages/cli/src/commands/export.ts): `packages/cli/src/commands/export.ts`
- [Export engine](https://github.com/beeper/cli/blob/main/packages/cli/src/lib/export/index.ts): `packages/cli/src/lib/export/index.ts`
- [Events and watch](https://github.com/beeper/cli/blob/main/packages/cli/src/commands/watch.ts): `packages/cli/src/commands/watch.ts`
- [Stdio RPC](https://github.com/beeper/cli/blob/main/packages/cli/src/commands/rpc.ts): `packages/cli/src/commands/rpc.ts`
- [Raw API requests](https://github.com/beeper/cli/blob/main/packages/cli/src/commands/api/request.ts): `packages/cli/src/commands/api/request.ts`
- [Plugin extensions](https://github.com/beeper/cli/blob/main/packages/cli/src/commands/plugins.ts): `packages/cli/src/commands/plugins.ts`

### Other components

- **User or agent**
- **Beeper API target**
- **Export files**
- **Signed webhooks**

## Connections

- User or agent → CLI launcher: runs commands
- CLI launcher → Setup workflow: dispatches setup
- CLI launcher → Target management: dispatches targets
- Setup workflow → Install targets: installs
- Setup workflow → Target profiles: reads and writes
- Setup workflow → OAuth PKCE: authorizes remote
- Setup workflow → Desktop credentials: adopts session
- Target management → Target profiles: updates profiles
- API client setup → Target profiles: resolves target
- API client setup → Desktop credentials: obtains token
- API client setup → Beeper API target: creates API client
- Accounts and bridges → API client setup: creates client
- Chat management → API client setup: creates client
- Message operations → API client setup: creates client
- Contact search → API client setup: creates client
- Send messages → API client setup: creates client
- Device verification → API client setup: uses target client
- Data export → API client setup: creates client
- Data export → Export engine: runs export
- Export engine → Beeper API target: reads chat data
- Export engine → Export files: writes export
- Events and watch → API client setup: connects to target
- Events and watch → Signed webhooks: dispatches events
- Stdio RPC → API client setup: uses target client
- Raw API requests → API client setup: creates client
- Plugin extensions → CLI launcher: extends commands