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. Ledger-skill updates that still mention a separate Beancount install are tracked in milestone m21.

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.

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

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, 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); ledger-skill onboarding updates remain milestone m21.

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.