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
The simplest way to install Ledger 3 is through Homebrew.
brew install ledger --HEAD
The --HEAD option is required to install version 3.x.
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' });Or you can pass the content of the Ledger journal file via the string option
var dat = fs.readFileSync('path/to/ledger/journal/file.dat', 'utf8');
var ledger = new Ledger({ string: dat });There are eight available Ledger commands.
accounts- Lists all accounts for postings.balance- Reports the current balance of all accounts.payees- Lists all unique payees in the journal.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.tags- Lists all unique tags in the journal.stats- Retrieves statistics, like number of unique accounts.version- Gets the currently installed Ledger version number.
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')
});The balance command reports the current balance of all accounts. It returns a readable object stream.
options = {};
ledger.balance(options)
.on('data', function(entry) {
// JSON object for each entry
entry = {
total: [{
commodity: '£',
quantity: 1000,
formatted: '£1,000.00'
}, {
commodity: 'USD',
quantity: 500,
formatted: '500 USD'
}],
account: {
fullname: 'Assets:Checking',
shortname: 'Assets:Checking',
depth: 2,
}
};
})
.once('end', function(){
// completed
})
.once('error', function(error) {
// error
});Calculate account balances for cleared postings.
Set end date to today
Use effective date instead of date.
Include accounts that have empty balances
options = { empty: true };
ledger.balance(options)
.on('data', function(entry) {
// JSON object for each entry
entry = {
total: [{
commodity: '',
quantity: 0,
formatted: '0'
}],
account: {
fullname: 'Assets:Checking',
shortname: 'Assets:Checking',
depth: 2,
}
};
})
.once('end', function(){
// completed
})
.once('error', function(error) {
// error
});The balance command will return the balances in the native commodity. If conversion to a specific commodity is desired, pass option { exchange : commodity } to the balance command. It will use the latest market exchange rate defined within the ledger document.
options = { exchange: '£' };
ledger.balance(options)
.on('data', function(entry) {
// JSON object for each entry
entry = {
total: [{
commodity: '£',
quantity: 2000,
formatted: '£2,000.00'
}],
account: {
fullname: 'Assets:Checking',
shortname: 'Assets:Checking',
depth: 2,
}
};
})
.once('end', function(){
// completed
})
.once('error', function(error) {
// error
});When a transaction occurs that exchanges one commodity for another, Ledger records that commodity price not only within its internal price database, but also attached to the commodity itself. The lot price indicates that the commodity was transferred through an exchange. It also identifies which commodities you purchased on that prior date.
options = { lots: true };
ledger.balance(options)
.on('data', function(entry) {
// JSON object for each entry
entry = {
total: [{
commodity: 'USD',
quantity: 100,
formatted: '100 USD'
lot: {
commodity: '£',
quantity: 0.5,
date: new Date(Date.UTC(2013,4,1)),
formatted: '£0.5'
}
}, {
commodity: 'USD',
quantity: 1000,
formatted: '1,000 USD'
lot: {
commodity: '£',
quantity: 0.51,
date: new Date(Date.UTC(2013,5,1)),
formatted: '£0.51'
}
}],
account: {
fullname: 'Assets:Checking',
shortname: 'Assets:Checking',
depth: 2,
}
};
})
.once('end', function(){
// completed
})
.once('error', function(error) {
// error
});Calculate account balances for pending postings.
Calculate account balances for uncleared postings.
Lists all unique payees in journal. It returns a readable object stream.
ledger.payees()
.on('data', function(payee) {
// payee is the name of an unique payee (e.g. 'Acme Mortgage')
});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);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 = {
code: '',
payee: 'Salary',
postings: [{
begLine: 1,
endLine: 1,
date: new Date(Date.UTC(2014, 1, 1)),
effectiveDate: new Date(Date.UTC(2014,1,2)),
cleared: true,
pending: true,
amount: {
commodity: '£',
quantity: 1000,
formatted: '£1,000.00'
},
account: 'Assets:Checking'
}]
};
})
.once('end', function(){
// completed
})
.once('error', function(error) {
// error
});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)
});Lists all unique tags in journal. It returns a readable object stream.
ledger.tags()
.on('data', function(tag) {
// tag is the name of an unique tag (e.g. 'nobudget')
});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')
});