1LEDGER(1) BSD General Commands Manual LEDGER(1)
2
4 ledger — Command-line, double-entry account reporting tool
5
7 ledger [options] [command] [arguments]
8
10 ledger is a command-line accounting tool based on the power and complete‐
11 ness of double-entry accounting. It is only a reporting tool, which
12 means it never modifies your data files, but it does offer a large selec‐
13 tion of reports, and different ways to customize them to your needs.
14
16 ledger accepts several top-level commands, each of which generates a dif‐
17 ferent kind of basic report. Most of them accept a report-query argu‐
18 ment, in order to determine what should be reported. To understand the
19 syntax of a report-query, see the section on QUERIES. In its most basic
20 form, simply specifying one or more strings produces a report for all
21 accounts containing those strings.
22 If no command is given, ledger enters a REPL, or command loop, allowing
24 several commands to be executed on the same dataset without reparsing.
25 The following is a complete list of accepted reporting commands:
27 accounts [report-query]
29 List all accounts for postings that match the report-query.
30 balance [report-query]
32 Print a balance report showing totals for postings that match
33 report-query, and aggregate totals for parents of those
34 accounts. Options most commonly used with this command are:
35 --basis (-B) Report in terms of cost basis, not amount or
36 value. This is the only form of report which
37 is guaranteed to always balance to zero, when
38 no report-query is specified. Only show totals
39 for the top-most accounts.
40 --empty (-E) Show accounts whose total is zero.
41 --flat Rather than display a hierarchical tree, flat‐
42 ten the report to show subtotals for only
43 accounts matching report-query.
44 --no-total Suppress the summary total shown at the bottom
45 of the report.
46 The synonyms bal and b are also accepted.
48 budget [report-query]
50 A special balance report which includes three extra columns: the
51 amount budgeted during the reporting period, how spending dif‐
52 fered from the budget, and the percentage of budget spent
53 (exceeds 100% if you go over budget). Note that budgeting
54 requires one or more “periodic transactions” to be defined in
55 your data file(s). See the manual for more information.
56 cleared [report-query]
58 A special balance report which adds two extra columns: the
59 cleared balance for each account, and the date of the most
60 recent cleared posting in that account. For this accounting to
61 be meaningful, the cleared flag must be set on at least one
62 posting. See the manual for more information.
63 commodities [report-query]
65 List all commodities for postings matching the report-query.
66 convert Reads data from a CSV (comma-separated values) file and gener‐
68 ates ledger transactions.
69 csv [report-query]
71 Report of postings matching the report-query in CSV format
72 (comma-separated values). Useful for exporting data to a
73 spreadsheet for further analysis or charting.
74 entry [entry-template]
76 Generate and display a new, properly formatted ledger transac‐
77 tion by comparing the entry-template to the transactions in your
78 data file(s). For more information on draft templates and using
79 this command to quickly create new transactions, see the section
80 ENTRIES.
81 The synonym xact is also accepted.
83 emacs [query]
85 Output posting and transaction data in a format readily consumed
86 by the Emacs editor, in a series of Lisp forms. This is used by
87 the Emacs ledger-mode to process reporting data from ledger.
88 equity [report-query]
90 Print a transaction with a series of postings that balance cur‐
91 rent totals for accounts matching the report-query in a special
92 account called Equity:Opening Balances. The purpose of this
93 report is to close the books for a prior year, while using these
94 equity postings to carry forward those balances.
95 payees [report-query]
97 List all payees for postings matching the report-query.
98 pricemap
100 Produce a file which can be used to generate a graph with
101 graphviz showing the relationship of commodities in the ledger
102 file.
103 prices [report-query]
105 Report prices for all commodities in postings matching the
106 report-query. The prices are reported with the granularity of a
107 single day.
108 pricedb [report-query]
110 Report prices for all commodities in postings matching the
111 report-query. Prices are reported down to the second, using the
112 same format as the ~/.pricedb file.
113 print [report-query]
115 Print out the full transactions of any matching postings using
116 the same format as they would appear in a data file. This can
117 be used to extract subsets from a ledger file to transfer to
118 other files.
119 push [options]
121 In the REPL, push a set of command-line options, so that they
122 will apply to all subsequent reports.
123 pop In the REPL, pop any option settings that have been pushed.
125 register [report-query]
127 List all postings matching the report-query. This is one of the
128 most common commands, and can be used to provide a variety of
129 useful reports. Options most commonly used with this command
130 are:
131 --average (-A) Show the running average, rather than a running
133 total.
134 --current (-c) Don't show postings beyond the present day.
135 --exchange commodity (-X)
136 Render all values in the given commodity, if a
137 price conversion rate can be determined. Rates
138 are always displayed relative to the date of
139 the posting they are calculated for. This
140 means a register report is a historical value
141 report. For current values, it may be prefer‐
142 able to use the balance report.
143 --gain (-G) Show any gains (or losses) in commodity values
144 over time.
145 --head number Only show the top number postings.
146 --historical (-H)
147 Value commodities at the time of their acquisi‐
148 tion.
149 --invert Invert the value of amounts shown.
150 --market (-V) Show current market values for all amounts.
151 This is determined in a somewhat magical fash‐
152 ion. It is probably more straightforward to
153 use --exchange option.
154 --period time-period (-p)
155 Show postings only for the given time-period.
156 --related (-r) Show postings that are related to those that
157 would have been shown. It has the effect of
158 displaying the "other side" of the postings.
159 --sort value-expression (-S)
160 Sort postings by evaluating the given
161 value-expression. Note that a comma-separated
162 list of expressions is allowed, in which case
163 each sorting term is used in order to determine
164 the final ordering. For example, to search by
165 date and then amount, one would use:
166 ledger reg --sort 'date, amount'
167 The sort order may be controlled with the '-'
168 sign. For example, to sort in reverse chrono‐
169 logical order:
170 ledger reg --sort '-date'
171 --tail number Only show the last number postings.
172 --uncleared (-U)
173 Only show uncleared (i.e., recent) postings.
174 There are also several grouping options that can be useful:
176 --by-payee (-P) Group postings by common payee names.
178 --daily (-D) Group postings by day.
179 --weekly (-W) Group postings by week (starting on Sundays).
180 --start-of-week day
181 Set the start of each report grouped by week to
182 the given day.
183 --monthly (-M) Group postings by month.
184 --quarterly Group postings by fiscal quarter.
185 --yearly (-Y) Group postings by year.
186 --days-of-week Group postings by the day of the week on which
187 they took place.
188 --subtotal (-s) Group all postings together. This is very sim‐
189 ilar to the totals shown by the balance report.
190 The synonyms reg and r are also accepted.
192 server This command requires that Python support be active. If so, it
194 starts up an HTTP server listening for requests on port 9000.
195 This provides an alternate interface to creating and viewing
196 reports. Note that this is very much a work-in-progress, and
197 will not be fully functional until a later version.
198 select [sql-query]
200 List all postings matching the sql-query. This command allows
201 to generate SQL-like queries, e.g.:
202 ledger select date,amount from posts where
203 account=~/Income/
204 source Parse a journal file and checks it for errors. ledger will
206 return success if no errors are found.
207 stats [report-query]
209 Provide summary information about all the postings matching
210 report-query. It provides information such as:
211 · Time range of all matching postings
212 · Unique payees
213 · Unique accounts
214 · Postings total
215 · Uncleared postings
216 · Days since last posting
217 · Posts in the last 7 days
218 · Posts in the last 30 days
219 · Posts this month
220 xml [report-query]
222 Output data relating to the current report in XML format. It
223 includes all accounts and commodities involved in the report,
224 plus the postings and the transactions they are contained in.
225 See the manual for more information.
226
228 --abbrev-len INT
229 Set the minimum length an account can be abbreviated to if it
230 doesn't fit inside the account-width. If INT is zero, then the
231 account name will be truncated on the right. If INT is greater
232 than account-width then the account will be truncated on the
233 left, with no shortening of the account names in order to fit
234 into the desired width.
235 --account EXPR
237 Prepend EXPR to all accounts reported. That is, the option
238 --account "'Personal'" would tack Personal: and --account
239 "tag('VAT')" would tack the value of the VAT tag to the begin‐
240 ning of every account reported in a balance or register report.
241 --account-width INT
243 Set the width of the account column in the register report to
244 INT characters.
245 --actual (-L)
247 Report only real transactions, with no automated or virtual
248 transactions used.
249 --add-budget
251 Show only un-budgeted postings.
252 --amount EXPR (-t)
254 Apply the given value expression to the posting amount. Using
255 --amount EXPR you can apply an arbitrary transformation to the
256 postings.
257 --amount-data (-j)
259 On a register report print only the dates and amount of post‐
260 ings. Useful for graphing and spreadsheet applications.
261 --amount-width INT
263 Set the width in characters of the amount column in the register
264 report.
265 --anon Anonymize registry output, mostly for sending in bug reports.
267 --ansi Use color if the terminal supports it. Alias for --color
269 --args-only
271 Ignore init files and environment variables for the ledger run.
272 --auto-match
274 When generating a ledger transaction from a CSV file using the
275 convert command, automatically match an account from the Ledger
276 journal.
277 --aux-date
279 Show auxiliary dates for all calculations. Alias for
280 --effective
281 --average (-A)
283 Print average values over the number of transactions instead of
284 running totals.
285 --average-lot-prices
287 Report the average price at which each commodity was purchased
288 in a balance report.
289 --balance-format FMT
291 Specify the format to use for the balance report.
292 --base Reduce convertible commodities down the bottom of the conver‐
294 sion, e.g. display time in seconds.
295 --basis (-B)
297 Report the cost basis on all posting. Alias for --cost
298 --begin DATE (-b)
300 Specify the start DATE of all calculations. Transactions before
301 that date will be ignored.
302 --bold-if EXPR
304 Print the entire line in bold if the given value expression is
305 true.
306 --budget
308 Only display budgeted items. In a register report this displays
309 transaction in the budget, in a balance report this displays
310 accounts in the budget.
311 --budget-format FMT
313 Specify the format to use for the budget report.
314 --by-payee (-P)
316 Group postings in the register report by common payee names.
317 --check-payees
319 Enable strict and pedantic checking for payees as well as
320 accounts, commodities and tags.
321 --cleared (-C)
323 Display only cleared postings.
324 --cleared-format FMT
326 Specify the format to use for the cleared report
327 --collapse (-n)
329 Print only the top level accounts.
330 --collapse-if-zero
332 Collapse the account display only if it has a zero balance.
333 --color Use color if the terminal supports it. Alias for --ansi
335 --columns INT
337 Make the register report INT characters wide. By default ledger
338 will use all available columns in your terminal.
339 --cost Report the cost basis on all posting. Alias for --basis.
341 --count Direct ledger to report the number of items when appended to the
343 commodities, accounts or payees commands.
344 --csv-format FMT
346 Format csv report according to FMT.
347 --current (-c)
349 Shorthand for --limit 'date <= today'.
350 --daily (-D)
352 Shorthand for --period daily.
353 --date EXPR
355 Transform the date of the transaction using EXPR.
356 --date-format DATEFMT (-y)
358 Print dates using DATEFMT. Refer to strftime(3) for details on
359 the format string syntax.
360 --datetime-format DATETIMEFMT
362 Print datetimes using DATETIMEFMT. Refer to strftime(3) for
363 details on the format string syntax.
364 --date-width INT
366 Specify the width, in characters, of the date column in the
367 register report.
368 --day-break
370 Break up register report of timelog entries that span multiple
371 days by day.
372 --days-of-week
374 Group transactions by the days of the week. Alias for --dow.
375 --dc Display register or balance in debit/credit format If you use
377 --dc with either the register or balance commands, you will now
378 get separate columns for debits and credits.
379 --debug STR
381 If ledger has been built with debug options this will provide
382 extra data during the run.
383 --decimal-comma
385 Direct ledger to parse journals using the European standard
386 comma as decimal separator, vice a period.
387 --depth INT
389 Limit the depth of the account tree. In a balance report, for
390 example, --depth 2 will print balances only for accounts with
391 two levels, i.e. Expenses:Entertainment but not
392 Expenses:Entertainment:Dining. This is a display predicate,
393 which means it only affects display, not the total calculations.
394 --detail
396 Related to convert command. Synonym to --rich-data option.
397 --deviation
399 Report each posting's deviation from the average. It is only
400 meaningful in the register and prices reports.
401 --display EXPR (-d)
403 Display lines that satisfy the expression EXPR.
404 --display-amount EXPR
406 Apply a transformation to the displayed amount. This occurs
407 after calculations occur.
408 --display-total EXPR
410 Apply a transformation to the displayed total. This occurs
411 after calculations occur.
412 --dow Group transactions by the days of the week. Alias for
414 --days-of-week.
415 --download
417 Cause quotes to be automagically downloaded, as needed, by run‐
418 ning a script named getquote and expecting that script to return
419 a value understood by ledger. A sample implementation of a
420 getquote script, implemented in Perl, is provided in the distri‐
421 bution. Downloaded quote price are then appended to the price
422 database, usually specified using the environment variable
423 LEDGER_PRICE_DB.
424 --effective
426 Show auxiliary dates for all calculations. Alias for
427 --aux-date.
428 --empty (-E)
430 Include empty accounts in report.
431 --end DATE (-e)
433 Constrain the report so that transactions on or after DATE are
434 not considered.
435 --equity
437 Related to the equity command. Gives current account balances
438 in the form of a register report.
439 --exact Report beginning and ending of periods by the date of the first
441 and last posting occurring in that period.
442 --exchange COMMODITY [, COMMODITY, ...] (-X)
444 Display values in terms of the given COMMODITY. The latest
445 available price is used.
446 --file FILE (-f)
448 Read journal data from FILE.
449 --first INT
451 Print the first INT entries. Opposite of --last INT. Alias for
452 --head.
453 --flat Force the full names of accounts to be used in the balance
455 report. The balance report will not use an indented tree.
456 --force-color
458 Output TTY color codes even if the TTY doesn't support them.
459 Useful for TTYs that don't advertise their capabilities cor‐
460 rectly.
461 --force-pager
463 Force ledger to paginate its output.
464 --forecast-while EXPR
466 Continue forecasting while VEXPR is true. Alias for --forecast.
467 --forecast-years INT
469 Forecast at most INT years into the future.
470 --format FMT (-F)
472 Use the given format string FMT to print output.
473 --gain (-G)
475 Report net gain or loss for commodities that have a price his‐
476 tory.
477 --generated
479 Include auto-generated postings (such as those from automated
480 transactions) in the report, in cases where you normally
481 wouldn't want them.
482 --group-by EXPR
484 Group transaction together in the register report. EXPR can be
485 anything, although most common would be payee or commodity. The
486 tag() function is also useful here.
487 --group-title-format FMT
489 Set the format for the headers that separate reports section of
490 a grouped report. Only has effect with a --group-by EXPR regis‐
491 ter report.
492 --head INT
494 Print the first INT entries. Opposite of --tail INT. Alias for
495 --first
496 --help Print this man page.
498 --immediate
500 Evaluate calculations immediately rather than lazily.
501 --import FILE
503 Import FILE as Python module.
504 --init-file FILE (-i)
506 Read FILE before any other ledger file. This file may not con‐
507 tain any postings, but it may contain option settings. To spec‐
508 ify options in the init file, use the same syntax as the com‐
509 mand-line, but put each option on its own line.
510 --inject STR
512 Use STR amounts in calculations. In case you know what amount a
513 transaction should be, but the actual transaction has the wrong
514 value you can use metadata STR to specify the expected amount.
515 --input-date-format DATEFMT
517 Specify the input date format for journal entries.
518 --invert
520 Change the sign of all reported values.
521 --last INT.
523 Report only the last INT entries. Opposite of --first INT.
524 Only useful on a register report. Alias for --tail.
525 --leeway INT (-Z)
527 Alias for --price-expr.
528 --limit EXPR (-l)
530 Limit postings in calculations.
531 --lot-dates
533 Report the date on which each commodity in a balance report was
534 purchased.
535 --lot-notes
537 Report the tag attached to each commodity in a balance report.
538 --lot-prices
540 Report the price at which each commodity in a balance report was
541 purchased.
542 --lots Report the date and price at which each commodity was purchased
544 in a balance report.
545 --lots-actual
547 Preserve the uniqueness of commodities so they aren't merged
548 during reporting without printing the lot annotations.
549 --market (-V)
551 Use the latest market value for all commodities.
552 --master-account STR
554 Prepend all account names with STR
555 --meta STR
557 In the register report, prepend the transaction with the value
558 of the given tag STR.
559 --meta-width INT
561 Specify the width of the Meta column used for the --meta TAG
562 options.
563 --monthly (-M)
565 Shorthand for --period monthly.
566 --no-aliases
568 Aliases are completely ignored.
569 --no-color
571 Suppress any color TTY output.
572 --no-pager
574 Disables the pager on TTY output.
575 --no-revalued
577 Stop ledger from showing <Revalued> postings.
578 --no-rounding
580 Don't output "<Adjustment>" postings. Note that this will cause
581 the running total to often not add up! Its main use is for
582 --amount-data (-j) and --total-data (-J) reports.
583 --no-titles
585 Suppress the output of group titles.
586 --no-total
588 Suppress printing the final total line in a balance report.
589 --now DATE
591 Use DATE as the current date. This affects the output when
592 using --period, --begin, --end, or --current to decide which
593 dates lie in the past or future.
594 --only EXPR
596 This is a postings predicate that applies after certain trans‐
597 forms have been executed, such as periodic gathering.
598 --options
600 Display the options in effect for this ledger invocation, along
601 with their values and the source of those values.
602 --output FILE (-o)
604 Redirect the output of ledger to FILE.
605 --pager STR
607 Use STR as the pager program.
608 --payee Sets a value expression for formatting the payee. In the
610 register report this prevents the second entry from having a
611 date and payee for each transaction.
612 --payee-width INT
614 Set the number of columns dedicated to the payee in the register
615 report to INT.
616 --pedantic
618 Accounts, tags or commodities not previously declared will cause
619 errors.
620 --pending
622 Use only postings that are marked pending.
623 --percent (-%)
625 Calculate the percentage value of each account in a balance
626 reports. Only works for account that have a single commodity.
627 --period PERIOD (-p)
629 Define a period expression that sets the time period during
630 which transactions are to be accounted. For a register report
631 only the transactions that satisfy the period expression with be
632 displayed. For a balance report only those transactions will be
633 accounted in the final balances.
634 --period-sort
636 Sort the posting within transactions using the given value
637 expression.
638 --permissive
640 Quiet balance assertions.
641 --pivot TAG
643 Produce a balance pivot report "around" the given TAG.
644 --plot-amount-format FMT
646 Define the output format for an amount data plot.
647 --plot-total-format FMT
649 Define the output format for a total data plot.
650 --prepend-format FMT
652 Prepend FMT to every line of the output.
653 --prepend-width INT
655 Reserve INT spaces at the beginning of each line of the output.
656 --price (-I)
658 Use the price of the commodity purchase for performing calcula‐
659 tions.
660 --price-db FILE
662 --price-exp STR (-Z)
664 Set the expected freshness of price quotes, in INT minutes.
665 That is, if the last known quote for any commodity is older than
666 this value, and if --download is being used, then the Internet
667 will be consulted again for a newer price. Otherwise, the old
668 price is still considered to be fresh enough. Alias for
669 --leeway.
670 --prices-format FMT
672 Set the format for the prices report.
673 --pricedb-format FMT
675 Set the format expected for the historical price file.
676 --primary-date
678 Show primary dates for all calculations. Alias for
679 --actual-dates
680 --quantity (-O)
682 Report commodity totals (this is the default).
683 --quarterly
685 Shorthand for --period quarterly.
686 --raw In the print report, show transactions using the exact same syn‐
688 tax as specified by the user in their data file. Don't do any
689 massaging or interpreting. Can be useful for minor cleanups,
690 like just aligning amounts.
691 --real (-R)
693 Account using only real transactions ignoring virtual and auto‐
694 matic transactions.
695 --recursive-aliases
697 Causes ledger to try to expand aliases recursively, i.e. try to
698 expand the result of an earlier expansion again, until no more
699 expansions apply.
700 --register-format FMT
702 Define the output format for the register report.
703 --related (-r)
705 In a register report show the related account. This is the
706 other side of the transaction.
707 --related-all
709 Show all postings in a transaction, similar to --related but
710 show both sides of each transaction.
711 --revalued
713 Report discrepancy in values for manual reports by inserting
714 <Revalued> postings. This is implied when using the --exchange
715 (-X) or --market (-V) option.
716 --revalued-only
718 Show only <Revalued> postings.
719 --revalued-total
721 Display the sum of the revalued postings as the running total,
722 which serves to show unrealized capital in a gain/losses report.
723 --rich-data
725 When generating a ledger transaction from a CSV file using the
726 convert command, add CSV, Imported, and UUID meta-data.
727 --seed INT
729 Set the random seed to INT for the generate command. Used as
730 part of development testing.
731 --script FILE
733 Execute a ledger script.
734 --sort EXPR (-S)
736 Sort the register report based on the value expression EXPR.
737 --sort-xacts
739 Sort the posting within transactions using the given value
740 expression.
741 --start-of-week STR
743 Use STR as the particular day of the week to start when using
744 the --weekly option. STR can be day names, their abbreviations
745 like "Mon", or the weekday number starting at 0 for Sunday.
746 --strict
748 Accounts, tags or commodities not previously declared will cause
749 warnings.
750 --subtotal (-s)
752 Report register as a single subtotal.
753 --tail INT
755 Report only the last INT entries. Only useful on a register
756 report. Alias for --last INT
757 --time-colon
759 Display the value for commodities based on seconds as hours and
760 minutes. Thus 8100s will be displayed as 2:15h instead of
761 2.25h.
762 --time-report
764 Add two columns to the balance report to show the earliest
765 checkin and checkout times for timelog entries.
766 --total EXPR (-T)
768 Define a value expression used to calculate the total in
769 reports.
770 --total-data (-J)
772 Show only dates and totals to format the output for plots.
773 --total-width INT
775 Set the width of the total field in the register report.
776 --trace INT
778 Enable tracing. The INT specifies the level of trace desired.
779 --truncate STR
781 Indicates how truncation should happen when the contents of col‐
782 umns exceed their width. Valid arguments for STR are leading,
783 middle, and trailing. The default is smarter than any of these
784 three, as it considers sub-names within the account name (that
785 style is called "abbreviate").
786 --unbudgeted
788 Show only un-budgeted postings.
789 --uncleared (-U)
791 Use only uncleared transactions in calculations and reports.
792 --unrealized
794 Show generated unrealized gain and loss accounts in the balance
795 report.
796 --unrealized-gains
798 Allow the user to specify what account name should be used for
799 unrealized gains. Defaults to Equity:Unrealized Gains. Often
800 set in one's ~/.ledgerrc file to change the default.
801 --unrealized-losses
803 Allow the user to specify what account name should be used for
804 unrealized losses. Defaults to Equity:Unrealized Losses. Often
805 set in one's ~/.ledgerrc file to change the default.
806 --unround
808 Perform all calculations without rounding and display results to
809 full precision.
810 --values
812 Show the values used by each tag when used in combination with
813 the tags command.
814 --value-expr EXPR
816 Set a global value expression annotation.
817 --verbose
819 Print detailed information on the execution of ledger.
820 --verify
822 Enable additional assertions during run-time. This causes a
823 significant slowdown. When combined with --debug CODE ledger
824 will produce memory trace information.
825 --verify-memory
827 Verify that every constructed object is properly destructed.
828 This is for debugging purposes only.
829 --version
831 Print version information and exit.
832 --weekly (-W)
834 Shorthand for --period weekly.
835 --wide (-w)
837 Assume 132 columns instead of the TTY width.
838 --yearly (-Y)
840 Shorthand for --period yearly.
841
843 Pre-commands are useful when you aren't sure how a command or option will
844 work. The difference between a pre-command and a regular command is that
845 pre-commands ignore the journal data file completely, nor is the user's
846 init file read.
847 args / query
849 Evaluate the given arguments and report how ledger interprets it
850 against the following model transaction:
851 2004/05/27 Book Store
853 ; This note applies to all postings. :SecondTag:
854 Expenses:Books 20 BOOK @ $10
855 ; Metadata: Some Value
856 ; Typed:: $100 + $200
857 ; :ExampleTag:
858 ; Here follows a note describing the posting.
859 Liabilities:MasterCard $-200.00
860 eval Evaluate the given value expression against the model transac‐
862 tion.
863 format Print details of how ledger uses the given formatting descrip‐
865 tion and apply it against a model transaction.
866 parse / expr
868 Print details of how ledger uses the given value expression
869 description and apply it against a model transaction.
870 generate
872 Randomly generates syntactically valid ledger data from a seed.
873 Used by the GenerateTests harness for development testing.
874 period Evaluate the given period and report how ledger interprets it.
876 template
878 Shows the insertion template that the xact command generates.
879 This is a debugging command.
880
882 The syntax for reporting queries can get somewhat complex. It is a
883 series of query terms with an implicit OR operator between them. The
884 following terms are accepted:
885 regex A bare string is taken as a regular expression matching
887 the full account name. Thus, to report the current bal‐
888 ance for all assets and liabilities, you would use:
889 ledger bal asset liab
891 payee regex (@regex)
893 Query on the payee, rather than the account.
894 tag regex (%regex)
896 Query on tags.
897 note regex (=regex)
899 Query on anything found in an item's note.
900 code regex (#regex)
902 Query on the xact's optional code (which can be any string
903 the user wishes).
904 term and term Query terms are joined by an implicit OR operator. You
906 can change this to AND by using the and keyword. For
907 example, to show food expenditures occurring at Shakee's
908 Pizza, you could say:
909 ledger reg food and @Shakee
911 term or term When you wish to be more explicit, use the OR operator.
913 show
915 not term Reverse the logical meaning of the following term. This
917 can be used with parentheses to great effect:
918 ledger reg food and @Shakee and not dining
920 ( term ) If you wish to mix OR and AND operators, it is often help‐
922 ful to surround logical units with parentheses. NOTE:
923 Because of the way some shells interpret parentheses, you
924 should always escape them:
925 ledger bal \( assets or liab \) and not food
927
929 abs(value) Return the absolute value of the given value.
930 account Return the posting's account.
932 account_base Return the base account, i.e. everything after the last
934 account delimiter ':'.
935 actual Return true if the transaction is real, i.e not an auto‐
937 mated or virtual transaction, false otherwise.
938 amount Return the amount of the posting.
940 amount_expr Return the calculated amount of the posting according to
942 the --amount option.
943 ansify_if(value, color, bool)
945 Render the given value as a string, applying the proper
946 ANSI escape codes to display it in the given color if
947 bool is true. It typically checks the value of the
948 option --color, for example:
949 ansify_if(amount, blue, options.color)
950 beg_line Line number where entry for posting begins.
952 beg_pos Character position where entry for posting begins.
954 ceiling(value) Return the next integer of value toward +infinity.
956 cleared Return true if the posting was cleared, false otherwise.
958 code Return the transaction code, the string between the
960 parenthesis after the date.
961 commodity(value)
963 Return the commodity of value or the posting amount when
964 value was not specified.
965 date Return the date of the posting.
967 end_line Line number where entry for posting ends.
969 end_pos Character position where entry for posting ends.
971 floor(value) Return the next integer of value toward -infinity.
973 filename The name of the ledger data file from whence the posting
975 came.
976 format(string) Evaluate string as format just like the --format option.
978 format_date(date, format)
980 Return the date as a string using format. Refer to
981 strftime(3) for format string details.
982 format_datetime(datetime, format)
984 Return the datetime as a string using format. Refer to
985 strftime(3) for format string details.
986 get_at(seq, index)
988 Return value at index from seq. Used internally to con‐
989 struct different reports.
990 has_meta(tag) Return true if the posting has metadata named tag, false
992 otherwise.
993 has_tag(tag) Return true if the posting has metadata named tag, false
995 otherwise.
996 is_seq(value) Return true if value is a sequence. Used internally.
998 join(value) Replace all newlines in value with \n.
1000 justify(value, first_width, latter_width, right_justify, colorize)
1002 Right or left justify the string representing value.
1003 The width of the field in the first line is given by
1004 first_width. For subsequent lines the width is given by
1005 latter_width. If latter_width is -1, first_width is
1006 used for all lines. If right_justify is true then the
1007 field is right justified within the width of the field.
1008 If it is false, then the field is left justified and
1009 padded to the full width of the field. If colorize is
1010 true, then ledger will honor color settings.
1011 market(value, datetime)
1013 Return the price of value at datetime. Note that
1014 datetime must be surrounded by brackets in order to be
1015 parsed correctly, e.g. [2012/03/23].
1016 meta(name) Return the value of metadata named name.
1018 note Return the note for the posting.
1020 now Return the current datetime.
1022 options A variable that allows access to the values of the given
1024 command-line options using the long option names, e.g.
1025 to see whether --daily (-D) was given use option.daily.
1026 payee Return the payee of the posting.
1028 percent(value_a, value_b)
1030 Return the percentage of value_a in relation to value_b
1031 (used as 100%).
1032 pending Return true if the posting is marked as pending, false
1034 otherwise.
1035 percent(value_a, value_b)
1037 Return the percentage of value_a in relation to value_b.
1038 print(value) Print value to stdout. Used internally for debugging.
1040 quantity(value) Return the quantity of value for values that have a per-
1042 unit cost.
1043 quoted(expression)
1045 Surround expression with double-quotes.
1046 quoted_rfc4180(expression)
1048 Surround expression with double-quotes, compatible with
1049 rfc 4180.
1050 real Return true if the transaction is real, i.e not an auto‐
1052 mated or virtual transaction, false otherwise.
1053 roundto(value, n)
1055 Return value rounded to n digits. Does not affect for‐
1056 matting.
1057 should_bold Return true if expression given to --bold-if evaluates
1059 to true. Internal use only!
1060 scrub(value) Clean value using various transformations such as round,
1062 stripping value annotations, and more.
1063 strip(value) Strip value annotation from value.
1065 tag(name) Return the value of tag named name.
1067 to_amount(value)
1069 Convert value to an amount. Internal use only!
1070 to_balance(value)
1072 Convert value to a balance. Internal use only!
1073 to_boolean(value)
1075 Convert value to a boolean. Internal use only!
1076 to_date(value) Convert value to a date. Internal use only!
1078 to_datetime(value)
1080 Convert value to a datetime. Internal use only!
1081 to_int(value) Return the integer value for value.
1083 to_mask(value) Convert value to a mask. Internal use only!
1085 to_sequence(value)
1087 Convert value to a sequence. Internal use only!
1088 to_string(value)
1090 Convert value to a character string.
1091 today Return today's date.
1093 total Return the total of the posting.
1095 total_expr Return the calculated total of the posting according to
1097 the --total option.
1098 trim(value) Trim leading and trailing whitespace from value.
1100 truncated(string, total_len, account_len)
1102 Truncate string to total_len ensuring that each account
1103 is at least account_len long.
1104 virtual Return true if the transaction is virtual, e.g auto‐
1106 mated, false otherwise.
1107
1109 In addition to the regular reporting commands, ledger also accepts sev‐
1110 eral debug commands:
1111 args [report-query]
1113 Display complete analysis of how ledger interpreted the given
1114 report-query. Useful if you want to understand how report
1115 queries are translated into value expressions.
1116 eval [value-expression]
1118 Evaluate the given value-expression and prints the result. For
1119 more on value expressions, see the section EXPRESSIONS.
1120 format [format-string]
1122 Display an analysis of how format-string was parsed, and what it
1123 would look like applied to a sample transaction. For more on
1124 format strings, see the section FORMATS.
1125 generate
1127 Generate 50 randomly composed yet valid ledger transactions.
1128 parse [value-expression]
1130 Parse the given value-expression and display an analysis of the
1131 expression tree and its evaluated value. For more on value
1132 expressions, see the section EXPRESSIONS.
1133 python [file]
1135 Invoke a Python interpreter to read the given file. What is
1136 special about this is that the ledger module is builtin, not
1137 read from disk, so it doesn't require ledger to be installed
1138 anywhere, or the shared library variants to be built.
1139 reload Reload all data files for the current session immediately. Can
1141 only be used in the REPL.
1142 template [draft-template]
1144 Display information about how draft-template was parsed. See
1145 the section on DRAFTS.
1146
1148 Every option to ledger may be set using an environment variable if the
1149 option has a long name. For example setting the environment variable
1150 LEDGER_DATE_FORMAT="%d.%m.%Y' will have the same effect as specifying
1151 --date-format '%d.%m.%Y' on the command-line. Options on the command-
1152 line always take precedence over environment variable settings, however.
1153
1155 ~/.ledgerrc
1156 Your personal ledger initializations.
1157
1159 beancount(1), hledger(1)
1160 The full documentation for ledger is maintained as a Texinfo manual. If
1162 the info program is installed on your system, the command
1163 info ledger3
1164 should give you access to the complete manual.
1165
1167 John Wiegley ⟨johnw@newartisans.com⟩
1168BSD March 15, 2019 BSD