hledger

What this skill does

# 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](https://hledger.org))
- Optional: `hledger-ui` (TUI), `hledger-web` (web UI)

## Journal Basics

### Transaction Format

```journal
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

```journal
    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

```bash
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

```bash
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

```bash
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

```bash
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

```bash
# 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](references/csv-import.md) for complete rules syntax.

### Multi-Currency

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

P 2024-03-15 EUR $1.09
```

```bash
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:

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

```bash
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

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

### Checks and Validation

```bash
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:

```bash
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` | Histo