rustledger

A pure Rust implementation of Beancount, the double-entry bookkeeping language.

Features

• Pure Rust - No Python dependencies, compiles to native and WebAssembly
• Full Beancount Syntax - Parses all directive types with error recovery
• Drop-in Replacement - Compatible CLI commands for Python beancount users
• 7 Booking Methods - STRICT, FIFO, LIFO, HIFO, AVERAGE, and more
• 14 Built-in Plugins - implicit_prices, auto_accounts, pedantic, etc.
• BQL Query Engine - SQL-like queries on your ledger
• Fast - 10x faster than Python beancount

Installation

CLI Tools

# Install with bean-* compatibility aliases (default)
cargo install rustledger

# Install only rledger-* commands (no bean-* aliases)
cargo install rustledger --no-default-features

As a Library

cargo add rustledger-core rustledger-parser rustledger-loader

CLI Usage

# Validate a ledger file
rledger-check ledger.beancount

# Format a ledger file
rledger-format ledger.beancount
rledger-format --in-place ledger.beancount

# Run a BQL query (one-shot or interactive)
rledger-query ledger.beancount "SELECT account, SUM(position) GROUP BY account"
rledger-query ledger.beancount   # Interactive shell with readline/history

# Generate reports
rledger-report ledger.beancount balances
rledger-report ledger.beancount accounts
rledger-report ledger.beancount stats

# Debugging tools
rledger-doctor ledger.beancount context 42        # Show context around line 42
rledger-doctor ledger.beancount linked ^link-name # Find linked transactions
rledger-doctor ledger.beancount missing           # Find missing Open directives
rledger-doctor ledger.beancount stats             # Ledger statistics

# Use plugins
rledger-check --native-plugin auto_accounts ledger.beancount
rledger-check --native-plugin pedantic ledger.beancount

Python Beancount Compatibility

For users migrating from Python beancount, the bean-* commands are also available:

bean-check ledger.beancount
bean-format ledger.beancount
bean-query ledger.beancount "SELECT ..."
bean-report ledger.beancount balances
bean-doctor ledger.beancount context 42

Library Usage

use rustledger_loader::load;

fn main() -> anyhow::Result<()> {
    let result = load("ledger.beancount")?;

    println!("Loaded {} directives", result.directives.len());

    for error in &result.errors {
        eprintln!("{}", error);
    }

    Ok(())
}

Crates

Supported Features

Parser

• All 12 directive types (transaction, balance, open, close, etc.)
• Cost specifications: {100 USD}, {{100 USD}}, {100 # 5 USD}, {*}
• Price annotations: @ 100 USD, @@ 1000 USD
• Arithmetic expressions: (40.00/3 + 5) USD
• Multi-line strings: """..."""
• All transaction flags: * ! P S T C U R M
• Metadata with 6 value types
• Error recovery (continues parsing after errors)

Booking Methods

• STRICT - Lots must match exactly (with total match exception)
• STRICT_WITH_SIZE - Exact-size matches accept oldest lot
• FIFO - First in, first out
• LIFO - Last in, first out
• HIFO - Highest cost first
• AVERAGE - Average cost basis
• NONE - No cost tracking

Built-in Plugins

Options (28 supported)

• Account prefixes (name_assets, name_liabilities, etc.)
• Equity accounts (account_previous_balances, etc.)
• Tolerance settings (inferred_tolerance_default with wildcards)
• Booking method, documents directories, and more

Compatibility

rustledger is compatible with Python beancount. It can parse and validate any valid beancount file. The bean-* command aliases are included by default for easy migration.

Performance

Benchmarks show rustledger is approximately 10x faster than Python beancount for parsing and validation.

License

This project is licensed under the GNU General Public License v3.0 - see the LICENSE file for details.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.