Ledger CLI Cheatsheet

Ledger is a powerful, command-line double-entry plain-text accounting tool. By tracking your finances in human-readable journal text files, Ledger allows you to calculate balances, generate registers, track budgets, and produce detailed financial statements.

---

Core Concepts & Getting Started

The Double-Entry Bookkeeping Equation

In Ledger, every transaction consists of two or more postings whose sum must strictly balance to zero:

$$\text{Assets} + \text{Expenses} = \text{Liabilities} + \text{Equity} + \text{Income}$$

Assets:Checking          -$600.00   ; Asset decreases (credit)
Expenses:Rent             $600.00   ; Expense increases (debit)
---------------------------------
Net balance = $0.00

Core Commands Overview

---

Journal Syntax Specification

Basic Transaction Structure

A standard transaction begins with a header line, followed by indented postings (at least two spaces or a tab):

2024/01/03 * (CODE#001) Landlord John ; tag:rent
    Expenses:Rent:Apartment       $600.00
    Assets:Checking:MainBank

• Header Line Breakdown:

  2024/01/03   *       (CODE#001)   Landlord John     ; tag:rent
  ^            ^       ^            ^                 ^
  Date         State   Code/Check#  Payee/Description Comment & Tags
  

• Automatic Elision: Ledger can automatically infer the amount of one posting so that total debits equal total credits (Assets:Checking automatically becomes -$600.00).

Transaction Status Flags

Auxiliary Dates

Using an equal sign allows separating the transaction date from the actual settlement date:

; Format: EventDate=SettlementDate
2024/01/01=2024/01/15 Consulting Client A
    Assets:AccountsReceivable    $1,000.00
    Income:Consulting

Balance Assertions & Assignments

• Balance Assertion (= $VALUE): Validates that after this posting, the cumulative account balance matches $VALUE. If not, Ledger halts with an error.
• Balance Assignment (= $VALUE): Instructs Ledger to calculate the difference required to bring the account to $VALUE, assigning the balancing offset to another account.

; 1. Balance Assertion (throws an error if Cash balance is not $500.00 after payment)
2024/01/01 * Restaurant
    Expenses:Food:Dinner          $20.00
    Assets:Cash                  -$20.00 = $500.00

; 2. Balance Assignment (initial balances setup)
2024/01/01 * Opening Balance
    Assets:Cash                 = $500.00
    Equity:OpeningBalances

Account Declarations & Validation

When running with --strict or --pedantic, declare accounts and rules upfront:

account Expenses:Food
    note Dining and grocery expenses
    alias food                      ; Shortcut alias for CLI queries
    payee ^(KFC|McDonalds|Starbucks)$ ; Regex restriction for payees
    check commodity == "$"          ; Commodity check
    assert commodity == "$"
    default

account Assets:Cash
    alias cash

Commodities & Currencies

Ledger handles multi-currency transactions, commodities, and stock lots:

; 1. Per-unit cost (@ symbol)
2024/05/31 * Farmers Market
    Assets:Fridge                35 Apples @ $0.42
    Assets:Cash

; 2. Total cost (@@ symbol)
2024/05/31 * Farmers Market
    Assets:Fridge                35 Apples @@ $14.70
    Assets:Cash

; 3. Fixed lot price ({=$PRICE})
2024/05/31 * Gas Station
    Expenses:Gasoline             11 GAL {=$2.299}
    Assets:Checking

Commodity Formatting & Defaults:

commodity $
    note US Dollar
    format $1,000.00
    nomarket
    default

; Global default currency
D $1,000.00

; Set default year (allows writing 01/25 in subsequent dates)
Y2024

Including Sub-Journals

Organize large journals into separate files using include:

include accounts.journal
include 2023.journal
include 2024.journal

; Add a namespace prefix to all entries in an included file
account Business
include company_expenses.journal
end

Budgeting

Define periodic budget expectations using the tilde ~ prefix:

~ Monthly
    Expenses:Rent               $600.00
    Expenses:Food               $400.00
    Expenses:Utilities          $100.00
    Expenses                    $100.00  ; Miscellaneous
    Assets

~ Yearly
    Expenses:Insurance        $1,200.00
    Assets

• ledger bal --budget Expenses: Compare actual spending against budget targets.
• ledger bal --unbudgeted Expenses: Display unbudgeted expenditures.

---

Period Expressions

Ledger provides a natural-language time filter via the -p or --period option.

Syntax Structure

[INTERVAL] [BEGIN] [END]

Intervals

Period Filtering Examples

# Register of transactions since last month
ledger reg -p "since last month"

# Monthly expense trend for 2024
ledger reg Expenses -p "every month from 2024 to 2024/12/31" -M

# Balances from Jan 1, 2024 until this month
ledger bal -p "from 2024/01/01 until this month"

# Dining expenses in the last quarter
ledger bal Expenses:Food -p "last quarter"

---

Query Expressions & Filtering

Match Identifiers

Boolean Logic

Combine expressions with and, or, not, and parentheses:

# Match Starbucks food expenses excluding regular dining
ledger reg Expenses:Food and @Starbucks and not dining

# Match rent or transportation
ledger bal Rent or Transportation

# Nested conditions (escape parentheses in shell)
ledger bal Expenses and not \( Drinks or Food \)

Common Filter Flags

---

Reports & Data Export

View Control Options

-s, --subtotal         # Calculate subtotals for grouped postings
-n, --collapse         # Collapse multi-line postings into one line
--flat                 # Render account tree as a flat list
--tail N               # Limit output to last N lines
--invert               # Invert numerical signs (display expenses as positive)
-X CUR, --exchange CUR # Convert foreign holdings to specified currency at latest rate

Exporting to CSV

# Export all entries to CSV
ledger csv > report.csv

# Export this month's dining expenses
ledger csv Expenses:Food -p "this month"

---

Practical Examples

1. Balance Sheet & Monthly Income

# Current assets vs liabilities
ledger bal ^Assets ^Liabilities

# Net revenue this month with positive expenses
ledger bal ^Expenses ^Income -p "this month" --invert

2. Expense Audits & High Spend Items

# Top 10 largest expenses
ledger reg Expenses -S amount --tail 10

# Monthly average daily expenses
ledger reg Expenses -M -n --average

---

References

• hledger Cheatsheet
• Ledger Official Documentation
• Plain Text Accounting Portal