ledger(1) BSD General Commands Manual ledger(1)NAMEledger — Command-line, double-entry account reporting tool
SYNOPSISledger [command] [options] [arguments]
DESCRIPTION
Ledger is a command-line accounting tool based on the power and complete‐
ness 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 lik‐
ing.
COMMANDS
Ledger accepts several top-level commands, each of which generates a dif‐
ferent kind of basic report. Most of them accept a report-query argu‐
ment, in order to determine what should be reported. To understand the
syntax of a report-query, see the section on QUERIES. In its most basic
form, simply specifying one or more strings produces a report for all
accounts containing those strings.
If no command is given, Ledger enters a REPL, or command loop, allowing
several commands to be executed against the same dataset without repars‐
ing.
The following is a complete list of reporting commands accepted by
Ledger:
accounts [report-query]
Lists all accounts for postings matching the report-query.
balance [report-query]
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:
--basis (-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 report-query is specified.
--collapse (-n) Only show totals for the top-most accounts.
--empty (-E) Also show accounts whose total is zero.
--flat Rather than display a hierarchical tree, flat‐
ten the report to show subtotals for only
accounts matching report-query.
--no-total Suppress the summary total shown at the bottom
of the report (when not zero).
The synonyms bal and b are also accepted.
budget [report-query]
A special balance report which includes three extra columns: the
amount budgeted during the reporting period, how spending dif‐
fered from the budget, and the percentage of budget spent
(exceeds 100% if you go over budget). Note that budgeting
requires one or more “periodic transactions” to be defined in
your data file(s). See the manual for more information.
cleared [report-query]
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.
commodities [report-query]
Lists all commodities for postings matching the report-query.
convert Reads data from a CSV (comma-separated values) file and gener‐
ates Ledger transactions.
csv [report-query]
Report of postings matching the report-query in CSV format
(comma-separated values). Useful for exporting data to a
spreadsheet for further analysis or charting.
entry [entry-template]
Generate and display a new, properly formatted Ledger transac‐
tion by comparing the 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
ENTRIES.
The synonym xact is also accepted.
emacs [query]
Outputs posting and transaction data in a format readily con‐
sumed by the Emacs editor, in a series of Lisp forms. This is
used by the ledger.el Emacs mode to process reporting data from
Ledger.
equity [report-query]
Prints a series of transactions that balance current totals for
accounts matching the report-query in a special account called
Equity:Opening Balances. The purpose of this report is to close
the books for a prior year, while using these equity transac‐
tions to carry forward those balances.
org Produces a journal file suitable for use in the Emacs org mode.
payees [report-query]
Lists all payees for postings matching the report-query.
pricemap
Produces a file which can be used to generate a graph with
graphviz showing the relationship of commodities in the Ledger
file.
prices [report-query]
Reports prices for all commodities in postings matching the
report-query. The prices are reported with the granularity of a
single day.
pricedb [report-query]
Reports prices for all commodities in postings matching the
report-query. Prices are reported down to the second, using the
same format as the ~/.pricedb file.
print [report-query]
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.
push [options]
In the REPL, this command pushes a set of command-line options,
so that they will apply to all subsequent reports.
pop In the REPL, pops any option settings that have been pushed.
register [report-query]
List all postings matching the 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:
--average (-A) Show the running average, rather than a running
total.
--current (-c) Don't show postings beyond the present day.
--exchange commodity (-X)
Render all values in the given 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 register report is a historical value
report. For current values, it may be prefer‐
able to use the balance report.
--gain (-G) Show any gains (or losses) in commodity values
over time.
--head number Only show the top number postings.
--historical (-H)
--invert Invert the value of amounts shown.
--market (-V) Show current market values for all amounts.
This is determined in a somewhat magical fash‐
ion. It is probably more straightforward to
use --exchange commodity (-X).
--period time-period (-p)
Show postings only for the given time-period.
--related (-r) Show postings that are related to those that
would have been shown. It has the effect of
displaying the “other side” of the values.
--sort value-expression (-S)
Sort postings by evaluating the given
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: -S 'date,
amount'.
--tail number Only show the last number postings.
--uncleared (-U)
Only show uncleared (i.e., recent) postings.
There are also several grouping options that can be useful:
--by-payee (-P) Group postings by common payee names.
--daily (-D) Group postings by day.
--weekly (-W) Group postings by week (starting on Sundays).
--start-of-week day-name
Set the start of each grouped way to the given
day-name.
--monthly (-M) Group postings by month.
--quarterly Group postings by fiscal quarter.
--yearly (-Y) Group postings by year.
--dow Group postings by the day of the week on which
they took place.
--subtotal (-s) Group all postings together. This is very sim‐
ilar to the totals shown by the balance report.
The synonyms reg and r are also accepted.
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.
select [sql-query]
List all postings matching the sql-query. This command allows
to generate SQL-like queries.
source Parses a journal file and checks it for errors. Ledger will
return success if no errors are found.
stats [report-query]
Provides summary information about all the postings matching
report-query. It provides information such as:
· Time range of all matching postings
· Unique payees
· Unique accounts
· Postings total
· Uncleared postings
· Days since last posting
· More...
xml [report-query]
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.
OPTIONS--abbrev-len INT
Set the minimum length an account can be abbreviated to if it
doesn't fit inside the account-width. If INT is zero, then the
account name will be truncated on the right. If INT is greater
than 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.
--account STR
Prepend STR to all accounts reported. That is, the option
--account Personal would tack Personal: to the beginning of
every account reported in a balance report or register report.
--account-width INT
Set the width of the account column in the register report to
INT characters.
--actual (-L)
Report only real transactions, with no automated or virtual
transactions used.
--add-budget
Show only un-budgeted postings.
--amount EXPR (-t)
Apply the given value expression to the posting amount. Using
--amount EXPR you can apply an arbitrary transformation to the
postings.
--amount-data (-j)
On a register report print only the dates and amount of post‐
ings. Useful for graphing and spreadsheet applications.
--amount-width INT
Set the width in characters of the amount column in the register
report.
--anon Anonymize registry output, mostly for sending in bug reports.
--args-only
--auto-match
--aux-date
Show auxiliary dates for all calculations. Alias for
--effective
--average (-A)
Print average values over the number of transactions instead of
running totals.
--balance-format FMT
Specify the format to use for the balance report.
--base
--basis (-B)
Report the cost basis on all posting. Alias for --cost
--begin DATE (-b)
Specify the start DATE of all calculations. Transactions before
that date will be ignored.
--bold-if EXPR
Print the entire line in bold if the given value expression is
true.
--budget
Only display budgeted items. In a register report this displays
transaction in the budget, in a balance report this displays
accounts in the budget.
--budget-format FMT
Specify the format to use for the budget report.
--by-payee (-P)
Group postings in the register report by common payee names.
--cache FILE
--check-payees
Enable strict and pedantic checking for payees as well as
accounts, commodities and tags.
--cleared (-C)
Display only cleared postings.
--cleared-format FMT
Specify the format to use for the cleared report
--collapse (-n)
By default ledger prints all accounts in an account tree. With
--collapse it prints only the top level account specified.
--collapse-if-zero
Collapse the account display only if it has a zero balance.
--color Use color if the terminal supports it. Alias for --ansi
--columns INT
Specify the width of the register report in characters.
--cost Report the cost basis on all posting. Alias for --basis.
--count Direct ledger to report the number of items when appended to the
commodities, accounts or payees commands.
--csv-format FMT
Specify the format to use for the csv report
--current (-c)
Shorthand for --limit 'date <= today'.
--daily (-D)
Shorthand for --period 'daily'.
--date EXPR
Transform the date of the transaction using EXPR.
--date-format DATEFMT (-y)
Specify the format ledger should use to print dates.
--datetime-format FMT
--date-width INT
Specify the width, in characters, of the date column in the
register report.
--day-break
--dc Display register or balance in debit/credit format If you use
--dc with either the register (reg) or balance (bal) commands,
you will now get separate columns for debits and credits.
--debug STR
If Ledger has been built with debug options this will provide
extra data during the run.
--decimal-comma
Direct Ledger to parse journals using the European standard
comma as decimal separator, vice a period.
--depth INT
Limit the depth of the account tree. In a balance report, for
example, a --depth -2 statement will print balances only for
account with two levels, i.e. Expenses:Entertainment but not
Expenses:entertainemnt:Dining. This is a display predicate,
which means it only affects display, not the total calculations.
--deviation (-D)
Report each posting’s deviation from the average. It is only
meaningful in the register and prices reports.
--display EXPR (-d)
Display lines that satisfy the expression EXPR.
--display-amount EXPR
Apply a transformation to the displayed amount. This occurs
after calculations occur.
--display-total EXPR
Apply a transformation to the displayed total. This occurs
after calculations occur.
--dow Group transactions by the days of the week. Alias for
--days-of-week
--download
Cause quotes to be automagically downloaded, as needed, by run‐
ning 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 distri‐
bution. Downloaded quote price are then appended to the price
database, usually specified using the environment variable
LEDGER_PRICE_DB.
--empty (-E)
Include empty accounts in report.
--end DATE (-e)
Specify the end DATE for a transaction to be considered in the
report.
--equity
Related to the equity command. Gives current account balances
in the form of a register report.
--exact
--exchange COMMODITY [, COMM, ...] (-X)
Display values in terms of the given COMMODITY. The latest
available price is used.
--explicit
--file FILE
Read FILE as a ledger file.
--first INT
Print the first INT entries. Opposite of --tail INT. Alias for
--head.
--flat Force the full names of accounts to be used in the balance
report. The balance report will not use an indented tree.
--force-color
Output TTY color codes even if the TTY doesn't support them.
Useful for TTYs that don't advertise their capabilities cor‐
rectly.
--force-pager
Force Ledger to paginate its output.
--forecast-while EXPR
Continue forecasting while VEXPR is true. Alias for --forecast.
--forecast-years INT
Forecast at most INT years into the future.
--format FMT (-F)
Use the given format string FMT to print output.
--gain (-G)
Report net gain or loss for commodities that have a price his‐
tory.
--generated
Include auto-generated postings (such as those from automated
transactions) in the report, in cases where you normally
wouldn't want them.
--group-by EXPR
Group transaction together in the register report. EXPR can be
anything, although most common would be payee or commodity. The
tags() function is also useful here.
--group-title-format FMT
Set the format for the headers that separate reports section of
a grouped report. Only has effect with a --group-by EXPR regis‐
ter report.
--head INT
Print the first INT entries. Opposite of --tail INT. Alias for
--first
--help Print 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.
--immediate
Instruct ledger to evaluate calculations immediately rather than
lazily.
--init-file FILE
Causes FILE to be read by ledger before any other ledger 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.
--inject STR
TODO
--input-date-format DATEFMT
Specify the input date format for journal entries.
--invert
Change the sign of all reported values.
--last INT
Report only the last INT entries. Only useful on a register
report. Alias for --tail.
--leeway INT (-Z)
Alias for --price-expr.
--limit EXPR (-l)
Limit postings in calculations.
--lot-dates
Report the date on which each commodity in a balance report was
purchased.
--lot-notes
Report the tag attached to each commodity in a balance report.
--lot-prices
Report the price at which each commodity in a balance report was
purchased.
--lots Report the date and price at which each commodity was purchased
in a balance report.
--lots-actual
--market (-V)
Use the latest market value for all commodities.
--master-account STR
Prepend all account names with STR
--meta EXPR
In the register report, prepend the transaction with the value
of the given TAG.
--meta-width INT
Specify the width of the Meta column used for the --meta TAG
options.
--monthly (-M)
Shorthand for --period -'monthly'.
--no-aliases
Aliases are completely ignored.
--no-color
Suppress any color TTY output.
--no-rounding
Don't output <Rounding> postings. Note that this will cause the
running total to often not add up! It's main use is for
--amount-data (-j) and --total-data (-J) reports.
--no-titles
Suppress the output of group titles.
--no-total
Suppress printing the final total line in a balance report.
--now DATE
Define the current date in case to you to do calculate in the
past or future using --current.
--only EXPR
This is a postings predicate that applies after certain trans‐
forms have been executed, such as periodic gathering.
--options
Display the options in effect for this Ledger invocation, along
with their values and the source of those values.
--output FILE (-o)
Redirect the output of ledger to the file defined in FILE.
--pager STR
Specify the pager program to use as STR.
--payee Sets a value expression for formatting the payee. In the
register report this prevents the second entry from having a
date and payee for each transaction.
--payee-width INT
Set the number of columns dedicated to the payee in the register
report to INT.
--pedantic
Accounts, tags or commodities not previously declared will cause
errors.
--pending
Use only postings that are marked pending.
--percent (-%)
Calculate the percentage value of each account in a balance
reports. Only works for account that have a single commodity.
--period PERIOD (-p)
Define a period expression that sets the time period during
which transactions are to be accounted. For a 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.
--period-sort
Sort the posting within transactions using the given value
expression.
--permissive
--pivot STR
Produce a balance pivot report around the given TAG.
--plot-amount-format FMT
Define the output format for an amount data plot.
--plot-total-format FMT
Define the output format for a total data plot.
--prepend-format FMT
Prepend STR to every line of the output.
--prepend-width INT
Reserve INT spaces at the beginning of each line of the output.
--price (-I)
Use the price of the commodity purchase for performing calcula‐
tions.
--price-db FILE
--price-exp STR (-Z)
Set the expected freshness of price quotes, in INT 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. Alias for --leeway INT
(-Z)
--prices-format FMT
--pricedb-format FMT
--primary-date
Show primary dates for all calculations. Alias for
--actual-dates
--quantity (-O)
Report commodity totals (this is the default).
--quarterly
Synonym for
-period 'quarterly' .
--raw In the print report, show transactions using the exact same syn‐
tax 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.
--real (-R)
Account using only real transactions ignoring virtual and auto‐
matic transactions.
--recursive-aliases
Causes ledger to try to expand aliases recursively, i.e. try to
expand the result of an earlier expansion again, until no more
expansions apply.
--register-format FMT
Define the output format for the register report.
--related (-r)
In a register report show the related account. This is the
other side of the transaction.
--related-all
Show all postings in a transaction, similar to --related but
show both sides of each transaction.
--revalued
--revalued-only
--revalued-total EXPR
--rich-data
--seed INT
Set the random seed to INT for the generate command. Used as
part of development testing.
--script FILE
Execute a ledger script.
--sort EXPR (-S)
Sort the register report based on the value expression given to
sort.
--sort-all
--sort-xacts
Sort the posting within transactions using the given value
expression.
--start-of-week STR
Tell ledger to use a particular day of the week to start its
"weekly" summary. --start-of-week=1 specifies Monday as the
start of the week.
--strict
Accounts, tags or commodities not previously declared will cause
warnings.
--subtotal (-s)
Report register as a single subtotal.
--tail INT
Report only the last INT entries. Only useful on a register
report. Alias for --last INT
--time-report
--total EXPR (-T)
Define a value expression used to calculate the total in
reports.
--total-data (-J)
Show only dates and totals to format the output for plots.
--total-width INT
Set the width of the total field in the register report.
--trace INT
Enable tracing. The INT specifies the level of trace desired.
--truncate CODE
Indicates how truncation should happen when the contents of col‐
umns exceed their width. Valid arguments are leading, middle,
and trailing. The default is smarter than any of these three,
as it considers sub-names within the account name (that style is
called "abbreviate").
--unbudgeted
Show only un-budgeted postings.
--uncleared (-U)
Use only uncleared transactions in calculations and reports.
--unrealized
Show generated unrealized gain and loss accounts in the balance
report.
--unrealized-gains
Allow the user to specify what account name should be used for
unrealized gains. Defaults to Equity:Unrealized Gains. Often
set in one's ~/.ledgerrc file to change the default.
--unrealized-losses
Allow the user to specify what account name should be used for
unrealized gains. Defaults to Equity:Unrealized Losses. Often
set in one's ~/.ledgerrc file to change the default.
--unround
Perform all calculations without rounding and display results to
full precision.
--values
Shows the values used by each tag when used in combination with
the tags command.
--value-expr EXPR
--verbose
Print detailed information on the execution of Ledger.
--verify
Enable additional assertions during run-time. This causes a sig‐
nificant slowdown. When combined with --debug CODE ledger will
produce memory trace information.
--verify-memory
--version
Print version information and exit.
--weekly (-W)
Synonym for --period -'weekly'.
--wide (-w)
Assume 132 columns instead of 80.
--yearly (-Y)
Synonym for --period -'yearly'.
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.
args / query
Evaluate the given arguments and report how Ledger interprets it
against the following model transaction.
eval Evaluate the given value expression against the model transac‐
tion.
format Print details of how ledger uses the given formatting descrip‐
tion and apply it against a model transaction.
parse / expr
Print details of how ledger uses the given value expression
description and apply it against a model transaction.
generate
Randomly generates syntactically valid Ledger data from a seed.
Used by the GenerateTests harness for development testing.
period Evaluate the given period and report how Ledger interprets it.
script
template
Shows the insertion template that the xact sub-command
generates. This is a debugging command.
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:
regex A bare string is taken as a regular expression matching
the full account name. Thus, to report the current bal‐
ance for all assets and liabilities, you would use:
ledger bal asset liab
payee regex (@regex)
Query on the payee, rather than the account.
tag regex (%regex)
note regex (=regex)
Query on anything found in an item's note.
code regex (#regex)
Query on the xact's optional code (which can be any string
the user wishes).
term and term Query terms are joined by an implicit OR operator. You
can change this to AND by using that keyword. For exam‐
ple, to show food expenditures occurring at Shakee's
Pizza, you could say:
ledger reg food and @Shakee
term or term When you wish to be more explicit, use the OR operator.
show
not term Reverse the logical meaning of the following term. This
can be used with parentheses to great effect:
ledger reg food and @Shakee and not dining
( term ) If you wish to mix OR and AND operators, it is often help‐
ful to surround logical units with parentheses. NOTE:
Because of the way some shells interpret parentheses, you
should always escape them:
ledger bal \( assets or liab \) and not food
EXPRESSIONS
account
account_base
account_amount
actual
amount
amount_expr
ansify_if(value, color, bool)
Render the given value as a string, applying the proper
ANSI escape codes to display it in the given color if
bool is true. It typically checks the value of the
option ledger--color, for example:
ansify_if(amount, blue, options.color)
beg_line
beg_pos
calculated
cleared
code
comment
commodity
cost
count
date
depth
depth_spacer
display_amount
display_total
end_line
end_pos
filename
format_date
get_at
has_meta
has_tag
is_seq
join
market
meta
note
null
options
partial_account
payee
pending
post
print
quantity
quoted
real
rounded
scrub
status
strip
subcount
tag
today
total
total_expr
truncate
uncleared
virtual
xact
ENTRIESFORMATSDEBUG COMMANDS
In addition to the regular reporting commands, Ledger also accepts sev‐
eral debug commands:
args [report-query]
Accepts a report-query as its argument and displays it back to
the user along with a complete analysis of how Ledger inter‐
preted it. Useful if you want to understand how report queries
are translated into value expressions.
eval [value-expression]
Evaluates the given value-expression and prints the result. For
more on value expressions, see the section EXPRESSIONS.
format [format-string]
Accepts a format-string and displays an analysis of how it was
parsed, and what it would look like applied to a sample transac‐
tion. For more on format strings, see the section FORMATS.
generate
Generates 50 randomly composed yet valid Ledger transactions.
parse [value-expression]
Parses the given value-expression and display an analysis of the
expression tree and its evaluated value. For more on value
expressions, see the section EXPRESSIONS.
python [file]
Invokes a Python interpreter to read the given 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.
reload Used only in the REPL, it causes an immediate reloading of all
data files for the current session.
template [draft-template]
Accepts a draft-template and displays information about how it
was parsed. See the section on DRAFTS.
SEE ALSO
beancount(1,) hledger(1)AUTHORS
John Wiegley ⟨johnw@newartisans.com⟩
March 23, 2012
