ledger

NAME

SYNOPSIS

DESCRIPTION

COMMANDS

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).

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 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.

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 Sx 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 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 fashion. It is probably more straightforward to use --exchange (-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 Do other side Dc 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 similar 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

--account STR

--account-width INT

--actual (-L )

--add-budget

--amount EXPR (-t )

--amount-data (-j )

--amount-width INT

--anon

--args-only

--auto-match

--aux-date

--average (-A )

--balance-format FMT

--base

--basis (-B )

--begin DATE (-b )

--bold-if EXPR

--budget

--budget-format FMT

--by-payee (-P )

--cache FILE

--check-payees

--cleared (-C )

--cleared-format FMT

--collapse (-n )

--collapse-if-zero

--color

--columns INT

--cost

See --basis

--count

--csv-format FMT

--current (-c )

--daily

--date EXPR

--date-format DATEFMT (-y )

--datetime-format FMT

--date-width INT

--day-break

--dc

--debug STR

--decimal-comma

--depth INT

--deviation (-D )

--display EXPR (-d )

--display-amount EXPR

--display-total EXPR

--dow

--download

--empty (-E )

--end (-e )

--equity

--exact

--exchange COMM [, COMM, ... (-X ) ]

--explicit

--file FILE

--first INT

See --head

--flat

--force-color

--force-pager

--forecast-while EXPR

(Also --forecast ).

--forecast-years INT

--format FMT (-F )

--full-help

--gain (-G )

--generated

--group-by EXPR

--group-title-format FMT

--head INT

--help

--help-calc

--help-comm

--help-disp

--immediate

--import STR

--init-file FILE

--inject STR

--input-date-format DATEFMT

--invert

--last INT

See --tail

--leeway INT (-Z )

--limit EXPR (-l )

--lot-dates

--lot-notes

--lot-prices

--lots

--lots-actual

--market (-V )

--master-account STR

--meta EXPR

--meta-width INT

--monthly (-M )

--no-color

--no-pager

--no-rounding

--no-titles

--no-total

--now DATE

--only EXPR

--options

--output FILE (-o )

--pager STR

--payee

--payee-width INT

--pedantic

--pending

--percent (- )

--period PERIOD (-p )

--period-sort

--permissive

--pivot STR

--plot-amount-format FMT

--plot-total-format FMT

--prepend-format FMT

--prepend-width INT

--price (-I )

--price-db FILE

--price-exp STR

See --leeway

--prices-format FMT

--pricedb-format FMT

--primary-date

--quantity (-O )

--quarterly

--raw

For use only with the print command, it causes Ledger to print out matching entries exactly as they appeared in the original journal file.

--real (-R )

--register-format FMT

--related (-r )

--related-all

--revalued

--revalued-only

--revalued-total EXPR

--rich-data

--seed INT

--script

--sort EXPR (-S )

--sort-all

--sort-xacts

--start-of-week STR

--strict

--subtotal (-s )

--tail INT

--time-report

--total EXPR

--total-data (-J )

--total-width INT

--trace INT

--truncate

--unbudgeted

--uncleared (-U )

--unrealized

--unrealized-gains

--unrealized-losses

--unround

--value-expr EXPR

--verbose

--verify

--verify-memory

--version

--weekly (-W )

--wide (-w )

--yearly (-Y )

PRECOMMANDS

args

eval

format

parse

period

python

template

QUERIES

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

Fn 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 --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

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 Sx 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 Sx 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 Sx 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 Sx DRAFTS .

SEE ALSO

AUTHORS

Index

NAME

SYNOPSIS

DESCRIPTION

COMMANDS

OPTIONS

PRECOMMANDS

QUERIES

EXPRESSIONS

ENTRIES

FORMATS

DEBUG COMMANDS

SEE ALSO

AUTHORS