hledger essentials

Welcome! You’ve found the newest intro to hledger. This one aims to distill just the most needed practical info to help you get productive as efficiently as possible. When you want more detail, follow links to the full website (and particularly the manuals, which describe everything hledger does: hledger, hledger-ui, hledger-web, journal, csv, timeclock, timedot).

What is it ?

hledger: free GPLv3+ accounting software for linux, mac, windows, web, etc.

How do I use it ?

At the start:

  1. Install one or more of the hledger tools

  2. Set up a journal, and maybe version control

On a regular basis (eg daily, can be <5m):

  1. Enter transactions manually and/or

  2. Import transactions from banks’ CSV

  3. Reconcile to catch mistakes

Whenever you like:

  1. Run reports to answer questions and gain insight

  2. Refine account names, CSV rules etc. to improve your reports and efficiency.

Knowing some double entry accounting will help you get the most from hledger, but you can do fine just by following the examples below. You’ll find your bookkeeping/accounting skills improve naturally (and help is available).

Install

Fastest: download binaries, eg one of:

$ apt install hledger hledger-ui hledger-web
$ brew install hledger
$ curl -LO https://github.com/simonmichael/hledger/releases/download/1.18.1/hledger-ubuntu.zip; unzip hledger-ubuntu.zip  # also macos, windows, etc.
$ dnf install hledger
$ docker pull dastapov/hledger
$ make -C /usr/ports/openbsd-wip/productivity/hledger install
$ nix-env -f https://github.com/NixOS/nixpkgs/archive/2f9a9064.tar.gz -iA hledger hledger-web hledger-ui 
$ pacman -S hledger hledger-ui hledger-web
$ sudo layman -a haskell && sudo emerge hledger hledger-ui hledger-web
$ xbps-install -S hledger hledger-ui hledger-web

Freshest: build from source:

  1. $ apt install libtinfo-dev or equivalent

  2. check UTF-8 locale

  3. then one of:

    $ curl -sO https://raw.githubusercontent.com/simonmichael/hledger/master/hledger-install/hledger-install.sh; less hledger-install.sh; bash hledger-install.sh
    $ stack update; stack install --resolver=lts hledger-lib-1.18.1 hledger-1.18.1 hledger-ui-1.18.1 hledger-web-1.18.1 --silent
    $ cabal update; cabal install hledger-1.18.1 hledger-web-1.18.1 hledger-ui-1.18.1
    $ git clone https://github.com/simonmichael/hledger; cd hledger; stack install  # super fresh
    

Set up a journal

The journal file is a plain text file where transactions are recorded. By default it is ~/.hledger.journal, and the add command or web add form described below will create it automatically, so actually you don’t need to do anything here.

But here are some common changes people make sooner or later, so why not now:

  • A dedicated folder, to consolidate financial files and make version control and backups easier:

    $ mkdir ~/finance
    $ cd ~/finance
    
  • A separate journal file for each year, for performance and data compartmentalisation:

    $ touch 2020.journal
    
  • A LEDGER_FILE environment variable, so you won’t have to add -f FILE to every command:

    $ echo "export LEDGER_FILE=~/finance/2020.journal" >> ~/.bashrc
    $ source ~/.bashrc
    
  • Some optional directives, useful especially with non-english account names (replace the account names below with the names you will be using):

    $ cat > 2020.journal
    
    ; Declare top level accounts, setting their types and display order
    account assets      ; type:A, things I own
    account liabilities ; type:L, things I owe
    account equity      ; type:E, net worth, A - L
    account revenues    ; type:R, money sources
    account expenses    ; type:X, money sinks
    
    ; Declare commodities/currencies and their decimal mark, digit grouping,
    ; number of decimal places..
    commodity $1000.00
    commodity 1.000,00 EUR
    
    <CTRL-D> (paste the command & text above into the terminal, then press control-d)
    
  • Version control, for tracking changes:

    $ git init
    $ git add 2020.journal
    $ git commit 2020.journal -m 'start journal for 2020'
    
  • Remember to also keep backups.

Enter transactions

Recording transactions manually may sound tedious, but with a good text editor or other tools it can be very fast. It also provides greatest financial awareness. Some people enter everything by hand for this reason.

Run the add command for assisted data entry in the terminal (tutorial):

$ hledger add
...
Date [2020-07-19]: ...

Or run hledger-web and when the web browser opens, press a to add (tutorial):

$ hledger-web
...
Opening web browser...

Or using a text editor, add transactions to your journal file like so:

2020-01-01 opening balances on january 1st
    assets:checking         $1000  ; a posting, increasing assets:checking's balance by $1000
    assets:cash              $100
    liabilities                $0
    equity                 $-1100  ; each transaction must sum to zero

2020-03-05 client payment
    assets:checking         $2000
    revenues:consulting    $-2000  ; revenues/liabilities/equity normally appear negative

2020-03-20 Sprouts
    expenses:food:groceries  $100
    assets:cash               $40
    assets:checking                ; a missing amount will be inferred ($-140 here)

As shown above, make the first transaction a dummy one that sets the opening balances of your asset & liability accounts on some start date. hledger will show accurate real-world account balances from this date onward, as long as you record the subsequent transactions.

To make things easy on yourself, you can pick a very recent start date, like today or last monday. Prioritise recording the transactions that happen after this date. (Tip: the more often you do this, the easier it is.)

Then, as your time and financial records and desire for historical reports allow, you can add older transactions. As you do, you’ll need to adjust the opening balances transaction, moving it back in time. Perhaps focus on one account at a time, each with its own opening balances transaction if necessary.

Import transactions

Import means 1. convert transaction data from some other format (usually a downloaded CSV file) and 2. save any new transactions to the main journal file. It is often possible to automate this, perhaps to the point of a nightly cron job and no manual data entry at all. This is convenient but costs some financial awareness.

Download one or more CSV files containing transaction info, then create a csv rules file for each. Eg if SomeBank.csv looks like:

"Date","Note","Amount"
"2020/3/22","DEPOSIT","50.00"
"2020/3/23","ATM WITHDRAWAL","-10.00"

Create SomeBank.csv.rules containing rules like:

skip 1
fields date, description, amount
currency $
account1 assets:checking
account2 expenses:misc
if DEPOSIT
 account2 revenues:misc
if ATM WITHDRAWAL
 account2 assets:cash

Check the csv conversion looks ok:

$ hledger -f SomeBank.csv print
2020-03-22 DEPOSIT
    assets:checking          $50.00
    revenues:misc           $-50.00

2020-03-23 ATM WITHDRAWAL
    assets:checking         $-10.00
    assets:cash              $10.00

You can run reports directly from the csv, but I like to import the new transactions into the main journal, keeping things in one place. The import command ignores csv records it has seen before, saving the latest dates in .latest.SomeBank.csv. This works for most csv files - you can try a dry run first:

$ hledger import *.csv --dry-run
; would import 2 new transactions from SomeBank.csv:

2020-03-22 DEPOSIT
    assets:checking          $50.00
    revenues:misc           $-50.00

2020-03-23 ATM WITHDRAWAL
    assets:checking         $-10.00
    assets:cash              $10.00

$ hledger import *.csv 
imported 2 new transactions from SomeBank.csv
$ hledger import *.csv
no new transactions found in SomeBank.csv

Now to commit the new rules file and changed journal file:

$ git add SomeBank.csv.rules
$ git commit -m 'SomeBank csv rules' SomeBank.csv.rules
$ git commit -m 'txns' 2020.journal

In the above workflow, the journal file is permanent and downloaded csv files are temporary. Some folks (Full-fledged hledger, hledger-flow) prefer to instead commit all csv files and regenerate the journal file.

Reconcile

After entering or importing transactions, it’s important to check for mistakes (yours or others’), by comparing your reports with reality - your wallet, statements, online balances etc. See Reconciling.

Run reports

$ hledger accounts   # account names declared and used, as a list
assets
assets:cash
assets:checking
liabilities
equity
revenues
revenues:consulting
expenses
expenses:food:groceries

$ hledger accounts --tree   # accounts are actually a hierarchy
assets
  cash
  checking
equity
expenses
  food
    groceries
liabilities
revenues
  consulting

$ hledger balancesheet    # what do I own and owe ?
Balance Sheet 2020-03-20

                 || 2020-03-20 
=================++============
 Assets          ||            
-----------------++------------
 assets:cash     ||       $140 
 assets:checking ||      $2860 
-----------------++------------
                 ||      $3000 
=================++============
 Liabilities     ||            
-----------------++------------
-----------------++------------
                 ||            
=================++============
 Net:            ||      $3000 

$ hledger aregister checking   # or hledger register checking
Transactions in assets:checking and subaccounts:
2020-01-01 opening balances on january..  as:cash, equity                        $1000         $1000
2020-03-05 client payment                 re:consulting                          $2000         $3000
2020-03-20 Sprouts                        ex:fo:groceries, as:cash               $-140         $2860

$ hledger incomestatement --monthly --depth 2    # where is it coming from and going to ?
Income Statement 2020-01-01..2020-03-20

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

$ hledger-ui
...

$ hledger
-------------------------------------------------------------------------------
hledger 1.18.99
Usage: hledger COMMAND [OPTIONS] [-- ADDONCMDOPTIONS]
Commands (+ addons found in $PATH):
...

$ hledger help
Please choose a manual by typing "hledger help MANUAL" (any substring is ok).
A viewer (info, man, a pager, or stdout) will be auto-selected,
or type "hledger help -h" to see options. Manuals available:

 hledger hledger-ui hledger-web journal csv timeclock timedot