dashed 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
hledgerinstalled (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, orYYYY.MM.DD - Status:
!(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 asname: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
commoditydirective - Multiple commodities in one transaction require cost notation:
@ UNITPRICEor@@ TOTALPRICE - Balance assertions:
= $500.00after 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