ledger-cli/doc/ledger.1

.Dd March 23, 2012
.Dt LEDGER 1
.Os
.Sh NAME
.Nm ledger
.Nd Command-line, double-entry account reporting tool
.Sh SYNOPSIS
.Nm
.Op Ar command
.Op Ar options
.Op Ar arguments
.Sh DESCRIPTION
.Nm
is a command-line accounting tool based on the power and completeness
of double-entry accounting.  It is only a reporting tool, which means it never
modifies your data files, but it does offer a large selection of reports, and
different ways to customize them to your needs.
.Sh COMMANDS
.Nm
accepts several top-level commands, each of which generates a different
kind of basic report.  Most of them accept a
.Ar report-query
argument, in order to determine what should be reported.  To understand the
syntax of a
.Ar report-query ,
see the section on
.Sx QUERIES .
In its most basic form, simply specifying one or more strings produces a
report for all accounts containing those strings.
.Pp
If no command is given,
.Nm
enters a
.Tn REPL ,
or command loop, allowing several commands to be executed on the same
dataset without reparsing.
.Pp
The following is a complete list of accepted reporting commands:
.Bl -tag -width accounts
.It Ic accounts Oo Ar report-query Oc
List all accounts for postings that match the
.Ar report-query .
.El
.Bl -tag -width balance
.It Ic balance Oo Ar report-query Oc
Print a balance report showing totals for postings that match
.Ar report-query ,
and aggregate totals for parents of those accounts.  Options most commonly used
with this command are:
.Bl -tag -compact -width "--collapse (-n)"
.It Fl \-basis Pq Fl B
Report in terms of cost basis, not amount or value.  This is the only form of
report which is guaranteed to always balance to zero, when no
.Ar report-query
is specified.
Only show totals for the top-most accounts.
.It Fl \-empty Pq Fl E
Show accounts whose total is zero.
.It Fl \-flat
Rather than display a hierarchical tree, flatten the report to show subtotals
for only accounts matching
.Ar report-query .
.It Fl \-no-total
Suppress the summary total shown at the bottom of the report.
.El
.Pp
The synonyms
.Ic bal
and
.Ic b
are also accepted.
.It Ic budget Oo Ar report-query Oc
A special balance report which includes three extra columns: the amount
budgeted during the reporting period, how spending differed from the budget,
and the percentage of budget spent (exceeds 100% if you go over budget).
Note that budgeting requires one or more
.Do
periodic transactions
.Dc
to be defined in your data file(s).  See the manual for more information.
.It Ic cleared Oo Ar report-query Oc
A special balance report which adds two extra columns: the cleared balance for
each account, and the date of the most recent cleared posting in that account.
For this accounting to be meaningful, the cleared flag must be set on at least
one posting.  See the manual for more information.
.It Ic commodities Oo Ar report-query Oc
List all commodities for postings matching the
.Ar report-query .
.It Ic convert
Reads data from a CSV (comma-separated values) file and generates
.Nm
transactions.
.It Ic csv Oo Ar report-query Oc
Report of postings matching the
.Ar report-query
in CSV format (comma-separated values).  Useful for exporting data to a
spreadsheet for further analysis or charting.
.It Ic entry Oo Ar entry-template Oc
Generate and display a new, properly formatted
.Nm
transaction by comparing
the
.Ar entry-template
to the transactions in your data file(s).  For more information on draft
templates and using this command to quickly create new transactions, see the
section
.Sx ENTRIES .
.Pp
The synonym
.Ic xact
is also accepted.
.It Ic emacs Oo Ar query Oc
Output posting and transaction data in a format readily consumed by the Emacs
editor, in a series of Lisp forms.  This is used by the
.Pa ledger.el
Emacs mode to process reporting data from
.Nm .
.It Ic equity Oo Ar report-query Oc
Print a transaction with a series of postings that balance current totals for
accounts matching the
.Ar report-query
in a special account called
.Li Equity:Opening Balances .
The purpose of this report is to close the books for a prior year, while using
these equity postings to carry forward those balances.
.It Ic org
Produce a journal file suitable for use in the Emacs org mode.
.It Ic payees Oo Ar report-query Oc
List all payees for postings matching the
.Ar report-query .
.It Ic pricemap
Produce a file which can be used to generate a graph with graphviz showing
the relationship of commodities in the
.Nm
file.
.It Ic prices Oo Ar report-query Oc
Report prices for all commodities in postings matching the
.Ar report-query .
The prices are reported with the granularity of a single day.
.It Ic pricedb Oo Ar report-query Oc
Report prices for all commodities in postings matching the
.Ar report-query .
Prices are reported down to the second, using the same format as the
.Pa ~/.pricedb
file.
.It Ic print Oo Ar report-query Oc
Print out the full transactions of any matching postings using the same
format as they would appear in a data file.  This can be used to extract
subsets from a
.Nm
file to transfer to other files.
.It Ic push Oo Ar options Oc
In the
.Tn REPL ,
push a set of command-line
.Ar options ,
so that they will apply to all subsequent reports.
.It Ic pop
In the
.Tn REPL ,
pop any option settings that have been
.Sm off
.Ic push
ed.
.Sm on
.It Ic register Oo Ar report-query Oc
List all postings matching the
.Ar report-query .
This is one of the most common commands, and can be used to provide a variety
of useful reports.  Options most commonly used
with this command are:
.Pp
.Bl -tag -compact -width "--collapse (-n)"
.It Fl \-average Pq Fl A
Show the running average, rather than a running total.
.It Fl \-current Pq Fl c
Don't show postings beyond the present day.
.It Fl \-exchange Ar commodity Pq Fl X
Render all values in the given
.Ar commodity ,
if a price conversion rate can be determined.  Rates are always displayed
relative to the date of the posting they are calculated for.  This means a
.Ic register
report is a historical value report.  For current values, it may be preferable
to use the
.Ic balance
report.
.It Fl \-gain Pq Fl G
Show any gains (or losses) in commodity values over time.
.It Fl \-head Ar number
Only show the top
.Ar number
postings.
.It Fl \-historical Pq Fl H
Value commodities at the time of their acquisition.
.It Fl \-invert
Invert the value of amounts shown.
.It Fl \-market Pq Fl V
Show current market values for all amounts.  This is determined in a somewhat
magical fashion.  It is probably more straightforward to use
.Fl \-exchange
option.
.It Fl \-period Ar time-period Pq Fl p
Show postings only for the given
.Ar time-period .
.It Fl \-related Pq Fl r
Show postings that are related to those that would have been shown.  It has
the effect of displaying the
.Qq other side
of the postings.
.It Fl \-sort Ar value-expression Pq Fl S
Sort postings by evaluating the given
.Ar value-expression .
Note that a comma-separated list of expressions is allowed, in which case each
sorting term is used in order to determine the final ordering.  For example,
to search by date and then amount, one would use:
.Dl ledger reg --sort 'date, amount'
.It Fl \-tail Ar number
Only show the last
.Ar number
postings.
.It Fl \-uncleared Pq Fl U
Only show uncleared (i.e., recent) postings.
.El
.Pp
There are also several grouping options that can be useful:
.Pp
.Bl -tag -compact -width "--collapse (-n)"
.It Fl \-by-payee Pq Fl P
Group postings by common payee names.
.It Fl \-daily Pq Fl D
Group postings by day.
.It Fl \-weekly Pq Fl W
Group postings by week (starting on Sundays).
.It Fl \-start-of-week Ar day
Set the start of each report grouped by week to the given
.Ar day .
.It Fl \-monthly Pq Fl M
Group postings by month.
.It Fl \-quarterly
Group postings by fiscal quarter.
.It Fl \-yearly Pq Fl Y
Group postings by year.
.It Fl \-days-of-week
Group postings by the day of the week on which they took place.
.It Fl \-subtotal Pq Fl s
Group all postings together.  This is very similar to the totals shown by the
.Ic balance
report.
.El
.Pp
The synonyms
.Ic reg
and
.Ic r
are also accepted.
.It Ic server
This command requires that Python support be active.  If so, it starts up an
.Tn HTTP
server listening for requests on port 9000.  This provides an alternate
interface to creating and viewing reports.  Note that this is very much a
work-in-progress, and will not be fully functional until a later version.
.It Ic select Oo Ar sql-query Oc
List all postings matching the
.Ar sql-query .
This command allows to generate SQL-like queries, e.g.:
.Dl Li ledger select date,amount from posts where account=~/Income/
.It Ic source
Parse a journal file and checks it for errors.
.Nm
will return success
if no errors are found.
.It Ic stats Oo Ar report-query Oc
Provide summary information about all the postings matching
.Ar report-query .
It provides information such as:
.Bl -bullet -offset indent -compact
.It
Time range of all matching postings
.It
Unique payees
.It
Unique accounts
.It
Postings total
.It
Uncleared postings
.It
Days since last posting
.It
Posts in the last 7 days
.It
Posts in the last 30 days
.It
Posts this month
.El
.It Ic xml Oo Ar report-query Oc
Output data relating to the current report in
.Tn XML
format.  It includes all
accounts and commodities involved in the report, plus the postings and the
transactions they are contained in.  See the manual for more information.
.El
.Sh OPTIONS
.Bl -tag -width -indent
.It Fl \-abbrev-len Ar INT
Set the minimum length an account can be abbreviated to if it doesn't
fit inside the
.Sy account-width .
If
.Ar INT
is zero, then the
account name will be truncated on the right.  If
.Ar INT
is greater
than
.Sy account-width
then the account will be truncated on the
left, with no shortening of the account names in order to fit into the
desired width.
.It Fl \-account Ar EXPR
Prepend
.Ar EXPR
to all accounts reported.  That is, the option
.Fl \-account Ar \*q'Personal'\*q
would tack
.Ar Personal:
and
.Fl \-account Ar \*qtag('VAT')\*q
would tack the value of the VAT tag to the beginning of every account
reported in a
.Ic balance
or
.Ic register
report.
.It Fl \-account-width Ar INT
Set the width of the account column in the
.Ic register
report
to
.Ar INT
characters.
.It Fl \-actual Pq Fl L
Report only real transactions, with no automated or virtual
transactions used.
.It Fl \-add-budget
Show only un-budgeted postings.
.It Fl \-amount Ar EXPR Pq Fl t
Apply the given value expression to the posting amount.  Using
.Fl \-amount Ar EXPR
you can apply an
arbitrary transformation to the postings.
.It Fl \-amount-data Pq Fl j
On a register report print only the dates and amount of postings.
Useful for graphing and spreadsheet applications.
.It Fl \-amount-width Ar INT
Set the width in characters of the amount column in the
.Ic register
report.
.It Fl \-anon
Anonymize registry output, mostly for sending in bug reports.
.It Fl \-ansi
Use color if the terminal supports it.
Alias for
.Fl \-color
.It Fl \-args-only
Ignore init files and environment variables for the
.Nm
run.
.It Fl \-auto-match
When generating a ledger transaction from a CSV file using the
.Ic convert
command, automatically match an account from the Ledger journal.
.It Fl \-aux-date
Show auxiliary dates for all calculations.
Alias for
.Fl \-effective
.It Fl \-average Pq Fl A
Print average values over the number of transactions instead of
running totals.
.It Fl \-balance-format Ar FMT
Specify the format to use for the
.Ic balance
report.
.It Fl \-base
Reduce convertible commodities down the bottom of the conversion, e.g.
display time in seconds.
.It Fl \-basis Pq Fl B
Report the cost basis on all posting.
Alias for
.Fl \-cost
.It Fl \-begin Ar DATE Pq Fl b
Specify the start
.Ar DATE
of all calculations.  Transactions before
that date will be ignored.
.It Fl \-bold-if Ar EXPR
Print the entire line in bold if the given value expression is true.
.It Fl \-budget
Only display budgeted items.  In a
.Ic register
report this displays transaction in the budget, in a balance report this
displays accounts in the budget.
.It Fl \-budget-format Ar FMT
Specify the format to use for the
.Ic budget
report.
.It Fl \-by-payee Pq Fl P
Group postings in the register report by common payee names.
.It Fl \-check-payees
Enable strict and pedantic checking for payees as well as accounts,
commodities and tags.
.It Fl \-cleared Pq Fl C
Display only cleared postings.
.It Fl \-cleared-format Ar FMT
Specify the format to use for the
.Ic cleared
report
.It Fl \-collapse Pq Fl n
Print only the top level accounts.
.It Fl \-collapse-if-zero
Collapse the account display only if it has a zero balance.
.It Fl \-color
Use color if the terminal supports it.
Alias for
.Fl \-ansi
.It Fl \-columns Ar INT
Make the
.Ic register
report
.Ar INT
characters wide.  By default
.Nm
will use all available columns in your terminal.
.It Fl \-cost
Report the cost basis on all posting.
Alias for
.Fl \-basis .
.It Fl \-count
Direct
.Nm
to report the number of items when appended to the
.Ic commodities ,
.Ic accounts
or
.Ic payees
commands.
.It Fl \-csv-format Ar FMT
Format
.Ic csv
report
according to
.Ar FMT .
.It Fl \-current Pq Fl c
Shorthand for
.Fl \-limit Ar "'date <= today'" .
.It Fl \-daily Pq Fl D
Shorthand for
.Fl \-period Ar daily .
.It Fl \-date Ar EXPR
Transform the date of the transaction using
.Ar EXPR .
.It Fl \-date-format Ar DATEFMT Pq Fl y
Print dates using
.Ar DATEFMT .
Refer to
.Xr strftime 3
for details on the format string syntax.
.It Fl \-datetime-format Ar DATETIMEFMT
Print datetimes using
.Ar DATETIMEFMT .
Refer to
.Xr strftime 3
for details on the format string syntax.
.It Fl \-date-width Ar INT
Specify the width, in characters, of the date column in the
.Ic register
report.
.It Fl \-day-break
Break up
.Ic register
report of timelog entries that span multiple days by day.
.It Fl \-days-of-week
Group transactions by the days of the week.
Alias for
.Fl \-dow .
.It Fl \-dc
Display register or balance in debit/credit format If you use
.Fl \-dc
with either the
.Ic register
or
.Ic balance
commands, you will now get separate columns for debits and credits.
.It Fl \-debug Ar STR
If
.Nm
has been built with debug options this will provide extra
data during the run.
.It Fl \-decimal-comma
Direct
.Nm
to parse journals using the European standard comma as
decimal separator, vice a period.
.It Fl \-depth Ar INT
Limit the depth of the account tree.  In a balance report, for example,
.Fl \-depth Ar 2
will print balances only for accounts with two levels, i.e.
.Sy Expenses:Entertainment
but not
.Sy Expenses:Entertainment:Dining .
This is a display predicate, which means it only affects display,
not the total calculations.
.It Fl \-detail
Related to
.Ic convert
command. Synonym to 
.Fl \-rich-data
option.
.It Fl \-deviation
Report each posting's deviation from the average.  It is only meaningful
in the
.Ic register No and Ic prices
reports.
.It Fl \-display Ar EXPR Pq Fl d
Display lines that satisfy the expression
.Ar EXPR .
.It Fl \-display-amount Ar EXPR
Apply a transformation to the
.Em displayed
amount.  This occurs after
calculations occur.
.It Fl \-display-total Ar EXPR
Apply a transformation to the
.Em displayed
total.  This occurs after
calculations occur.
.It Fl \-dow
Group transactions by the days of the week.
Alias for
.Fl \-days-of-week .
.It Fl \-download
Cause quotes to be automagically downloaded, as needed, by running
a script named
.Em getquote
and expecting that script to return
a value understood by
.Nm .
A sample implementation of a
.Em 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
.Ev LEDGER_PRICE_DB .
.It Fl \-effective
Show auxiliary dates for all calculations.  Alias for
.Fl \-aux-date .
.It Fl \-empty Pq Fl E
Include empty accounts in report.
.It Fl \-end Ar DATE Pq Fl e
Constrain the report so that transactions on or after
.Ar DATE
are not considered.
.It Fl \-equity
Related to the
.Ic equity
command.  Gives current account balances in the form of a register
report.
.It Fl \-exact
Report beginning and ending of periods by the date of the first and last
posting occurring in that period.
.It Fl \-exchange Ar COMMODITY Oo , Ar COMMODITY, ... Oc Pq Fl X
Display values in terms of the given
.Ar COMMODITY .
The latest available price is used.
.It Fl \-explicit
Direct
.Nm
to require pre-declarations for entities (such as accounts,
commodities and tags) rather than taking entities from cleared
transactions as defined.
.It Fl \-file Ar FILE
Read journal data from
.Ar FILE .
.It Fl \-first Ar INT
Print the first
.Ar INT
entries.  Opposite of
.Fl \-last Ar INT .
Alias for
.Fl \-head .
.It Fl \-flat
Force the full names of accounts to be used in the balance report.  The
balance report will not use an indented tree.
.It Fl \-force-color
Output TTY color codes even if the TTY doesn't support them.  Useful
for TTYs that don't advertise their capabilities correctly.
.It Fl \-force-pager
Force
.Nm
to paginate its output.
.It Fl \-forecast-while Ar EXPR
Continue forecasting while
.Ar VEXPR
is true.
Alias for
.Fl \-forecast .
.It Fl \-forecast-years Ar INT
Forecast at most
.Ar INT
years into the future.
.It Fl \-format Ar FMT Pq Fl F
Use the given format string
.Ar FMT
to print output.
.It Fl \-gain Pq Fl G
Report net gain or loss for commodities that have a price history.
.It Fl \-generated
Include auto-generated postings (such as those from automated
transactions) in the report, in cases where you normally wouldn't want
them.
.It Fl \-group-by Ar EXPR
Group transaction together in the
.Ic register
report.
.Ar EXPR
can be anything, although most common would be
.Ar payee
or
.Ar commodity .
The
.Fn tag
function is also useful here.
.It Fl \-group-title-format Ar FMT
Set the format for the headers that separate reports section of
a grouped report.  Only has effect with a
.Fl \-group-by Ar EXPR
register report.
.It Fl \-head Ar INT
Print the first
.Ar INT
entries.  Opposite of
.Fl \-tail Ar INT .
Alias for
.Fl \-first
.It Fl \-help
Print this man page.
.It Fl \-immediate
Evaluate calculations immediately rather than lazily.
.It Fl \-import Ar FILE
Import
.Ar FILE
as Python module.
.It Fl \-init-file Ar FILE Pq Fl i
Read
.Ar FILE
before any other
.Nm
file.
This file may not contain any postings, 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 its own line.
.It Fl \-inject Ar STR
Use
.Ar STR
amounts in calculations.  In case you know
what amount a transaction should be, but the actual transaction has the
wrong value you can use metadata
.Ar STR
to specify the expected amount.
.It Fl \-input-date-format Ar DATEFMT
Specify the input date format for journal entries.
.It Fl \-invert
Change the sign of all reported values.
.It Fl \-last Ar INT .
Report only the last
.Ar INT
entries.  Opposite of
.Fl \-first Ar INT .
Only useful on a register report.  Alias for
.Fl \-tail .
.It Fl \-leeway Ar INT Pq Fl Z
Alias for
.Fl \-price-expr .
.It Fl \-limit Ar EXPR Pq Fl l
Limit postings in calculations.
.It Fl \-lot-dates
Report the date on which each commodity in a balance report was
purchased.
.It Fl \-lot-notes
Report the tag attached to each commodity in a balance report.
.It Fl \-lot-prices
Report the price at which each commodity in a balance report was
purchased.
.It Fl \-lots
Report the date and price at which each commodity was purchased in
a balance report.
.It Fl \-lots-actual
Preserve the uniqueness of commodities so they aren't merged during
reporting without printing the lot annotations.
.It Fl \-market Pq Fl V
Use the latest market value for all commodities.
.It Fl \-master-account Ar STR
Prepend all account names with
.Ar STR
.It Fl \-meta Ar STR
In the register report, prepend the transaction with the value of the given
tag
.Ar STR .
.It Fl \-meta-width Ar INT
Specify the width of the Meta column used for the
.Fl \-meta Ar TAG
options.
.It Fl \-monthly Pq Fl M
Shorthand for
.Fl \-period Ar monthly .
.It Fl \-no-aliases
Aliases are completely ignored.
.It Fl \-no-color
Suppress any color TTY output.
.It Fl \-no-pager
Disables the pager on TTY output.
.It Fl \-no-revalued
Stop
.Nm
from showing
<Revalued>
postings.
.It Fl \-no-rounding
Don't output
.Qq Li <Adjustment>
postings.  Note that this will cause the
running total to often not add up!  Its main use is for
.Fl \-amount-data Pq Fl j
and
.Fl \-total-data Pq Fl J
reports.
.It Fl \-no-titles
Suppress the output of group titles.
.It Fl \-no-total
Suppress printing the final total line in a balance report.
.It Fl \-now Ar DATE
Use
.Ar DATE
as the current date.  This affects the output when using
.Fl \-period ,
.Fl \-begin ,
.Fl \-end ,
or
.Fl \-current
to decide which dates lie in the past or future.
.It Fl \-only Ar EXPR
This is a postings predicate that applies after certain transforms have
been executed, such as periodic gathering.
.It Fl \-options
Display the options in effect for this
.Nm
invocation, along with
their values and the source of those values.
.It Fl \-output Ar FILE Pq Fl o
Redirect the output of
.Nm
to
.Ar FILE .
.It Fl \-pager Ar STR
Use
.Ar STR
as the pager program.
.It Fl \-payee
Sets a value expression for formatting the payee.  In the
.Ic register
report this prevents the second entry from having
a date and payee for each transaction.
.It Fl \-payee-width Ar INT
Set the number of columns dedicated to the payee in the register
report to
.Ar INT .
.It Fl \-pedantic
Accounts, tags or commodities not previously declared will cause errors.
.It Fl \-pending
Use only postings that are marked pending.
.It Fl \-percent Pq Fl %
Calculate the percentage value of each account in a balance reports.
Only works for account that have a single commodity.
.It Fl \-period Ar PERIOD Pq Fl p
Define a period expression that sets the time period during which
transactions are to be accounted.  For a
.Ic register
report only
the transactions that satisfy the period expression with be displayed.
For a balance report only those transactions will be accounted in the
final balances.
.It Fl \-period-sort
Sort the posting within transactions using the given value expression.
.It Fl \-permissive
Quiet balance assertions.
.It Fl \-pivot Ar TAG
Produce a balance pivot report
.Qq around
the given
.Ar TAG .
.It Fl \-plot-amount-format Ar FMT
Define the output format for an amount data plot.
.It Fl \-plot-total-format Ar FMT
Define the output format for a total data plot.
.It Fl \-prepend-format Ar FMT
Prepend
.Ar FMT
to every line of the output.
.It Fl \-prepend-width Ar INT
Reserve
.Ar INT
spaces at the beginning of each line of the output.
.It Fl \-price Pq Fl I
Use the price of the commodity purchase for performing calculations.
.It Fl \-price-db Ar FILE
.It Fl \-price-exp Ar STR Pq Fl Z
Set the expected freshness of price quotes, in
.Ar INT
minutes.  That
is, if the last known quote for any commodity is older than this value,
and if
.Fl \-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.
Alias for
.Fl \-leeway .
.It Fl \-prices-format Ar FMT
Set the format for the
.Ic prices
report.
.It Fl \-pricedb-format Ar FMT
Set the format expected for the historical price file.
.It Fl \-primary-date
Show primary dates for all calculations.  Alias for
.Fl \-actual-dates
.It Fl \-quantity Pq Fl O
Report commodity totals (this is the default).
.It Fl \-quarterly
Shorthand for
.Fl \-period Ar quarterly .
.It Fl \-raw
In the
.Ic print
report, show transactions using the exact same syntax as
specified by the user in their data file.  Don't do any massaging or
interpreting.  Can be useful for minor cleanups, like just aligning
amounts.
.It Fl \-real Pq Fl R
Account using only real transactions ignoring virtual and automatic
transactions.
.It Fl \-recursive-aliases
Causes
.Nm
to try to expand aliases recursively, i.e. try to expand
the result of an earlier expansion again, until no more expansions apply.
.It Fl \-register-format Ar FMT
Define the output format for the
.Ic register
report.
.It Fl \-related Pq Fl r
In a register report show the related account.  This is the other
.Em side
of the transaction.
.It Fl \-related-all
Show all postings in a transaction, similar to
.Fl \-related
but show both sides of each transaction.
.It Fl \-revalued
Report discrepancy in values for manual reports by inserting
<Revalued>
postings.
This is implied when using
the
.Fl \-exchange Pq Fl X
or
.Fl \-market Pq Fl V
option.
.It Fl \-revalued-only
Show only
<Revalued>
postings.
.It Fl \-revalued-total
Display the sum of the revalued postings as the running total, which serves
to show unrealized capital in a gain/losses report.
.It Fl \-rich-data
When generating a ledger transaction from a CSV file using the
.Ic convert
command, add CSV, Imported, and UUID meta-data.
.It Fl \-seed Ar INT
Set the random seed to
.Ar INT
for the
.Ic generate
command.  Used as part of development testing.
.It Fl \-script Ar FILE
Execute a
.Nm
script.
.It Fl \-sort Ar EXPR Pq Fl S
Sort the register report based on the value expression
.Ar EXPR .
.\".It Fl \-sort-all Ar EXPR
.It Fl \-sort-xacts
Sort the posting within transactions using the given value expression.
.It Fl \-start-of-week Ar STR
Use
.Ar STR
as the particular day of the week to start when using the
.Fl \-weekly
option.
.Ar STR
can be day names, their abbreviations like
.Qq Mon ,
or the weekday number
starting at 0 for Sunday.
.It Fl \-strict
Accounts, tags or commodities not previously declared will cause warnings.
.It Fl \-subtotal Pq Fl s
Report register as a single subtotal.
.It Fl \-tail Ar INT
Report only the last
.Ar INT
entries.  Only useful on a register report.  Alias for
.Fl \-last Ar INT
.It Fl \-time-colon
Display the value for commodities based on seconds as hours and minutes.
Thus 8100s will be displayed as 2:15h instead of 2.25h.
.It Fl \-time-report
Add two columns to the
.Ic balance
report to show the earliest checkin and checkout times for timelog entries.
.It Fl \-total Ar EXPR Pq Fl T
Define a value expression used to calculate the total in reports.
.It Fl \-total-data Pq Fl J
Show only dates and totals to format the output for plots.
.It Fl \-total-width Ar INT
Set the width of the total field in the register report.
.It Fl \-trace Ar INT
Enable tracing.  The
.Ar INT
specifies the level of trace desired.
.It Fl \-truncate Ar STR
Indicates how truncation should happen when the contents of columns
exceed their width.  Valid arguments for
.Ar STR
are
.Ar leading ,
.Ar middle ,
and
.Ar trailing .
The default is smarter than any of these three,
as it considers sub-names within the account name (that style is
called
.Qq abbreviate ) .
.It Fl \-unbudgeted
Show only un-budgeted postings.
.It Fl \-uncleared Pq Fl U
Use only uncleared transactions in calculations and reports.
.It Fl \-unrealized
Show generated unrealized gain and loss accounts in the balance
report.
.It Fl \-unrealized-gains
Allow the user to specify what account name should be used for
unrealized gains.  Defaults to
.Sy "Equity:Unrealized Gains" .
Often set in one's
.Pa ~/.ledgerrc
file to change the default.
.It Fl \-unrealized-losses
Allow the user to specify what account name should be used for
unrealized losses.  Defaults to
.Sy "Equity:Unrealized Losses" .
Often set in one's
.Pa ~/.ledgerrc
file to change the default.
.It Fl \-unround
Perform all calculations without rounding and display results to full
precision.
.It Fl \-values
Show the values used by each tag when used in combination with the
.Ic tags
command.
.It Fl \-value-expr Ar EXPR
Set a global value expression annotation.
.It Fl \-verbose
Print detailed information on the execution of
.Nm .
.It Fl \-verify
Enable additional assertions during run-time.  This causes a significant
slowdown.  When combined with
.Fl \-debug Ar CODE
.Nm
will produce memory trace information.
.It Fl \-verify-memory
Verify that every constructed object is properly destructed.  This is for
debugging purposes only.
.It Fl \-version
Print version information and exit.
.It Fl \-weekly Pq Fl W
Shorthand for
.Fl \-period Ar weekly .
.It Fl \-wide Pq Fl w
Assume 132 columns instead of the TTY width.
.It Fl \-yearly Pq Fl Y
Shorthand for
.Fl \-period Ar yearly .
.El
.Sh PRE-COMMANDS
Pre-commands are useful when you aren't sure how a command or option
will work.  The difference between a pre-command and a regular command
is that pre-commands ignore the journal data file completely, nor is
the user's init file read.
.Bl -tag -width -indent
.It Ic args No / Ic query
Evaluate the given arguments and report how
.Nm
interprets it against the following model transaction:
.Bd -literal -offset indent
2004/05/27 Book Store
    ; This note applies to all postings. :SecondTag:
    Expenses:Books                 20 BOOK @ $10
    ; Metadata: Some Value
    ; Typed:: $100 + $200
    ; :ExampleTag:
    ; Here follows a note describing the posting.
    Liabilities:MasterCard        $-200.00
.Ed
.It Ic eval
Evaluate the given value expression against the model transaction.
.It Ic format
Print details of how
.Nm
uses the given formatting description and
apply it against a model transaction.
.It Ic parse No / Ic expr
Print details of how
.Nm
uses the given value expression description
and apply it against a model transaction.
.It Ic generate
Randomly generates syntactically valid
.Nm
data from a seed.  Used
by the GenerateTests harness for development testing.
.It Ic period
Evaluate the given period and report how
.Nm
interprets it.
.\".It Ic script
.It Ic template
Shows the insertion template that the
.Ic xact
command generates.  This is a debugging command.
.El
.Sh QUERIES
The syntax for reporting queries can get somewhat complex.  It is a series of
query terms with an implicit OR operator between them.  The following terms
are accepted:
.Bl -tag -width "term and term"
.It Ar regex
A bare string is taken as a regular expression matching the full account name.
Thus, to report the current balance for all assets and liabilities, you would
use:
.Pp
.Dl ledger bal asset liab
.It Ic payee Ar regex Pq Ic \&@ Ns Ar regex
Query on the payee, rather than the account.
.It Ic tag Ar regex Pq Ic \&% Ns Ar regex
.It Ic note Ar regex Pq Ic \&= Ns Ar regex
Query on anything found in an item's note.
.It Ic code Ar regex Pq Ic \&# Ns Ar regex
Query on the xact's optional code (which can be any string the user wishes).
.It Ar term Cm and Ar term
Query terms are joined by an implicit OR operator.  You can change this to AND
by using the
.Cm and
keyword.  For example, to show food expenditures occurring at
Shakee's Pizza, you could say:
.Pp
.Dl Li ledger reg food and @Shakee
.It Ar term Cm or Ar term
When you wish to be more explicit, use the OR operator.
.It Ic show
.It Cm not Ar term
Reverse the logical meaning of the following term.  This can be used with
parentheses to great effect:
.Pp
.Dl Li ledger reg food and @Shakee and not dining
.It \&( Ar term No \&)
If you wish to mix OR and AND operators, it is often helpful to surround
logical units with parentheses.  \fBNOTE\fR: Because of the way some shells
interpret parentheses, you should always escape them:
.Pp
.Dl Li ledger bal \e( assets or liab \e) and not food
.El
.Sh EXPRESSIONS
.Bl -tag -width "partial_account"
.It Fn abs value
Return the absolute value of the given
.Ar value .
.It Sy account
Return the posting's account.
.It Sy account_base
Return the base account, i.e. everything after the last account delimiter ':'.
.\".It Sy account_amount
.It Sy actual
.\" Is there a difference between real and actual?
Return true if the transaction is real, i.e not a automated or virtual
transaction, false otherwise.
.It Sy amount
Return the amount of the posting.
.It Sy amount_expr
Return the calculated amount of the posting according to the
.Fl \-amount
option.
.It Fn ansify_if value color bool
Render the given
.Ar value
as a string, applying the proper ANSI escape codes to display it in the given
.Ar color
if
.Ar bool
is true.  It typically checks the value of the option
.Fl \-color ,
for example:
.Dl Li ansify_if(amount, "blue", options.color)
.It Sy beg_line
Line number where entry for posting begins.
.It Sy beg_pos
Character position where entry for posting begins.
.\".It Sy calculated
.It Fn ceiling value
Return the next integer of
.Ar value
toward +infinity.
.It Sy cleared
Return true if the posting was cleared, false otherwise.
.It Sy code
Return the transaction code, the string between the parenthesis after the date.
.\".It Sy comment
.It Fn commodity value
Return the commodity of
.Ar value
or the posting amount when
.Ar value
was not specified.
.\".It Sy cost
.\".It Sy count
.It Sy date
Return the date of the posting.
.\".It Sy depth
.\".It Sy depth_spacer
.\".It Sy display_amount
.\".It Sy display_total
.It Sy end_line
Line number where entry for posting ends.
.It Sy end_pos
Character position where entry for posting ends.
.It Fn floor value
Return the next integer of
.Ar value
toward -infinity.
.It Sy filename
The name of the
.Nm
data file from whence the posting came.
.It Fn format string
Evaluate
.Ar string
as format just like the
.Fl \-format
option.
.It Fn format_date date format
Return the
.Ar date
as a string using
.Ar format .
Refer to
.Xr strftime 3
for format string details.
.It Fn format_datetime datetime format
Return the
.Ar datetime
as a string using
.Ar format .
Refer to
.Xr strftime 3
for format string details.
.It Fn get_at seq index
Return value at
.Ar index
from
.Ar seq .
Used internally to construct different reports.
.It Fn has_meta
Return true if the posting has metadata named
.Ar tag ,
false otherwise.
.It Fn has_tag tag
Return true if the posting has metadata named
.Ar tag ,
false otherwise.
.It Fn is_seq value
Return true if
.Ar value
is a sequence. Used internally.
.It Fn join value
Replace all newlines in
.Ar value
with
.Li \en .
.It Fn justify value first_width latter_width right_justify colorize
Right or left justify the string representing
.Ar value .
The width of the field in the first line is given by
.Ar first_width .
For subsequent lines the width is given by
.Ar latter_width .
If
.Ar latter_width
is -1,
.Ar first_width
is used for all lines.
If
.Ar right_justify
is true then the field is right justified within the width of the field.  If it
is false, then the field is left justified and padded to the full width of the
field.  If
.Ar colorize
is true, then ledger will honor color settings.
.It Fn market value datetime
Return the price of
.Ar value
at
.Ar datetime .
Note that
.Ar datetime
must be surrounded by brackets in order to be parsed correctly, e.g.
.Bq 2012/03/23 .
.It Fn meta
Return the value of metadata named
.Ar name .
.It Sy note
Return the note for the posting.
.It Sy now
Return the current datetime.
.\".It Sy null
.It Sy options
A variable that allows access to the values of the given command-line options
using the long option names, e.g. to see whether
.Fl \-daily Pq Fl D
was given use
.Sy option.daily .
.\" .It Sy partial_account
.It Sy payee
Return the payee of the posting.
.It Fn percent value_a value_b
Return the percentage of
.Ar value_a
in relation to
.Ar value_b
(used as 100%).
.It Sy pending
Return true if the posting is marked as pending, false otherwise.
.It Fn percent value_a value_b
Return the percentage of
.Ar value_a
in relation to
.Ar value_b .
.\".It Sy post
.\" A variable scope
.It Fn print value
Print
.Ar value
to stdout.
Used internally for debugging.
.It Fn quantity value
Return the quantity of
.Ar value
for values that have a per-unit cost.
.It Fn quoted expression
Surround
.Ar expression
with double-quotes.
.It Sy real
.\" Is there a difference between real and actual?
Return true if the transaction is real, i.e not a automated or virtual
transaction, false otherwise.
.\".It Sy rounded
.It Fn roundto value n
Return
.Ar value
rounded to
.Ar n
digits.  Does not affect formatting.
.It Sy should_bold
Return true if expression given to
.Fl \-bold-if
evaluates to true.  Internal use only!
.It Fn scrub value
Clean
.Ar value
using various transformations such as round,
stripping value annotations, and more.
.\".It Sy status
.It Fn strip value
Strip value annotation from
.Ar value .
.\".It Sy subcount
.It Fn tag name
Return the value of tag named
.Ar name .
.It Fn to_amount value
Convert
.Ar value
to an amount.  Internal use only!
.It Fn to_balance value
Convert
.Ar value
to a balance.  Internal use only!
.It Fn to_boolean value
Convert
.Ar value
to a boolean.  Internal use only!
.It Fn to_date value
Convert
.Ar value
to a date.  Internal use only!
.It Fn to_datetime value
Convert
.Ar value
to a datetime.  Internal use only!
.It Fn to_int value
Return the integer value for
.Ar value .
.It Fn to_mask value
Convert
.Ar value
to a mask.  Internal use only!
.It Fn to_sequence value
Convert
.Ar value
to a sequence.  Internal use only!
.It Fn to_string value
Convert
.Ar value
to a character string.
.It Sy today
Return today's date.
.It Sy total
Return the total of the posting.
.It Sy total_expr
Return the calculated total of the posting according to the
.Fl \-total
option.
.It Fn trim value
Trim leading and trailing whitespace from
.Ar value .
.It Fn truncated string total_len account_len
Truncate
.Ar string
to
.Ar total_len
ensuring that each account is at least
.Ar account_len
long.
.\".It Sy uncleared
.It Sy virtual
Return true if the transaction is virtual, e.g automated, false otherwise.
.\".It Sy xact
.\" A variable scope
.El
.\".Sh ENTRIES
.\".Sh FORMATS
.Sh DEBUG COMMANDS
In addition to the regular reporting commands,
.Nm
also accepts several
debug commands:
.Bl -tag -width balance
.It Ic args Oo Ar report-query Oc
Display complete analysis of how
.Nm
interpreted the given
.Ar report-query .
Useful if you want to understand how report queries are translated into value
expressions.
.It Ic eval Oo Ar value-expression Oc
Evaluate the given
.Ar value-expression
and prints the result.  For more on value expressions, see the section
.Sx EXPRESSIONS .
.It Ic format Oo Ar format-string Oc
Display an analysis of how
.Ar format-string
was parsed, and what it would look like applied to a sample transaction.  For
more on format strings, see the section
.Sx FORMATS .
.It Ic generate
Generate 50 randomly composed yet valid
.Nm
transactions.
.It Ic parse Oo Ar value-expression Oc
Parse the given
.Ar value-expression
and display an analysis of the expression tree and its evaluated value.  For
more on value expressions, see the section
.Sx EXPRESSIONS .
.It Ic python Oo Ar file Oc
Invoke a Python interpreter to read the given
.Ar file .
What is special about this is that the
.Nm
module is builtin, not read from
disk, so it doesn't require
.Nm
to be installed anywhere, or the shared
library variants to be built.
.It Ic reload
Reload all data files for the current session immediately.
Can only be used in the
.Tn REPL .
.It Ic template Oo Ar draft-template Oc
Display information about how
.Ar draft-template
was parsed.  See the section on
.Sx DRAFTS .
.El
.Sh ENVIRONMENT
Every option to
.Nm
may be set using an environment variable if the option has a long name.
For example setting the environment variable
.Ev LEDGER_DATE_FORMAT="%d.%m.%Y'
will have the same effect as specifying
.Fl \-date-format Ar '%d.%m.%Y'
on the command-line.  Options on the command-line always take precedence over
environment variable settings, however.
.Sh FILES
.Bl -tag -width -indent
.It Pa ~/.ledgerrc
Your personal
.Nm
initializations.
.El
.Sh SEE ALSO
.Xr beancount 1 ,
.Xr hledger 1
.Sh AUTHORS
.An "John Wiegley"
.Aq johnw@newartisans.com
.\" .Sh BUGS              \" Document known, unremedied bugs
.\" .Sh HISTORY           \" Document history if command behaves in a unique manner