Ubuntu Manpage: ledger - command-line accounting

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