For technical founders, developers, and agent builders
Give your AI agent a ledger
Install the bea command-line tool, then paste one task into the shell-capable AI agent you already use. Minutes later it hands back a validated local ledger — no Beancount.io account required.
Install bea
Two published ways to get the same command. Pick the one that fits your machine, then confirm it answers with its version.
With uv (anywhere with Python 3.12 or newer)
uv tool install beancount-ioWith Homebrew (macOS or Linux)
brew install bex-co/tap/beabea --versionExample verified with bea 0.1.0: the Python distribution is beancount-io and the executable it installs is bea.
What you need
A terminal, a network connection, and either Homebrew or uv with Python 3.12 or newer. Local bookkeeping needs no Beancount.io account — that only enters the picture for the optional hosted step below.
Your books stay on your machine
Every command below works on plain-text .bean files in a directory you choose. New ledger files are private to your user, and each addition is validated against the complete ledger before the file is replaced — on the default local CLI path, an unknown account or an unbalanced transaction is an error with guidance, and the file is left untouched.
Your agent's first task
Paste this into your agent. It starts with 1,000 USD in checking, records a 12.50 USD coffee, validates the ledger, and reports back the balance with the query it used.
Agent task prompt
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.
Read the CLI quick startOptional: hosted AI help
Nothing above needs an account or sends your ledger anywhere. Two optional extras do, and both are 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 MCP server and hosted ledgers likewise sign in with your Beancount.io account to authorize access. Start local; connect hosting only if you want it.
Agent skills for Beancount live in the product repository and load into your agent separately — installing the CLI does not install or configure them.
Questions agent builders ask
Do I need a Beancount.io account?
Not for anything on this page. Installing bea, creating a local ledger, recording purchases, and checking balances all work without an account. You only sign in for the optional hosted extras: bea ask, the MCP server, and hosted ledgers.
Does installing the CLI set up my AI agent?
No. Installing gives you the bea command; your agent stays exactly as it is. You paste the task above into the shell-capable agent you already use, and loading agent skills is a separate step of its own.
Does my ledger leave my machine?
Local commands work on local .bean files and make no network calls. Only the hosted commands — bea cloud and bea ask, whose model calls run through the hosted AI proxy — talk to Beancount.io services.
What happens if my agent writes a bad entry?
On the default local CLI path, every addition is checked against the complete ledger before the file is replaced. An unknown account or an unbalanced transaction fails with guidance and leaves your file untouched — have the agent run bea check after any hand edit, too.
What exactly does bea ask need?
Two things beyond this page: the ask dependency extra and hosted credentials to sign in with. The default bea installation intentionally omits the AI dependencies until you ask for them.
Start with coffee, stay for the books
One install, one pasted task, one verified balance — then keep going with the full quick start.