path: root/doc/ledger.1

.Dd March 17, 2012
.Dt ledger 1
.Sh NAME
.Nm ledger
.Nd Command-line, double-entry account reporting tool
.Sh SYNOPSIS
ledger
.Op Ar command
.Op Ar options
.Op Ar arguments
.Sh DESCRIPTION
Ledger 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 offers a large selection of reports, and
different ways to customize them to your liking.
.Pp
.Sh COMMANDS
Ledger 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, Ledger enters a
.Tn REPL ,
or command loop, allowing several commands to be executed against the same
dataset without reparsing.
.Pp
The following is a complete list of reporting commands accepted by Ledger:
.Pp
.Bl -tag -width balance
.It Nm balance Oo Ar report-query Oc
Produces a balance report showing totals for all matching accounts, and
aggregate totals for parents of those accounts.  Options most commonly used
with this command are:
.Pp
.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.
.It Fl \-collapse Pq Fl n
Only show totals for the top-most accounts.
.It Fl \-empty Pq Fl E
Also 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 (when not zero).
.El
.Pp
The synonyms
.Nm bal
and
.Nm b
are also accepted.
.It Nm 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 Nm 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 Nm 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 Nm draft Oo Ar draft-template Oc
Generate and display a new, properly formatted Ledger transaction by comparing
the
.Ar draft-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 DRAFTS .
.Pp
The synonyms
.Nm entry
and
.Nm xact
are also accepted.
.It Nm emacs Oo Ar query Oc
Outputs posting and transaction data in a format readily consumed by the Emacs
editor, in a series of Lisp forms.  This is used by the
.Li ledger.el
Emacs mode to process reporting data from Ledger.
.Pp
The synonym
.Nm lisp
is also accepted.
.It Nm equity Oo Ar report-query Oc
Prints a series of transactions 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 transactions to carry forward those balances.
.It Nm prices Oo Ar report-query Oc
Reports prices for all commodities in postings matching the
.Ar report-query .
The prices are reported with the granularity of a single day.
.It Nm pricesdb Oo Ar report-query Oc
Reports prices for all commodities in postings matching the
.Ar report-query .
Prices are reported down to the second, using the same format as the
.Li ~/.pricedb
file.
.It Nm print Oo Ar report-query Oc
Prints 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 Ledger file to transfer to other files.
.It Nm push Oo Ar options Oc
In the
.Tn REPL ,
this command pushes a set of command-line options, so that they will apply to
all subsequent reports.
.It Nm pop
In the
.Tn REPL ,
pops any option settings that have been pushed.
.It Nm 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
.Nm register
report is a historical value report.  For current values, it may be preferable
to use the
.Nm 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
.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 Pq Fl X .
.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
.Do
other side
.Dc
of the values.
.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:
.Li -S '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-name
Set the start of each grouped way to the given
.Ar day-name .
.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 \-dow
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
.Nm balance
report.
.El
.Pp
The synonyms
.Nm reg
and
.Nm r
are also accepted.
.It Nm server
This command requires that Python support be active.  If so, it starts up an
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 Nm stats Oo Ar report-query Oc
Provides 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
More...
.El
.It Nm xml Oo Ar report-query Oc
Outputs data relating to the current report in 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
.Pp
.Sh OPTIONS
.Pp
.Bl -tag -width -indent
.It Fl \-abbrev-len Ar INT
.It Fl \-account Ar STR
.It Fl \-account-width Ar INT
.It Fl \-actual Pq Fl L
.It Fl \-add-budget
.It Fl \-amount Ar EXPR Pq Fl t
.It Fl \-amount-data Pq Fl j
.It Fl \-amount-width Ar INT
.It Fl \-anon
.It Fl \-args-only
.It Fl \-auto-match
.It Fl \-aux-date
.It Fl \-average Pq Fl A
.It Fl \-balance-format Ar FMT
.It Fl \-base
.It Fl \-basis Pq Fl B
.It Fl \-begin Ar DATE Pq Fl b
.It Fl \-bold-if Ar EXPR
.It Fl \-budget
.It Fl \-budget-format Ar FMT
.It Fl \-by-payee Pq Fl P
.It Fl \-cache Ar FILE
.It Fl \-check-payees
.It Fl \-cleared Pq Fl C
.It Fl \-cleared-format Ar FMT
.It Fl \-collapse Pq Fl n
.It Fl \-collapse-if-zero
.It Fl \-color
.It Fl \-columns Ar INT
.It Fl \-cost
See
.Fl \-basis .
.It Fl \-count
.It Fl \-csv-format Ar FMT
.It Fl \-current Pq Fl c
.It Fl \-daily
.It Fl \-date Ar EXPR
.It Fl \-date-format Ar DATEFMT Pq Fl y
.It Fl \-datetime-format Ar FMT
.It Fl \-date-width Ar INT
.It Fl \-day-break
.It Fl \-dc
.It Fl \-debug Ar STR
.It Fl \-decimal-comma
.It Fl \-depth Ar INT
.It Fl \-deviation Pq Fl D
.It Fl \-display Ar EXPR Pq Fl d
.It Fl \-display-amount Ar EXPR
.It Fl \-display-total Ar EXPR
.It Fl \-dow
.It Fl \-download
.It Fl \-empty Pq Fl E
.It Fl \-end Pq Fl e
.It Fl \-equity
.It Fl \-exact
.It Fl \-exchange Ar COMM Oo , COMM, ... Oc Pq Fl X
.It Fl \-explicit
.It Fl \-file Ar FILE
.It Fl \-first Ar INT
See
.Fl \-head .
.It Fl \-flat
.It Fl \-force-color
.It Fl \-force-pager
.It Fl \-forecast-while Ar EXPR
(Also
.Fl \-forecast
).
.It Fl \-forecast-years Ar INT
.It Fl \-format Ar FMT Pq Fl F
.It Fl \-full-help
.It Fl \-gain Pq Fl G
.It Fl \-generated
.It Fl \-group-by Ar EXPR
.It Fl \-group-title-format Ar FMT
.It Fl \-head Ar INT
.It Fl \-help
.It Fl \-help-calc
.It Fl \-help-comm
.It Fl \-help-disp
.It Fl \-immediate
.It Fl \-import Ar STR
.It Fl \-init-file Ar FILE
.It Fl \-inject Ar STR
.It Fl \-input-date-format Ar DATEFMT
.It Fl \-invert
.It Fl \-last Ar INT
See
.Fl \-tail .
.It Fl \-leeway Ar INT Pq Fl Z
.It Fl \-limit Ar EXPR Pq Fl l
.It Fl \-lot-dates
.It Fl \-lot-notes
.It Fl \-lot-prices
.It Fl \-lots
.It Fl \-lots-actual
.It Fl \-market Pq Fl V
.It Fl \-master-account Ar STR
.It Fl \-meta Ar EXPR
.It Fl \-meta-width Ar INT
.It Fl \-monthly Pq Fl M
.It Fl \-no-color
.It Fl \-no-pager
.It Fl \-no-rounding
.It Fl \-no-titles
.It Fl \-no-total
.It Fl \-now Ar DATE
.It Fl \-only Ar EXPR
.It Fl \-options
.It Fl \-output Ar FILE Pq Fl o
.It Fl \-pager Ar STR
.It Fl \-payee
.It Fl \-payee-width Ar INT
.It Fl \-pedantic
.It Fl \-pending
.It Fl \-percent Pq Fl \%
.It Fl \-period Ar PERIOD Pq Fl p
.It Fl \-period-sort
.It Fl \-permissive
.It Fl \-pivot Ar STR
.It Fl \-plot-amount-format Ar FMT
.It Fl \-plot-total-format Ar FMT
.It Fl \-prepend-format Ar FMT
.It Fl \-prepend-width Ar INT
.It Fl \-price Pq Fl I
.It Fl \-price-db Ar FILE
.It Fl \-price-exp Ar STR
See
.Fl \-leeway .
.It Fl \-prices-format Ar FMT
.It Fl \-pricedb-format Ar FMT
.It Fl \-primary-date
.It Fl \-quantity Pq Fl O
.It Fl \-quarterly
.It Fl \-raw
For use only with the
.Nm print
command, it causes Ledger to print out matching entries exactly as they
appeared in the original journal file.
.It Fl \-real Pq Fl R
.It Fl \-register-format Ar FMT
.It Fl \-related Pq Fl r
.It Fl \-related-all
.It Fl \-revalued
.It Fl \-revalued-only
.It Fl \-revalued-total Ar EXPR
.It Fl \-rich-data
.It Fl \-seed Ar INT
.It Fl \-script
.It Fl \-sort Ar EXPR Pq Fl S
.It Fl \-sort-all
.It Fl \-sort-xacts
.It Fl \-start-of-week Ar STR
.It Fl \-strict
.It Fl \-subtotal Pq Fl s
.It Fl \-tail Ar INT
.It Fl \-time-report
.It Fl \-total Ar EXPR
.It Fl \-total-data Pq Fl J
.It Fl \-total-width Ar INT
.It Fl \-trace Ar INT
.It Fl \-truncate
.It Fl \-unbudgeted
.It Fl \-uncleared Pq Fl U
.It Fl \-unrealized
.It Fl \-unrealized-gains
.It Fl \-unrealized-losses
.It Fl \-unround
.It Fl \-value-expr Ar EXPR
.It Fl \-verbose
.It Fl \-verify
.It Fl \-version
.It Fl \-weekly Pq Fl W
.It Fl \-wide Pq Fl w
.It Fl \-yearly Pq Fl Y
.El
.Pp
.Sh PRECOMMANDS
.Pp
.Bl -tag -width -indent
.It Nm args
.It Nm eval
.It Nm format
.It Nm parse
.It Nm period
.It Nm python
.It Nm template
.El
.Pp
.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 Nm payee Ar regex Pq \&@ Ns Ar regex
Query on the payee, rather than the account.
.It Nm tag Ar regex Pq \&% Ns Ar regex
.It Nm note Ar regex Pq \&= Ns Ar regex
Query on anything found in an item's note.
.It Nm code Ar regex Pq \&# Ns Ar regex
Query on the xact's optional code (which can be any string the user wishes).
.It Ar term Nm and Ar term
Query terms are joined by an implicit OR operator.  You can change this to AND
by using that keyword.  For example, to show food expenditures occurring at
Shakee's Pizza, you could say:
.Pp
.Dl ledger reg food and @Shakee
.It Ar term Nm or Ar term
When you wish to be more explicit, use the OR operator.
.It Nm show
.It Nm not Ar term
Reverse the logical meaning of the following term.  This can be used with
parentheses to great effect:
.Pp
.Dl 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 ledger bal \e\\\&( assets or liab \e\\\&) and not food
.El
.Pp
.Sh EXPRESSIONS
.Bl -tag -width "partial_account"
.It Nm account
.It Nm account_base
.It Nm account_amount
.It Nm actual
.It Nm amount
.It Nm amount_expr
.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
.Nm Fl \-color ,
for example:
.Dl ansify_if(amount, "blue", options.color)
.It Nm beg_line
.It Nm beg_pos
.It Nm calculated
.It Nm cleared
.It Nm code
.It Nm comment
.It Nm commodity
.It Nm cost
.It Nm count
.It Nm date
.It Nm depth
.It Nm depth_spacer
.It Nm display_amount
.It Nm display_total
.It Nm end_line
.It Nm end_pos
.It Nm filename
.It Nm format_date
.It Nm get_at
.It Nm has_meta
.It Nm has_tag
.It Nm is_seq
.It Nm join
.It Nm market
.It Nm meta
.It Nm note
.It Nm null
.It Nm options
.It Nm partial_account
.It Nm payee
.It Nm pending
.It Nm post
.It Nm print
.It Nm quantity
.It Nm quoted
.It Nm real
.It Nm rounded
.It Nm scrub
.It Nm status
.It Nm strip
.It Nm subcount
.It Nm tag
.It Nm today
.It Nm total
.It Nm total_expr
.It Nm truncate
.It Nm uncleared
.It Nm virtual
.It Nm xact
.El
.Pp
.Sh DRAFTS
.Pp
.Sh FORMATS
.Pp
.Sh DEBUG COMMANDS
In addition to the regular reporting commands, Ledger also accepts several
debug commands:
.Bl -tag -width balance
.It Nm args Oo Ar report-query Oc
Accepts a
.Ar report-query
as its argument and displays it back to the user along with a complete
analysis of how Ledger interpreted it.  Useful if you want to understand how
report queries are translated into value expressions.
.It Nm eval Oo Ar value-expression Oc
Evaluates the given
.Ar value-expression
and prints the result.  For more on value expressions, see the section
.Sx EXPRESSIONS .
.It Nm format Oo Ar format-string Oc
Accepts a
.Ar format-string
and displays an analysis of how it was parsed, and what it would look like
applied to a sample transaction.  For more on format strings, see the section
.Sx FORMATS .
.It Nm generate
Generates 50 randomly composed yet valid Ledger transactions.
.It Nm parse Oo Ar value-expression Oc
Parses 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 Nm python Oo Ar file Oc
Invokes a Python interpreter to read the given
.Ar file .
What is special about this is that the ledger module is builtin, not read from
disk, so it doesn't require Ledger to be installed anywhere, or the shared
library variants to be built.
.It Nm reload
Used only in the
.Tn REPL ,
it causes an immediate reloading of all data files for the current session.
.It Nm template Oo Ar draft-template Oc
Accepts a
.Ar draft-template
and displays information about how it was parsed.  See the section on
.Sx DRAFTS .
.El
.Pp
.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