.Dd March 10, 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 \-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 \-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 \-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