beancount-cli

A robust command-line interface and Python library for programmatically managing Beancount ledgers. Designed for AI agents and automation workflows.

Features

• Validation: Wrap bean-check to validate ledgers programmatically.
• Visualization: View the file inclusion tree (tree command).
• Transactions:
  • List transactions with regex filtering (account, payee, tags).
  • Add transactions via CLI arguments or JSON (stdin supported).
  • Draft mode support (flag !).
• Entities:
  • Manage Accounts (list, create, balance assertion).
  • Manage Commodities (list, create, check undeclared).
  • Manage Prices (check gaps, fetch/update via bean-price).
• Formatting:
  • Auto-format ledgers (bean-format wrapper).
  • Global output formatting: --format support (table, json, csv) for all data commands.
• Reporting: Generate balance, holding, and audit reports with multi-currency conversion.
• Composability: Built for Unix piping (json | csv) and batch processing via STDIN.
• JSONL Stream Execution: bean exec dispatches a mixed-command JSONL stream to the ledger; --dry-run previews the result without writing.
• Configuration: Custom Beancount directives for routing new entries to specific files.
• Tab Completion: We provide tab completions for bash and zsh.

Installation

Install using uv or pip:

uv pip install beancount-cli
# or
pip install beancount-cli

For development:

uv sync

For setting up tab completion for your shell, see Tab Completion under Configuration.

Global Formatting Flag

All data-retrieval and reporting commands support the --format flag.

# Default human-readable table
bean report bs

# Machine-readable CSV (highly token-efficient for AI agents)
bean --format csv transaction list

# Structural JSON (perfect for piping into jq or other scripts)
bean --format json account list

Check Ledger

Validate your ledger file:

bean check main.beancount

Format Ledger

Format your ledger file in-place (uses bean-format):

bean format main.beancount

View Inclusion Tree

Visualize the tree of included files:

bean tree main.beancount

Reports

Generate specialized accounting reports with multi-currency support:

# Balance Sheet (Assets, Liabilities, Equity)
bean report balance-sheet main.beancount

# Trial Balance (All accounts including Income/Expenses)
bean report trial-balance main.beancount

# Holdings (Net worth per Asset account)
bean report holdings main.beancount

# Audit a specific currency (Source of Exposure)
bean report audit --currency USD main.beancount

Unified Currency Reporting

Use the --convert and --valuation flags for a consolidated view:

# View Trial Balance in USD using historical cost
bean report trial main.beancount --convert USD --valuation cost

# View Balance Sheet in EUR using current market prices
bean report bs main.beancount --convert EUR --valuation market

List Transactions:

bean transaction list main.beancount --account "Assets:US:.*" --payee "Amazon"

Add Transaction:

# JSON via argument
bean transaction add main.beancount --json '{"date": "2023-10-27", ...}'

# JSON via stdin (Recommended for complex data)
cat tx.json | bean transaction add main.beancount --json -

# Create as Draft (!)
bean transaction add main.beancount --json ... --draft

JSONL Stream Execution

Use bean exec to dispatch a mixed-command JSONL stream (one JSON object per line) to the ledger in a single pass.

Each line must contain a _cmd field mapping to any CLI command (transaction.add, account.create, commodity.create, etc.). Use _opts to pass CLI flags that cannot go through the payload.

# Write a mixed stream to the ledger
cat commands.jsonl | uv run bean exec

# Preview without writing
cat commands.jsonl | uv run bean exec --dry-run

# Continue after errors, collect all failures
cat commands.jsonl | uv run bean exec --ignore-errors 2>errors.log

Example JSONL line:

{"_cmd": "transaction.add", "_opts": {"draft": true}, "date": "2024-01-01", "narration": "Buy coffee", "postings": [{"account": "Expenses:Food", "units": {"number": 5, "currency": "USD"}}, {"account": "Assets:Cash", "units": {"number": -5, "currency": "USD"}}]}

Manage Accounts & Commodities

All creation commands (transaction add, account create, commodity create) support batch processing via JSON arrays on STDIN. Use --target to override the destination file.

# Batch add transactions from a file
cat txs.json | bean transaction add --json -

# Pipe accounts from one ledger to another
bean --format json account list --file old.beancount | bean account create --json -

Accounts:

# List accounts
bean account list

# Create account
bean account create --name "Assets:NewBank" --currency "USD"

# Add a balance assertion
bean account balance --json '{"date": "2024-01-01", "account": "Assets:Bank", "amount": {"number": 1000, "currency": "USD"}}'

Commodities:

# List all declared commodities
bean commodity list

# List by asset class
bean commodity list --asset-class stock

# Find currencies used in transactions but missing a commodity directive
bean commodity check

# Create a commodity
bean commodity create "BTC" --name "Bitcoin"

Prices:

# Check for periods of missing price data
bean price check

# Check with weekly rate and 14-day tolerance
bean price check --rate weekly --tolerance 14

# Fetch latest quotes (dry run)
bean price fetch --dry-run

# Fetch and write new prices to the ledger
bean price fetch --update

beancount-cli is specifically optimized for AI agents, providing both operational guidance and machine-readable interfaces.

Agent Documentation

We provide specialized documentation for different types of AI interactions:

• AGENTS.md: Guide for AI End Agents operating the CLI (prompting strategies, token optimization, batch workflows).
• CODING_AGENTS.md: Mandatory rules for AI Coding Agents modifying the source code (Value Objects, Fail-Fast rules, type safety).

Transaction Schema

Agents can dynamically retrieve the JSON schema for transactions to ensure valid data generation:

bean transaction schema

Complex Transaction Example

Agents should aim to generate JSON in this format for a standard purchase with multiple postings:

{
  "date": "2023-10-27",
  "payee": "Amazon",
  "narration": "Office supplies",
  "postings": [
    {
      "account": "Expenses:Office:Supplies",
      "units": { "number": 45.99, "currency": "USD" }
    },
    {
      "account": "Liabilities:US:Chase:Slate",
      "units": { "number": -45.99, "currency": "USD" }
    }
  ]
}

Scripting with uv run

For reliable cross-platform execution in agent workflows:

uv run bean transaction add --json - < tx.json

Configuration

Ledger Discovery

bean uses a 4-tier discovery logic to find your ledger file automatically:

1. Explicit Argument: Passing the filename directly (e.g. bean check my.beancount).
2. BEANCOUNT_FILE: Direct path to a ledger file.
3. BEANCOUNT_PATH: Looks for main.beancount inside this directory.
4. Local Directory: Fallback to ./main.beancount.

Custom Directives

You can configure where new entries are written using custom directives in your Beancount file.

Note: custom directives require a date (e.g. 2023-01-01).

2023-01-01 custom "cli-config" "new_transaction_file" "inbox.beancount"
2023-01-01 custom "cli-config" "new_account_file" "accounts.beancount"
2023-01-01 custom "cli-config" "new_commodity_file" "commodities.beancount"

Context-Aware Insertion: You can use placeholders to route transactions to dynamic paths:

2023-01-01 custom "cli-config" "new_transaction_file" "{year}/{month}/txs.beancount"

Supported placeholders: {year}, {month}, {day}, {payee}, {slug}.

Directory Mode (One file per transaction): If new_transaction_file points to a directory, bean will create a new file for each transaction inside that directory, named with an ISO timestamp.

2023-01-01 custom "cli-config" "new_transaction_file" "inbox/"

Tab Completion

bean supports shell tab completion through argcomplete.

For the current Bash session:

eval "$(register-python-argcomplete bean)"

For the current Zsh session:

autoload -U +X bashcompinit && bashcompinit
eval "$(register-python-argcomplete bean)"

To enable globally for future sessions:

activate-global-python-argcomplete --user

If completion does not work, confirm your shell has loaded the generated completion script and that register-python-argcomplete is available in your environment.

Development

Run tests:

uv run pytest