hledger Plain Text Accounting Experiment
Rob Coles
I am probably over the top in wanting to keep a close eye on our finances. They are slightly more complex than the norm as I follow a modified version of the barefoot investor “buckets” system, we have a hobby business, and a loan to a family member that we are tracking. Until recently this was managed through separate spreadsheets. This was OK, but when we needed to find out our annual expenditure for pension forecasting, getting to the number was time-consuming. We are moving into retirement now and may need to look more closely at expenditure in various areas. I wanted a better way to look at this.
I’m in Australia and use the “Frollo”" app on my phone to aggregate multiple accounts across multiple banks. Frollo offers an export that contains most of my financial transactions. I’d been pulling this into the spreadsheets and didn’t want to have to enter the data manually, so any replacement needed to be able to include the spreadsheet data automatically, and offer flexible reporting options.
I also wanted to own the data. I am a big fan of Obsidian for notes, and having my data in plain text means whatever happens to Obsidian, my notes are still safe and readable. I went through significant pain moving my notes out of the Evernote ecosystem and I don’t want to be in that position again.
I had seen a blog post by Ellane on plain text accounting with hledger, and when I put my requirements to the three wise AIs there was a consensus that hledger was at least a reasonable starting point.
Setup
Installation was straightforward. I started with an hledger folder under my documents folder, and used GIT version control so I could undo anything dim I did. Moving on to the configuration and this was pretty overwhelming initially. I needed to define a chart of accounts but didn’t know where to start. Back to the three wise AIs, and mostly with ChatGPT and Claude looking at the Frollo export I got a start point. As a bonus, Claude generated an initial version of the csv import rules file that hledger needs to understand the Frollo export file. I was to become very familiar with this rules file 😁
The hledger import goes to a file “main.journal” by default. I expected to have to run multiple imports before I got the rules right so I created a separate opening-balances.journal. I also created a separate cash.journal and cogs.journal for the cost of goods sold for the hobby business. I had a couple of slightly weird things I wanted to track. An example is dealing with drawings from the hobby business. This needs 3 transactions, and a balancing transaction somewhere in hledger. The transactions need to add up to zero, the very basic requirements of a double-entry system. I had some issues with AI trying to get advice on how to set this up in the import rules file, including this gem from Perplexity.
I swear this is exactly what was provided, claiming the sum balances to zero when it clearly doesn’t.
There were a number of similar hallucinations, but I eventually got a set of rules and chart of accounts that seemed like they would do what I wanted.
When I first set things up, it was mid-month, but I thought that would be OK, I’d just set the opening balances from the bank at the mid point of the month and go from there. Pro tip: Don’t do this! It was OK to allow me to test the basic transactions, but trying to reconcile at month end was a nightmare as the opening balances hadn’t taken into account things like transactions already on the credit card, but not yet “paid off” by my splurge account.
I used the “hledger setup” command to confirm my configuration was at least coherent, and fiddled with the configuration until all the red indicators were gone. I also used “hledger check” on accounts and commodities.
Testing
I trimmed the input file to a couple of transactions, ran the import and looked at what it was doing, gradually expanding the range of imported data as I tweaked the import rules. There was a fair bit of to-ing and fro-ing with AI to understand the best way to do what I wanted to do via double-entry, and my knowledge of double-entry was very rusty. The iterations took probably 8-10 runs until I was mostly happy with what it claimed to do, and I moved on to reconciling with the bank and credit card statements as a start point. The “hledger register” command got a serious workout as I tried to fix the differences, but got there in the end. I have now run a complete month and have most of the transactions balancing as expected. I have reconciled the bank balances and added a bit of automation to allow me to select the downloaded frollo file and filter out only the transactions for the current month.
I am doing trial loads during the month, to allow me to pre-empt any issues, and mostly it is showing me tagging errors where I have missed a tag in frollo. I did need some creative accounting to deal with keeping track of loan accounts and how those were paid off, but that is now working too.I’m now on the 16th of the month and have only needed to tweak tagging in frollo, not the rules. The banks balanced today too.
What’s next
I am still at the start of my hledger learning journey. I have bookmarked a bunch of Youtube videos to watch, and specifically want to explore:
- Learning more about the reporting
- The tui - hledger-ui and if this is helpful
- The web version and how this differs and/or helps
- Tracking things like Vanguard. I have a Vanguard ETF and a small amount of crypto. At the end of the month in the old spreadsheet I grabbed a snapshot of the value and included it in my overall net worth. I don’t know how best to handle these, potentially tracking the changes yet.
Conclusion so far
Reporting is now much better than the spreadsheet was, and it’s easy to see cash and bank balances without needing to log in. I am pretty confident about the other balances and the “owing/paid” mechanism is working well. There is a lot more to explore, but now the basics are there it is already proving worth the time spent with the setup. My tiny experiment statement was: “I will use HLedger as the primary method of controlling personal and business finances for 3 months to see if it is less effort and more accurate then the spreadsheet.” so I am just about half way through, but so far, it is a keeper.
Resources: