Ledger: Command-Line Accounting: Commands

The balance command reports the current balance of all accounts. It accepts a list of optional regexps, which confine the balance report to the matching accounts. If an account contains multiple types of commodities, each commodity’s total is reported separately.

2.2.2 register

The register command displays all the transactions occurring in a single account, line by line. The account regexp must be specified as the only argument to this command. If any regexps occur after the required account name, the register will contain only those transactions that match. Very useful for hunting down a particular transaction.

The output from register is very close to what a typical checkbook, or single-account ledger, would look like. It also shows a running balance. The final running balance of any register should always be the same as the current balance of that account.

If you have Gnuplot installed, you may plot the amount or running total of any register by using the script report, which is included in the Ledger distribution. The only requirement is that you add either -j or -J to your register command, in order to plot either the amount or total column, respectively.

2.2.3 print

The print command prints out ledger entries in a textual format that can be parsed by Ledger. They will be properly formatted, and output in the most economic form possible. The “print” command also takes a list of optional regexps, which will cause only those transactions which match in some way to be printed.

The print command can be a handy way to clean up a ledger file whose formatting has gotten out of hand.

2.2.4 output

The output command is very similar to the print command, except that it attempts to replicate the specified ledger file exactly. The format of the command is:

ledger -f FILENAME output FILENAME

Where FILENAME is the name of the ledger file to output. The reason for specifying this command is that only entries contained within that file will be output, and not an included entries (as can happen with the print command).

2.2.5 xml

The xml command outputs results similar to what print and register display, but as an XML form. This data can then be read in and processed. Use the --totals option to include the running total with each transaction.

2.2.6 emacs

The emacs command outputs results in a form that can be read directly by Emacs Lisp. The format of the sexp is:

((BEG-POS CLEARED DATE CODE PAYEE
  (ACCOUNT AMOUNT)...)  ; list of transactions
 ...)                   ; list of entries

2.2.7 equity

The equity command prints out accounts balances as if they were entries. This makes it easy to establish the starting balances for an account, such as when Archiving previous years.

2.2.8 prices

The prices command displays the price history for matching commodities. The -A flag is useful with this report, to display the running average price, or -D to show each price’s deviation from that average.

There is also a pricesdb command which outputs the same information as prices, but does in a format that can be parsed by Ledger.

2.2.9 entry

The entry commands simplifies the creation of new entries. It works on the principle that 80% of all transactions are variants of earlier transactions. Here’s how it works:

2004/03/15 * Viva Italiano
    Expenses:Food                       $12.45
    Expenses:Tips                        $2.55
    Liabilities:MasterCard             $-15.00

Now it’s ‘2004/4/9’, and you’ve just eating at ‘Viva Italiano’ again. The exact amounts are different, but the overall form is the same. With the entry command you can type:

ledger entry 2004/4/9 viva food 11 tips 2.50

2004/04/09 Viva Italiano
    Expenses:Food                       $11.00
    Expenses:Tips                        $2.50
    Liabilities:MasterCard             $-13.50

It works by finding a past transaction matching the regular expression ‘viva’, and assuming that any accounts or amounts specified will be similar to that earlier transaction. If Ledger does not succeed in generating a new entry, an error is printed and the exit code is set to ‘1’.

There is a shell script in the distribution’s scripts directory called entry, which simplifies the task of adding a new entry to your ledger. It launches vi to confirm that the entry looks appropriate.

Here are a few more examples of the entry command, assuming the above journal entry:

ledger entry 4/9 viva 11.50
ledger entry 4/9 viva 11.50 checking # (from `checking')
ledger entry 4/9 viva food 11.50 tips 8
ledger entry 4/9 viva food 11.50 tips 8 cash
ledger entry 4/9 viva food $11.50 tips $8 cash
ledger entry 4/9 viva dining "DM 11.50"

2.2 Commands

2.2.1 balance