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

# Installs software; needs Homebrew or uv plus network.
brew install bex-co/tap/bea      # macOS and Linuxbrew
uv tool install beancount-io     # anywhere with uv and Python 3.12+

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 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

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

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, Beancount v3, Beanquery, Pydantic, and a vendored Fava reporting subset (it does not start the Fava web interface). src/cli/ holds command UX; src/fava/ the vendored library (retain NOTICE.fava attribution); 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.

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

MIT © Beancount.io. Vendored Fava attribution is preserved in NOTICE.fava.