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 --balance-format FMT
287 Specify the format to use for the balance report.
288 --base Reduce convertible commodities down the bottom of the conver‐
290 sion, e.g. display time in seconds.
291 --basis (-B)
293 Report the cost basis on all posting. Alias for --cost
294 --begin DATE (-b)
296 Specify the start DATE of all calculations. Transactions before
297 that date will be ignored.
298 --bold-if EXPR
300 Print the entire line in bold if the given value expression is
301 true.
302 --budget
304 Only display budgeted items. In a register report this displays
305 transaction in the budget, in a balance report this displays
306 accounts in the budget.
307 --budget-format FMT
309 Specify the format to use for the budget report.
310 --by-payee (-P)
312 Group postings in the register report by common payee names.
313 --check-payees
315 Enable strict and pedantic checking for payees as well as
316 accounts, commodities and tags.
317 --cleared (-C)
319 Display only cleared postings.
320 --cleared-format FMT
322 Specify the format to use for the cleared report
323 --collapse (-n)
325 Print only the top level accounts.
326 --collapse-if-zero
328 Collapse the account display only if it has a zero balance.
329 --color Use color if the terminal supports it. Alias for --ansi
331 --columns INT
333 Make the register report INT characters wide. By default ledger
334 will use all available columns in your terminal.
335 --cost Report the cost basis on all posting. Alias for --basis.
337 --count Direct ledger to report the number of items when appended to the
339 commodities, accounts or payees commands.
340 --csv-format FMT
342 Format csv report according to FMT.
343 --current (-c)
345 Shorthand for --limit 'date <= today'.
346 --daily (-D)
348 Shorthand for --period daily.
349 --date EXPR
351 Transform the date of the transaction using EXPR.
352 --date-format DATEFMT (-y)
354 Print dates using DATEFMT. Refer to strftime(3) for details on
355 the format string syntax.
356 --datetime-format DATETIMEFMT
358 Print datetimes using DATETIMEFMT. Refer to strftime(3) for
359 details on the format string syntax.
360 --date-width INT
362 Specify the width, in characters, of the date column in the
363 register report.
364 --day-break
366 Break up register report of timelog entries that span multiple
367 days by day.
368 --days-of-week
370 Group transactions by the days of the week. Alias for --dow.
371 --dc Display register or balance in debit/credit format If you use
373 --dc with either the register or balance commands, you will now
374 get separate columns for debits and credits.
375 --debug STR
377 If ledger has been built with debug options this will provide
378 extra data during the run.
379 --decimal-comma
381 Direct ledger to parse journals using the European standard
382 comma as decimal separator, vice a period.
383 --depth INT
385 Limit the depth of the account tree. In a balance report, for
386 example, --depth 2 will print balances only for accounts with
387 two levels, i.e. Expenses:Entertainment but not
388 Expenses:Entertainment:Dining. This is a display predicate,
389 which means it only affects display, not the total calculations.
390 --detail
392 Related to convert command. Synonym to --rich-data option.
393 --deviation
395 Report each posting's deviation from the average. It is only
396 meaningful in the register and prices reports.
397 --display EXPR (-d)
399 Display lines that satisfy the expression EXPR.
400 --display-amount EXPR
402 Apply a transformation to the displayed amount. This occurs
403 after calculations occur.
404 --display-total EXPR
406 Apply a transformation to the displayed total. This occurs
407 after calculations occur.
408 --dow Group transactions by the days of the week. Alias for
410 --days-of-week.
411 --download
413 Cause quotes to be automagically downloaded, as needed, by run‐
414 ning a script named getquote and expecting that script to return
415 a value understood by ledger. A sample implementation of a
416 getquote script, implemented in Perl, is provided in the distri‐
417 bution. Downloaded quote price are then appended to the price
418 database, usually specified using the environment variable
419 LEDGER_PRICE_DB.
420 --effective
422 Show auxiliary dates for all calculations. Alias for
423 --aux-date.
424 --empty (-E)
426 Include empty accounts in report.
427 --end DATE (-e)
429 Constrain the report so that transactions on or after DATE are
430 not considered.
431 --equity
433 Related to the equity command. Gives current account balances
434 in the form of a register report.
435 --exact Report beginning and ending of periods by the date of the first
437 and last posting occurring in that period.
438 --exchange COMMODITY [, COMMODITY, ...] (-X)
440 Display values in terms of the given COMMODITY. The latest
441 available price is used.
442 --explicit
444 Direct ledger to require pre-declarations for entities (such as
445 accounts, commodities and tags) rather than taking entities from
446 cleared transactions as defined.
447 --file FILE (-f)
449 Read journal data from FILE.
450 --first INT
452 Print the first INT entries. Opposite of --last INT. Alias for
453 --head.
454 --flat Force the full names of accounts to be used in the balance
456 report. The balance report will not use an indented tree.
457 --force-color
459 Output TTY color codes even if the TTY doesn't support them.
460 Useful for TTYs that don't advertise their capabilities cor‐
461 rectly.
462 --force-pager
464 Force ledger to paginate its output.
465 --forecast-while EXPR
467 Continue forecasting while VEXPR is true. Alias for --forecast.
468 --forecast-years INT
470 Forecast at most INT years into the future.
471 --format FMT (-F)
473 Use the given format string FMT to print output.
474 --gain (-G)
476 Report net gain or loss for commodities that have a price his‐
477 tory.
478 --generated
480 Include auto-generated postings (such as those from automated
481 transactions) in the report, in cases where you normally
482 wouldn't want them.
483 --group-by EXPR
485 Group transaction together in the register report. EXPR can be
486 anything, although most common would be payee or commodity. The
487 tag() function is also useful here.
488 --group-title-format FMT
490 Set the format for the headers that separate reports section of
491 a grouped report. Only has effect with a --group-by EXPR regis‐
492 ter report.
493 --head INT
495 Print the first INT entries. Opposite of --tail INT. Alias for
496 --first
497 --help Print this man page.
499 --immediate
501 Evaluate calculations immediately rather than lazily.
502 --import FILE
504 Import FILE as Python module.
505 --init-file FILE (-i)
507 Read FILE before any other ledger file. This file may not con‐
508 tain any postings, but it may contain option settings. To spec‐
509 ify options in the init file, use the same syntax as the com‐
510 mand-line, but put each option on its own line.
511 --inject STR
513 Use STR amounts in calculations. In case you know what amount a
514 transaction should be, but the actual transaction has the wrong
515 value you can use metadata STR to specify the expected amount.
516 --input-date-format DATEFMT
518 Specify the input date format for journal entries.
519 --invert
521 Change the sign of all reported values.
522 --last INT.
524 Report only the last INT entries. Opposite of --first INT.
525 Only useful on a register report. Alias for --tail.
526 --leeway INT (-Z)
528 Alias for --price-expr.
529 --limit EXPR (-l)
531 Limit postings in calculations.
532 --lot-dates
534 Report the date on which each commodity in a balance report was
535 purchased.
536 --lot-notes
538 Report the tag attached to each commodity in a balance report.
539 --lot-prices
541 Report the price at which each commodity in a balance report was
542 purchased.
543 --lots Report the date and price at which each commodity was purchased
545 in a balance report.
546 --lots-actual
548 Preserve the uniqueness of commodities so they aren't merged
549 during reporting without printing the lot annotations.
550 --market (-V)
552 Use the latest market value for all commodities.
553 --master-account STR
555 Prepend all account names with STR
556 --meta STR
558 In the register report, prepend the transaction with the value
559 of the given tag STR.
560 --meta-width INT
562 Specify the width of the Meta column used for the --meta TAG
563 options.
564 --monthly (-M)
566 Shorthand for --period monthly.
567 --no-aliases
569 Aliases are completely ignored.
570 --no-color
572 Suppress any color TTY output.
573 --no-pager
575 Disables the pager on TTY output.
576 --no-revalued
578 Stop ledger from showing <Revalued> postings.
579 --no-rounding
581 Don't output "<Adjustment>" postings. Note that this will cause
582 the running total to often not add up! Its main use is for
583 --amount-data (-j) and --total-data (-J) reports.
584 --no-titles
586 Suppress the output of group titles.
587 --no-total
589 Suppress printing the final total line in a balance report.
590 --now DATE
592 Use DATE as the current date. This affects the output when
593 using --period, --begin, --end, or --current to decide which
594 dates lie in the past or future.
595 --only EXPR
597 This is a postings predicate that applies after certain trans‐
598 forms have been executed, such as periodic gathering.
599 --options
601 Display the options in effect for this ledger invocation, along
602 with their values and the source of those values.
603 --output FILE (-o)
605 Redirect the output of ledger to FILE.
606 --pager STR
608 Use STR as the pager program.
609 --payee Sets a value expression for formatting the payee. In the
611 register report this prevents the second entry from having a
612 date and payee for each transaction.
613 --payee-width INT
615 Set the number of columns dedicated to the payee in the register
616 report to INT.
617 --pedantic
619 Accounts, tags or commodities not previously declared will cause
620 errors.
621 --pending
623 Use only postings that are marked pending.
624 --percent (-%)
626 Calculate the percentage value of each account in a balance
627 reports. Only works for account that have a single commodity.
628 --period PERIOD (-p)
630 Define a period expression that sets the time period during
631 which transactions are to be accounted. For a register report
632 only the transactions that satisfy the period expression with be
633 displayed. For a balance report only those transactions will be
634 accounted in the final balances.
635 --period-sort
637 Sort the posting within transactions using the given value
638 expression.
639 --permissive
641 Quiet balance assertions.
642 --pivot TAG
644 Produce a balance pivot report "around" the given TAG.
645 --plot-amount-format FMT
647 Define the output format for an amount data plot.
648 --plot-total-format FMT
650 Define the output format for a total data plot.
651 --prepend-format FMT
653 Prepend FMT to every line of the output.
654 --prepend-width INT
656 Reserve INT spaces at the beginning of each line of the output.
657 --price (-I)
659 Use the price of the commodity purchase for performing calcula‐
660 tions.
661 --price-db FILE
663 --price-exp STR (-Z)
665 Set the expected freshness of price quotes, in INT minutes.
666 That is, if the last known quote for any commodity is older than
667 this value, and if --download is being used, then the Internet
668 will be consulted again for a newer price. Otherwise, the old
669 price is still considered to be fresh enough. Alias for
670 --leeway.
671 --prices-format FMT
673 Set the format for the prices report.
674 --pricedb-format FMT
676 Set the format expected for the historical price file.
677 --primary-date
679 Show primary dates for all calculations. Alias for
680 --actual-dates
681 --quantity (-O)
683 Report commodity totals (this is the default).
684 --quarterly
686 Shorthand for --period quarterly.
687 --raw In the print report, show transactions using the exact same syn‐
689 tax as specified by the user in their data file. Don't do any
690 massaging or interpreting. Can be useful for minor cleanups,
691 like just aligning amounts.
692 --real (-R)
694 Account using only real transactions ignoring virtual and auto‐
695 matic transactions.
696 --recursive-aliases
698 Causes ledger to try to expand aliases recursively, i.e. try to
699 expand the result of an earlier expansion again, until no more
700 expansions apply.
701 --register-format FMT
703 Define the output format for the register report.
704 --related (-r)
706 In a register report show the related account. This is the
707 other side of the transaction.
708 --related-all
710 Show all postings in a transaction, similar to --related but
711 show both sides of each transaction.
712 --revalued
714 Report discrepancy in values for manual reports by inserting
715 <Revalued> postings. This is implied when using the --exchange
716 (-X) or --market (-V) option.
717 --revalued-only
719 Show only <Revalued> postings.
720 --revalued-total
722 Display the sum of the revalued postings as the running total,
723 which serves to show unrealized capital in a gain/losses report.
724 --rich-data
726 When generating a ledger transaction from a CSV file using the
727 convert command, add CSV, Imported, and UUID meta-data.
728 --seed INT
730 Set the random seed to INT for the generate command. Used as
731 part of development testing.
732 --script FILE
734 Execute a ledger script.
735 --sort EXPR (-S)
737 Sort the register report based on the value expression EXPR.
738 --sort-xacts
740 Sort the posting within transactions using the given value
741 expression.
742 --start-of-week STR
744 Use STR as the particular day of the week to start when using
745 the --weekly option. STR can be day names, their abbreviations
746 like "Mon", or the weekday number starting at 0 for Sunday.
747 --strict
749 Accounts, tags or commodities not previously declared will cause
750 warnings.
751 --subtotal (-s)
753 Report register as a single subtotal.
754 --tail INT
756 Report only the last INT entries. Only useful on a register
757 report. Alias for --last INT
758 --time-colon
760 Display the value for commodities based on seconds as hours and
761 minutes. Thus 8100s will be displayed as 2:15h instead of
762 2.25h.
763 --time-report
765 Add two columns to the balance report to show the earliest
766 checkin and checkout times for timelog entries.
767 --total EXPR (-T)
769 Define a value expression used to calculate the total in
770 reports.
771 --total-data (-J)
773 Show only dates and totals to format the output for plots.
774 --total-width INT
776 Set the width of the total field in the register report.
777 --trace INT
779 Enable tracing. The INT specifies the level of trace desired.
780 --truncate STR
782 Indicates how truncation should happen when the contents of col‐
783 umns exceed their width. Valid arguments for STR are leading,
784 middle, and trailing. The default is smarter than any of these
785 three, as it considers sub-names within the account name (that
786 style is called "abbreviate").
787 --unbudgeted
789 Show only un-budgeted postings.
790 --uncleared (-U)
792 Use only uncleared transactions in calculations and reports.
793 --unrealized
795 Show generated unrealized gain and loss accounts in the balance
796 report.
797 --unrealized-gains
799 Allow the user to specify what account name should be used for
800 unrealized gains. Defaults to Equity:Unrealized Gains. Often
801 set in one's ~/.ledgerrc file to change the default.
802 --unrealized-losses
804 Allow the user to specify what account name should be used for
805 unrealized losses. Defaults to Equity:Unrealized Losses. Often
806 set in one's ~/.ledgerrc file to change the default.
807 --unround
809 Perform all calculations without rounding and display results to
810 full precision.
811 --values
813 Show the values used by each tag when used in combination with
814 the tags command.
815 --value-expr EXPR
817 Set a global value expression annotation.
818 --verbose
820 Print detailed information on the execution of ledger.
821 --verify
823 Enable additional assertions during run-time. This causes a
824 significant slowdown. When combined with --debug CODE ledger
825 will produce memory trace information.
826 --verify-memory
828 Verify that every constructed object is properly destructed.
829 This is for debugging purposes only.
830 --version
832 Print version information and exit.
833 --weekly (-W)
835 Shorthand for --period weekly.
836 --wide (-w)
838 Assume 132 columns instead of the TTY width.
839 --yearly (-Y)
841 Shorthand for --period yearly.
842
844 Pre-commands are useful when you aren't sure how a command or option will
845 work. The difference between a pre-command and a regular command is that
846 pre-commands ignore the journal data file completely, nor is the user's
847 init file read.
848 args / query
850 Evaluate the given arguments and report how ledger interprets it
851 against the following model transaction:
852 2004/05/27 Book Store
854 ; This note applies to all postings. :SecondTag:
855 Expenses:Books 20 BOOK @ $10
856 ; Metadata: Some Value
857 ; Typed:: $100 + $200
858 ; :ExampleTag:
859 ; Here follows a note describing the posting.
860 Liabilities:MasterCard $-200.00
861 eval Evaluate the given value expression against the model transac‐
863 tion.
864 format Print details of how ledger uses the given formatting descrip‐
866 tion and apply it against a model transaction.
867 parse / expr
869 Print details of how ledger uses the given value expression
870 description and apply it against a model transaction.
871 generate
873 Randomly generates syntactically valid ledger data from a seed.
874 Used by the GenerateTests harness for development testing.
875 period Evaluate the given period and report how ledger interprets it.
877 template
879 Shows the insertion template that the xact command generates.
880 This is a debugging command.
881
883 The syntax for reporting queries can get somewhat complex. It is a
884 series of query terms with an implicit OR operator between them. The
885 following terms are accepted:
886 regex A bare string is taken as a regular expression matching
888 the full account name. Thus, to report the current bal‐
889 ance for all assets and liabilities, you would use:
890 ledger bal asset liab
892 payee regex (@regex)
894 Query on the payee, rather than the account.
895 tag regex (%regex)
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 a 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() 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() 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 a 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