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).
  • Manage Commodities (create).
  • Manage Prices (fetch, update).
• 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.
• 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 USD main.beancount

Tip

Convenience aliases are supported: bs (balance-sheet) and trial (trial-balance).

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

Valuation	Description	Use Case
market (default)	Uses latest prices from the ledger.	Current Net Worth tracking.
cost	Uses historical price basis ({}).	Accounting Verification (proving balance).

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

Manage Accounts & Commodities

All creation commands (transaction add, account create, commodity create) support batch processing via JSON arrays on STDIN.

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

Standard CLI usage:

# List Accounts
bean account list

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

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

# Fetch and Update Prices
bean price --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