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

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

If you do not use Homebrew, install [uv](https://docs.astral.sh/uv/) and use `uv tool install beancount-io`. The Python package requires Python 3.12 or newer. Homebrew provisions the accounting engine during installation. With PyPI, keep `uv` available: the first local command downloads the managed engine, then later commands reuse it offline. You do not need to install Beancount separately.

## 2. Create your ledger

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

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

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

```bash
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:

```bash
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:

```bash
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 -i main.bean` to align its columns in place. Without `-i`, formatted text goes to stdout and the file stays unchanged. 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:

```bash
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](https://beancount.io/docs/Solutions/import-bank-exports-cli) with a preview and duplicate review.
- [Hand an external agent two bookkeeping jobs](https://beancount.io/docs/Solutions/accounting-with-ai-agents) with copyable prompts and CLI equivalents.
- [Compare five accounting tools for AI agents](/compare/best-accounting-tools-for-ai-agents) on installation, authentication, scope, data, preview, output and repeats, with dated sources.
- [Look up commands and options](https://beancount.io/docs/bea-cli-reference) for accounts, balances, investments, reports, and automation.
- [Organize a ledger across files](https://beancount.io/docs/Tips/multi-file-support). Use `--into` to write an included file while validating against the root.
- [Use the browser interface](https://beancount.io/docs/add-your-first-transaction-ui) 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.