Skip to main content

CLI

campbooks is the developer CLI for Campbooks — read and send email, manage documents, contacts, and tags, and talk to Scout, all from your terminal. It's a single static binary that wraps the public REST API.

Install​

brew install notacamp/tap/campbooks

Or build from source (Go 1.20+):

go install github.com/notacamp/campbooks/cli@latest

Sign in​

The CLI signs you in through your browser — no API keys to copy:

campbooks login

This opens your browser, you sign in with your normal Campbooks session and approve the "Campbooks CLI" client, and the CLI stores a token that refreshes itself. Point it at a self-hosted instance with --host:

campbooks login --host campbooks.example.com
campbooks whoami

Under the hood this is the OAuth 2.0 authorization-code + PKCE grant against a first-party public client — distinct from the client-credentials grant used for server-to-server access. For CI or headless use, sign in with a client-credentials client (from Settings → API access) instead:

campbooks login --client-id YOUR_ID --client-secret YOUR_SECRET
# or --no-browser to paste a code without opening a browser at all

Credentials live in ~/.config/campbooks/config.yml (mode 0600). The CLI is multi-host: campbooks config list and campbooks config use <host> switch between the cloud and self-hosted instances.

Output​

Commands print human-friendly tables by default; add --json for raw, script-friendly output (and set NO_COLOR to disable color):

campbooks emails list --unread --json | jq '.[].subject'

Commands​

Run campbooks <group> --help for the full flags of any group.

Email​

campbooks emails list --unread --category finance -q invoice
campbooks emails get 42
campbooks emails send --account 3 --to a@b.com --subject "Hi" --body "…"
campbooks emails reply 42 --body "Thanks!"
campbooks emails read 42        # · unread · tag <name> · untag <id>

Documents​

campbooks documents list --review-status pending
campbooks documents download 88 -o invoice.pdf
campbooks documents upload invoice.pdf            # AI processing is async
campbooks documents update 88 --vendor-name ACME --amount-cents 12900
campbooks documents approve 88                    # · reject · reclassify --type 3

Contacts, tags, document types​

campbooks contacts list --starred
campbooks contacts star 5                          # · unstar · allow · block · unblock
campbooks tags list
campbooks doctypes list

Scout​

campbooks scout ask "What needs my attention today?" --wait
campbooks scout threads list

Scopes & permissions​

campbooks login requests the full scope set, but scopes are only a ceiling — every request is still gated by your own permissions (you can only send from accounts you may send from, see emails you may see, and so on). See Scopes for the full list, and the interactive API reference for every endpoint the CLI calls.

Last updated on