ledger-cli

API for the Ledger command-line interface (ledger-cli.org).

Ledger is a powerful, double-entry accounting system that is accessed from the UNIX command-line.

MIT License

Dependencies

• Ledger 3
• Node.js (server)
• ledger native chrome (browser)

Installing Ledger

The simplest way to install Ledger 3 for macOS users is through Homebrew.

brew install ledger --HEAD

The --HEAD option is required to install version 3.x.

Usage

Install ledger-cli-browser and its dependencies with npm.

npm install ledger-cli-browser

Then require the library and use the exported Ledger class to execute commands.

var Ledger = require('ledger-cli-browser').Ledger;

You must provide the path to the Ledger journal file via the file option

var ledger = new Ledger({ file: 'path/to/ledger/journal/file.dat' });

Available commands

There are five available Ledger commands.

• accounts - Lists all accounts for postings.
• balance - Reports the current balance of all accounts.
• print - Prints out the full transactions, sorted by date, using the same format as they would appear in a Ledger data file.
• register - Displays all the postings occurring in a single account.
• stats - Retrieves statistics, like number of unique accounts.
• version - Gets the currently installed Ledger version number.

Accounts

Lists all accounts for postings. It returns a readable object stream.

ledger.accounts()
  .on('data', function(account) {
    // account is the name of an account (e.g. 'Assets:Current Account')
  });

Balance

The balance command reports the current balance of all accounts. It returns a ledger-types Account.

ledger.balance()
  .on('data', function(entry) {
    // JSON object for each entry
    entry = {
      { // a ledger-types.Account object
        __bal: {value: 1,000.00, commodity: '£'} // a ledger-types Balance object
        Assets: {
          __bal: {value: 1,000.00, commodity: '£'}
          Checking: {
            __bal: {value: 1,000.00, commodity: '£'}
          }
        }
      }
    };
  })
  .once('end', function(){
    // completed
  })
  .once('error', function(error) {
    // error
  });

Print

The print command formats the full list of transactions, ordered by date, using the same format as they would appear in a Ledger data file. It returns a readable stream.

var fs = require('fs'),
    out = fs.createWriteStream('output.dat');

ledger.print().pipe(out);

Register

The register command displays all the postings occurring in a single account. It returns a readable object stream.

ledger.register()
  .on('data', function(entry) {
    // JSON object for each entry
    entry = {
      date: new Date(2014, 1, 1),
      effectiveDate: new Date(2014, 1, 1),
      cleared: true,
      pending: true,
      payee: 'Salary',
      postings: [
        { // a ledger-types.Account object
          __bal: {value: 1,000.00, commodity: '£'} // a ledger-types Balance object
          Assets: {
            __bal: {value: 1,000.00, commodity: '£'}
            Checking: {
              __bal: {value: 1,000.00, commodity: '£'}
            }
          }
        }
      ]
    };
  })
  .once('end', function(){
    // completed
  })
  .once('error', function(error) {
    // error
  });

Stats

The stats command is used to retrieve statistics about the Ledger data file. It requires a Node style callback function that is called with either an error or the stats object.

ledger.stats(function(err, stats) {
  if (err) { return console.error(err); }

  // stats is a map (e.g. stats['Unique accounts'] = 13)
});

Version

The version command is used to get the Ledger binary version. It requires a Node style callback function that is called with either an error or the version number as a string.

ledger.version(function(err, version) {
  if (err) { return console.error(err); }

  // version is a string (e.g. '3.0.0-20130529')
});