Tracking your finances with Reckon and Ledger

Tracking finances and budgeting is unsexy but is the base from which flows investing, capital, and wise use of credit. It clarifies activity, priorities, obligations, and opportunities. Making money work for you is a minor superpower. It, if you can excuse the pun, pays dividends.

And it makes most sense in your hands, rather than a SaaS or bank. Many apps and online services give financial visibility but ultimately tie you to a (paid) upgrade cycle, ecosystem, or upsell where you lack control of your financial data and insights. Most make it difficult to get your data out once it’s theirs.

You have alternatives. Let’s talk about what I use and why: Ledger teamed with Reckon. As a bonus, both open source and free (See? Saving cash already 😝).

Ledger is a plain text, command line, double entry accounting program that takes a specific file format of journals and magically transforms it into accounting reports and insight. It’s been around since 2003, and battle-hardened.

Reckon is a small Bayesian ML library that works with Ledger. It takes csv files you grab (or convert) from your bank and automagically transforms them into Ledger entries for you based on estimating the probability of which account each line should go into. Together, they minimize the time I spend tracking finances, while giving me a lot of insight. I’d estimate an hour-ish every month to keep on top of my (complex) financial life.

Why Plain Text?

Flexibility, portability, and longevity end up being the short answers. Financial companies come and go, online financial SaaSes close down, and banks are allergic to innovation and/or rarely keep your full transaction history around or available to you.

Surprisingly, I’ve been increasingly moving back to plain text as a format for holding my personal data. Sure, databases are great when you need them, but with a little scripting, plain text formats are portable, version controllable, human readable, and rarely deprecate or need massive conversion. You can also manipulate them into any format you need given a little text munging know-how. Plain text emphasizes data. And data formats are effectively standards that allow you to do a lot once you understand the semantic structure of the information. Much like I loved Taskpaper (and now org-mode) for the simple hierarchical list nature of the text, you can do the exact same thing with financial information.

But why for accounting? Go back ten years and look at your financial records. Bet you can’t, right? Your bank won’t provide them that long and your accounting or money tracking software probably can’t even parse files from that far back. OK, admittedly, less of a problem than others in your life, but it’s damn interesting to see how your financial life has changed over time (As an example, how much money I pay Apple, Amazon, and Google monthly now compared to five years ago. You’ll then understand how they became FAANGBAT. Or how much you paid in cost adjusted dollars on your car loans or similar). It’s amazingly illuminating besides providing actionable insights on your financial life. If you need more convincing, there is an entire site devoted to selling you on plain text accounting

Enter Ledger

Ledger itself is a command line program for processing text files in the ledger journal double-entry accounting format. It’s been around since 2003 and is robust and reliable. It never alters your files, so maintenance of the text journal file(s) is your responsibility. There’re web interfaces like Ledger Web for it if you are not crazy about the idea of text editing and which can give you nice web-based charts (and which preserves the same underlying ledger text file format immutably.). Frankly, it’s incredible what people have done with the format even re-implement ledger in languages such as Haskell (which has both a CLI, a UI, and web-based interface as well as good docs.).

Everything in ledger runs around double entry accounting. All money flows must balance so you will learn a teensy bit about double-entry accounting (which is handy to know for work anyhow). This will often surprise you. It can be somewhat counterintuitive at first. It’s a good primer and helps you learn basics about Finance career-wise.

If you use a text editor, Ledger has a surprising amount of support as a file format. Syntax highlighting as a minimum is supported across all major editors I checked (VS Code, vim, emacs, Sublime, Atom, Textmate) though I use emacs which has an <em>excellent</em> ledger-mode which gives you syntax highlighting, account auto-completion, and allows you to pull up reports in-emacs and use ledger in-editor. It also autoformats everything so the file looks nice and neat.

A ledger journal entry looks somewhat like this:


2020-01-05 Amazon
    ; The Moon by Oliver Morton
    Expenses:Books                             20.50 CAD
    Liabilities:RBC Visa

That’s it. A Date, a payee, a semi-colon delimited comment, and both the taking and receiving account. In sticking with double entry accounting principles there must always be two accounts.

Technically, the entry should look like this:

2020-01-05 Amazon
    ; Bought The Moon
    Expenses:Books                             20.50 CAD
    Liabilities:RBC Visa                      -20.50 CAD

but ledger understands the short form of entering in the values once (so does the emacs ledger mode). I use the two money amounts in manual entries only for foreign currency transactions since you’ll often have to balance out separate currencies to reconcile a transaction. As an example, transferring money between two countries:

2020-01-01 Bank Transfer to Canada
    ; My bank has notes like this "WWW TRANSFER 12090879870313"
    Assets:Canadian bank                      5000.00 CAD
    Assets:Singaporean bank                  -5250.50 SGD

I generally charge the fees both banks shaft me with separately and only track FX losses for business accounting (note: if you’re tracking FX losses or gains you add those in as a separate account as long as the overall transaction balances. Suffice it to say, banks are hosing you on international transfers so, as a tip, consider something like Transferwise).

When I am entering entries into the ledger journal file, I often find it helpful to have the balance report open in a split window in emacs since it will generally let me know right away if I’ve messed something up by refusing to balance or numbers get out of whack. It’s handy error checking and one of the features I like about the emacs ledger-mode.

Issuing a command once you have data in ledger to get a report looks something like this:

$ ledger -f 2020_perso.ledger bal

Where I am asking for my balance report (accounting sense) from all entries in the 2020 perso file (so everything in there). It’ll return something that look somewhat like this:

      xx2,376.30 CAD
             x31 RSU
      xxx,960.88 SGD  Assets
          153.00 SGD    Cash
      -10,500.00 SGD    Loans Outstanding
      xx2,376.30 CAD    CDN Savings
       10,500.00 SGD    Receivables
        3,500.00 SGD      Friend1
        2,000.00 SGD      Friend2
        5,000.00 SGD      Friend3
       -x,824.39 CAD    Reimbursements
             x31 RSU    Equity RSUs
      xxx,107.88 SGD    SIN Savings
      xx3,233.30 CAD
     -xxx,200.75 SGD
     -xxx,500.00 USD  Equity:Opening Balances
       xx,248.43 CAD
       x5,451.81 SGD  Expenses
          183.00 CAD
           90.00 SGD    Bank Fees
          584.56 CAD
           63.13 SGD    Books
          x40.00 SGD    Cleaner
        2,480.00 SGD    Computer

The Balance report (unsurprisingly) balances; Assets must balance Liabilities plus Equity. Double entry accounting is surprisingly powerful when it comes to understanding the wheres and hows of your money. For example, when I am updating the ledger text file in emacs ledger-mode, I keep the balance report open in a split window (which updates every time I save) so I can see if I’ve made any mistakes (note: in the above example, RSU refer to equity shares I have in a company not a currency. I track my portfolio in a separate ledger. It can track any sort of commodity that you can assign value to - stocks I track in USD to keep myself sane.).

The nice thing about the reports is you can instantly see how much you’ve spent and where for the year by assigning amounts to accounts (like Expenses:Computer) which let me know that I’ve bought a single laptop this year (ahem), as well as letting me know I’ve spent way more on books than I can possibly have read in three months even including textbooks (it’s a slight problem.).

Most people do not have a good grasp on their expenses, and even fewer have a budget they adhere to (#protip Pay yourself first: Move 20%-30% of your salary into savings every month and live on 80%-60% if you can.). Let’s take a look at what sort of spending we might be able to reduce with ledger, because this is where its power shines.

Wanna take a look at your food spending? Peope are often surprised by how much they spend on food versus costs like rent or transport. How much is Delivery vs Restaurants vs Groceries each month? As long as you are tracking that in your chart of accounts (more on that setup later), you can assign expenses to Accounts like Expenses:Food:Groceries, Expenses:Food:Delivery, Expenses:Food:Restaurants to get a sobering look at how much you could be saving if you started cooking at home more often (when not forced to from lockdown).

Let’s take a look at how you’d get Ledger to tell you that:

 λ  ledger -f ~/Dropbox/ledger/2020_perso.ledger -M reg "^Expenses:Food"

Will yield something like this:

2020-01m-01d - 2020-01m-31d             Expenses:Food:Delivery             919.86 SGD       919.86 SGD
                                        Expenses:Food:Groceries            214.83 SGD     x,134.69 SGD
                                        Expenses:Food:Restos             x,408.28 SGD     x,542.97 SGD

2020-02m-01d - 2020-02m-29d             Expenses:Food:Delivery             648.58 SGD     x,191.55 SGD
                                        Expenses:Food:Groceries            469.36 SGD     x,660.91 SGD
                                        Expenses:Food:Restos             x,614.13 SGD     x,275.04 SGD

2020-03m-01d - 2020-03m-31d             Expenses:Food:Delivery             789.22 SGD     x,064.26 SGD
                                        Expenses:Food:Groceries            695.74 SGD     x,760.00 SGD
                                        Expenses:Food:Restos             x,144.99 SGD     x,904.99 SGD
                                                                                                                

Here’s the kicker: this is way higher than what I had budgeted for from a daily “I spend this” estimate projections I extrapolated out for a year for my budget. Here was a huge area I could start economizing (#protip, it’s not enough to budget and do projections, you also need to track.). As weird as it sounds though, I’m really enjoying cooking at home since WFH and lockdown started. Forgot how much I missed it or the fact I used to be a passable chef (though am struggling to get back to even good again.).

And strangely looking monthly expenses, it’s not books or online services or even discretionary purchases that were the real culprits (and like most people rent, food, and transport will probably be your main areas of expenses where you might have an impact if you make changes.). Though it’s important to know what your financial goals are. For me, bending towards financial independence in a few years, that means foregoing some expenses for the sake of a better future.

Reckon - Making the machine work for you

Let’s talk about the other side of the coin of using Ledger here: updating. I can hear what you’re thinking. Wow, managing a text file looks like a lot of work. Entering in every one of those ledger entries by hand? Isn’t that what we have drop down interfaces for and importing for? Does any bank offer downloads in Ledger format?

Banks are strangely behind the times on most data fronts, but the good news is, as long as you can get a csv export from your bank, you can get your machine to enter almost everything for you. Despite the financial complexity of my life: living in one country, assets in another, and company in a complete other, I spend maybe an hour a month updating everything and figuring out where the money all goes. How?

This is where Reckon comes in. Reckon is a Ruby gem which parses csv files from your bank, learns from your current (and growing) ledger data file via Bayesian statistics ML, interactively queries you about each line, and then creates the entries for you in ledger format. It massively reduced the overhead required on administering my finances. Without it I probably would’ve given up on ledger due to the entry overhead.

If you’re on any linux based system, as long as you have ruby installed (and most people should) you are all ready to go. On OSX, I personally recommend using homebrew and installing a more modern version of ruby than may be your system default (and you should be using homebrew anyway to install what you can for command line and applications) and then brew install ruby to get the latest version of ruby.

if you have a working ruby on your system, you can install reckon with a simple:

$ gem install reckon

Reckon is surprisingly robust for something someone built to scratch their own itch and cantino deserves some major credit for building something useful and great.

Reckon takes the entries for your ledger files, learns from them, and then goes line by line through a csv file you grab from your bank and figures out probabilistically what the entry is probably for (eg. Expenses:Rent, Expenses:Entertainment, Expenses:Business:Software etc etc) and creates and writes the ledger entry for you. Bliss.

This automates the onerous maintenance part. It massively reduces the PITA aspect (I could also automate the grabbing and massaging of files from my various banks, but haven’t had time to get around to it - also they all require secure logins which makes things trickier to automate. For example, one of my banks, which I should fire them for, only allows an Excel download to see your transactions. They also stupidly provide multiple rows in a cell meaning I need to export to csv and then remove all \n within a description field. Yeesh.).

Assuming you have a decent csv file in whatever format that has a date, an amount of transaction, and a description, it is a wonder to watch Reckon rip through your financial records and do the work for oyu. Let’s walk through the standard command I would issue on the command line:

$ reckon -f ./bankX_source_mar2020.csv --currency 'SGD ' -l ~/Dropbox/ledger/2020_master.ledger -o bankX_mar2020.ledger --suffixed

The csv file needs the same basics as a ledger entry, obviously: a date, a description, and an amount are the minimums though you can force Reckon to ignore columns or recognize a particular column as the important money column (important if your bank csv download also provides, say a running balance.). See reckon --help for command line options (which are very comprehensive.).

In the example above, BankX is in Singapore so I want the file to recognize that all entries are in SGD in the file so use --currency 'SGD '. I also use the --suffixed flag to make sure reckon writes ledger entries like 1000.00 SGD rather than its default $1000.00.

The -l switch for “learning” is where all the magic happens. Point this at your main ledger file and that file gets parsed and used as the basis for the bayesian predictions that reckon makes.You will be amazed how little work you need to do besides hitting return to accept Reckon’s suggestions on which account to expense debits to. As time goes on and you get more entries, the predictions become even more accurate and you do even less work (I’ve found.). It also skips lines that are too identical to entries already in the ledger file which is handy for avoiding duplicates.

Finally, the -o flag for output tells reckon where to write the collated ledger file to. I separate out my files into source files for bank and month but there is no reason you could not write directly back to your source file or a single monthly file. I generally then copy-paste the entire output into my ledger file and do a quick once over to correct for strangeness or where I got a little too hasty on hitting return with reckon.

After it asks you about which account the csv is for, it then will run through the csv file and interactively prompt you to confirm which account you want to assign an entry to. Here’s an actual example of one of mine from the evil XLS bank with some details fuzzed for obfuscation.

+------------+-------------+-------------------------------------------------------------------+
| 2020-02-29 | -30.10 SGD  | Misc DR-Debit Card DELIVEROO.COM.SG SINGAPORE 28 FEB 4359 0861709 |
+------------+-------------+-------------------------------------------------------------------+
To which account did this money go? ([account]/[q]uit/[s]kip) |Expenses:Food:Delivery|

Hit return to accept the entry and have it written to your file, or type to change the account you want it to debit to. Bliss.

Once you’ve got a high degree of confidence that Reckon is going to get its prediction right almost every time you can even run the whole thing with the --unattended flag but I find having to charge to the same vendors for different reasons (Amazon, Apple etc for entertainment versus, say software or books vs online services) makes this work less well than doing overrides in interactive mode.

Setting Up

You can save yourself rework later if you choose a robust setup for Ledger. This is what I’d recommend based on what I’ve learned over time. YMMV.

Use as Few Files as possible

Ledger can include (with an include keyword) multiple files to merge all your information together. While some setups advise doing this by account, I find this ends up being counterproductive from a complexity perspective. It’s far better to keep everything in one file if your financial life will allow it.

As advice, I’d combine accounts semantically, with one file for everything that affects your personal finances, perhaps with a separate file for a budget (so you can also track how you might change that over time), a business (if you have one, or other sources of alternative income), and any investment portfolios you might have as separate files. Keep organization as simple as possible until its no longer viable (though make siure you can record changes over time - use git or dropbox to make sure your files are versioned). If you prefer to also understand your finances in a single currency, you will also need a price file for tracking foreign exchange as well stock prices if you have a portfolio (see next section).

Comment Block to organize the file

I use big commented headers to navigate what ends up being the long ledger file I have for the year.

For example, a block header by month and account makes figuring out where entries might have gone wrong easier (90% of time, mispellings on accounts or two banks recording the same entry )

;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;; Mar 2020 - SIN Bank Account
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
...

I also do this in the budget file to denote when I’ve got a new version of a budget and then commenting out the old one with some notes to explain why. It’s ridiculously useful when you’re looking back months from then and trying to understand your thinking.

Use suffixed currencies not $ £ € ¥ prefixed

Many countries have single prefixed symbols to denote their money. While your life now may be single-currency, longer term, if you’re the type of person to read this post, your financial life gets more complex, and you will need to include other currencies. Set yourself up right. Use suffixed ISO codes for currencies like you see in airport foreign exchange counters. Cause, well… standards. It might take getting used to but it will make international entanglements in your life easier in the future.

If you prefer to see all your finances in a single currency you can do that too, but will need to start a separate “price” file to start tracking foreign exchange on currencies. Again, this is something that is easily automated. I whipped up a small ruby program called get-FX to get foreign exchange rates from an online provider which you can write directly to a price file and operate on a cron script daily or weekly. Hands off, and keeps everything tidy and updated (I’ll rewrite it in Go at some point to be faster and asynchronous.)

Opening Balances

If you’ve never done any accounting before, you need to think about setting up files by year and then “closing” accounts at year end and opening a new ledger (as accountants do). Opening the books means thinking about what your position is at the start of each year and opening balances. Surprisingly, setting this up will avoid a lot of problems for you and let you focus on recording and understanding and actioning your finances. The key problem is getting a snapshot of your financial situation at point-in-time. Traditionally, I do this on the first day of the new year (but rollover is easy if you’ve been tracking).

You open up your account with Opening Balances. Note that you will need to have entries in each currency and account if you’ve got a multi-currency life.

20xx-01-01 Opening Balance
    Equity:Opening Balances              -xxx,200.75 CAD
    Equity:Opening Balances               xxx,233.30 SGD
    Equity:Opening Balances              -xxx,500.00 USD
    Assets:SIN Savings                    XXX,160.59 SGD
    Assets:CDN Savings                    xxx,239.83 CAD
    Assets:RSUs                                x,250 RSU @ 255.00 USD
    Assets:Reimbursements                   x,040.16 SGD
    Assets:Cash                               150.00 SGD
    Assets:Loans Outstanding                 -xx,000 SGD
    Assets:Receivables:Fin1                 x,000.00 SGD
    Assets:Receivables:Fin2                 x,500.00 SGD
    Assets:Receivables:Fin3                 x,500.00 SGD
    Liabilities:Visa                      -xx,256.00 CAD
    Liabilities:Credit Line                -x,217.13 CAD
... etc

I’ve not bothered with Accounts like Mortgages or Home Equity for brevity. This should give you an idea of how to set up after looking at your financial accounts. As a tip, do not look at the first date after the start of month or year but at the date before that. Often, you’ll need to make sure you’ve actually accounted for the payments made before the year if they hit your accounts days later (I have this issue in Singapore all the time. Debits hit my account days after I incurred them at a vendor because of the slowness of the NETS system and Visa here.).

From there, it’s a simple matter of running your bank account exports through Reckon and tracking cash expenses by hand/note (if you need to worry about that a lot.) and by how interested in looking at what you spend, which is how we get to figuring out your Chart of Accounts.

Chart of Accounts

While a cliché, what you measure is what you manage from a financial perspective. For example, I’m terrible at tracking petty cash expenses because I am using cash in a situation where someone will not accept a card and then forget to write it down. But those are rare that and immaterial to my spending. There’s a low chance it’s indicative of a trend in my spending or finances (though probably understates my taxi, grocery, and housewares accounts slightly.). Your own Chart of Accounts will differ by your personal situation. There’re heaps of google-able articles on this by better financial whizzes than me, but this is what I find works for me. YMMV and it depends on what you care about tracking (in fact, I should probably revise some of mine since the things I thought were financial wary watches were not.).

Assets
    Cash
    Loans Outstanding
    Country1 Savings
    Receivables
      Finn1
      Finn2
    RSUs
    Country2 Savings

  Equity:Opening Balances

  Expenses
    Bank Fees
    Books
    Cleaner
    Computer
    Education
    Electronics
    Entertainment
    Food
      Delivery
      Groceries
      Restaurants
    Gifts
    Government Fees
    Gym
    Health and Beauty
    Housewares
    Interest:Loans
    Interest:Mortgage
    Internet
    Medical
    Online Services
      AWS
      DNSimple
      Dropbox
      Github
      Heroku
    Phone
    Rent
    Software
      Apple
      Google
      MS
      Others
    Taxi
    Travel:Flights
    Travel:Hotels
    Utilities

  Income
    Deferred:RSUs
    Deferred:Reimbursements
    Interest
    Rental
    Salary
  Liabilities
    Credit Card1
    Credit Card2
    Credit Line
    Loans
    Mortgage

As I said, think about what’s important for you to track and why since the less complex you can make your life and tracking (limiting to actionable financial decisions), the easier it will be for you.

Budgeting

You need a budget. Tracking spending is about understanding where your money goes, but it’s implicitly about whether you are spending according to expectations. Those expectations are your budget.

Budgets end up being surprising. I thumbnail projections out at the start of most years in a sort of Fermi estimation type exercise and it’s shocking sometimes how far those napkin projections differ from reality in some categories (restaurant spending, for example).

Ledger supports budgets with a simple syntax related to your Accounts. You can put this at the top of your Ledger file though I generally like having it in a separate file (which I can also comment out and update a new budget as conditions evolve or financial needs change.).

So, I recommend setting up a separate budget file by year (mine is 2020_budget.ledger) and then importing that into the main ledger file you use. At the top of my master file I have the following:

include 2020_budger.ledger

which does the trick.

Budgeting entries get demarcated with a tilde ~:

~ Monthly
    Expenses:Rent              2,500.00 SGD 
    Expenses:Food              2,500.00 SGD
    Expenses:Books               200.00 SGD
    Expenses:Internet             60.00 SGD
    Expenses:Phone               100.00 SGD
    Expenses:Transport           500.00 SGD
    Expenses:Utilities           200.00 SGD
    Expenses:Cleaner             120.00 SGD
    Expenses:Gym                 200.00 CAD
    Expenses:Entertainment       500.00 CAD
    Expenses:Online Services     100.00 CAD
    Expenses:Software            150.00 CAD
    Expenses                    x200.00 SGD ; all other expenses
    Assets

~ Yearly
    Expenses:Vacation            xx,000 SGD
    Expenses:Vision               1,000 SGD 
    Expenses:Computer             2,500 SGD
    Assets

Here’s a theoretical example (with two currencies to simulate having a foreign CC or similar). I’ve also split the budget into Monthly and Yearly, though in a future post I’ll start talking about Funds (virtual) and using those to get a better idea of how you’re tracking monthly on finances. The nice thing here is you can look at top level categories like Expenses:Food rather than each individual sub-account (eg Expenses:Food:Restaurants) to get a better idea of what big areas may be looking like. Also, note that you can catch-all expenses beyond specific categories you’re interested in to get a handle on total spending versus your projections (very powerful).

The commands to handle actual to budget are pretty easy: add a –budget flag to regular ledger commands and a “grouping” time flag like your monthly reporting with a -M or -Y for monthly and yearly. Let’s take a look at Expenses:Food for example:

ledger -f ~/Dropbox/ledger/2020_master.ledger --budget -M reg "^Expenses:Food"

This takes my main ledger file (which has the budget included via the include statement above and compares the register report to budget for the Food accounts including subcategories like Groceries, Delivery, and Restaurants.). It gives you something like this:

2020-01m-01d - 2020-01m-31d           Expenses:Food        1,542.97 SGD    1,542.97 SGD
2020-02m-01d - 2020-02m-29d           Expenses:Food        1,732.07 SGD    3,275.04 SGD
2020-03m-01d - 2020-03m-31d           Expenses:Food          629.95 SGD    3,904.99 SGD

I am significantly over-budget on food spending for the first quarter. As you can probably tell from the first report I showed you, it’s pretty clear I need to reduce restaurant spending dramatically to get myself back onto track for the year.

The key thing here is to figure out what actions you need to take from looking at the trends and other reporting you get and change your financial behaviour.

Tips, Tricks, and Gotchas

It’s a good idea to invest a tiny bit of time in reading up on double entry accounting. Some of the conventions can be (at least to me) counter-intuitive at first until you start thinking in Assets, Liabilities, Equity etc etc. Here’s some examples that affected me personally to help you avoid wasting time or frustration (note: I am not a bookkeeper or account so if any person who knows what they’re talking about or sees a logical inconsistency in what I’ve done here, please hit me up with a mention @awws on twitter).

Watch for double counting crediting between accounts

Succintly: have a strategy for credits/debits between your accounts to avoid double entering in double entry accounting. Credits like income and salary take care of themselves.

When your financial life becomes a bit more complex, you will do things like transfer money from one account ot another or between countries, or your bank will have a crazy way of denoting charging interest on your credit line. Reckon and Ledger write entries into your ledger file, not realizing that the transfer on your foreign bank account is actually duplicated by your domestic bank’s entry for the inbound credit. If you’re not paying attention to that and double entry accounting you will end up overcounting or have a rather large mess in accounts (yes, I got caught by this at first.).

My personal let the “pulling”/credited account be the one where the single source of truth resides as in general that feels easier to track since credits are easier to parse out than debits on most accounts. So, in the above example, if I’ve moved money from the foreign country I am working in to my home accounts to pay some bills, I let the home account have the single record for that transaction and delete the journal entry for the originating bank so I do not have a double debit and credit.

Reimbursements

Counter-intuitively, you need to think of Reimbursements as an Asset held by your company (or whoever needs to pay you back) until they pay it back. For example, my previous company made its executives use their own credit cards rather than issue corporate cards. Whenever you take on an expense the company needs to pay back, your entry should look a bit something like this:

2020-01-17 Scoot
    ; Flight to Jakarta return
    Liabilities:CC                   -287.00 SGD
    Assets:Reimbursements

That is, you are taking on credit card liability and you have an asset that will be repaid in the future. When you company pays you back you would see a credit in your bank account.

2020-01-17 Inward transfer from BigCo
    ; Expenses reimbursement
    Assets:Bank Account                287.00 SGD
    Assets:Reimbursements

This zeroes out your reimbursements account (if your company repaid you correctly) and helps track it to make sure you are settled especially if your company lags payments by a month as most companies do (while you’re still incurring expenses for them). You still have to pay off your credit card, but you’ve squared your reimbursements. Note: This technique also works with putting expenses on foreign credit cards but needing to track reimbursements with multiple currencies though FX then gets involved.

Loans

You can use a similar technique for Loans that are not liabilities to yourself (ie. owed to a bank etc). Think of them as an asset which is a Receivable held by someone else until it’s paid back.

2020-01-17 Loan to Finn
    ; WWW Transfer 459683687
    Assets:Bank account                 -1500.00 SGD
    Assets:Receivables:Finn

And handle repayments the same way you would Reimbursements above.

RSUs and Stock Options

Perhaps an edge case not so applicable for most people, but I spent a good day surveying people (even bookkeepers and accountants!) and googling to get good info on how RSUs (Reserved Stock Units) or illiquid equity grants gets handled from an accounting perspective.

If you work in tech, if you received equity, it will generally be some sort of illiquid asset which has implied value (due to valuation or paid-up investment capitalization) but is neither tradable nor convertible. Basically, it’s worth what the company or investors say it’s worth, even if you can’t use that money.

In some tax jurisdictions you might even have a tax liability because of it, so track it. Generally, RSUs or similar equity vest every month or every quarter after a one year vesting cliff (meaning: you need to spend a year at the company before getting any shares but then you get a year’s worth and rest the reamining on whatever the vesting schedule is.). Usually, the terms are you are fully vested after four years in standard “Silicon Valley” vesting schemes.

The trick here is that the value of the asset will change over time. If your company doubles in value due to injected capital (or worse, a down round), your vested shares can be at a different value than your original shares (appreciating share value) and often in a reference currency other than the one you track in (in my case, USDs) The scope of dealing with capital gains and taxation is beyond the scope of this post, but here’s how I handled this for myself in ledger.

Keep in mind, this is an esoteric area and I have to admit after speaking to two bookkeepers and a business accountant, they were themselves unable to give me a universal opinion, so not entirely sure how it gets handled canonically. IANAA (I am not an accountant - if you do know, please mention @awws on twitter and educate me.). That said, here’s a theoretical example of a quarterly equity grant.

2020-02-02 Big Co Equity grant
    ; Quarterly Equity vesting
    Assets:RSUs                         55 RSU @ 110 USD
    Income:Deferred:RSUs

You’ll notice that I use the three-letter acronym RSU to identify this as a “commodity” as far as ledger is concerned and then index that to a USD value to understand the money implications. Ledger has pretty amazing commodity value support so you do get to see the number of RSUs you actually have and can actually use the program to determine capital gains (or losses) with a little work (same as you could in the Loans section above with writing off Bad Loan Expense.).

Note: In Opening Balances, you would want to keep your RSUs (or whatever indicator you use for them consistent between years so you can see how they’re appreciating/depreciating and understand your gains or losses. Reconcile them at year end in so you can understand capital gains/losses and your financial position and then close that year’s books.).

Bonus: Emacs ledger-mode

If you are an emacs user, someone has created a fantastic major-mode for ledger you can use which makes your life even easier. It provides syntax highlighting (and aligning) of entries, auto-completion, and even allows you to run reports in a split pane on the right with a simple CTRL-C-O-R (hold down Control the entire chord) and then selecting the report you want. It also updates the report every time you save. I use this when pasting in Reckon-run ledger entries to check the balance report and make sure everything stays, well… balanced. It’s fantastic. I have not investigated this near enough but am going to look into customizing it a bit more to automate regular reports like budget and virtual Funds.

In your ~/.emacs.d/init.el use the following if you are using the fantastic use-package package manager. It will make emacs go into ledger-mode for any file with a .ledger extension.

(use-package ledger-mode
  :ensure t
  :defer t
  :init
  )
(add-to-list 'auto-mode-alist '("\\.ledger$" . ledger-mode))

You can also go full emacs on this and use babel for inserting code blocks into files and going “literate programming” on this but it’s not something I’ve had a great deal of time to loo into to see if the benefit outweighs the time cost.

As a final recommendation, I’d also recommend using ivy and swiper in emacs for ridiculously fast searching and jumping through your file when you need to find something (typos for accounts for example). Emacs makes the setup on this awesome though I do note that VS Code has a ledger mode as well though it looks more to be about syntax highlighting than having the completeness of the emacs package.

Fin

While it’s a long post, I wanted a one stop post to getting started and going with Ledger and Reckon to get people past the basic documentation you might find and get you into a routine of a financial habit that allows you minimal time to update and more time to understand your finances to control them. I hope it’s been helpful if you’re looking at doing your finances this way and I hope you’re convinced that plain text tracking of your finances is something that is robust, portable, and has longevity beyond most every other thing I’ve tried.

If this post did help you out or you have suggestion for improvements (or gasp, corrections), please ping me by mention @awws on twitter.