API v1 · agent-friendly docs
CLI for agents & shell
Use @bennybooks/cli to wire Streamable HTTP MCP and run curated ledger commands from the terminal.
MCP is the product for IDE and chat agents. The CLI is the installer plus shell/CI companion — same bb_live_ token, same proposal-only writes, not a second API.
| Host | Prefer |
|---|---|
| Cursor / Claude / Codex with MCP | Streamable HTTP tools at /api/mcp |
| Terminal, scripts, CI | @bennybooks/cli (JSON) or REST /api/v1 |
Do not thrash
If BennyBooks MCP tools are already registered in the host, prefer those tools. Do not shell the CLI as a substitute.
Install
npx
npx @bennybooks/cli --help
# or
npm i -g @bennybooks/cliEnable an agent
- Create a bb_live_ token in Settings → MCP & agents (read or propose-write)
- export BENNYBOOKS_TOKEN=bb_live_… (optional BENNYBOOKS_URL)
- npx @bennybooks/cli agent setup — merges ~/.cursor/mcp.json and prints Claude/Codex steps
- Restart / reload MCP; confirm list_transactions is available
Dry-run MCP config
npx @bennybooks/cli agent mcp-configCurated commands
| Command | Maps to |
|---|---|
| auth set-token | whoami | logout | Local config + dashboard check |
| agent setup | mcp-config | Wire /api/mcp |
| transactions list | get | GET /api/v1/transactions |
| dashboard summary | GET /api/v1/dashboard/summary |
| categories list | GET /api/v1/categories |
| proposals list | GET /api/v1/proposals |
| propose categorize | POST /api/v1/proposals/categorization |
All commands print JSON to stdout. Writes create pending proposals until a human approves in Ledger → Approvals (also recorded in Log).
Agent skill
Install from this repo
npx skills add . --skill bennybooks -y
# source folder: agent-skills/bennybooks/SKILL.mdRemote playbook: https://bennybooks.com/skill.md · Auth: https://bennybooks.com/auth.md · Native MCP: Connect Streamable HTTP MCP.