Beancount Tools and Reporting

Core Command-line Tools

1. bean-check

Primary validation tool for Beancount files:

bean-check /path/to/ledger.beancount

• Validates syntax and transaction balance
• Reports errors with filename and line numbers
• Exit code 0 indicates successful validation

2. bean-report

Main reporting tool with multiple output formats:

bean-report /path/to/ledger.beancount <report-name>

Key Reports:

• balances - Trial balance
• balsheet - Balance sheet
• income - Income statement
• journal - Transaction journal
• holdings - Investment holdings
• networth - Net worth summary

3. bean-query

SQL-like query interface:

bean-query /path/to/ledger.beancount

Features:

• Interactive SQL-style queries
• Custom aggregations
• Position and inventory handling
• Balance assertions

4. bean-web

Web interface server:

bean-web /path/to/ledger.beancount

Capabilities:

• Serves reports on localhost:8080
• Interactive navigation
• Multiple view options
• Document management

Report Types and Options

1. Balance Reports

# Trial Balance
bean-report ledger.beancount balances

# Balance Sheet
bean-report ledger.beancount balsheet

# Income Statement
bean-report ledger.beancount income

Configuration Options:

• Operating currency specification
• Account filtering
• Date range selection
• Cost basis vs. market value

2. Journal Reports

# Basic Journal
bean-report ledger.beancount journal -a Account:Name

# With Balance Column
bean-report ledger.beancount journal -a Account:Name -b

# At Cost Basis
bean-report ledger.beancount journal -a Account:Name -c

Format Options:

• -w WIDTH: Character width
• -k PRECISION: Decimal precision
• -x: Compact mode
• -X: Verbose mode

3. Holdings Reports

# Detailed Holdings
bean-report ledger.beancount holdings

# Aggregated by Commodity
bean-report ledger.beancount holdings -g currency

# Net Worth Summary
bean-report ledger.beancount networth

4. Supporting Tools

bean-format

Code formatting tool:

bean-format input.beancount > formatted.beancount

bean-doctor

Diagnostic utilities:

# Check Dependencies
bean-doctor deps

# Context Analysis
bean-doctor context ledger.beancount LINENO

bean-bake

Static site generator:

bean-bake ledger.beancount output_dir

Common Query Patterns

Trial Balance

SELECT account, sum(position)
GROUP BY account
ORDER BY account;

Balance Sheet

SELECT account, sum(position)
FROM CLOSE ON 2024-01-01
GROUP BY account
ORDER BY account;

Account Journal

SELECT date, flag, description,
       account, cost(position), cost(balance)
WHERE account ~ 'Assets:Checking';

Report Formatting Considerations

1. Operating Currency Display:

option "operating_currency" "USD"
option "operating_currency" "EUR"

2. Balance Assertions:

• Regular validation against external statements
• Helps detect data entry errors
• Supports multiple currencies

3. Cost Basis Handling:

• Book value vs. market value reporting
• Unrealized gains tracking
• Lot reduction methods

4. Document Management:

• Automatic filing based on account structure
• Document linking in web interface
• Search and retrieval capabilities

This guide serves as a technical reference for Beancount's reporting tools and capabilities. Each tool and report type can be further customized based on specific needs through additional options and arguments.