rledger query

Run BQL (Beancount Query Language) queries against your ledger.

Usage

rledger query [OPTIONS] [FILE] [QUERY]

Arguments

Argument	Description
FILE	The beancount file (uses $RLEDGER_FILE or config if not specified)
QUERY	BQL query string (interactive mode if not specified)

Options

Option	Description
-P, --profile <PROFILE>	Use a profile from config
-F, --query-file <FILE>	Read query from file
-o, --output <FILE>	Output file (default: stdout)
-f, --format <FORMAT>	Output format: text, csv, json, beancount
-m, --numberify	Remove currencies, output raw numbers
-q, --no-errors	Suppress ledger validation errors on load
-v, --verbose	Show verbose output

Examples

One-shot Query

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

Interactive Mode

rledger query ledger.beancount

Opens an interactive shell with tab completion:

rledger> SELECT date, narration WHERE account ~ 'Expenses'
rledger> BALANCES
rledger> .exit

Output Formats

# Text (default)
rledger query ledger.beancount "BALANCES"

# CSV (for spreadsheets)
rledger query ledger.beancount "BALANCES" -f csv > balances.csv

# JSON (for scripts)
rledger query ledger.beancount "BALANCES" -f json | jq '.rows[]'

Common Queries

# Account balances
rledger query ledger.beancount "BALANCES"

# Expenses by category
rledger query ledger.beancount "
  SELECT account, sum(position)
  WHERE account ~ 'Expenses'
  GROUP BY account
  ORDER BY sum(position) DESC
"

# Recent transactions
rledger query ledger.beancount "
  SELECT date, payee, narration, account, position
  ORDER BY date DESC
  LIMIT 20
"

# Transactions matching pattern
rledger query ledger.beancount "
  SELECT date, narration, position
  WHERE narration ~ 'Coffee'
"

# Monthly expenses
rledger query ledger.beancount "
  SELECT month(date) as month, sum(number) as total
  WHERE account ~ 'Expenses'
  GROUP BY month
  ORDER BY month
"

Using with Pipes

# Filter output with grep
rledger query ledger.beancount "BALANCES" | grep Expenses

# Process JSON with jq
rledger query ledger.beancount "BALANCES" -f json | jq '.rows[] | select(.balance > 100)'

# Export to file
rledger query ledger.beancount "SELECT *" -f csv > transactions.csv

BQL Reference

See BQL Reference for complete query language documentation.

Quick Reference

-- Select columns
SELECT date, narration, account, position

-- Filter rows
WHERE account ~ 'Expenses' AND year(date) = 2024

-- Aggregate
GROUP BY account
HAVING sum(number) > 100

-- Sort and limit
ORDER BY date DESC
LIMIT 10

-- Built-in reports
BALANCES [FROM ...]
JOURNAL 'Account:Name'

See Also

• BQL Reference - Full query language docs
• Common Queries - Useful query examples