Beancount CLI quick start

Create a local ledger and record your first purchase with bea, the Beancount.io command-line tool. Local bookkeeping needs no Beancount.io account.

This walkthrough starts with 1,000 USD in checking. After a 12.50 USD coffee purchase, you will verify a balance of 987.50 USD.

1. Install the command​

With Homebrew on macOS or Linux:

brew install bex-co/tap/bea
bea --version

If you do not use Homebrew, install uv and use uv tool install beancount-io. The Python package requires Python 3.12 or newer.

2. Create your ledger​

Choose a new directory. This example creates main.bean inside ~/my-books:

bea --no-input init ~/my-books --currency USD --date 2026-08-01 \
  --opening-balance "Assets:Checking 1000"
cd ~/my-books

The template opens common checking, savings, cash, credit card, income, and expense accounts. The opening balance is offset against Equity:OpeningBalances.

For your own books, choose the earliest date you intend to record. All template accounts open on that date. The opening balance must describe the account on that day. Credit card debt uses a negative amount.

init never overwrites an existing ledger. New files are private on POSIX systems: only the owner can read and write them. To share with your local user group, explicitly change the permissions with chmod 640 main.bean.

For guided setup instead, run bea init ~/my-books in a terminal. The wizard asks for your currency, history start date, and checking balance.

3. Record a purchase​

bea add transaction --date 2026-08-02 --narration "Coffee" \
  --posting "Expenses:Dining 12.50" \
  --posting "Assets:Checking"

The expense uses the account's USD currency. Beancount fills in the other posting as -12.50 USD. You can omit --date for purchases made today.

Each addition is checked against the complete ledger before the file is replaced. An unknown account or an unbalanced transaction produces an error with guidance.

4. Check the result​

bea check
bea list transaction --limit 10
bea report balance-sheet

The transaction list shows the newest entries first, with their posting amounts. The balance sheet shows 987.50 USD in checking.

To verify that amount directly:

bea query "SELECT account, sum(position) WHERE account = 'Assets:Checking' GROUP BY account"

Query tables preserve the result's precision. For structured output, put the global --json flag before the command:

bea --json list transaction --limit 10

5. Keep your books in good shape​

Run bea check after editing the file by hand. Run bea format main.bean to align its columns. Use bea format main.bean --check when a script should fail if formatting is needed.

To work from another directory, select the root file explicitly:

bea --file ~/my-books/main.bean check

The root is selected by --file, then BEA_FILE, then main.bean in the working directory. Global options go before the command. Formatting takes its own file or directory argument.

Continue with your own records​

• Import a bank export with a preview and duplicate review.
• Look up commands and options for accounts, balances, investments, reports, and automation.
• Organize a ledger across files. Use --into to write an included file while validating against the root.
• Use the browser interface if you prefer forms to terminal commands.

Check for updates with bea upgrade --check. Run bea upgrade to invoke the package manager that installed your copy. Use bea --help or bea add transaction --help to inspect the options available in your installed version.