Personal Finance Management using Ledger CLI

Where does my money go? — am sure this is a question that most of us ask, if not always, probably by the end of the first week of every month 😃 Maintaining a personal finance tracking mechanism is quite important to get an outlook on what’s happening with your money and feed data into some system you can build to help with savings.

I am a sucker for CLIs ( Command Line Tools ) and also prefer plain text mechanisms for storing and processing data. This helps me to have control over my data, keep it on any cloud drive of my choosing and also have the data portable if I decide to move to a different system.

I went with Ledger, a very powerful command-line-oriented tool which follows the `double-entry` based accounting system.

Double-entry bookkeeping means that all transactions should have two accounts, one from which the money goes out and the other into which the money goes in. A debit account (one which receives money) and a credit account (from which money is deducted). At any point in time, the accounts should balance to zero.

To start using `ledger`, all you need is an empty text file.

Create a file in any folder of your choice. Let us call it `ledger.txt`. Will refer to this as the `ledger` file in the rest of this article.

The typical structure of an entry in the ledger file would look like this.

2022–01–04 Airtel mobile payment
Expenses:Utilities:Mobile ₹470.82
Liabilities:CC:Manhattan

- This records an entry for `4th of Jan 2022` with a brief description of the payment.
- Indicates that I spent 470.82 on this. The amount moved from the Liabilities:CC:Manhattan account to the Expenses:Utilities:Mobile account. As I mentioned before, the double-entry system needs two accounts to tally an entry.

The accounts above are the ones that I use in my `ledger` files. These can be multi-level as you notice, like Expenses:Utilities which would be an account under theExpensesand Expenses:Utilities:Mobile is an account under Expenses:Utilities and so on.

I usually follow the below methodology to name my accounts.

- Assets like `bank` accounts etc — Assets:Savings:{bankname}
- Credit CardsLiabilities:CC:{cardname}
- Any Income (incoming money) — Income:{type}
- Any kind of expenseExpenses:{subcategories}

I have been consistently following this for the last 3 years and have found it to be very useful.

Let us take some example scenarios to understand how one adds entries to the ledger file.

To start with, one needs to set an initial balance on the different accounts we will be interacting with. You do that like below:

Open the `ledger` file and put this at the top of the file

;Ledger — Year 2023
2023–01–01 * Opening balance
Assets:Savings:Kotak ₹10000.00
Liabilities:CC:Manhattan ₹-10726.76
Equity:Opening Balances

The above indicates:
- Starting on Jan 2023 with the mentioned balances in the Savings account
- Also, starting with a due amount on my credit card

That's all it takes. Post this, it is all about being prudent about adding entries to keep track of things.

Say, the month beginning, I received an income from my salary, I make an entry like below:

2023–01–05 * Paycheck
Income:Paycheck ₹-24000.00
Assets:Savings:Kotak

Notice here that I have mentioned a ‘-ve’ sign to indicate that the money is going from the Income:Paycheckaccount to my Savings account.

Then, say, I ended up paying the electricity bill. I add it like so:

2023–01–05 BESCOM Bill Payment
Expenses:Utilities:BESCOM ₹1990.00
Liabilities:CC:Manhattan
  • first line — date of expense followed by a brief description of what the entry is for.

Then, let us say that I get a message saying that my Audible subscription was due for renewal and was charged to my card. I make an entry in my ledger file:

2023–01–12 Audible
Expenses:Subscriptions:Audible ₹199.00
Liabilities:CC:Manhattan

As before:
- first line — date and description
- second line — Category of expense (expense account) and amount
- third line — Source of the money or the account from which the expense was made

As one last example, say I went and bought some groceries and paid using GooglePay or something using my Savings account, I make an entry like the below:

2023–01–15 * Groceries
Expenses:Shopping:Groceries ₹820.00
Assets:Savings:Kotak

Similarly, over the days and months, you will add entries to the ledger file.

Here’s a sample ledger file. (this will be saved as `ledger.txt` as mentioned before)

;Ledger - Year 2023
2023-01-01 * Opening balance
Assets:Savings:Kotak ₹10730.88
Liabilities:CC:Manhattan ₹-10726.76
Equity:Opening Balances

2023-01-04 Airtel mobile payment
Expenses:Utilities:Mobile ₹470.82
Liabilities:CC:Manhattan

2023-01-05 * Paycheck
Income:Paycheck ₹-24000.00
Assets:Savings:Kotak

2023-01-05 BESCOM
Expenses:Utilities:BESCOM ₹1990.00
Liabilities:CC:Manhattan

2023-01-05 * Card payment
Liabilities:CC:Manhattan ₹10000.00
Assets:Savings:Kotak

2023-01-08 * BSNL
Expenses:Utilities:BSNL ₹395.00
Assets:Savings:Kotak

2023-01-14 Netflix
Expenses:Subscriptions:Netflix ₹199.00
Liabilities:CC:Manhattan

2023-01-21 Adobe Photography Pack
Expenses:Subscriptions:Adobe ₹807.09
Liabilities:CC:Manhattan

2023-02-02 BESCOM
Expenses:Utilities:BESCOM ₹2033.94
Liabilities:CC:Manhattan

2023-02-03 * Food - Chaat
Expenses:EatOut ₹120.00
Assets:Savings:Kotak

2023-02-03 * Indane Gas
Expenses:Utilities:Gas ₹902.50
Assets:Savings:Kotak

2023-02-04 Jetpens - Stationery
Expenses:Shopping:Stationery ₹7813.63
Liabilities:CC:Manhattan

2023-02-05 * Paycheck
Income:Paycheck ₹-24000.00
Assets:Savings:Kotak

2023-02-06 * Groceries
Expenses:Shopping:Groceries ₹1793.00
Assets:Savings:Kotak

2023-02-12 * BWSSB Water bill
Expenses:Utilities:BWSSB ₹996.00
Assets:Savings:Kotak

2023-02-12 * BSNL Landline
Expenses:Utilities:BSNL ₹388.00
Assets:Savings:Kotak

2023-02-12 * Card payment
Liabilities:CC:Manhattan ₹30000.00
Assets:Savings:Kotak

2023-02-12 Amazon - Monitor Arm
Expenses:Shopping:Gadgets ₹1989.00
Liabilities:CC:Manhattan

2023-02-12 Amazon BenQ Monitor
Expenses:Shopping:Gadgets ₹15000.00
Liabilities:CC:Manhattan

2023-02-14 Netflix
Expenses:Subscriptions:Netflix ₹199.00
Liabilities:CC:Manhattan

2023-02-15 * Groceries
Expenses:Shopping:Groceries ₹1180.00
Assets:Savings:Kotak

2023-02-19 ACT Cable
Expenses:Utilities:Cable ₹334.39
Liabilities:CC:Manhattan

Now that we know how to update and manage the ledger file, just data stored in a file is not much use. The use comes from being able to analyse and draw reports out of it right.

This is where ledger shines.

Let us get ledger installed on our system.

If you are on macOS, use brew to install:

`brew install ledger`

For other OSes, you will find pre-built binaries on the ledger website here - Download Ledger

The `ledger` cli provides a lot of options to query your ledger file and gather data as reports for you to analyse. Some simple examples are below.

Switch to a terminal and try these out:

To know the current balance of your accounts (assets and liabilities), run:

ledger -w -f ledger.txt bal ^assets ^liabilities

This should give an output like the below:

           ₹12956.38  Assets:Savings:Kotak
₹-1563.63 Liabilities:CC:Manhattan
--------------------
₹11392.75
-------------------------------------------------------------------------------------------------------------------

Finding out the balance is going to be the most commonly used command.

Let us do a query to find out the `Expenses` grouped by month.

ledger r -M -f ledger.txt -- period-sort total expenses

you should see an output like this:

23-Jan-01 - 23-Jan-31                     Expenses:Subscriptions:Adobe                    ₹807.09            ₹807.09
Expenses:Subscriptions:Netflix ₹199.00 ₹1006.09
Expenses:Utilities:BESCOM ₹1990.00 ₹2996.09
Expenses:Utilities:BSNL ₹395.00 ₹3391.09
Expenses:Utilities:Mobile ₹470.82 ₹3861.91
23-Feb-01 - 23-Feb-28 Expenses:EatOut ₹120.00 ₹3981.91
Expenses:Shopping:Gadgets ₹16989.00 ₹20970.91
Expenses:Shopping:Groceries ₹2973.00 ₹23943.91
Expenses:Shopping:Stationery ₹7813.63 ₹31757.54
Expenses:Subscriptions:Netflix ₹199.00 ₹31956.54
Expenses:Utilities:BESCOM ₹2033.94 ₹33990.48
Expenses:Utilities:BSNL ₹388.00 ₹34378.48
Expenses:Utilities:BWSSB ₹996.00 ₹35374.48
Expenses:Utilities:Cable ₹334.39 ₹35708.87
Expenses:Utilities:Gas ₹902.50 ₹36611.37 ₹2973.00 ₹23943.91

Gives a nice view of all the expenses grouped by the month. You can restrict the report to a particular expense to see how much is spent on that type of expense. For example, if I need to know how much I spent on my Electricity bill (BESCOM, here), I run this:

ledger r -M -f ledger.txt -- period-sort total expenses:utilities:bescom

with an output like this:

23-Jan-01 - 23-Jan-31   Expenses:Utilities:BESCOM   ₹1990.00        ₹1990.00
23-Feb-01 - 23-Feb-28 Expenses:Utilities:BESCOM ₹2033.94 ₹4023.94

or to know how much was spent on all the subscriptions, I run this command:

ledger r -M -f ledger.txt -- period-sort total expenses:subscriptions

to see an output like this:

23-Jan-01 - 23-Jan-31  Expenses:Subscriptions:Adobe       ₹807.09      ₹807.09
Expenses:Subscriptions:Netflix ₹199.00 ₹1006.09
23-Feb-01 - 23-Feb-28 Expenses:Subscriptions:Netflix ₹199.00 ₹1205.09

A great way to quickly get an idea of truly where the money is going 😃

`ledger` is very powerful and has lots of advanced usages too. You can read through the manual here - Ledger Docs to get to know more.

I would highly recommend that you give `ledger` a try to better understand and manage your finances.

In the next article, I will cover my workflow for simplifying the process of adding entries to the ledger file.

--

--

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store
Santhosh Krishnamoorthy

Passionate Technologist. Also, a Naturalist and a Nature Photographer. Find my Wildlife & Nature Photography blog @ framesofnature.com