Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Workflows

There are lots of ways to use hledger; here is an overview. Of course you can mix and match these. Also remember always to back up your files regularly to safeguard your data.

Basic workflows

Command line

At a terminal prompt, run hledger add and follow the interactive prompts to enter transactions. It will store data in its default location. Run hledger to list commands to try. Eg, run hledger bs to see your account balances (a balance sheet), and hledger is to see your income and expenses (an income statement).

Tutorial: hledger add describes this process, and hledger's basic concepts and file format, step by step. You might want to skim through this one even if you don't plan to use hledger add.

Web UI

This is the easiest hledger workflow, if it works for you:

Download and run hledger-web, eg by double-clicking on it. It should open in your web browser. Use the add form to add transactions. It will store data in its default location. (So you'll see your transactions next time you run it.)

Tutorial: hledger-web describes this in more detail.

Terminal UI

Use hledger add once to create a journal file with an opening balances transaction. Now run hledger-ui to view account balances. Use the onscreen help to get around and discover the controls. Eg, press a to add new transactions.

Tutorial: hledger-ui describes this setup in more detail.

Text editor

Open your preferred text editor and create a journal file, either .hledger.journal in your home directory, or somewhere else like ~/finance/2023.journal (and set the LEDGER_FILE environment variable). Create transactions by hand using journal file format. Once you have a few, you can copy/paste them to make more. When you want more assistance, set up an editor mode. Here's an example:

; $HOME/.hledger.journal

2020-01-01 opening balances
    assets:checking         $1234
    equity

2020-03-15 client payment
    assets:checking         $2000
    income:consulting

2020-03-20 Sprouts
    expenses:food:groceries  $100
    assets:cash               $40
    assets:checking

Run hledger in a terminal to see reports, as in the Command line workflow. Eg:

$ hledger bs
Balance Sheet 2020-03-20

             || 2020-03-20 
=============++============
 Assets      ||            
-------------++------------
 assets      ||      $3134 
   cash      ||        $40 
   checking  ||      $3094 
-------------++------------
             ||      $3134 
=============++============
 Liabilities ||            
-------------++------------
-------------++------------
             ||            
=============++============
 Net:        ||      $3134 

$ hledger is -M
Income Statement 2020-01-01-2020-03-20

                         || Jan  Feb    Mar 
=========================++=================
 Revenues                ||                 
-------------------------++-----------------
 income:consulting       ||   0    0  $2000 
-------------------------++-----------------
                         ||   0    0  $2000 
=========================++=================
 Expenses                ||                 
-------------------------++-----------------
 expenses:food:groceries ||   0    0   $100 
-------------------------++-----------------
                         ||   0    0   $100 
=========================++=================
 Net:                    ||   0    0  $1900 

CSV import

Download CSV files from banks and financial institutions, manually or using tools/services that automate this (ledger_autosync, Plaid, plaid2qif, Tiller etc.) Use hledger's import command to convert and import the new transactions, and use any of the hledger UIs to see reports.

Tutorial: Import CSV data is a quick tutorial on the importing from CSV part. Some downloading helpers can be found at https://plaintextaccounting.org/#data-importconversion (search for "download").

Comparing CSV workflows

hledger's import command, hledger reading CSV files directly, hledger-flow and Full-fledged hledger are four ways to get bank data into hledger. The main difference:

  • With hledger import, your journal is the main record, and new transactions are appended to it. CSV files can overlap, and can be downloaded often (eg daily).
  • With the other three, your CSV files are the main record and transactions are regenerated from them, so improving the rules also reclassifies old transactions. CSV files must be disjoint (each must start just after the previous one ended).
hledger importhledger, reading CSV directlyhledger-flowFull-fledged hledger
What it isA built-in commandA built-in feature: -f FILE.csv, or (since 1.99.5) include-ing a CSV or rules file in your journalA separate program that you installA tutorial, template and build script that you copy and adapt
PlatformsAllAllLinux, Mac, WindowsUnix-like systems (Linux, Mac, WSL); others via Docker
Requireshledgerhledgerhledger, hledger-flowhledger, stack (Haskell), bash and Unix tools, optionally pricehist; or the Docker image
Transactions from CSVAppended to your main journal; you can edit themConverted in-memory on every run; not editableConverted when needed, and saved; not editableConverted when needed, and saved; not editable
Transactions entered by handAlso in the main journalIn a journal fileIn separate _manual_ filesIn yearly journal files
File layoutYour choice; optional rules, data, prices folders for convenienceYour choiceFolders per owner, bank, account and yearOne folder per source, one journal per year
Price downloadingOptional: --get (since 1.99.3) runs your getprices script; fetches daily prices for each commodity from first use to today; preserves existing pricesLikewise, via getNot supported; you supply yearly price filesOptional, using pricehist; fetches prices on transaction dates, for commodities and years you configure; regenerates (can drop prices)
Transaction downloadingOptional: --get runs your getdata script; or source runs a fetching commandLikewise, via get or sourceNot supported; you supply transaction CSV filesNot supported; you supply transaction CSV files
Overlapping downloadsSupported; only new transactions are addedNot supported; needs disjoint CSV filesNot supported; needs disjoint CSV filesNot supported; needs disjoint CSV files
Keeping CSV filesOptional (archive rule)Required; they are the dataRequired; they are the dataRequired; they are the data
CSV conversionCSV rules, optional cleaning command (source rule)CSV rules, optional cleaning command (source rule)CSV rules, optional preprocess and construct scriptsPer-source cleaning and conversion scripts, plus CSV rules
Journal regenerationNot neededNot needed; CSV data is reconverted on every runhledger-flow importA build script that you maintain
After changing rulesOnly later imports are affectedAll transactions in later reports are affectedAll regenerated journals are affectedAll regenerated journals are affected
Loading a subset of yearsYour choice; see closeYour choice; see closePossible by adding closing/opening entries, eg with close; normally all years are loadedSupported; closing/opening transactions are generated
ReportsNo special support, run as neededNo special support, run as neededA standard set per owner and year, generated by hledger-flow reportA standard set per year, plus your own, regenerated with the journals
Other topics coveredSee the manualSee the manualTransfers, opening and closing balancesInvestments, mortgages, foreign currency, tax returns, lots, prices
Good forUpdating the journal often; easy overlapping downloads; editing imported transactionsA smallish set of disjoint CSV files; reclassifying old transactions; no special import stepMany, disjoint CSV files; reclassifying old transactions; reviewing changes; a ready-to-run toolMany, disjoint CSV files; reclassifying old transactions; reviewing changes; customising every step

Version control

It's optional, but keeping your journal files in a version control system is a very useful way to track changes, undo mistakes, and keep backups. Eg with git:

$ git init                                     # start tracking changes in this directory
$ git add main.journal                         # start tracking this file
$ git commit -m 'first commit' main.journal    # save a snapshot
$ git status; git diff                         # see uncommitted changes
$ git commit -m 'updates' main.journal         # save another snapshot
$ git log                                      # see past commits

Other tools such as darcs or jj work just as well. Committing after each reconciliation or import is a good habit; and you can commit report output too, to detect changes (see Checking for errors).

Custom workflows

SM

hledger YouTube Business Template

phobo3s Excel

Full-fledged hledger

hledger-flow

  • Andreas Pauley's hledger-flow, a tool implementing a variant of the above

rtrLEDGER

barrucadu