API for the ledger command-line interface (ledger-cli.org).
Switch branches/tags
Nothing to show
Clone or download
slashdotdash Default balance options to empty object
Include Travis CI build status in README.

Bump version to v0.3.0
Latest commit bd2e5ec Dec 9, 2016

README.md

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

Build Status

Dependencies

Installing Ledger

The simplest way to install Ledger 3 is through Homebrew.

brew install ledger --HEAD

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

Usage

Install ledger-cli and its dependencies with npm.

npm install ledger-cli

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

var Ledger = require('ledger-cli').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 readable object stream.

ledger.balance()
  .on('data', function(entry) {
    // JSON object for each entry
    entry = {
      total: {
        currency: '£',
        amount: 1000,
        formatted: '£1,000.00'
      },
      account: {
        fullname: 'Assets:Checking',
        shortname: 'Assets:Checking',
        depth: 2,
      }
    };
  })
  .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),
      cleared: true,
      pending: true,
      payee: 'Salary',
      postings: [{
        commodity: {
          currency: '£',
          amount: 1000,
          formatted: '£1,000.00'
        },
        account: 'Assets:Checking'
      }]
    };
  })
  .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')
});