Plaintext Accounting with hledger

Posted on: May 24 2020

When most people think of accounting software I imagine the first idea that pops up is Excel or something else with a spreadsheet. Excel-wizards can also have scripts that perform complex calculations to help automate tedious work or give valuable reflections of the data. One person even managed to make a 3d engine out of Excel formulas. But accounting can be much simpler than that while also being just as capable.

Benefits of Self Accounting

Staying on top of your transactions in life can be rewarding in many ways. Here are a few points:

So, what is "plaintext* accounting"?

While there's a dedicated website devoted to explaining it, I'll try to sum it up here:

It is programmer-focused but simple enough for anyone to pick up. One can even create their own accounting file format and drive their own workflow with it. But the gist is to keep it simple and human-readable. You should be able to open the file in any text-editing program, even notepad, and have the data be legible. But instead of creating your own, let's look at one example of plaintext accounting software and the benefits it brings: hledger

* hledger displays it as "plain text" but I figure I'll stick with the combined word due to the cryptography we'll include later in the series.

Install and Setup

Let's walk through a simple example. Click on the link above to hledger and install it based on your OS. If you're tech savvy, you can probably find it in a repo within your package manager.

Next, open your favorite text editor. Don't have one? Feel free to use a default editor on your OS for now, such as Textedit for MacOS, Notepad for Windows, or gedit (or the like) on Linux variants. We won't use this quite yet but it'll be useful once we create our first hledger journal.

Fire up your terminal or command prompt based on your OS. For Mac you can usually get it via CMD+Spacebar and type terminal then ENTER/RETURN key, and for Windows you can press the Windows key then type cmd or powershell then ENTER key to start up the corresponding program.

Type hledger then ENTER, and you should see a printout of options for the command. If the terminal isn't recognizing it, try reinstalling hledger again then restart your terminal program. We're now ready to create a journal and submit our first transaction!

Our First Transaction

Type hledger add and you'll see some helpful text on how to get started. On the prompt, you'll see a date. By default the date is usually the current day. You can change it by submitting a new one in the same format. Here's an example changing it to the 20th of May.

Date [2020/05/24]: 2020/05/20

Next, you can type a description. Keep it short and to the point:

Description: bought book, DUNE

After, it'll ask for an account. Treat this as the account that's accepting the cash. Let's also start using sub-accounts right off the bat.

Account 1: expenses:my fav bookstore

It'll then wait for an amount that's going into this first account. Make sure to type in the currency sign.

Amount 1: $10

Then hledger will ask for a second account, such as where the money is coming out of. I spent cash, so I'll type that in under my assets top-level account.

Account 2: assets:cash

Next is the amount coming out from that account. Since I just paid with cash and didn't split it with a friend or partner (hledger can account for that if so!), I'll just press ENTER to go with the full amount so far:

Amount 2 [$-10]:

Last, it'll start with a third account, but since that's the end of the transaction and all the money is accounted for (remember, double-entry bookkeeping!) I'll submit a period "." to end this transaction. hledger will show a summary of my transaction and I accept with y, and quit in the next prompt with another period input.

Account 3 (or . or enter to finish this transaction): .
2020/05/20 bought book, DUNE
    expenses:my fav bookstore             $10

Save this transaction to the journal ? [y]: y
Starting the next transaction (. or ctrl-D/ctrl-C to quit)
Date [2020/05/20]: .

...And we're done with our first transaction!

Opening the journal

To find where the journal is located, enter hledger files in your terminal and check the output. It'll print out a directory to where your journal lies. Open up the directory, then click and drag the document to your text editor. Here's what mine looks like.

; journal created 2020-05-24 by hledger

2020/05/20 bought book, DUNE
    expenses:my fav bookstore             $10
    assets:cash                          $-10

Simple, right? If you want it even simpler you don't even have to use sub-accounts and instead opt for just using the top-levels. But sooner or later, you're going to want that granularity to answer questions like "how much coffee did I buy last May?" and sub-accounts help to provide that.

This also shows the practice of double-entry bookkeeping which works like a certain law of physics (reaction) - for every transaction amount going to an account there must be corresponding opposite amounts coming from one or more accounts. In the above, the $10.00 is coming out of my cash assets (hence a minus sign for the money leaving that account) while the expense of the book is receiving the $10.00 (shown by a positive cash value). If the $10.00 was split between two accounts, I could have added a third account from where the other $5 was coming from. If I wanted to change the book store from "my fav bookstore" to "the best bookstore", I can can do so via my text editor! That's the beauty of plaintext accounting.

hledger is Feature Rich

hledger add is just a small example of what hledger can do. Submitting the hledger command brings up many other options you can try, such as hledger bs or hledger balancesheet, which displays the current amount in each account you've submitted transactions for.

If you're wondering how to have "starting balances" to explain where your assets came from, here's a shortcut to the hledger docs section for it. Check out the rest of the hledger manual page for more info around the command.

Don't be intimidated by any of the arguments of the command! Simply make a copy of your journal file as backup and feel free to mess with it. It's all plaintext in the end, after all!

Building a Habit

It can be hard to have your hledger journal accessible throughout your day, so here are some tips to staying on top of your bookkeeping.

Next: Keys.pub

In the next part of the series, I'll be going over keys.pub, it's features and uses, and how to encrypt our journal with it. See you soon!