hledger

name: hledger description: Plain-text double-entry accounting with hledger. Use when recording transactions, checking balances, generating financial reports (balance sheet, income statement, cashflow), importing CSV bank statements, budgeting, tracking time, managing multiple currencies, or doing year-end closing. Triggers on mentions of hledger, ledger-cli, journal files, double-entry accounting, balance assertions, or plain-text accounting.

hledger

Overview

hledger is a plain-text accounting tool implementing double-entry bookkeeping. You record transactions in a human-readable journal file, then query it for balance reports, income statements, cashflow, and more. Data stays in version-controllable text files — no database, no lock-in.

Prerequisites

• hledger installed (brew install hledger, apt install hledger, or hledger.org)
• Optional: hledger-ui (TUI), hledger-web (web UI)

Journal Basics

Transaction Format

2024-01-15 * (INV-042) Grocery store  ; tag:value
    expenses:food:groceries    $45.00
    assets:bank:checking

• Date: YYYY-MM-DD, YYYY/MM/DD, or YYYY.MM.DD
• Status: (unmarked), ! (pending), * (cleared)
• Code: (CODE) in parentheses — check numbers, invoice IDs
• Description: free text, optionally split as payee | note
• Postings: indented lines with account name and optional amount
• Comments: ; starts a comment; tags embedded as name:value

At least two postings per transaction. One amount may be omitted (inferred to balance).

Account Names

Colon-separated hierarchy: assets:bank:checking, expenses:food:groceries. Five conventional top-level types:

Declare accounts for validation: account assets:bank:checking ; type:A

Amounts and Commodities

    expenses:food         $45.00        ; symbol left, no space
    expenses:travel       100.00 EUR    ; symbol right, with space
    assets:bank          -45.00 USD

• Commodity symbol position and spacing learned from first use or commodity directive
• Multiple commodities in one transaction require cost notation: @ UNITPRICE or @@ TOTALPRICE
• Balance assertions: = $500.00 after amount (assert this account balance)

Key Directives

Essential Commands

Common Workflows

Check Balances

hledger bal                          # all account balances
hledger bal assets liabilities       # filter by account pattern
hledger bs                           # balance sheet
hledger is -M                        # monthly income statement
hledger cf -Q                        # quarterly cashflow

View Transactions

hledger print                        # all transactions
hledger reg expenses -M              # monthly expense register
hledger areg assets:bank:checking    # bank statement view
hledger areg checking -H             # with historical running balance

Filtering and Queries

hledger bal date:thismonth           # current month
hledger reg desc:grocery             # by description
hledger bal tag:project=alpha        # by tag
hledger bal amt:'>100'               # amounts over 100
hledger bal cur:EUR                  # EUR amounts only
hledger bal depth:2                  # top 2 account levels
hledger bal not:expenses:food        # exclude pattern

Query terms are AND'd by default. Multiple account patterns are OR'd.

Multi-Period Reports

hledger bal -M                       # monthly
hledger bal -Q                       # quarterly
hledger bal -Y                       # yearly
hledger bal -p 'monthly from 2024'   # custom period
hledger bal -M --tree                # hierarchical
hledger bal -M -S                    # sorted by amount
hledger bal -M -T -A                 # with row totals and averages

CSV Import

# Create rules file for your bank format
hledger import bank-download.csv --rules bank.csv.rules --dry-run
hledger import bank-download.csv --rules bank.csv.rules

Rules file example (bank.csv.rules):

skip 1
fields date, description, amount
date-format %m/%d/%Y
currency $
account1 assets:bank:checking

if grocery|supermarket
  account2 expenses:food:groceries

if salary|payroll
  account2 income:salary

See references/csv-import.md for complete rules syntax.

Multi-Currency

2024-03-01 * Buy euros
    assets:bank:eur       €500 @@ $540
    assets:bank:usd

P 2024-03-15 EUR $1.09

hledger bal -B                       # at cost (purchase price)
hledger bal -V                       # at market value (period end)
hledger bal -X USD                   # convert everything to USD
hledger bal --infer-market-prices    # infer prices from costs

Budgeting

Define budget goals with periodic transaction rules:

~ monthly
    (expenses:food)         $500
    (expenses:rent)        $1200
    (expenses:transport)    $150

hledger bal --budget -M              # monthly budget comparison
hledger bal --budget -M -E           # include zero/unbudgeted

Output shows ACTUAL [PERCENT% of GOAL] per cell.

Year-End Closing

hledger close --clopen -e 2025       # closing + opening transactions
hledger close --retain -e 2025       # retained earnings
hledger close --assert               # generate balance assertions

Checks and Validation

hledger check                        # basic checks (parseable, balanced, assertions)
hledger check -s                     # strict (also: accounts, commodities declared)
hledger check ordereddates payees    # specific checks

Available checks: parseable, autobalanced, assertions, balanced, commodities, accounts, ordereddates, payees, tags, recentassertions, uniqueleafnames.

Output Formats

Most report commands support:

hledger bal -O csv                   # CSV output
hledger bal -O json                  # JSON output
hledger bal -O html                  # HTML output
hledger bal -o report.csv            # format inferred from extension

Formats: txt (default), csv, tsv, json, html, fods. print also supports beancount and sql.

Report Display Options

Configuration File

hledger.conf (searched in current dir, parent dirs, then ~/.hledger.conf):

--pretty
--infer-costs
--infer-market-prices

[print]
--explicit
--show-costs

[web]
--port 5050
--allow edit

Disable with --no-conf or -n.

Time Tracking

Timedot format (.timedot)

2024-03-15
fos.haskell   .... ..    ; 1.5h (each dot = 0.25h)
biz.research  .          ; 0.25h
inc.client1   3          ; 3h

Timeclock format (.timeclock)

i 2024-03-15 09:00:00 client1:development
o 2024-03-15 12:30:00
i 2024-03-15 13:30:00 client1:meetings
o 2024-03-15 15:00:00

hledger -f time.timedot bal          # time totals by account
hledger -f time.timedot reg -D       # daily time register

Troubleshooting

Advanced Topics

For comprehensive reference documentation, see:

• references/commands.md — Full command reference with all flags
• references/journal-format.md — Complete journal syntax and directives
• references/queries.md — Query language, smart dates, periods
• references/csv-import.md — CSV rules file format and import workflow
• references/reports.md — Report types, valuation, custom formatting
• references/budgeting.md — Budgeting, time tracking, ROI, year-end