beancount-io

bea is the command-line interface for Beancount.io. Create and edit plain-text Beancount ledgers, import bank exports, validate accounts, run BQL queries, and generate financial reports. Local bookkeeping needs no Beancount.io account. Optional AI assistance and hosted ledger management use your Beancount.io credentials.

The Python distribution is beancount-io; its executable is bea. Run bea --version and bea COMMAND --help to check the version and options you have installed.

Contents

• Install · Quick start · Command map
• Exit codes · Learn more
• Development · Releases · License

Install

Install bea once. You do not install Beancount, Beanquery, or Fava yourself — bea manages a separate engine environment automatically.

# Installs software; needs Homebrew or uv plus network.
brew install bex-co/tap/bea      # macOS and Linuxbrew — dual venv at install time
uv tool install beancount-io     # anywhere with uv and Python 3.12+ — engine on first use

Optional Beangulp and Beanprice stay out of that base install. Enable them explicitly into the managed engine when you need ingest helpers or quote fetching:

# Needs network once; Beangulp also needs system libmagic.
bea engine enable beangulp    # then: bea ingest identify|extract|archive …
bea engine enable beanprice   # then: bea price …  (not bea add price)

bea import --csv and bea add price work without those features. The eight beancount-* ledger skills for Claude Code and Codex run on this single bea installation and never ask you to install Beancount separately — see the skills installation guide and the first-query walkthrough.

bea upgrade updates the frontend through its package manager and refreshes the matching engine. If a first-use or upgrade provision fails, retry a local command such as bea check once the network is available — do not pip install beancount.

Which bea is running?

A shell can resolve a different bea than you expect. This happens when an older install sits earlier on PATH, or when a coding agent runs commands in a login shell that rebuilds PATH. Diagnose from the shell that actually runs the command. For an agent, that means asking it to run these steps, not running them in your own terminal.

# Needs an installed bea; reads only, except the last line's check.
type -a bea              # every bea on PATH, in resolution order
bea --version            # the version this shell selects
bea engine status        # the engine it would use: managed, first-use, override, checkout
BEA=/absolute/path/to/the/bea/you/verified
"$BEA" --version && "$BEA" --file main.bean check

• An old executable shows an older --version, or a different first path in type -a. Call the verified absolute path, as in the last line, or fix PATH in the shell's startup files. For an agent session, give it that absolute path to use for every command.
• An unprovisioned engine shows the expected version, but engine status reports not provisioned; provisions on first use. That is not a version problem: the first local command, such as bea check, sets the engine up once the network is available.

The default installation omits AI dependencies. For bea ask, install the extra (or run it without replacing your bea):

# Installs software; needs uv plus network.
uv tool install 'beancount-io[ask]'
uvx --from 'beancount-io[ask]' bea ask --help

Quick start

bea --no-input init books --currency USD --date 2026-08-01 \
  --opening-balance "Assets:Checking 1000"
cd books
bea add transaction "Coffee" --date 2026-08-02 \
  --posting "Expenses:Dining 12.50" --posting "Assets:Checking"
bea check
bea format -i main.bean
bea list transaction --limit 10
bea report balance-sheet

The purchase leaves 987.50 USD in checking: the currency comes from the account and Beancount fills in the balancing posting. For a bank export, see the import guide; for your first month end to end, follow the tutorial.

Command map

Global options come before the command; --file selects the root ledger:

bea --file main.bean check
bea --json list transaction --limit 100
bea --json query "SELECT account, sum(position) GROUP BY account" -o balances.json
bea doctor region --help

Every flag, default, and help string is listed in the generated command reference.

Managed price includes

In bea 0.3.0 and later, sign in with bea cloud login (or set BEA_TOKEN for automation), choose a pair at Live Prices, then add one line to value a holding in every bea command:

include "https://beancount.io/prices/BTC-USD"

bea price status shows each source's freshness, bea price refresh re-resolves on demand and exits nonzero if any source fails, --offline reads the cache only, --strict-prices fails the load on a stale or unavailable source, and bea price export snapshots portable local includes for stock Beancount and Fava — which cannot fetch the URL themselves. The usage guide has the full contract.

Exit codes

The usage guide documents the full contract: JSON error shape, cloud HTTP mapping, prompts, and output exceptions.

Learn more

• Tutorial: your first month, from init to a month-end report.
• Usage: the contract — targets, JSON envelope, exit codes, prompts, environment.
• Importing: no-code CSV import, rules, and Python importers.
• Reference: every command's usage, arguments, and options, generated from the code.

Development

# Clones the repo and syncs dependencies; needs git and network.
git clone https://github.com/bex-co/beancount-io.git
cd beancount-io/cli
uv sync --all-groups
uv run bea --help
make check-all

Python 3.12+, Typer, and Pydantic for the beancount-io frontend. The frontend never loads Beancount, Beanquery, or Fava. The single beancount-io wheel bundles helper/Fava sources as resources; a child process runs them with automatically managed upstream dependencies. Retain NOTICE.fava and LICENSE.engine. src/cli/ holds command UX; src/bea_engine/ and src/fava/ are engine-side; tests/ the pytest suite; docs/ the guides above; openapi/v1.json the pinned contract for hosted commands. make check-all is the handoff gate: lint, deadcode, format-check, typecheck, test, spec-check, and docs-check. Do not hand-edit generated API clients, command stubs, docs/REFERENCE.md, or lockfiles; keep scratch files under tmp/. See the package guide for architecture boundaries and contribution rules. Optional Beangulp/Beanprice are enabled with bea engine enable (see Usage); the customer-facing beancount-* ledger skills live in skills/ and target this same single installation.

Releases

Releases ship to PyPI and Homebrew from cli-vX.Y.Z tags; the release guide holds the tagging procedure and one-time credentials setup.

License

Frontend: MIT © Beancount.io. Bundled ledger helper: GPL-2.0-only; vendored Fava retains its MIT notice. Vendored Fava attribution is preserved in NOTICE.fava.