{"id":50373683,"url":"https://github.com/beeper/cli","last_synced_at":"2026-05-30T08:30:27.431Z","repository":{"id":334305826,"uuid":"1140933434","full_name":"beeper/cli","owner":"beeper","description":"One CLI for all your chats","archived":false,"fork":false,"pushed_at":"2026-05-18T02:17:09.000Z","size":1824,"stargazers_count":9,"open_issues_count":0,"forks_count":3,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-18T03:50:43.225Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/beeper.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-01-24T00:28:03.000Z","updated_at":"2026-05-18T02:17:12.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/beeper/cli","commit_stats":null,"previous_names":["beeper/desktop-api-cli","beeper/cli"],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/beeper/cli","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/beeper%2Fcli","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/beeper%2Fcli/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/beeper%2Fcli/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/beeper%2Fcli/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/beeper","download_url":"https://codeload.github.com/beeper/cli/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/beeper%2Fcli/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33686018,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-05-30T02:00:06.278Z","response_time":92,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-05-30T08:30:26.654Z","updated_at":"2026-05-30T08:30:27.423Z","avatar_url":"https://github.com/beeper.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# beeper — One CLI for all your chats\n\n\u003e Built for you and your agent. Batteries included.\n\nTalks to Beeper Desktop on this machine, to a Beeper Server you self-host, or\nto either one running somewhere else. Send and receive across the chat\nnetworks Beeper bridges, from one CLI shaped for scripts, agents, and humans\nin a hurry.\n\n**Supported chat networks** (via Beeper's bridges):\nWhatsApp · iMessage · Telegram · Discord · Signal · Instagram DMs ·\nFacebook Messenger · X (Twitter) DMs · LinkedIn · Slack ·\nGoogle Messages (RCS/SMS) · Google Chat · Matrix · IRC · Bluesky.\nRun `beeper bridges list` for the live list on your target.\n\nCommand manual: `beeper man` · CLI docs: `beeper docs`\n\n## Features\n\n- **Connects to your Beeper.** Local Beeper Desktop on this machine (default), a Beeper Server you install and manage via the CLI, or a remote Beeper Desktop or Beeper Server authorized over OAuth/PKCE — or a bearer token in CI.\n- **Setup that does the work.** `beeper setup` finds Beeper Desktop, offers to launch it, adopts the session. `--server --install` installs and starts a headless server in one step. `--oauth` opens the browser. `--remote URL` does the rest.\n- **Every chat, every network.** List, search, start, archive, pin, mute, rename, focus. Read, edit, delete, react. Send text, files, stickers, voice, typing indicators. Download media. Export to JSON or Markdown.\n- **Verification first-class.** SAS/QR device verification, recovery-key unlock, `status`/`doctor` to reach an encrypted-ready target — without leaving the shell.\n- **Agent-shaped automation.** `--json` everywhere, NDJSON `--events`, `watch` with WebSocket + outbound HMAC-signed webhooks, `rpc` over stdin/stdout, `man --json` tool manifests, raw `api get`/`post`/`request` for Beeper Client API endpoints we haven't wrapped yet.\n- **Safe by default.** `--read-only` rejects every mutating command. Writes stay explicit. Plugins extend the CLI without forking it.\n\n## Install\n\n### Homebrew (recommended)\n\n```sh\nbrew install beeper/tap/cli\n```\n\nThe installed command is `beeper`.\n\n### npm\n\n```sh\nnpx beeper-cli --help\nnpm install -g beeper-cli\n```\n\nThe package name is `beeper-cli`; the installed command is `beeper`.\n\n### Build from source\n\nThis repo is a Bun workspace. From the repo root:\n\n```sh\nbun install\nbun --filter @beeper/cli run build\nbun --filter @beeper/cli run dev -- --help\n```\n\nFor local CLI development inside `packages/cli`:\n\n```sh\nbun run dev -- --help\n```\n\nRegenerate this README after command, flag, or argument changes:\n\n```sh\nbun run readme\n```\n\n## Quick start\n\nThe happy path: Beeper Desktop is already on this machine. `beeper setup` finds\nit, offers to launch it if it's not running, and adopts the session.\n\n```text\n$ beeper setup\nLooking for Beeper Desktop… found, not running.\nLaunch it now? [Y/n] y\n▎ Launched   Beeper Desktop\n  next       Run `beeper setup` again once it finishes starting.\n\n$ beeper setup\nUse this Desktop session for CLI access? [Y/n] y\n▎ Connected  desktop\n  accounts   whatsapp, telegram, imessage\n  endpoint   http://127.0.0.1:23373\n\n$ beeper chats list --limit 3\n  10313  Family             3 unread\n   8951  Alice              ·\n   7204  Eng standup        12 unread\n\n$ beeper messages search \"flight\"\n   8951  Alice    · \"your flight is at 6:40, gate B23\"   2d ago\n  10313  Family   · \"what flight are you on?\"            1w ago\n\n$ beeper send text --to Family --message \"on my way\"\n▎ Sent       Family\n  message    \"on my way\"\n  at         2026-05-18T14:02:11Z\n\n$ beeper export --out ./beeper-export\n▎ Exported   ./beeper-export\n  chats      214   messages   38,901   attachments 1,205\n```\n\nRecipients accept a numeric local chat ID, a full Beeper/Matrix chat ID, an\niMessage chat ID, an exact title, or search text. Ambiguous matches prompt in a\nTTY; pass `--pick N` in scripts.\n\n## Connecting a target\n\nA *target* is the Beeper endpoint `beeper` talks to — local Beeper Desktop,\nlocal Beeper Server, or a remote Beeper Desktop or Beeper Server. Pick one of\nfour paths.\n\n### 1. Local Beeper Desktop (default, recommended)\n\nIf Beeper Desktop is installed and signed in here, `beeper setup` discovers it\non `http://127.0.0.1:23373` and adopts the existing session. If it's installed\nbut not running, `setup` offers to launch it. If it's not installed at all,\n`--install` does that in one step.\n\n```text\n$ beeper setup --desktop --install\n▎ Installed   Beeper Desktop (stable)\n▎ Launched    Beeper Desktop\n  next        Sign in to Beeper Desktop, then re-run `beeper setup`.\n\n$ beeper setup\n▎ Connected   desktop\n  accounts    whatsapp, telegram\n```\n\nVariants: `beeper setup --local` to skip discovery and force the local path;\n`beeper install desktop --channel nightly` for the nightly channel.\n\n### 2. Local Beeper Server (self-hosted, managed by the CLI)\n\nFor a headless long-running setup on this machine, install and adopt a local\nBeeper Server. The CLI manages the process — `targets start/stop/restart/logs/enable`.\n\n```text\n$ beeper setup --server --install\n▎ Installed   Beeper Server (stable)\n▎ Started     server on http://127.0.0.1:23373\n  auth        Opening browser to authorize this server…\n▎ Connected   server\n  accounts    (none)\n  next        Run `beeper accounts add` to connect a network.\n\n$ beeper accounts add\n? Which bridge?  whatsapp\n  Scan this QR code with WhatsApp on your phone:\n    ▄▄▄▄▄▄▄  ▄ ▄  ▄▄▄▄▄▄▄\n    █ ███ █  ▄█▄  █ ███ █\n    █ ███ █  ▀█▀  █ ███ █\n    ▀▀▀▀▀▀▀  ▀ ▀  ▀▀▀▀▀▀▀\n▎ Connected   whatsapp · +1•••4242\n```\n\nVariants: `beeper install server`, `beeper install server --server-env staging`.\n\n### 3. Remote Desktop or Server via OAuth (PKCE)\n\nFor a Beeper Desktop or Server running on another machine, authorize the CLI\nthrough a browser-based OAuth/PKCE flow.\n\n```text\n$ beeper setup --remote https://desktop.example.com\n▎ Authorizing  https://desktop.example.com\n  flow         OAuth (PKCE) — opening browser…\n▎ Connected    remote (desktop.example.com)\n  accounts     whatsapp, telegram, signal\n```\n\nVariants: `beeper setup --oauth` (PKCE against the default Beeper auth);\n`beeper targets add remote work https://desktop.example.com --default` to\nregister additional remotes.\n\n### 4. Bearer token (non-interactive / CI)\n\nFor agents, CI, and scripts, hand the CLI a bearer token directly — no\nbrowser, no interactive prompts.\n\n```sh\nBEEPER_ACCESS_TOKEN=... beeper chats list --json\nBEEPER_ACCESS_TOKEN=... BEEPER_DESKTOP_BASE_URL=https://desktop.example.com \\\n  beeper messages list --chat 10313 --json\n```\n\nOnce connected, `beeper accounts add` walks each chat-network bridge through\nits own login — QR, code, OAuth, cookie, whatever the bridge requires — so\nWhatsApp, Telegram, Discord, iMessage, and the rest show up under `accounts list`.\n\n## Documentation\n\n| Topic | Page | Commands |\n| --- | --- | --- |\n| **Setup + install** | [setup](docs/setup.md) · [auth](docs/auth.md) | `setup` · `install desktop` · `install server` · `verify` · `status` · `doctor` · `auth status` |\n| **Targets** | [targets](docs/targets.md) | `targets list` · `targets add desktop` · `targets add server` · `targets add remote` · `targets use` · `targets status` · `targets logs` |\n| **Bridges + accounts** | [accounts](docs/accounts.md) | `bridges list` · `bridges show` · `accounts list` · `accounts add` · `accounts show` · `accounts use` · `accounts remove` |\n| **Chats** | [chats](docs/chats.md) | `chats list` · `chats search` · `chats show` · `chats start` · `chats archive` · `chats pin` · `chats mute` · `chats priority` · `chats remind` · `chats rename` · `chats draft` · `chats focus` |\n| **Messages** | [messages](docs/messages.md) · [send](docs/send.md) · [presence](docs/presence.md) | `messages list` · `messages search` · `messages export` · `send text` · `send file` · `send sticker` · `send voice` · `send react` · `presence` |\n| **Contacts + media** | [contacts](docs/contacts.md) · [media](docs/media.md) · [export](docs/export.md) | `contacts list` · `contacts search` · `media download` · `export` |\n| **Automation** | [watch](docs/watch.md) · [rpc](docs/rpc.md) · [api](docs/api.md) | `watch` · `watch --webhook` · `rpc` · `man` · `api get` · `api post` · `api request` |\n| **Maintenance** | [config](docs/config.md) · [update](docs/update.md) | `update` · `config` · `completion` · `docs` · `version` |\n\nUse `beeper docs` to open the CLI docs and `beeper man` to print the local\ncommand manual.\n\n## Configuration\n\nDefault Beeper Client API target: `http://127.0.0.1:23373`. CLI configuration is\nstored under your user config dir; print it with `beeper config path`.\n\n**Global flags:** `--base-url`, `--target`, `--json`, `--events`,\n`--full`, `--timeout`, `--read-only`, `--debug`, `--yes`, `--quiet`.\n\n**Environment overrides:**\n\n| Variable | Effect |\n| --- | --- |\n| `BEEPER_ACCESS_TOKEN` | Bearer token for the selected target. Overrides stored OAuth login. |\n| `BEEPER_DESKTOP_BASE_URL` | Beeper Client API base URL (Desktop or Server). Defaults to `http://127.0.0.1:23373`. |\n| `BEEPER_READONLY` | `1`/`true`/`yes`/`on` enables read-only mode globally. |\n| `BEEPER_CLI_CONFIG_DIR` | Override config directory for testing or isolated profiles. |\n\n## Exit codes\n\n| Code | Meaning |\n| --- | --- |\n| `0` | Success. |\n| `1` | Generic runtime error. |\n| `2` | Usage error (parsing, validation, missing required flag/arg, read-only refusal). |\n| `3` | Auth required (no stored token; sign in or set `BEEPER_ACCESS_TOKEN`). |\n| `4` | Target/account not ready (`doctor` reports this when readiness is not `ready`). |\n| `5` | Selector matched nothing (unknown target, account, chat, contact). |\n| `6` | Ambiguous selector (multiple matches; pass an exact ID or `--pick N`). |\n\nJSON output preserves the same envelope on failure: `{\"success\":false,\"data\":null,\"error\":\"...\",\"exitCode\":N}` written to stderr.\n\n## Addressing\n\n- Chat arguments accept numeric local chat IDs, full Beeper/Matrix chat IDs, iMessage chat IDs, exact titles, or search text.\n- For scripts on the same target/profile, prefer the numeric local chat ID shown by `beeper chats list`; use the full Beeper/Matrix chat ID when the selector must work across targets or profiles.\n- Numeric local chat IDs come from the selected Desktop database. Treat them as local to that target/profile.\n- Ambiguous chat matches return numbered choices; pass `--pick N` to select one.\n- Account arguments accept account IDs, network names, bridge type/id, or account user identity.\n- Account filters can expand a network name to multiple matching accounts.\n- `contacts search` and `chats start` can search across all accounts when `--account` is omitted.\n- `contacts list` accepts the same account selectors as other account-scoped commands.\n\n## Output and scripting\n\nMost commands support:\n\n- app-like text by default, optimized for scanning chats, messages, contacts, accounts, and media\n- `--json` for `{\"success\":true,\"data\":...,\"error\":null}` output on stdout\n- `--events` for NDJSON lifecycle events on stderr from long-running commands\n- `--read-only` to reject commands that modify Beeper or local CLI state\n- `--full` to disable truncation\n- `--debug` for SDK debug logging\n- `--target` or `--base-url` to point at a different target\n\n`man --json` prints a compact command manifest for tools and agents.\n`rpc` runs newline-delimited JSON command RPC over stdin/stdout.\n\n## Raw API access\n\nRaw Beeper Client API calls live under `api`, so scripts can reach a new\nendpoint before a workflow command exists:\n\n```sh\nbeeper api get /v1/info\nbeeper api post /v1/messages/{chatID}/send --body '{\"text\":\"hello\"}'\nbeeper api request DELETE /v1/chats/abc/messages/def/reactions --body '{\"reactionKey\":\"👍\"}'\n```\n\n## Plugins\n\nBeeper CLI supports optional oclif plugins. List recommended Beeper plugins:\n\n```sh\nbeeper plugins available\n```\n\nInstall a published plugin:\n\n```sh\nbeeper plugins install @beeper/cli-plugin-cloudflare\n```\n\nFor plugin development, import from `@beeper/cli/plugin-sdk` and expose oclif\ncommands from your package. Link a local plugin while working on it:\n\n```sh\nbeeper plugins link ./packages/cli-plugin-cloudflare\nbeeper targets tunnel --help\n```\n\nFirst-party optional plugins:\n\n| Package | Adds |\n| --- | --- |\n| `@beeper/cli-plugin-cloudflare` | `targets tunnel` for exposing a selected Beeper target through Cloudflare Tunnel. |\n\n\n## Full command reference\n\nThe complete `beeper` command summary and per-command reference (every flag,\narg, and example) lives in [`packages/cli/README.md`](packages/cli/README.md).\nFor terminal-side reference, `beeper man` prints the same manual locally and\n`beeper man --json` emits a tool manifest for agents.\n\n## Inspiration\n\n- [wacli](https://wacli.sh/) — scriptable WhatsApp CLI whose command-line product shape we borrow from.\n\n## License\n\nMIT — see [`packages/cli/LICENSE`](packages/cli/LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbeeper%2Fcli","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbeeper%2Fcli","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbeeper%2Fcli/lists"}