Give your AI agent a ledger: the bea accounting CLI is here

You already hand your AI agent your codebase, your terminal, and your hardest debugging sessions. Now hand it your books — with every entry it drafts passing through a preview you approve and a validator that checks the math. The bea command-line tool installs in two commands, works on plain-text ledger files on your own machine, and needs no account for local bookkeeping.

Install it in two commands​

There are two published ways to get the same command. Pick the one that fits your machine, then confirm it answers with its version:

$ uv tool install beancount-io
$ brew install bex-co/tap/bea
$ bea --version
bea 0.1.0

The Python distribution is beancount-io and the executable it installs is bea, currently at version 0.1.0. The uv path works anywhere with Python 3.12 or newer; the Homebrew path covers macOS and Linux. The full walkthrough lives on the install page, with the same steps in the CLI quick start.

Your agent's first task takes minutes​

You do not need a new agent, a plugin, or a platform migration. Paste this into the shell-capable AI agent you already use, in a fresh empty demo directory:

You have shell access and the bea CLI installed. First run bea --help and read what it offers. Then, in a NEW empty demo directory (do not touch any existing ledger): 1) create a USD ledger opening Assets:Checking at 1000 on 2026-08-01; 2) add a 12.50 USD purchase narrated "Coffee" to Expenses:Dining on 2026-08-02; 3) run bea check; 4) report the Assets:Checking balance together with the exact BQL query you used. Expected result: 987.50 USD.

The same steps as plain commands:

$ bea --no-input init demo-books --currency USD --date 2026-08-01 --opening-balance "Assets:Checking 1000"
$ cd demo-books
$ bea add transaction --date 2026-08-02 --narration "Coffee" --posting "Expenses:Dining 12.50" --posting "Assets:Checking"
$ bea check
$ bea query "SELECT account, sum(position) WHERE account = 'Assets:Checking' GROUP BY account"

Expected result: Assets:Checking holds 987.50 USD — 1000 minus 12.50, validated by check and reported back with the query that computed it. When your agent hands you that number, it has done its first closed loop: draft, validate, report. The agent guide builds on the same loop with two fuller recipes — importing a bank CSV with preview-first review, and answering a balance question from query output.

What you need, and who this fits​

A terminal, a network connection, and either Homebrew or uv with Python 3.12 or newer. Local import, query, report, and check commands need no Beancount.io account, and your ledger files stay in a directory you choose as plain text you can diff, back up, and version-control.

This fits technical founders keeping their own startup books, independent developers who already live in a terminal, and agent builders looking for a ledger an AI can draft changes against without silent writes. If your books already live in a cloud product, the honest answer is different — see the comparison section below.

The hosted path is optional and separate​

Nothing above needs an account or sends your ledger anywhere. Two extras do, and both are deliberately separate from installing the CLI:

• bea ask answers questions about a local ledger through the hosted AI service. It needs the ask extra — uv tool install 'beancount-io[ask]' — plus your Beancount.io credentials. The default installation omits the AI dependencies until you ask for them.
• The MCP server and hosted ledgers likewise sign in with your Beancount.io account to authorize access. Agent skills for Beancount live in the product repository and load into your agent separately — installing the CLI does not install or configure them.

Start local; connect hosting only if you want it.

Proof: one agent, three rows, checked books​

A launch claim is only as good as its reproduction. So alongside the CLI ships a synthetic three-row challenge with an answer derived from arithmetic before any report ran: books open on 2026-09-01 with 1000 USD in checking, the statement carries a 2000.00 USD client payment, a −29.00 USD hosting bill, and a −12.50 USD cafe visit, and the expected answers are 2958.50 USD in checking (1000 + 2000 − 29 − 12.50) and 1958.50 USD of September profit (2000 − 29 − 12.50).

An installed-CLI verifier runs the whole loop in a fresh temporary directory: preview reports 3 ready and writes nothing, the first apply writes 3 entries, an identical reimport writes 0 with ledger bytes preserved, an unbalanced write (−5 checking against +4 dining) exits 1 with bytes preserved, and check returns valid. The exact inputs are downloadable as main.bean, statement.csv, and rules.toml.

Then one real agent ran the same challenge: client muse 1.1.1 (Muse Code) with model muse-spark-1.3-contributor, headless, 22 tool calls, exit 0, no human interventions — and critically, no rules.toml supplied, so the agent derived its own categorization. It previewed 3 ready, applied 3 entries, ran a clean check, and reported 2958.50 USD checking and 1958.50 USD September profit, both re-verified afterwards against the independent expected values. The full record — actual prompt, every tool call, and the one real failure it diagnosed itself (a sandboxed cache lock, fixed by pointing XDG_CACHE_HOME inside the workdir) — is published as the recorded run, with the raw transcript alongside it.

The terminal session below is a deterministic replay of that run's working path, rebuilt from the canonical downloads by demo-replay.sh — it re-enacts the commands, so it embeds the categorization rules for determinism rather than re-deriving them. The captured output in demo-replay.txt carries the same information as watching it:

$ bea --version
bea 0.1.0
$ bea import (preview)
csv → Assets:Checking: 3 ready, 0 exact duplicates, 0 possible duplicates
$ bea import --apply
Wrote 3 entries to $WORK/books/main.bean.
$ bea check
$WORK/books/main.bean: no errors
$ bea balance Assets:Checking
    Checking                                      2,958.50 USD
$ bea report income-statement -t 2026-09
Net Profit: 1,958.50 USD
checking: 2958.50 USD (expected)
profit: 1958.50 USD (expected)
REPLAY OK: preview 3/0, applied 3, check clean, 2958.50 / 1958.50 USD.

Two honest limits travel with this evidence. It is CLI-output verification of one run of one client on synthetic data — not a model benchmark, and it claims nothing about other clients or unattended production use. And a passing check proves the ledger balances, never that the agent picked the right account for the cafe: category judgment is the agent's, structural validation is bea's. A three-row toy tests the loop, not the judgment.

Choosing between tools​

If you are picking a ledger for agent workflows rather than sold on this one, read the five-tool comparison: Beancount.io, Xero, QuickBooks Online, Puzzle, and hledger scored on the same seven agent-workflow criteria — installation, authentication, read/write scope, local versus cloud data, preview and validation, structured output, and repeated-import behavior — with dated official sources checked 2026-09-10. Beancount.io is the only tool there with an observed end-to-end run behind it; the page says so, names its publisher, and labels what it did not test.

Where to go from here​

• Install page — the two commands, the first task, and the challenge downloads in one place.
• CLI quick start — installation plus the 987.50 USD worked example.
• Agent guide — two recipes: CSV import with preview-first review, and balance questions from query output.
• Recorded run — the full proof story with methodology, failures, and limits.
• Five-tool comparison — which tool fits which agent workflow.

Simplify Your Financial Management​

The fastest way to judge any of this is the demo above: install bea, paste the task into the agent you already use, and check the 987.50 USD yourself. Beancount.io provides plain-text accounting that keeps every balance reproducible and every change reviewable — no black boxes, no vendor lock-in. Give your agent its first ledger and see what it hands back.