Tracking Finances with Ledger

Published on

The Move from Koku

I wrote a little script to parse the CSV output from Koku to a format that Ledger would understand. It worked rather well, but I wasn’t quite sure where to start the “Opening Balance” and ultimately, I decided to start from scratch and just create an “Opening Balance” that gave me raw figures for how much money I had on hand and how much I currently owed.

Understanding the ledger file format

The basic transaction format for Ledger is:

    #{Date} [*|!] #{Payee}  ; Some comment if needed
    #{Account:Paid}     [$|¥]#{Amount}

This simple format will let you specify everything about a transaction in human-readable form and the equity doesn’t even need to be specified. Ledger will assume that the total amount paid into the account must have been withdrawn from the listed equity account in total. You can specify multiple sources and multiple amounts, but for most transactions, this simple format will do.


The original reason I wanted to move from Koku to Ledger (aside from the fact that Koku is an abandoned piece of software) was that scripting Koku (although it had AppleScript support) was a giant pain in the neck. Since Ledger is merely a reporting tool (it parses a text file and outputs reports only) it’s easy to use any scripting language you choose (mine being Ruby) and manipulate your data any way you want to. Already, I’ve written a command-line tool to add transactions, sort transactions that have gotten out of order, clear unreconciled transactions, and tag transactions that don’t have a more detailed account listed other than “Expenses”.

Ledger Reports

Of the two most used Ledger commands, balance is the most useful. It will give you a quick view of how much money you have and what you owe. You can customize this report to include only reconciled transactions, limit its date ranges and output only transactions matching certain accounts, payees, amounts or tags. The register command takes all the same options as balance but outputs a list of transactions. Also handy is the ability to split up transaction by units of time, such as daily, weekly, monthly and yearly. (-D, -W, -M, -Y)