Why rustledger?

Install

_{Missing your platform? Open an issue to request it.}

Coming from Python beancount? See the Migration Guide for command equivalents and plugin mapping.

AI & agents

Two complementary ways to drive rustledger from AI tools:

• MCP server — npx @rustledger/mcp-server exposes rustledger to AI assistants (Claude, Cursor, …) over the Model Context Protocol. Best for interactive assistants that call tools mid-conversation.

• ag-rledger — an agent-native CLI that mirrors every rledger command but emits a single structured JSON envelope per call instead of human-readable text, so coding agents and scripts parse results directly (no output scraping). Each envelope carries ok, a typed exit_code, the command's output under result, and a HATEOAS next_action hint; pass the inner command's --json to get fully structured result.data. Best for headless agents and shell pipelines. It ships beside rledger in the release archives (or build it with cargo build -p rustledger --bin ag-rledger --no-default-features --features ag-rledger):

  $ ag-rledger check --json ledger.beancount
  {"ok":true,"exit_code":0,"result":{"data":{"error_count":0}},"next_action":"…"}
  

  Same subcommands as rledger (check, query, format, report, extract, …) — only the I/O is JSON.

Quick Start

rledger check ledger.beancount
rledger query ledger.beancount "SELECT account, SUM(position) GROUP BY account"

CLI Commands

Python beancount users can install bean-check, bean-query, etc. wrapper scripts via rledger compat install.

# Debug a parsing issue at line 42
rledger doctor context ledger.beancount 42

# Find all transactions with a link
rledger doctor linked ledger.beancount ^trip-2024

# Generate Open directives for accounts missing them
rledger doctor missing-open ledger.beancount >> ledger.beancount

_{Run rledger <command> --help for all options.}

# Validate with plugins
rledger check --native-plugin auto_accounts ledger.beancount

# Interactive query shell
rledger query ledger.beancount

# One-shot query
rledger query ledger.beancount "SELECT date, narration WHERE account ~ 'Expenses:Food'"

# Reports
rledger report ledger.beancount balances
rledger report ledger.beancount stats

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

Import & Categorization

rustledger includes a complete bank import pipeline (rledger extract) with automatic CSV/OFX parsing, duplicate detection, transaction categorization, and balance reconciliation.

CSV Import with Auto-Detection

# Auto-detect delimiter, date format, and column roles
rledger extract bank-statement.csv --auto -a Assets:Bank:Checking

# Check against existing ledger to avoid duplicates
rledger extract statement.csv --auto -a Assets:Bank --existing ledger.beancount

# Append balance assertion from bank statement
rledger extract statement.csv --auto -a Assets:Bank --balance 5000.00

# List available importers from config
rledger extract --list-importers --config importers.toml

Importers Configuration

Create importers.toml for reusable import profiles:

[[importers]]
name = "chase"
account = "Assets:Bank:Chase"
date_column = "Transaction Date"
amount_column = "Amount"
date_format = "%m/%d/%Y"

[importers.mappings]
"AMAZON" = "Expenses:Shopping"
"WHOLE FOODS" = "Expenses:Groceries"

rledger extract --importer chase chase-statement.csv

Config is searched in: current directory, ~/.config/rledger/importers.toml, or via --config.

Transaction Categorization

A 3-tier pipeline automatically categorizes transactions:

1. Rules engine — substring, regex, and exact match patterns from importers.toml
2. Merchant dictionary — ~75 built-in patterns across 10 categories (groceries, dining, transport, subscriptions, etc.)
3. ML categorization — TF-IDF + a self-contained Multinomial Naive Bayes classifier (pure std, no ML framework dependency)

Transfer Detection

Automatically identifies inter-account transfers by matching opposite-sign amounts within date windows, with keyword boosting for common transfer indicators.

Duplicate Detection

Fuzzy matching on date + amount + payee/narration prevents importing the same transaction twice. Structural fingerprinting (BLAKE3) provides stable hashes for comparison.

Balance Reconciliation

The --balance flag appends a balance assertion directive matching your bank statement's ending balance, helping verify import accuracy.

Custom WASM Importers

Beyond the built-in CSV and OFX importers, third parties can ship importers as sandboxed .wasm modules — no need to fork the workspace:

# Single file
rledger extract --wasm-importer ./my-bank.wasm statement.dat -a Assets:Bank

# Or scan a directory of .wasm modules (also configurable via importers.toml)
rledger extract --wasm-importer-dir /etc/rledger/importers.d statement.dat -a Assets:Bank

WASM importers implement the same Importer trait as the built-ins via the wasm_importer_main! macro and run inside the same wasmtime sandbox as directive plugins (no FS / network / WASI; configurable memory + fuel caps). See examples/wasm-importer-csv-example for a reference implementation.

Crates

# Run a native plugin from CLI
rledger check --native-plugin implicit_prices ledger.beancount

# Or declare in your beancount file (auto-detected as native):
# plugin "beancount.plugins.auto_accounts"

# Declare in your beancount file:
# plugin "/path/to/my_plugin.py"

# Load a WASM plugin
rledger check --plugin /path/to/plugin.wasm ledger.beancount

Editor Integration

rustledger includes a full-featured Language Server (rledger-lsp) for IDE support:

• Real-time diagnostics
• Autocompletion (accounts, currencies, payees)
• Go to definition / find references
• Hover information with account balances
• Rename refactoring
• Document formatting

See LSP setup guide for VS Code, Neovim, Helix, Zed, and Emacs.

Performance

_{Benchmarks run nightly on 10K transaction ledgers. View workflow →}

# Quick comparison (requires nix)
nix develop .#bench
./scripts/bench.sh

# Criterion micro-benchmarks
cargo bench -p rustledger-core
cargo bench -p rustledger-parser

Contributing

See CONTRIBUTING.md for development setup and guidelines.

Documentation:

• Architecture - Crate structure and data flow
• BQL Reference - Query language guide
• Importing - CSV/OFX bank import tutorial
• Validation errors - Error code reference
• API docs - Rust API documentation

By submitting a pull request, you agree to the Contributor License Agreement.

License

GPL-3.0-only

Commercial licensing available - contact us for proprietary license options.

Funding

rustledger is free and open source. If you find it useful, consider supporting development: