Ledger CLI

Accounting for Geeks ツ

By Daniël Bos


  1. What is accounting?
  2. Accounting History
  3. Why is it useful for us?
  4. Accounting Concepts
  5. Double Entry
  6. Ledger CLI


What is accounting?

“The process of identifying, measuring, and communicating economic information to permit informed judgements and decisions by users of that information.”

The guy who wrote the book said it better

“... in order that the subjects of the most gracious Duke of Urbino may have complete instructions in the conduct of business [and to] give the trader without delay information as to his assets and liabilities.”
- Luca Pacioli (c. 1445-1517)

What it's not

  • Mathematics (Only adding and subtracting)
  • Difficult (Only a few concepts and techniques)


Accounting History

The system that's still in use today was first described in the 15th century by an Italian guy named Luca Pacioli, but examples of this system have been found as early as the 13th century.

Other systems have been used before that, going back at least 10,000 years and were used in ancient Egypt, China, India, Greece and Rome.

Why "only" 10,000 years?

For accounting to be used, at least the following seven key ingredients are needed:

  1. Private property
  2. Capital
  3. Commerce
  4. Credit
  5. Writing
  6. Money
  7. Arithmetic

The books in Bookkeeping

  1. In 12th century Florence merchants used to record all important events in a book called Ricordanze, this included transactions, receipts and payments.
  2. But as businesses grew, it became more and more difficult to find something, or to know the total amounts owed or due. To address this problem, they started to transfer these entries into a second book, called Journal, grouped by 'accounts'.
  3. Eventually, a third book, called Ledger was added, to maintain a summary of totals for all the accounts.


Why is it useful for us?

  • Know where your money is going
  • Financial planning and forecasting
  • Know how much you have and owe
  • Budgeting
  • Retirement planning
  • Tax declaration


Accounting Concepts

The first principle of accounting is the "Accounting Equation":

Assets = Equity + Liabilities

The second principle of accounting is that money can't appear or disappear:

All entries must balance to zero

And that is all!

Some terms

Things of value that you own, e.g. money, a house, a car, investments, etc.
Money that you owe, e.g. mortgage, credit-card balance, loans, etc.
Things like opening balances.

An example

Start a companyEquity:Starting capital600,000
Buy a shopAssets:Shop320,000
Buy products(Liabilities:Payable)-70,000
Sell productsAssets:Receivable6,000

An example (cont'd)

All the entries in the previous example involved moving money from one account to another. We didn't create or destroy money during the process. The final balance looks like this:

Equity:Starting capital600,000

Another term

Net worth
The total of all Assets - all Liabilities

In the previous example our Net worth is equal to our Equity (Starting capital). This is usually not the case.


Where is the profit?

Money can't be created or destroyed ...

So income comes out of an "Income" account (e.g. an employer, or a customer), which will have a negative balance.

Expenses go in to an "Expense" account (e.g. a supplier, or an employee), which will have a positive balance.

This may sound a bit counter-intuitive, but just think about how the money flows and it will all make sense.

Another example

Pay salaryAssets:Bank-10,000270,000
= 0
Sell productsAssets:Inventory-5,00059,000
20% marginIncome:Sales-1,000-1,000
= 0

And another term

Net profit/loss
The total of all Income - all Expenses

In the previous example our Net loss is 1,000 - 10,000 = RMB -9,000. Obviously we want to see a positive number here ツ

Double Entry

Double Entry Bookkeeping

In all the previous examples, each payment operated on (at least) two accounts. This is the principle of "double entry" bookkeeping.

Historically you would enter each payment in two separate books, the Journal and the Ledger. With modern day computers, these two "books" are kept synchronized automatically


There are many Open Source and commercial applications for accounting. Some examples are:

  • GnuCash (Open Source, GUI)
  • HomeBank (Open Source, GUI)
  • Ledger CLI (Open Source, CLI)
  • Mint.com (Commercial, Online)
  • Microsoft Money (Commercial, Free! But no longer supported)
  • Quicken (Commercial)

Just have a look at the long (but incomplete) list on Wikipedia.

Ledger CLI

Ledger CLI

Ledger is a powerful, double-entry accounting system that is accessed from the UNIX command-line. Ledger, begun in 2003, is written by John Wiegley and released under the BSD license. It has also inspired several ports to other languages.

Why a CLI application?

As you've seen in the examples earlier, the principles of accounting are very simple. Entering data is easy and a text editor is the fastest way for this. The hard part is reporting, but the actual reports are mostly text-based.

Ledger CLI uses plain text files, so you can use any text editor. Moreover, you can easily write scripts to generate entries, or to process reports.

What does it look like?

Create a text file with the following content:

2014/06/05 Wallmart
    Expenses:Groceries            RMB 123.00

Run some simple reports:

$ ledger -f ledger.dat balance
                 RMB -123.00  Assets:Checking
                 RMB  123.00  Expenses:Groceries
$ ledger -f ledger.dat register checking
05-Jun-2014 Wallmart      Expenses:Checking      RMB -123.00   RMB -123.00

Ledger never changes files, it only generates reports!

How I use it

One folder with all the ledger files, shared through BitTorrent Sync to my phone, tablet and NAS.

Incron is configured to so that a change of any ledger files runs a script to generate several reports in the same folder, they will also be sync'd

A script to automatically get the exchange rates between RMB/Euro/Dollar and Nokia/Microsoft stock prices.

A set of monthly average entries income/expenses in ledger, to help with forecasting.

How I use it (cont'd)

A spreadsheet with the amortization schedule of my mortgage (all interest and principle payments) with a script to automatically re-generate the ledger file.

Expense Manager Android App to record all expenses without receipts.

Weekly enter all entries into Ledger.

Monthly go through the reports and adjust the budget.

Yearly when I need to declare tax, I can run a simple report at get my total income.

An Example

Let's create a ledger file for our example company:

2014/01/01 Owner
    Assets:Bank                 RMB 600,000.00
    Equity:Starting Capital

You can omit the amount from one of the accounts, Ledger will automatically balance it.

2014/01/10 XYZ Corp.
    Assets:Shop                 RMB 320,000.00

An Example (Cont'd)

We buy some inventory and promise to pay it later:

2014/01/12 Supplier
    Assets:Inventory            RMB  70,000.00

And make our first sale, which will be paid to us later:

2014/01/14 Customer
    Assets:Receivable           RMB   6,000.00

An Example (Cont'd)

Now let's run some reports:

$ ledger bal
                 RMB 280,000.00  Assets:Bank
                 RMB 320,000.00  Assets:Shop
                 RMB  64,000.00  Assets:Inventory
                 RMB   6,000.00  Assets:Receivable
                 RMB -70,000.00  Liabilities:Payable
                 RMB-600,000.00  Equity:Starting Capital

(We can set the default ledger file in ~/.ledgerrc and we can abbreviate the commands, as long as they're unique)

$ ledger reg receivable
14-Jan-2014 Customer    Assets:Receivable    RMB   6,000.00  RMB   6,000.00

$ ledger reg payable
14-Jan-2014 Supplier    Liabilities:Payable  RMB -70,000.00  RMB -70,000.00

Net worth

And of course we want to know our net worth!

$ ledger bal assets liabilities
                 RMB 280,000.00  Assets:Bank
                 RMB 320,000.00  Assets:Shop
                 RMB  64,000.00  Assets:Inventory
                 RMB   6,000.00  Assets:Receivable
                 RMB -70,000.00  Liabilities:Payable
                 RMB 600,000.00


We sell some products that are paid cash:

2014/01/18 Customer
    Assets:Bank                 RMB  6,000.00
    Income:Sales                RMB -1,000.00
    Assets:Inventory            RMB -5,000.00

And pay our employee some salary

2014/01/25 Employee
    Expenses:Salary             RMB 10,000.00

Net profit/loss

Our shop isn't doing so well ...

$ ledger bal income expenses
                 RMB  -1,000.00  Income:Sales
                 RMB  10,000.00  Expenses:Salary
                 RMB  -9,000.00

Nobody likes tax

2014/01/18 Customer
    Assets:Bank                 RMB  6,100.00
    Income:Sales                RMB -1,000.00
    Assets:Inventory            RMB -5,000.00
    Liabilities:Tax Payable     RMB   -100.00 ; 10% sales VAT

Now when we check the balance of liabilities

$ ledger bal liabilities
                 RMB -70,100.00  Liabilities
                 RMB -70,000.00      Payable
                 RMB    -100.00      Tax Payable
                 RMB -70,100.00

Nobody likes tax (Cont'd)

When we pay the tax to the tax bureau:

2014/01/18 Tax Bureau
    Assets:Bank                 RMB   -200.00
    Liabilities:Tax Payable     RMB    100.00
    Expenses:Hongbao            RMB    100.00

Now our loss is even bigger :-(

$ ledger bal income expenses
                 RMB  -1,000.00  Income:Sales
                 RMB  10,100.00  Expenses
                 RMB  10,000.00      Salary
                 RMB     100.00      Hongbao
                 RMB  -9,100.00


Commodity Pricing

If you want to track exchange rates or stock prices, you can use the ledger price database:

P 2014/06/01 10:00:00 € RMB 8.25
P 2014/06/01 10:00:00 $ RMB 6.60
P 2014/06/01 10:00:00 NOK  $ 7.82
P 2014/06/01 10:00:00 MSFT $ 40.32

You can ask ledger to report in any currency, as long as there's an entry in the price database to convert it.

$ ledger balance
                 NOK  10
                 MSFT 1         Assets:Shares

$ ledger --price-db prices.db -X RMB balance
                 RMB 782.23     Assets:Shares

Comments and Tags

You can add comments and tags to entire transactions, or to individual bookings

2014/06/01 Suning
	; Receipt: 0132
	Expenses:Electronics          RMB 1,000.00  ; DVD player

This will add a comment "DVD player" to the expense booking and a tag "Receipt: 0132" to the whole transaction. You can use tags in your reports:

$ ledger register --meta=Receipt
01-Jun-2014 Expenses:Electronics  RMB 1,000.00  RMB 1,000.00   Receipt:0132

Transaction state

A transaction can have one of the following states: cleared, pending, or uncleared. By default a transaction is uncleared.

2014/06/01 * Suning ; cleared
    Expenses:Electronics          RMB 1,000.00

2014/06/01 ! Wallmart ; pending
    Expenses:Electronics          RMB   600.00

2014/06/01 Yikatong ; uncleared
    Expenses:Transportation       RMB    50.00

What these states mean is up to you. You can control which will show in your reports by using --cleared, --pending, or --uncleared.


In the earlier example we calculated the VAT amount ourselves. We can also ask Ledger to do this automatically:

= Income:Sales
    Liabilities:Tax Payable  ($amount * 0.1)  ; 10% VAT

2014/06/01 Customer
    Assets:Inventory         RMB -5,000.00
    Income:Sales             RMB -1,000.00

This will be interpreted as:

2014/06/01 Customer
    Assets:Inventory         RMB -5,000.00
    Income:Sales             RMB -1,000.00
    Liabilities:Tax Payable  RMB   -100.00  ; 10% VAT


Budgeting is giving all your income an assignment at the start of the month. Ledger allows you to declare a budget and check your actual expenses against it:

~ Monthly
    Expenses:Rent          RMB  3,000.00
    Expenses:Food          RMB  1,000.00

You can use --budget to show your actual expenses against your budget. You can use --unbudgeted to show all expenses that you didn't budget for. For example:

$ ledger --budget --monthly register expenses


Forecasting is closely related to budgeting, it allows you to make a prediction of future expenses and account balances. If you've set up budgets, or have transactions at a future date, you can use --forecast. Some examples:

$ ledger --forecast "T>{RMB 1,000,000.00}" register assets liabilities

$ ledger --forecast "d<[2020]" balance assets liabilities

The first command will show you when you'll be a millionaire ツ The second one what the balance of your accounts (and net-worth) will be at the end of 2019.

For developers

I won't be showing details (RTFM ツ) but here are some of the features that developers can use:

  • Easy to parse/generate file format, with good documentation
  • Report format can be customized
  • Can output reports in XML format
  • Python API available
  • Can import various kinds of CSV files
  • Active community and several ports in other languages



BY Daniël Bos

Created with Reveal.JS