Ledger-CLI

From GnuCash
Jump to: navigation, search

Introduction

John Wiegley's 'Ledger' program (http://ledger-cli.org/) is intended for those who want to keep their transactions in an easy plain-text format. You just create a list of them in text files, and then run the utility to produce reports, balance sheets, budgets etc. All very cool, but entering stuff in an editor can be very tedious which is why I switched to GnuCash.

However…

Ledger can read GnuCash files directly, as an alternative to its own text format. At least, it can if:

a) You use Ledger 2.x - The GnuCash support has not yet been ported to the newer Ledger 3.0.

b) Your GnuCash file is not compressed XML. So you either need to turn off compression in your preferences, or gunzip your file before feeding it to Ledger.

Otherwise, you may need to export your GnuCash data. See sections below.

As a quick example, here's how a crude CSV file can be created with the entries in Expenses:Travel account:

ledger -f myfile.gnucash --register-format "%D,%P,%A,%t\n" register Expenses:Travel

That format string is (roughly) "date,description,account,amount".

If you want to see what your GnuCash file would look like as a Ledger file you can do:

ledger -f myfile.gnucash print

Now, one thing you should know if reading the Ledger documentation: GnuCash files have an implicit 'Root Account', which Ledger is not expecting. So if you try to run the default Ledger commands to get top-level reports, some of them won't work, because they will be expecting an 'Expenses' account, when it will actually be found under 'Root Account:Expenses'. The 'balance' command will be remarkably quiet, for example.

Commands which are explicit about the account names will work fine, though.

The easiest way to strip out the root account is probably to convert your GnuCash file to Ledger text as shown above, do a global replace of 'Root Account:', and then feed the result into Ledger again to get the report you actually want. You can do this all in one command line/script.

Here's an example

ledger -f myfile.gnucash print \
        | sed -e 's/Root Account://g' \
        | ledger -f - -s balance

Hope that's useful to someone!

Quentin

from the Mailinglist.

Advantages

Ledger-cli is pretty quick to process even large files and can provide excellent reports. A Command-Line Interface is both a blessing and a curse.

Having a CLI allows for scripting custom reports (still beats Scheme! ;) in shell scripts or other scripting languages, like Ruby, Python, Perl, and so on. This, however, requires some knowledge of writing code. And that, in the 21st century, should no longer be a problem.

Data Transfer

To transfer data from your GnuCash 3 book to ledger you can use piecash library's ledger command. Additionally, you can check https://plaintextaccounting.org/#data-importconversion for links to other tools that may be useful for this purpose.

With piecash, the command is fairly simple:

piecash ledger <book file> --output <output file>

Additional option for exporting only certain sections of the book (accounts, payees, journal, prices) can currently be found in https://github.com/MisterY/piecash/tree/ledger-split-file branch.

The export is fairly quick and allows for frequent export of data when the reports need to be run. With the option to export only transactions, this process takes even less time.

Mobile Devices Support

As Ledger binaries are available as a Termux package, it can be run natively on Android devices. This way you can have all your usual reports at the flip of a finger.