rustledger rustfava PTA Standards
rustledger

Quick Start ​

This guide walks you through basic rustledger usage.

Create a Ledger File ​

Create a file called ledger.beancount:

beancount
; Define accounts
2024-01-01 open Assets:Bank:Checking
2024-01-01 open Assets:Cash
2024-01-01 open Expenses:Food
2024-01-01 open Expenses:Transport
2024-01-01 open Income:Salary
2024-01-01 open Equity:Opening-Balances

; Opening balance
2024-01-01 * "Opening Balance"
  Assets:Bank:Checking   1000.00 USD
  Equity:Opening-Balances

; Transactions
2024-01-15 * "Employer" "Monthly salary"
  Assets:Bank:Checking   3000.00 USD
  Income:Salary

2024-01-16 * "Grocery Store" "Weekly groceries"
  Expenses:Food           150.00 USD
  Assets:Bank:Checking

2024-01-17 * "Metro" "Transit pass"
  Expenses:Transport       50.00 USD
  Assets:Cash

Validate Your Ledger ​

Check for errors:

bash
rledger check ledger.beancount

If everything is correct, you'll see:

✓ No errors found

View Balances ​

See all account balances:

bash
rledger report balances ledger.beancount

Output:

Assets:Bank:Checking      3850.00 USD
Assets:Cash                -50.00 USD
Equity:Opening-Balances  -1000.00 USD
Expenses:Food              150.00 USD
Expenses:Transport          50.00 USD
Income:Salary            -3000.00 USD

Run Queries ​

Use BQL (Beancount Query Language) for custom reports:

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

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

Generate Reports ​

bash
# Balance sheet
rledger report balsheet ledger.beancount

# Income statement
rledger report income ledger.beancount

# Transaction register
rledger report journal ledger.beancount

Format Your Ledger ​

Auto-format your file for consistent style:

bash
# Preview changes
rledger format ledger.beancount

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

Set a Default Ledger File ​

Avoid typing the filename every time:

bash
# Set environment variable
export RLEDGER_FILE="$HOME/finances/ledger.beancount"

# Now commands use it automatically
rledger check
rledger report balances

Add this to your ~/.bashrc or ~/.zshrc to make it permanent.

Alternatively, create a config file:

bash
rledger config init
rledger config edit  # In the [default] section, set file = "~/finances/ledger.beancount"

Next Steps ​