Agent Skills: hledger

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:

| Type | Prefix | Normal Balance | |------|--------|----------------| | Asset | assets: | Debit (positive) | | Liability | liabilities: | Credit (negative) | | Equity | equity: | Credit | | Revenue | income: or revenue: | Credit | | Expense | expenses: | Debit |

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

| Directive | Example | Purpose | |-----------|---------|---------| | account | account expenses:food ; type:X | Declare account (with optional type) | | commodity | commodity $1,000.00 | Declare display format | | P | P 2024-01-15 EUR $1.08 | Market price | | D | D $1,000.00 | Default commodity | | include | include 2024/*.journal | Include files (supports globs) | | alias | alias savings = assets:bank:savings | Account name alias | | ~ | ~ monthly\n (expenses:rent) $1200 | Periodic rule (budgets/forecast) | | = | = ^income\n (liabilities:tax) *.33 | Auto posting rule |

Essential Commands

| Command | Alias | Purpose | |---------|-------|---------| | hledger print | | Show journal entries | | hledger balance | bal | Show account balances | | hledger register | reg | Show postings with running total | | hledger aregister | areg | Account register (bank-statement view) | | hledger balancesheet | bs | Assets and liabilities | | hledger incomestatement | is | Revenue and expenses | | hledger cashflow | cf | Changes in liquid assets | | hledger accounts | | List account names | | hledger import | | Import CSV with duplicate detection | | hledger check | | Run correctness checks | | hledger close | | Year-end closing transactions | | hledger stats | | Journal statistics | | hledger roi | | Return on investment (IRR/TWR) |

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

| Flag | Description | |------|-------------| | -T / --tree | Hierarchical account display | | -F / --flat | Flat account list (default) | | --depth N | Limit account depth | | -E / --empty | Show zero-balance items | | -S / --sort-amount | Sort by amount | | -N / --no-total | Hide grand total | | -A / --average | Show row averages | | --layout=wide\|tall\|bare\|tidy | Multi-commodity layout | | --pretty | Box-drawing characters | | -H / --historical | Historical end balances (vs period changes) | | --invert | Flip all amount signs |

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

| Problem | Solution | |---------|----------| | "transaction is unbalanced" | Check amounts sum to zero; use @ for currency conversion | | "balance assertion failed" | Use hledger print to check actual balance; use =* for inclusive assertions | | "undeclared account" | Add account directive or remove --strict | | "unknown commodity" | Add commodity directive or remove --strict | | Amounts look wrong | Check decimal-mark directive; 1,000 may be parsed as 1.000 | | CSV import duplicates | Use hledger import (not print); check .latest files | | "could not parse date" | Check date-format in CSV rules matches your bank's format |

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