bpr

Better Beeper CLI for Agents

A Beeper Desktop CLI designed for LLM agents: short stable ids, output that switches to JSON when piped, structured errors with hints, and a one-shot prime contract. Wraps the official Go SDK (github.com/beeper/desktop-api-go/v5).

Requirements

• Go 1.24+
• Beeper Desktop running locally, with BEEPER_ACCESS_TOKEN set

Install

go install github.com/doublej/bpr@latest   # puts `bpr` on your PATH

Or grab a prebuilt binary from the latest release, or build from source:

git clone https://github.com/doublej/bpr && cd bpr
just build-release   # → bin/bpr

Getting Started

export BEEPER_ACCESS_TOKEN=…   # bpr prime shows whether it is detected
bpr prime                      # the full agent contract
bpr chats list                 # dense table on a TTY, JSON when piped
bpr chats list | jq            # auto-JSON on pipe

Commands

Command	Description
bpr prime	print the full agent contract (commands, ids, output, errors)
bpr doctor	check token, connectivity, and account health (exit 1 if unhealthy)
bpr chats list · chats search <q> · chats get <id> · chats stale [--days N]	list / search / inspect / find quiet chats
bpr messages list <chat> · messages search <q> · messages get <id>	list / search (with filters) / inspect messages
bpr count messages <q> · count chats <q>	how many match — a bare number, no bodies fetched
bpr open @1 · open @last	re-expand a saved result ref into its full record
bpr send <chat> <text>	send a message (prints only the new id; --dry-run to preview)
bpr takeout <chat> --out chat.md	export a chat's full history to a Markdown file
bpr pick chats [q] · pick messages <chat>	choose an id via fzf (interactive) or a plain list (agent)
bpr watch add <chat> · watch check [--peek] · watch list · watch rm <chat>	subscribe to a chat; check returns only messages newer than your last check
bpr accounts list · contacts list --account <id>	accounts / per-account contacts
bpr config set <key> <value>	save defaults (limit, account, format, auth-ttl)
bpr auth login [--ttl 12h] · auth status · auth logout	cache the token for this directory (macOS Keychain) so you can unset BEEPER_ACCESS_TOKEN
bpr upgrade · bpr version	how to update / print the version

Global flags (accepted anywhere on the line): --json, --limit N, --account <id>, --fields a,b, --out <file>, -q. IDs are short and stable (CHT-, MSG-, ACC-, USR-) and can be passed straight back into the next command. The most recent list/search is also addressable positionally as @1..@N and @last.

search and count accept a compact query syntax mixed with literal words — from:me, has:media|image|video|link|file, is:group|single, and after:/before: taking 2026-01-01, an RFC3339 time, or a relative offset (7d/2w/12h). Example: bpr messages search "dinner from:me has:image after:7d".

Development

Command	Description
just run -- <args>	run the CLI
just check	all quality gates (just-fmt, loc, dir, fmt, vet, test)
just smoke	live smoke test (needs BEEPER_ACCESS_TOKEN)
just build-release	stripped release binary into bin/

See CLAUDE.md for the package tree and the SDK adapter boundary.