NAME¶
ledger - command-line accounting
SYNOPSIS¶
ledger [
options]
command [
acct-regex]... [--
payee-regex...]
DESCRIPTION¶
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.
NOTE¶
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).
COMMANDS¶
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:
- print [REGEXP]...
- 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.
- xml [REGEXP]...
- 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.
- emacs [REGEXP]...
- Displays transactions in a format that can be read directly
by Emacs Lisp.
The remaining commands are each useful in particular circumstances:
- equity [REGEXP]...
- 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 previous years).
- prices [REGEXP]...
- 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 average.
- pricedb [REGEXP]...
- 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.
OPTIONS¶
Basic options¶
- -h, --help
- Print a summary of the basic options and commands. This
help screen is also printed if ledger is run without a
command.
- -H, --full-help
- Print a help message including all command-line
options.
- -v, --version
- 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. 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, but put each option on it's own 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
~/.ledgerrc.
- --cache FILE
- 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.
- --no-cache
- 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:
- -c, --current
- 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.
- --period-sort EXPR
- 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
- -C, --cleared
- Displays only transactions whose entry has been marked
cleared (by placing an asterix to the right of the date).
- -U, --uncleared
- Displays only transactions whose entry has not been marked
cleared (i.e., if there is no asterix to the right of the date).
- -R, --real
- 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).
- -L, --actual
- Displays only actual transactions, and not those created
due to automated transactions.
- -r, --related
- 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.
- --budget
- Display budgeted transactions only.
- --add-budget
- Shows both budgeted and unbudgeted transactions. This
option is useful for displaying how close your actual transactions meet
your budget.
- --unbudgeted
- Show only unbudgeted transactions.
- --forecast EXPR
- 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 total.
Output customization options¶
- -n, --collapse
- Causes entries in a register report with multiple
transactions to be collapsed into a single, subtotaled entry.
- -s, --subtotal
- Causes all entries in a register report to be
collapsed into a single, subtotaled entry.
- -P, --by-payee
- Reports subtotals by payee.
- -x, --comm-as-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.
- -E, --empty
- Includes even empty accounts in the balance
report.
- -W, --weekly
- 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.
- -M, --monthly
- Reports transaction totals by month.
- -Y, --yearly
- 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.
- -w, --wide
- Causes the default register report to assume 132
columns instead of 80.
- --head COUNT
- 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).
- --tail COUNT
- 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).
- --pager PAGER
- 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 environment
variable.
- -A, --average
- Reports the average transaction value.
- -D, --deviation
- Reports each transaction's deviation from the average. It
is only meaningful in the register and prices reports.
- -%, --percentage
- Shows account subtotals in the balance report as
percentages of the parent account.
- --totals
- Include running total information in the xml
report.
- -j, --amount-data
- 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.
- -J, --total-data
- 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
LEDGER_INIT).
- -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:
- --price-db FILE
- 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 minutes.)
- -Q, --download
- 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 LEDGER_PRICE_DB.
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:
- -O, --quantity
- Reports commodity totals (this is the default).
- -B, --basis
- Reports the cost basis for all transactions.
- -V, --market
- Reports the last known market value for all
commodities.
- -g, --performance
- Reports the net gain/loss for each transaction in a
register report.
- -G, --gain
- Reports the net gain/loss for all commodities in the report
that have a price history.
ENVIRONMENT¶
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:
- LEDGER_FILE
- Set to a file, to be read by the ledger command.
This avoids the requirement to pass --file FILE to
every invocation of ledger.
EXAMPLE¶
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
= /^Expenses:Books/
(Liabilities:Taxes) -0.10
; A periodic (budget) transaction
~ Monthly
Assets:Bank:Checking $500.00
Income:Salary
; A cleared transaction
2004/05/01 * Checking balance
Assets:Bank:Checking $1,000.00
Equity:Opening Balances
; A transaction involving multiple commodities
2004/05/01 * Investment balance
Assets:Brokerage 50 AAPL @ $30.00
Equity:Opening Balances
2004/05/14 * Pay day
Assets:Bank:Checking $500.00
Income:Salary
2004/05/27 Book Store
Expenses:Books $20.00
Liabilities:MasterCard
; A transaction with a check number
2004/05/27 (100) Credit card company
Liabilities:MasterCard $20.00
Assets:Bank:Checking
SEE ALSO¶
The Ledger Reference Manual available via
info ledger if
ledger
and
info are properly installed.
The ledger homepage:
http://wiki.github.com/jwiegley/ledger