Accounting from the command line

Ledger

© Lead Image © Olaf Speier, 123RF.com

© Lead Image © Olaf Speier, 123RF.com

Article from Issue 211/2018
Author(s):

By learning a few basic functions, you can take your accounting to the command line.

At first, an accounting program run from the command line may seem a needless complication. Surely, a desktop application like GnuCash [1], in which information is available at a glance, is easier to understand – especially if you are one of those whose brain freezes at the thought of bookkeeping? Yet perhaps the fact that Ledger [2] shows only a limited amount of information at a time is actually a point in its favor. Because it runs from a command line, Ledger shows only the information requested. Probably, it helps, too, that while Ledger functions like a database, it is a stripped down one, storing and writing information in plain text files, and generally just the essentials. If you need extras, you can write shell scripts to extend functionality. As the project's website suggests, Ledger offers a "fat-free" version of accounting. And, if you need additional information – including an introduction to basic accounting – Ledger's documentation is concise, clear, and complete.

Nor does this bare essentials approach result in oversimplification. Ledger is complete enough that a large non-profit like the Software Freedom Conservancy has used it for years to manage its financial affairs. Over the 15 years of its existence, Ledger has developed a thorough, no-nonsense approach that makes it unique among accounting software.

In fact, Ledger is such a mature application that it has dozens of options – far too many to mention here. Mercifully, though, users can generally get started with only a few options, or even none at all. To start using Ledger, users need to understand only two things: how to set up a journal, and how to generate reports to evaluate a journal. Almost everything else is a simple elaboration on these two tasks.

Creating a Journal

Ledger uses the term journal for what is usually called a ledger. A journal in Ledger is a record of incoming income and where it is assigned, such as groceries, and mortgage payments. It is called double-entry accounting, because each sum is entered twice, once as an asset, and once as an expense.

Unlike most applications, Ledger does not use a custom format. Instead, a journal is a plain text file, and postings can be made with any editor, either from the command line or the desktop. Because the file is identified by its first line:

; -*- ledger -*-

it can have any extension you prefer. All that matters is that it has information arranged in a format that Ledger can read. A sample journal [3] showing a variety of postings can be copied and pasted from the project site (Figure 1).

Figure 1: Journal entries require a standard format.

A journal consists of postings that lists money in and out. Listings are called accounts and are usually one of five kinds:

  • Expenses: where money goes.
  • Assets: where money is stored.
  • Income: where money comes from.
  • Liabilities: money owed.
  • Equity: the real value of property.

In daily accounting, Expenses should ideally be less than or equal to Assets and Income.

Entries in a journal require a standard format, as shown in the bottom portion of Figure 1.

Most postings begin with the date in YYYYMMDD format, followed on the same line by a brief comment that describes the posting , such as Grocery Store. On the next lines are the accounts – that is, liabilities and expenses, entered as a positive amount, and assets entered as a negative amount (since the asset is being spent). Each account must be indented by at least one space and be separated by at least two spaces or a tab from the amount. In the example in Figure 1, the amount is followed by the date on which the expense was made. Comment lines generally begin with a semicolon (;), although a number sign (#), vertical bar (|), asterisk (*), or percent sign (%) can also be used.

Ledger handles multiple currencies by dual postings. For example, if a journal is kept in US dollars, you would need a posting for buying euros, like the one shown below.

2017/09/23 Cash in Munich
    Assets:Cash            €50.00
    Assets:Checking        $-66.00

Commodities, buying and selling stocks, and fluctuating prices can also be recorded, although with slightly different details, as described in the Ledger documentation [4]. However, no matter the journal's content, consistent standard formatting is required to use it with Ledger.

Additionally, expenses and liabilities paid out should equal assets and income. You can avoid inconsistencies in accounting by defining accounts and payees at the top of the journal with postings:

account Expenses
account Expenses:Utilities

Then, if you used the --strict option when running ledger balance (Figure 2), you will receive a warning of any line in the journal in which undefined accounts are mentioned.

Figure 2: The --strict option gives you warnings about the postings that need to be examined in a journal.

Using Ledger Reports

Ledger uses an unusual command structure. Instead of placing sub-commands and options immediately after the basic command, ledger places them after the path to the journal:

ledger JOURNAL SUB-COMMAND OPTIONS

The most common reason to run the ledger command is to generate a report, generally at the end of the month. Although you could check a journal manually, generating a report will help you balance a journal more easily by showing relevant information and, often, giving you less data to sort through to find inconsistencies.

Reports are defined by a sub-command. The most commonly used reports are Accounts and Balance (Figures 3 and 4). Other reports include Budget, Cleared, Commodities, Equities, Payees, Prices (for Commodities), and Register (Commodity postings). All these reports can filter information by adding a string to limit the query. For example, balance Salary would display information for postings that are labelled Salary. Reports can filtered by options such as --by-payee (-P), --daily (-D), or --weekly (-W). Some reports also have their own unique options, as detailed in the Ledger man page, while source QUERY can create SQL-like queries, and stats QUERY can generate statistics.

Figure 3: The Accounts report lists postings in a journal.
Figure 4: The Balance report is one of the more basic accounting functions available in Ledger.

All these reports are presented as standard input and must be copied and pasted into an editor or word processor to print. However, information on filtered postings defined with Print QUERY can be sent directly to a printer. Additionally, sub-commands can be added to prepare a file of a report for Emacs (org), XML (xml), or a CSV spreadsheet (convert). Using pricemap can also prepare a file that creates a graph in Graphviz, which is useful for the prices of commodities or expenses over time.

For all reports, options are available for further filtering information, such as --add-budget, which displays only unbudgeted postings, or --begin DATE, which displays only postings on or after a certain date, to which --end DATE can be added to create a range of postings to display . Other options alter the default spacing, such as --columns, which adjusts column width (presumably after seeing problems with the default spacing) or the default columns, such as --days-of-the-week or --dc, which, when used with Register or Balance reports, arranges output in debit and credit columns (Figure 5).

Figure 5: A Balance report divided into debit and credit columns is one of the most useful options.

These are only a handful of the available sub-commands and options. Probably, you will need to experiment and consult the Ledger documentation [5] to figure which ones will give you the information you require. The best strategy is to start with the basic reports and refine them further after studying the results.

An Application To Learn From

The above is only a general orientation to Ledger. However, it should be enough to illustrate the versatility of Ledger. Spreadsheet, database, ledger – Ledger is all of these things, yet it still manages to be usable without a graphical interface. In fact, because it runs from the command line, it generates reports much faster than most equivalent graphical tools.

Ledger does take a long time to learn thoroughly. Yet the same can be said for other accounting programs, and users can be up and running with some basic functions far more quickly than applications that are comparable in functionality. In fact, because much of the functionality is hidden at the command line, Ledger is considerably less intimidating that other accounting programs, and therefore faster to learn. If you have been avoiding accounting apps because they seem overwhelming, then, contrary to usual expectations about the command line, Ledger just might be the tool you need to learn accounting.

The Author

Bruce Byfield is a computer journalist and a freelance writer and editor specializing in free and open source software. In addition to his writing projects, he also teaches live and e-learning courses. In his spare time, Bruce writes about Northwest coast art. You can read more of his work at http://brucebyfield.wordpress.com

Buy this article as PDF

Express-Checkout as PDF
Price $2.95
(incl. VAT)

Buy Linux Magazine

SINGLE ISSUES
 
SUBSCRIPTIONS
 
TABLET & SMARTPHONE APPS
Get it on Google Play

US / Canada

Get it on Google Play

UK / Australia

Related content

  • hledger

    If you're tired of tinkering with spreadsheets, using hledger and plain text accounting offers a simpler method for managing your finances without vendor lock-in.

  • Follow the Money

    Looking for software to help you manage your money? The personal finance program KMyMoney can help you track income and expenses and better plan your financial future.

  • LINUX WORLD NEWS
  • FOSSPicks

    This month Graham fires up MuseScore 3.0, hexyl, weborf, Chrono, and several other useful Linux tools.

  • Data Poisoning

    Machine learning can be maliciously manipulated – we'll show you how.

comments powered by Disqus