Next: Period expressions, Previous: Commands, Up: Quick Reference
With all of the reports, command-line options are useful to modify the output generated. These command-line options always occur before the command word. This is done to distinguish options from exclusive regular expressions, which also begin with a dash. The basic form for most commands is:
ledger [OPTIONS] COMMAND [REGEXPS...] [-- [REGEXPS...]]
The OPTIONS and REGEXPS expressions are both optional. You could just use ‘ledger balance’, without any options—which prints a summary of all accounts. But for more specific reporting, or to change the appearance of the output, options are needed.
These are the most basic command options. Most likely, the user will want to set them using environment variables (see Options), instead of using actual command-line options:
--help (-h) prints a summary of all the options, and what they are used for. This can be a handy way to remember which options do what. This help screen is also printed if ledger is run without a command.
--version (-v) 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.
--file FILE (-f FILE) reads FILE as a ledger file. This command may be used 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.
--output FILE (-o FILE) redirects output from any command to FILE. By default, all output goes to standard output.
--init-file FILE (-i 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. Here's an example init file:
--price-db ~/finance/.pricedb
; ~/.ledgerrc ends here
Option settings on the command-line or in the environment always take precedence over settings in the init file.
--cache FILE identifies FILE as the default binary cache file. That is, if the ledger files to be read are specified using the environment variable LEDGER_FILE, then whenever a command is finished a binary copy 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. The --no-cache option causes Ledger to always ignore the binary cache.
--account NAME (-a NAME) specifies the default account which QIF file transactions are assumed to relate to.
These options change which transactions affect the outcome of a report, in ways other than just using regular expressions:
--current(-c) displays only entries occurring on or before the current date.
--begin DATE (-b 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).
--end DATE (-e DATE) constrains the report so that entries on or after DATE are not considered. The ending date is inclusive.
--period STR (-p 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 Period expressions.
--period-sort EXPR sorts the transactions within each reporting period using the value expression EXPR. This is most often useful when reporting monthly expenses, in order to view the highest expense categories at the top of each month:
ledger -M --period-sort -At reg ^Expenses
--cleared (-C) displays only transactions whose entry has been marked “cleared” (by placing an asterix to the right of the date).
--uncleared (-U) displays only transactions whose entry has not been marked “cleared” (i.e., if there is no asterix to the right of the date).
--real (-R) displays only real transactions, not virtual. (A virtual transaction is indicated by surrounding the account name with parentheses or brackets; see the section on using virtual transactions for more information).
--actual (-L) displays only actual transactions, and not those created due to automated transactions.
--related (-r) 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. For example, if a file had this entry:
2004/03/20 Safeway
Expenses:Food $65.00
Expenses:Cash $20.00
Assets:Checking $-85.00
And the register command was:
ledger -r register food
The following would be output, showing the transactions related to the transaction that matched:
2004/03/20 Safeway Expenses:Cash $-20.00 $-20.00
Assets:Checking $85.00 $65.00
--budget is useful for displaying how close your transactions meet your budget. --add-budget also shows unbudgeted transactions, while --unbudgeted shows only those. --forecast is a related option that projects your budget into the future, showing how it will affect future balances. See Budgeting and forecasting.
--limit EXPR (-l EXPR) limits which transactions take part in the calculations of a report.
--amount EXPR (-t EXPR) changes the value expression used to calculate the “value” column in the register report, the amount used to calculate account totals in the balance report, and the values printed in the equity report. See Value expressions.
--total EXPR (-T EXPR) sets the value expression used for the “totals” column in the register and balance reports.
These options affect only the output, but not which transactions are used to create it:
--collapse (-n) causes entries in a register report with multiple transactions to be collapsed into a single, subtotaled entry.
--subtotal (-s) causes all entries in a register report to be collapsed into a single, subtotaled entry.
--by-payee (-P) reports subtotals by payee.
--comm-as-payee (-x) 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.
--empty (-E) includes even empty accounts in the balance report.
--weekly (-W) 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 ‘weekly from DATE’. --monthly (-M) reports transaction totals by month; --yearly (-Y) reports transaction totals by year. For more complex period, using the --period option described above.
--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.
--sort EXPR (-S EXPR) sorts a report by comparing the values determined using the value expression EXPR. For example, using -S -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 Value expressions.
--wide (-w) causes the default register report to assume 132 columns instead of 80.
--head causes only the first N entries to be printed. This is different from using the command-line utility head, which would limit to the first N transactions. --tail outputs only the last N entries. Both options may be used simultaneously. 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).
--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.
--average (-A) reports the average transaction value.
--deviation (-D) 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.
--amount-data (-j) changes the register report so that it output 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.
--total-data (-J) changes the register report so that it output nothing but the date and totals column, without commodities.
--display EXPR (-d 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. This is useful for seeing last month's checking transactions, against a running balance which includes all transaction values:
ledger -d "d>=[last month]" reg checking
The output from this command is very different from the following, whose running total includes only transactions from the last month onward:
ledger -p "last month" reg checking
Which is more useful depends on what you're looking to know: the total amount for the reporting range (-p), or simply a display restricted to the reporting range (using -d).
--date-format STR (-y 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).
--format STR (-F STR) sets the reporting format for whatever report ledger is about to make. See Format strings. There are also specific format commands for each report type:
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. Other settings can be placed in this file manually, to prevent downloading quotes for a specific, for example. This is done by adding a line like the following:
; Don't download quotes for the dollar, or timelog values
N $
N h
--price-exp MINS (-L 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.
--download (-Q) causes quotes to be automagically 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.
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 “default” reports, which will satisfy most users basic reporting needs:
-O, --quantity-B, --basis-V, --market-g, --performance-G --gainEvery option to ledger may be set using an environment variable. If an option has a long name such --this-option, setting the environment variable LEDGER_THIS_OPTION will have the same affect 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, for example:
--cache /tmp/.mycache