table of contents
ledger(1) | General Commands Manual | ledger(1) |
NAME¶
ledger
—
Command-line, double-entry account reporting
tool
SYNOPSIS¶
ledger [command
]
[options
]
[arguments
]
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.COMMANDS¶
Ledger accepts several top-level commands, each of which generates a different kind of basic report. Most of them accept a report-query argument, 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 reparsing. 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, flatten 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).
bal
andb
are also accepted. budget
[report-query]- 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 “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 generates 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 transaction 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 consumed 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 transactions 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 preferable to use thebalance
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 fashion. 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.
--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 similar to the totals shown
by the
balance
report.
reg
andr
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 thanaccount-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 tackPersonal:
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 postings. 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
orpayees
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 notExpenses: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 running a
script named
getquote
and expecting that script to return a value understood by ledger. A sample implementation of agetquote
script, implemented in Perl, is provided in the distribution. Downloaded quote price are then appended to the price database, usually specified using the environment variableLEDGER_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 correctly.
--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 history.
--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 bepayee
orcommodity
. Thetags()
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 register 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 transforms 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 calculations.
--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 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. --real
(-R
)- Account using only real transactions ignoring virtual and automatic 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 showboth 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 columns exceed
their width. Valid arguments are
leading
,middle
, andtrailing
. 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 significant
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 transaction.
format
- Print details of how ledger uses the given formatting description 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 balance 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 example, 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 helpful 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
ENTRIES¶
FORMATS¶
DEBUG COMMANDS¶
In addition to the regular reporting commands, Ledger also accepts several 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 interpreted 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 transaction. 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 |