Intro

One of my new years resolutions was to commit to using ledger – a commandline accounting tool. Ledger is a bit like Quicken, GnuCash or Mint, but for UNIX nerds.

Note: No relation to the cr*pto product with the same name.

It’s coming up to the end of the year, and this was one of the few resolutions I actually managed to keep!

I think you can probably accomplish everything ledger can do with other personal finance software. The reason you would choose ledger is that you’re sold on the efficiency and scriptability of the commandline, along with the grep, editor and revision control friendly file format.

If that sounds interesting, go take a look at the docs to learn more!

The TL;DR is that I’m hooked, and will keep using it.

Getting Started

It’s not easy to get started with ledger, and you’re probably going to have some uncommon financial arrangements that the documentation didn’t cover exactly. It could be anything, maybe something mundane like you split the utilities with a partner, but you’re the one who pays the bill?¹

These things are easy to handle once you’re familiar with ledger concepts, but as nobody has the exact same arrangements as you, it’s not always a copy-and-paste situation.

This is where ledger’s flexibility can be a curse – the answer to questions like “How do I handle …?” tends to be “However you like!”. Cool, but you’re not going to have any opinions formed yet, so how do you know what you like?

I don’t really have a good solution – I think you just have to wing it until you’re proficient, then go back and fix any naive mistakes you made 🙈

Another problem is that you need a few months worth of data before you can fairly evaluate if you find it useful or not. That’s a big commitment to something that you’re not sure you’re actually going to enjoy!

After you’ve finally built up some data… your reward is having to learn the query syntax so you can actually do something useful with it… and that’s when you’ll realize you didn’t organize things optimally, and have to go back and edit the last few months of data! 😂

Now that I’ve scared everyone off, I can tell you I don’t regret that effort – ledger is great! You know that feeling when you find a solution that just feels “correct”? Well, ledger gives me that feeling.

Examples

So, what exactly does ledger look like? Well, there is no user interface, it’s a commandline tool to query your finances.

Note: If you want graphs, you pipe the output into gnuplot, like this. If you’re a stats nerd, you might prefer ledger-plots.

You can automatically import transactions from whatever format your bank provides, but I prefer to enter some transactions manually. I use vim’s colorcolumn feature to make margins and keep everything neatly aligned.

Once you’ve got importing and editing working smoothly, you can start answering questions about your finances.

How much have I spent this month?

$ ledger bal --period "this month" ^Expenses:

How much did I spend on gas each month this year?

$ ledger reg --period "this year" --monthly ^Expenses:Auto:Gas

What is my current networth?

$ ledger bal --depth 1 --market ^Assets: ^Liabilities:

How much have my investments grown?

$ ledger bal --gain ^Assets:Brokerage

Okay, but what about my investment in stock FOOBAR specifically?

$ ledger bal --gain --limit 'commodity == "FOOBAR"' ^Assets:Brokerage

Okay, but how much of that is long term capital gains?

$ ledger bal --gain --limit 'commodity == "FOOBAR"' --limit 'lot_date(amount) < [365 days ago]' ^Assets:Brokerage

How much did I spend at McDonalds in June?

$ ledger bal --period "this june" ^Expenses: and @McDonalds

How much do I spend each month on average in total?

$ ledger reg --period "this year" --average --monthly --depth 1 ^Expenses:

Where is that money going, but only show me the categories I spend more than $20 on?

$ ledger bal --period "last 12 months" --amount "amount / 12" --display 'top_amount(amount) > 20' ^Expenses:

Did I earn enough credit card rewards to justify the fees, or should I cancel them?

$ ledger reg --period "this year" --subtotal --related ^Income:Reward

Show me all the donations I made that I can deduct on my taxes?

$ ledger reg --period "this year" %deductible

These are just some random examples, there are also budgeting and forecasting tools. It’s flexible enough that people use it for tracking billable hours, inventory and so on.

Naturally, it handles multiple currencies, arbitrary commodities, and you can track them as precisely (or coarsely) as you like.

Advice

This post is really just encouraging anyone considering getting started to take the leap if you were thinking about getting started in the new year!

fyi, you could probably record that like this:

; Pay the power bill, John owes me half
2023/10/1 * Power Company
   Expenses:Utilities:Power    $50
   Assets:Receivables:John     $50
   Assets:Checking            -$100
; John reimbursed me.
2023/10/2 * John Doe  ; Flatmate
   Assets:Checking             $50
   Assets:Receivables:John    -$50

…but maybe you want to record it like this:

; Pay the power bill, John owes me half
2023/10/1 * Power Company
   Expenses:Utilities:Power    $100
   Assets:Checking             $100
; John reimbursed me his half.
2023/10/2 * John Doe  ; Flatmate
   Assets:Checking             $50
   Expenses:Utilities:Power   -$50 ; [=2023/10/1]

There is not always one right answer!↩︎