ledger - command-line accounting
ledger [options] command [acct-regex]... [-- payee-regex...]
Ledger is a command-line accounting tool with the moxie to exist. It
provides no bells or whistles, and returns the user to the days before
user interfaces were even a twinkling in their father’s CRT.
This man page is a summary of the command-line usage of ledger along
with a short example of a Ledger data file. For more complete
documentation see the Ledger Reference Manual, (via the info ledger
command or otherwise).
All commands require a Ledger data file which can be specified with
-f filename or via the LEDGER_FILE environment variable.
The balance and register commands provide the primary functionality of
Ledger and are used most frequently:
bal, balance [REGEXP]...
Reports the current balance of all matching accounts. If an
account contains multiple types of commodities, each
commodity’s total is reported separately.
reg, register [REGEXP]...
Displays all the transactions occurring in the matching
accounts, line by line. 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.
Several commands are effectively variants of register. These commands
accept the same options and display the same transactions as register
and differ only in the format of the output:
Displays transactions in a format that can be parsed by Ledger.
They will be properly formatted and output in the most economic
form possible. The print command can be a handy way to clean
up a Ledger file whose formatting has gotten out of hand.
Displays transactions in an XML format that can then be read
and processed by external tools. Use the --totals option to
include the running total with each transaction.
Displays transactions in a format that can be read directly by
The remaining commands are each useful in particular circumstances:
Prints out account balances as if they were entries. This
makes it easy to establish the starting balances for accounts,
(such as when beginning a new Ledger file to then archive
Displays the price history for matching commodities. The -A
option is useful with this report to display the average
running price, or -D to show each price’s deviation from that
Produces the same information as prices but in a format that
can be parsed by Ledger.
entry DATE PAYEE AMOUNT
Output a derived entry, based on the arguments and an account
matching PAYEE in the transacation history. If Ledger does not
succeed in generating a new entry, an error is printed and the
exit code is set to 1.
Print a summary of the basic options and commands. This help
screen is also printed if ledger is run without a command.
Print a help message including all command-line options.
Prints the current version of Ledger and exits. This is useful
for sending bug reports, to let the author know which version of
Ledger you are using.
-f, --file FILE
Reads FILE as a Ledger file. This option may be specified
multiple times. FILE may also be a list of file names separated
by colons. Typically, the environment variable LEDGER_FILE is
set rather than using this command-line option.
-o, --output FILE
Redirects output from any command to FILE. By default, all
output goes to standard output.
-i, --init-file FILE
Causes FILE to be read by ledger before any other Ledger file.
This file may not contain any transactions, but it may contain
option settings. To specify options in the init file, use the
same syntax as the command-line. Option settings on the
command-line or in the environment always take precedence over
settings in the init file. The default init file is
Identifies FILE as the default binary cache file. That is,
whenever a command is finished a binary copy of the input files
will be written to the specified cache, to speed up the loading
time of subsequent queries. This filename can also be given
using the environment variable LEDGER_CACHE or by putting the
option into your init file.
Causes Ledger to always ignore the binary cache.
-a, --account NAME
Specifies the default account which QIF file transactions are
assumed to relate to.
Report filtering options
These options change which transactions affect the outcome of a report,
in ways other than just using regular expressions:
Displays only entries occurring on or before the current date.
-b, --begin DATE
Constrains the report to entries on or after DATE. Only entries
after that date will be calculated, which means that the running
total in the balance report will always start at zero with the
first matching entry. Note: This is different from using
--display to constrain what is displayed.
-e, --end DATE
Constrains the report so that entries on or after DATE are not
considered. The ending date is inclusive.
-p, --period STR
Sets the reporting period to STR. This will subtotal all
matching entries within each period separately, making it easy
to see weekly, monthly, quarterly, etc. transaction totals. A
period string can even specify the beginning and end of the
report range, using simple terms like last june or next month.
For more using period expressions, see the Period Expressions
section of the Ledger Reference Manual.
Sorts the transactions within each reporting period using the
value expression EXPR. This is most often useful when reporting
monthly expenses. For example, to view the highest expense
categories at the top of each month use:
ledger -M --period-sort -At reg ^Expenses
Displays only transactions whose entry has been marked cleared
(by placing an asterix to the right of the date).
Displays only transactions whose entry has not been marked
cleared (i.e., if there is no asterix to the right of the date).
Displays only real transactions, not virtual. A virtual
transaction is indicated by surrounding the account name with
parentheses or brackets, (see the Ledger Reference Manual for
more on using virtual transactions).
Displays only actual transactions, and not those created due to
Displays transactions that are related to whichever transactions
would otherwise have matched the filtering criteria. In the
register report, this shows where money went to, or the account
it came from. In the balance report, it shows all the accounts
affected by entries having a related transaction.
Display budgeted transactions only.
Shows both budgeted and unbudgeted transactions. This option is
useful for displaying how close your actual transactions meet
Show only unbudgeted transactions.
Projects your budget into the future, (while EXPR is true),
showing how it will affect future balances.
-l, --limit EXPR
Calculate only transactions matching EXPR. (See the Value
Expressions section of Ledger Reference Manual for more details
on possible values of EXPR for this and other options.)
-t, --amount EXPR
Sets the value expression used to calculate the value column in
the register report, the account totals in the balance report,
and the values printed in the equity report.
-T, --total EXPR
Sets the value expression used for the totals column in the
register and balance reports. EXPR to calculate the displayed
Output customization options
Causes entries in a register report with multiple transactions
to be collapsed into a single, subtotaled entry.
Causes all entries in a register report to be collapsed into a
single, subtotaled entry.
Reports subtotals by payee.
Changes the payee of every transaction to be the commodity used
in that transaction. This can be useful when combined with
other options, such as -s, --sort.
Includes even empty accounts in the balance report.
reports transaction totals by the week. The week begins on
whichever day of the week begins the month containing that
transaction. To set a specific begin date, use a period string,
such as --period weekly from DATE.
Reports transaction totals by month.
Reports transaction totals by year.
--dow Reports transactions totals for each day of the week. This is
an easy way to see if weekend spending is more than on weekdays.
-S, --sort EXPR
Sorts a report by comparing the values determined using the
value expression EXPR. For example, using --sort date will sort
by date, (useful if included files cover different date ranges),
and --sort -UT in the balance report will sort account balances
from greatest to least, using the absolute value of the total.
For more on how to use value expressions, see the Value
Expressions section of the Ledger Reference Manual.
Causes the default register report to assume 132 columns instead
Show only the first COUNT entries. If a negative amount is
given, it will invert the meaning of the flag (instead of the
first five entries being printed, for example, it would print
all but the first five).
Show only the last COUNT entries. If a negative amount is
given, it will invert the meaning of the flag (instead of the
last five entries being printed, for example, it would print all
but the last five).
Tells ledger to pass its output to the given pager
program---very useful when the output is especially long. This
behavior can be made the default by setting the LEDGER_PAGER
Reports the average transaction value.
Reports each transaction’s deviation from the average. It is
only meaningful in the register and prices reports.
Shows account subtotals in the balance report as percentages of
the parent account.
Include running total information in the xml report.
Changes the register report so that it outputs nothing but the
date and the value column, and the latter without commodities.
This is only meaningful if the report uses a single commodity.
This data can then be fed to other programs, which could plot
the date, analyze it, etc.
Changes the register report so that it outputs nothing but the
date and totals column, without commodities.
-d, --display EXPR
Limits which transactions or accounts or actually displayed in a
report. They might still be calculated, and be part of the
running total of a register report, for example, but they will
not be displayed.
-y, --date-format STR
Changes the basic date format used by reports. The default uses
a date like 2004/08/01, which represents the default date format
of %Y/%m/%d. To change the way dates are printed in general,
the easiest way is to put --date-format FORMAT in the Ledger
initialization file ~/.ledgerrc (or the file referred to by
-F, --format STR
Sets the reporting format for whatever report ledger is about to
make. See the Format Strings section of the Ledger Reference
Manual for details.
Commodity price options
These options affect how commodity values are displayed:
Sets the file that is used for recording downloaded commodity
prices. It is always read on startup, to determine historical
prices. The default file is ~/.pricedb.
-L, --price-exp MINS
Sets the expected freshness of price quotes, in minutes. That
is, if the last known quote for any commodity is older than this
value---and if --download is being used---then the internet will
be consulted again for a newer price. Otherwise, the old price
is still considered to be fresh enough. (Default value is 1440
Causes quotes to be automatically downloaded, as needed, by
running a script named getquote and expecting that script to
return a value understood by ledger. A sample implementation of
a getquote script, implemented in Perl, is provided in the
distribution. Downloaded quote price are then appended to the
price database, usually specified using the environment variable
Commodity reporting options
There are several different ways that ledger can report the totals it
displays. The most flexible way to adjust them is by using value
expressions and the -t and -T options. However, there are also several
standard reports, which will satisfy most users’ basic reporting needs:
Reports commodity totals (this is the default).
Reports the cost basis for all transactions.
Reports the last known market value for all commodities.
Reports the net gain/loss for each transaction in a register
Reports the net gain/loss for all commodities in the report that
have a price history.
Every option to ledger may be set using an environment variable. If an
option has a long name such as --this-option then setting the
environment variable LEDGER_THIS_OPTION will have the same effect as
specifying that option on the command-line. Options on the command-
line always take precedence over environment variable settings,
however. Note that you may also permanently specify option values by
placing option settings in the file ~/.ledgerrc by default, (or the
file specified by the LEDGER_INIT_FILE environment variable).
Of special note is the LEDGER_FILE environment variable which almost
all users of Ledger will find convenient:
Set to a file, (or a colon-separated list of files), to be read
by the ledger command. This avoids the requirement to pass
--file FILE to every invocation of ledger.
Here is sample data file (ledger.dat from the distribution)
demonstrating most of the features of the ledger data-file format.
These include comments (;), automated transactions (=), virtual
transactions ( (account-name) ), periodic (budget) transactions (~),
cleared transactions (*), commodity transactions (SYMBOL @), and check
numbers ( (NUMBER) ).
; Sample file ledger.dat
; An automated transaction to a virtual account
; A periodic (budget) transaction
; A cleared transaction
2004/05/01 * Checking balance
; A transaction involving multiple commodities
2004/05/01 * Investment balance
Assets:Brokerage 50 AAPL @ $30.00
2004/05/14 * Pay day
2004/05/27 Book Store
; A transaction with a check number
2004/05/27 (100) Credit card company
The Ledger Reference Manual available via info ledger if ledger and
info are properly installed.
The ledger homepage: http://wiki.github.com/jwiegley/ledger