1LEDGER(1) BSD General Commands Manual LEDGER(1)
2
4 ledger — Command-line, double-entry account reporting tool
5
7 ledger [command] [options] [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 ledger.el Emacs 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 org Produce a journal file suitable for use in the Emacs org mode.
97 payees [report-query]
99 List all payees for postings matching the report-query.
100 pricemap
102 Produce a file which can be used to generate a graph with
103 graphviz showing the relationship of commodities in the ledger
104 file.
105 prices [report-query]
107 Report prices for all commodities in postings matching the
108 report-query. The prices are reported with the granularity of a
109 single day.
110 pricedb [report-query]
112 Report prices for all commodities in postings matching the
113 report-query. Prices are reported down to the second, using the
114 same format as the ~/.pricedb file.
115 print [report-query]
117 Print out the full transactions of any matching postings using
118 the same format as they would appear in a data file. This can
119 be used to extract subsets from a ledger file to transfer to
120 other files.
121 push [options]
123 In the REPL, push a set of command-line options, so that they
124 will apply to all subsequent reports.
125 pop In the REPL, pop any option settings that have been pushed.
127 register [report-query]
129 List all postings matching the report-query. This is one of the
130 most common commands, and can be used to provide a variety of
131 useful reports. Options most commonly used with this command
132 are:
133 --average (-A) Show the running average, rather than a running
135 total.
136 --current (-c) Don't show postings beyond the present day.
137 --exchange commodity (-X)
138 Render all values in the given commodity, if a
139 price conversion rate can be determined. Rates
140 are always displayed relative to the date of
141 the posting they are calculated for. This
142 means a register report is a historical value
143 report. For current values, it may be prefer‐
144 able to use the balance report.
145 --gain (-G) Show any gains (or losses) in commodity values
146 over time.
147 --head number Only show the top number postings.
148 --historical (-H)
149 Value commodities at the time of their acquisi‐
150 tion.
151 --invert Invert the value of amounts shown.
152 --market (-V) Show current market values for all amounts.
153 This is determined in a somewhat magical fash‐
154 ion. It is probably more straightforward to
155 use --exchange option.
156 --period time-period (-p)
157 Show postings only for the given time-period.
158 --related (-r) Show postings that are related to those that
159 would have been shown. It has the effect of
160 displaying the "other side" of the postings.
161 --sort value-expression (-S)
162 Sort postings by evaluating the given
163 value-expression. Note that a comma-separated
164 list of expressions is allowed, in which case
165 each sorting term is used in order to determine
166 the final ordering. For example, to search by
167 date and then amount, one would use:
168 ledger reg --sort 'date, amount'
169 --tail number Only show the last number postings.
170 --uncleared (-U)
171 Only show uncleared (i.e., recent) postings.
172 There are also several grouping options that can be useful:
174 --by-payee (-P) Group postings by common payee names.
176 --daily (-D) Group postings by day.
177 --weekly (-W) Group postings by week (starting on Sundays).
178 --start-of-week day
179 Set the start of each report grouped by week to
180 the given day.
181 --monthly (-M) Group postings by month.
182 --quarterly Group postings by fiscal quarter.
183 --yearly (-Y) Group postings by year.
184 --days-of-week Group postings by the day of the week on which
185 they took place.
186 --subtotal (-s) Group all postings together. This is very sim‐
187 ilar to the totals shown by the balance report.
188 The synonyms reg and r are also accepted.
190 server This command requires that Python support be active. If so, it
192 starts up an HTTP server listening for requests on port 9000.
193 This provides an alternate interface to creating and viewing
194 reports. Note that this is very much a work-in-progress, and
195 will not be fully functional until a later version.
196 select [sql-query]
198 List all postings matching the sql-query. This command allows
199 to generate SQL-like queries, e.g.:
200 ledger select date,amount from posts where
201 account=~/Income/
202 source Parse a journal file and checks it for errors. ledger will
204 return success if no errors are found.
205 stats [report-query]
207 Provide summary information about all the postings matching
208 report-query. It provides information such as:
209 · Time range of all matching postings
210 · Unique payees
211 · Unique accounts
212 · Postings total
213 · Uncleared postings
214 · Days since last posting
215 · Posts in the last 7 days
216 · Posts in the last 30 days
217 · Posts this month
218 xml [report-query]
220 Output data relating to the current report in XML format. It
221 includes all accounts and commodities involved in the report,
222 plus the postings and the transactions they are contained in.
223 See the manual for more information.
224
226 --abbrev-len INT
227 Set the minimum length an account can be abbreviated to if it
228 doesn't fit inside the account-width. If INT is zero, then the
229 account name will be truncated on the right. If INT is greater
230 than account-width then the account will be truncated on the
231 left, with no shortening of the account names in order to fit
232 into the desired width.
233 --account EXPR
235 Prepend EXPR to all accounts reported. That is, the option
236 --account "'Personal'" would tack Personal: and --account
237 "tag('VAT')" would tack the value of the VAT tag to the begin‐
238 ning of every account reported in a balance or register report.
239 --account-width INT
241 Set the width of the account column in the register report to
242 INT characters.
243 --actual (-L)
245 Report only real transactions, with no automated or virtual
246 transactions used.
247 --add-budget
249 Show only un-budgeted postings.
250 --amount EXPR (-t)
252 Apply the given value expression to the posting amount. Using
253 --amount EXPR you can apply an arbitrary transformation to the
254 postings.
255 --amount-data (-j)
257 On a register report print only the dates and amount of post‐
258 ings. Useful for graphing and spreadsheet applications.
259 --amount-width INT
261 Set the width in characters of the amount column in the register
262 report.
263 --anon Anonymize registry output, mostly for sending in bug reports.
265 --ansi Use color if the terminal supports it. Alias for --color
267 --args-only
269 Ignore init files and environment variables for the ledger run.
270 --auto-match
272 When generating a ledger transaction from a CSV file using the
273 convert command, automatically match an account from the Ledger
274 journal.
275 --aux-date
277 Show auxiliary dates for all calculations. Alias for
278 --effective
279 --average (-A)
281 Print average values over the number of transactions instead of
282 running totals.
283 --balance-format FMT
285 Specify the format to use for the balance report.
286 --base Reduce convertible commodities down the bottom of the conver‐
288 sion, e.g. display time in seconds.
289 --basis (-B)
291 Report the cost basis on all posting. Alias for --cost
292 --begin DATE (-b)
294 Specify the start DATE of all calculations. Transactions before
295 that date will be ignored.
296 --bold-if EXPR
298 Print the entire line in bold if the given value expression is
299 true.
300 --budget
302 Only display budgeted items. In a register report this displays
303 transaction in the budget, in a balance report this displays
304 accounts in the budget.
305 --budget-format FMT
307 Specify the format to use for the budget report.
308 --by-payee (-P)
310 Group postings in the register report by common payee names.
311 --check-payees
313 Enable strict and pedantic checking for payees as well as
314 accounts, commodities and tags.
315 --cleared (-C)
317 Display only cleared postings.
318 --cleared-format FMT
320 Specify the format to use for the cleared report
321 --collapse (-n)
323 Print only the top level accounts.
324 --collapse-if-zero
326 Collapse the account display only if it has a zero balance.
327 --color Use color if the terminal supports it. Alias for --ansi
329 --columns INT
331 Make the register report INT characters wide. By default ledger
332 will use all available columns in your terminal.
333 --cost Report the cost basis on all posting. Alias for --basis.
335 --count Direct ledger to report the number of items when appended to the
337 commodities, accounts or payees commands.
338 --csv-format FMT
340 Format csv report according to FMT.
341 --current (-c)
343 Shorthand for --limit 'date <= today'.
344 --daily (-D)
346 Shorthand for --period daily.
347 --date EXPR
349 Transform the date of the transaction using EXPR.
350 --date-format DATEFMT (-y)
352 Print dates using DATEFMT. Refer to strftime(3) for details on
353 the format string syntax.
354 --datetime-format DATETIMEFMT
356 Print datetimes using DATETIMEFMT. Refer to strftime(3) for
357 details on the format string syntax.
358 --date-width INT
360 Specify the width, in characters, of the date column in the
361 register report.
362 --day-break
364 Break up register report of timelog entries that span multiple
365 days by day.
366 --days-of-week
368 Group transactions by the days of the week. Alias for --dow.
369 --dc Display register or balance in debit/credit format If you use
371 --dc with either the register or balance commands, you will now
372 get separate columns for debits and credits.
373 --debug STR
375 If ledger has been built with debug options this will provide
376 extra data during the run.
377 --decimal-comma
379 Direct ledger to parse journals using the European standard
380 comma as decimal separator, vice a period.
381 --depth INT
383 Limit the depth of the account tree. In a balance report, for
384 example, --depth 2 will print balances only for accounts with
385 two levels, i.e. Expenses:Entertainment but not
386 Expenses:Entertainment:Dining. This is a display predicate,
387 which means it only affects display, not the total calculations.
388 --detail
390 Related to convert command. Synonym to --rich-data option.
391 --deviation
393 Report each posting's deviation from the average. It is only
394 meaningful in the register and prices reports.
395 --display EXPR (-d)
397 Display lines that satisfy the expression EXPR.
398 --display-amount EXPR
400 Apply a transformation to the displayed amount. This occurs
401 after calculations occur.
402 --display-total EXPR
404 Apply a transformation to the displayed total. This occurs
405 after calculations occur.
406 --dow Group transactions by the days of the week. Alias for
408 --days-of-week.
409 --download
411 Cause quotes to be automagically downloaded, as needed, by run‐
412 ning a script named getquote and expecting that script to return
413 a value understood by ledger. A sample implementation of a
414 getquote script, implemented in Perl, is provided in the distri‐
415 bution. Downloaded quote price are then appended to the price
416 database, usually specified using the environment variable
417 LEDGER_PRICE_DB.
418 --effective
420 Show auxiliary dates for all calculations. Alias for
421 --aux-date.
422 --empty (-E)
424 Include empty accounts in report.
425 --end DATE (-e)
427 Constrain the report so that transactions on or after DATE are
428 not considered.
429 --equity
431 Related to the equity command. Gives current account balances
432 in the form of a register report.
433 --exact Report beginning and ending of periods by the date of the first
435 and last posting occurring in that period.
436 --exchange COMMODITY [, COMMODITY, ...] (-X)
438 Display values in terms of the given COMMODITY. The latest
439 available price is used.
440 --explicit
442 Direct ledger to require pre-declarations for entities (such as
443 accounts, commodities and tags) rather than taking entities from
444 cleared transactions as defined.
445 --file FILE
447 Read journal data from FILE.
448 --first INT
450 Print the first INT entries. Opposite of --last INT. Alias for
451 --head.
452 --flat Force the full names of accounts to be used in the balance
454 report. The balance report will not use an indented tree.
455 --force-color
457 Output TTY color codes even if the TTY doesn't support them.
458 Useful for TTYs that don't advertise their capabilities cor‐
459 rectly.
460 --force-pager
462 Force ledger to paginate its output.
463 --forecast-while EXPR
465 Continue forecasting while VEXPR is true. Alias for --forecast.
466 --forecast-years INT
468 Forecast at most INT years into the future.
469 --format FMT (-F)
471 Use the given format string FMT to print output.
472 --gain (-G)
474 Report net gain or loss for commodities that have a price his‐
475 tory.
476 --generated
478 Include auto-generated postings (such as those from automated
479 transactions) in the report, in cases where you normally
480 wouldn't want them.
481 --group-by EXPR
483 Group transaction together in the register report. EXPR can be
484 anything, although most common would be payee or commodity. The
485 tag() function is also useful here.
486 --group-title-format FMT
488 Set the format for the headers that separate reports section of
489 a grouped report. Only has effect with a --group-by EXPR regis‐
490 ter report.
491 --head INT
493 Print the first INT entries. Opposite of --tail INT. Alias for
494 --first
495 --help Print this man page.
497 --immediate
499 Evaluate calculations immediately rather than lazily.
500 --import FILE
502 Import FILE as Python module.
503 --init-file FILE (-i)
505 Read FILE before any other ledger file. This file may not con‐
506 tain any postings, but it may contain option settings. To spec‐
507 ify options in the init file, use the same syntax as the com‐
508 mand-line, but put each option on its own line.
509 --inject STR
511 Use STR amounts in calculations. In case you know what amount a
512 transaction should be, but the actual transaction has the wrong
513 value you can use metadata STR to specify the expected amount.
514 --input-date-format DATEFMT
516 Specify the input date format for journal entries.
517 --invert
519 Change the sign of all reported values.
520 --last INT.
522 Report only the last INT entries. Opposite of --first INT.
523 Only useful on a register report. Alias for --tail.
524 --leeway INT (-Z)
526 Alias for --price-expr.
527 --limit EXPR (-l)
529 Limit postings in calculations.
530 --lot-dates
532 Report the date on which each commodity in a balance report was
533 purchased.
534 --lot-notes
536 Report the tag attached to each commodity in a balance report.
537 --lot-prices
539 Report the price at which each commodity in a balance report was
540 purchased.
541 --lots Report the date and price at which each commodity was purchased
543 in a balance report.
544 --lots-actual
546 Preserve the uniqueness of commodities so they aren't merged
547 during reporting without printing the lot annotations.
548 --market (-V)
550 Use the latest market value for all commodities.
551 --master-account STR
553 Prepend all account names with STR
554 --meta STR
556 In the register report, prepend the transaction with the value
557 of the given tag STR.
558 --meta-width INT
560 Specify the width of the Meta column used for the --meta TAG
561 options.
562 --monthly (-M)
564 Shorthand for --period monthly.
565 --no-aliases
567 Aliases are completely ignored.
568 --no-color
570 Suppress any color TTY output.
571 --no-pager
573 Disables the pager on TTY output.
574 --no-revalued
576 Stop ledger from showing <Revalued> postings.
577 --no-rounding
579 Don't output "<Adjustment>" postings. Note that this will cause
580 the running total to often not add up! Its main use is for
581 --amount-data (-j) and --total-data (-J) reports.
582 --no-titles
584 Suppress the output of group titles.
585 --no-total
587 Suppress printing the final total line in a balance report.
588 --now DATE
590 Use DATE as the current date. This affects the output when
591 using --period, --begin, --end, or --current to decide which
592 dates lie in the past or future.
593 --only EXPR
595 This is a postings predicate that applies after certain trans‐
596 forms have been executed, such as periodic gathering.
597 --options
599 Display the options in effect for this ledger invocation, along
600 with their values and the source of those values.
601 --output FILE (-o)
603 Redirect the output of ledger to FILE.
604 --pager STR
606 Use STR as the pager program.
607 --payee Sets a value expression for formatting the payee. In the
609 register report this prevents the second entry from having a
610 date and payee for each transaction.
611 --payee-width INT
613 Set the number of columns dedicated to the payee in the register
614 report to INT.
615 --pedantic
617 Accounts, tags or commodities not previously declared will cause
618 errors.
619 --pending
621 Use only postings that are marked pending.
622 --percent (-%)
624 Calculate the percentage value of each account in a balance
625 reports. Only works for account that have a single commodity.
626 --period PERIOD (-p)
628 Define a period expression that sets the time period during
629 which transactions are to be accounted. For a register report
630 only the transactions that satisfy the period expression with be
631 displayed. For a balance report only those transactions will be
632 accounted in the final balances.
633 --period-sort
635 Sort the posting within transactions using the given value
636 expression.
637 --permissive
639 Quiet balance assertions.
640 --pivot TAG
642 Produce a balance pivot report "around" the given TAG.
643 --plot-amount-format FMT
645 Define the output format for an amount data plot.
646 --plot-total-format FMT
648 Define the output format for a total data plot.
649 --prepend-format FMT
651 Prepend FMT to every line of the output.
652 --prepend-width INT
654 Reserve INT spaces at the beginning of each line of the output.
655 --price (-I)
657 Use the price of the commodity purchase for performing calcula‐
658 tions.
659 --price-db FILE
661 --price-exp STR (-Z)
663 Set the expected freshness of price quotes, in INT minutes.
664 That is, if the last known quote for any commodity is older than
665 this value, and if --download is being used, then the Internet
666 will be consulted again for a newer price. Otherwise, the old
667 price is still considered to be fresh enough. Alias for
668 --leeway.
669 --prices-format FMT
671 Set the format for the prices report.
672 --pricedb-format FMT
674 Set the format expected for the historical price file.
675 --primary-date
677 Show primary dates for all calculations. Alias for
678 --actual-dates
679 --quantity (-O)
681 Report commodity totals (this is the default).
682 --quarterly
684 Shorthand for --period quarterly.
685 --raw In the print report, show transactions using the exact same syn‐
687 tax as specified by the user in their data file. Don't do any
688 massaging or interpreting. Can be useful for minor cleanups,
689 like just aligning amounts.
690 --real (-R)
692 Account using only real transactions ignoring virtual and auto‐
693 matic transactions.
694 --recursive-aliases
696 Causes ledger to try to expand aliases recursively, i.e. try to
697 expand the result of an earlier expansion again, until no more
698 expansions apply.
699 --register-format FMT
701 Define the output format for the register report.
702 --related (-r)
704 In a register report show the related account. This is the
705 other side of the transaction.
706 --related-all
708 Show all postings in a transaction, similar to --related but
709 show both sides of each transaction.
710 --revalued
712 Report discrepancy in values for manual reports by inserting
713 <Revalued> postings. This is implied when using the --exchange
714 (-X) or --market (-V) option.
715 --revalued-only
717 Show only <Revalued> postings.
718 --revalued-total
720 Display the sum of the revalued postings as the running total,
721 which serves to show unrealized capital in a gain/losses report.
722 --rich-data
724 When generating a ledger transaction from a CSV file using the
725 convert command, add CSV, Imported, and UUID meta-data.
726 --seed INT
728 Set the random seed to INT for the generate command. Used as
729 part of development testing.
730 --script FILE
732 Execute a ledger script.
733 --sort EXPR (-S)
735 Sort the register report based on the value expression EXPR.
736 --sort-xacts
738 Sort the posting within transactions using the given value
739 expression.
740 --start-of-week STR
742 Use STR as the particular day of the week to start when using
743 the --weekly option. STR can be day names, their abbreviations
744 like "Mon", or the weekday number starting at 0 for Sunday.
745 --strict
747 Accounts, tags or commodities not previously declared will cause
748 warnings.
749 --subtotal (-s)
751 Report register as a single subtotal.
752 --tail INT
754 Report only the last INT entries. Only useful on a register
755 report. Alias for --last INT
756 --time-colon
758 Display the value for commodities based on seconds as hours and
759 minutes. Thus 8100s will be displayed as 2:15h instead of
760 2.25h.
761 --time-report
763 Add two columns to the balance report to show the earliest
764 checkin and checkout times for timelog entries.
765 --total EXPR (-T)
767 Define a value expression used to calculate the total in
768 reports.
769 --total-data (-J)
771 Show only dates and totals to format the output for plots.
772 --total-width INT
774 Set the width of the total field in the register report.
775 --trace INT
777 Enable tracing. The INT specifies the level of trace desired.
778 --truncate STR
780 Indicates how truncation should happen when the contents of col‐
781 umns exceed their width. Valid arguments for STR are leading,
782 middle, and trailing. The default is smarter than any of these
783 three, as it considers sub-names within the account name (that
784 style is called "abbreviate").
785 --unbudgeted
787 Show only un-budgeted postings.
788 --uncleared (-U)
790 Use only uncleared transactions in calculations and reports.
791 --unrealized
793 Show generated unrealized gain and loss accounts in the balance
794 report.
795 --unrealized-gains
797 Allow the user to specify what account name should be used for
798 unrealized gains. Defaults to Equity:Unrealized Gains. Often
799 set in one's ~/.ledgerrc file to change the default.
800 --unrealized-losses
802 Allow the user to specify what account name should be used for
803 unrealized losses. Defaults to Equity:Unrealized Losses. Often
804 set in one's ~/.ledgerrc file to change the default.
805 --unround
807 Perform all calculations without rounding and display results to
808 full precision.
809 --values
811 Show the values used by each tag when used in combination with
812 the tags command.
813 --value-expr EXPR
815 Set a global value expression annotation.
816 --verbose
818 Print detailed information on the execution of ledger.
819 --verify
821 Enable additional assertions during run-time. This causes a
822 significant slowdown. When combined with --debug CODE ledger
823 will produce memory trace information.
824 --verify-memory
826 Verify that every constructed object is properly destructed.
827 This is for debugging purposes only.
828 --version
830 Print version information and exit.
831 --weekly (-W)
833 Shorthand for --period weekly.
834 --wide (-w)
836 Assume 132 columns instead of the TTY width.
837 --yearly (-Y)
839 Shorthand for --period yearly.
840
842 Pre-commands are useful when you aren't sure how a command or option will
843 work. The difference between a pre-command and a regular command is that
844 pre-commands ignore the journal data file completely, nor is the user's
845 init file read.
846 args / query
848 Evaluate the given arguments and report how ledger interprets it
849 against the following model transaction:
850 2004/05/27 Book Store
852 ; This note applies to all postings. :SecondTag:
853 Expenses:Books 20 BOOK @ $10
854 ; Metadata: Some Value
855 ; Typed:: $100 + $200
856 ; :ExampleTag:
857 ; Here follows a note describing the posting.
858 Liabilities:MasterCard $-200.00
859 eval Evaluate the given value expression against the model transac‐
861 tion.
862 format Print details of how ledger uses the given formatting descrip‐
864 tion and apply it against a model transaction.
865 parse / expr
867 Print details of how ledger uses the given value expression
868 description and apply it against a model transaction.
869 generate
871 Randomly generates syntactically valid ledger data from a seed.
872 Used by the GenerateTests harness for development testing.
873 period Evaluate the given period and report how ledger interprets it.
875 template
877 Shows the insertion template that the xact command generates.
878 This is a debugging command.
879
881 The syntax for reporting queries can get somewhat complex. It is a
882 series of query terms with an implicit OR operator between them. The
883 following terms are accepted:
884 regex A bare string is taken as a regular expression matching
886 the full account name. Thus, to report the current bal‐
887 ance for all assets and liabilities, you would use:
888 ledger bal asset liab
890 payee regex (@regex)
892 Query on the payee, rather than the account.
893 tag regex (%regex)
895 note regex (=regex)
897 Query on anything found in an item's note.
898 code regex (#regex)
900 Query on the xact's optional code (which can be any string
901 the user wishes).
902 term and term Query terms are joined by an implicit OR operator. You
904 can change this to AND by using the and keyword. For
905 example, to show food expenditures occurring at Shakee's
906 Pizza, you could say:
907 ledger reg food and @Shakee
909 term or term When you wish to be more explicit, use the OR operator.
911 show
913 not term Reverse the logical meaning of the following term. This
915 can be used with parentheses to great effect:
916 ledger reg food and @Shakee and not dining
918 ( term ) If you wish to mix OR and AND operators, it is often help‐
920 ful to surround logical units with parentheses. NOTE:
921 Because of the way some shells interpret parentheses, you
922 should always escape them:
923 ledger bal \( assets or liab \) and not food
925
927 abs(value) Return the absolute value of the given value.
928 account Return the posting's account.
930 account_base Return the base account, i.e. everything after the last
932 account delimiter ':'.
933 actual Return true if the transaction is real, i.e not a auto‐
935 mated or virtual transaction, false otherwise.
936 amount Return the amount of the posting.
938 amount_expr Return the calculated amount of the posting according to
940 the --amount option.
941 ansify_if(value, color, bool)
943 Render the given value as a string, applying the proper
944 ANSI escape codes to display it in the given color if
945 bool is true. It typically checks the value of the
946 option --color, for example:
947 ansify_if(amount, blue, options.color)
948 beg_line Line number where entry for posting begins.
950 beg_pos Character position where entry for posting begins.
952 ceiling(value) Return the next integer of value toward +infinity.
954 cleared Return true if the posting was cleared, false otherwise.
956 code Return the transaction code, the string between the
958 parenthesis after the date.
959 commodity(value)
961 Return the commodity of value or the posting amount when
962 value was not specified.
963 date Return the date of the posting.
965 end_line Line number where entry for posting ends.
967 end_pos Character position where entry for posting ends.
969 floor(value) Return the next integer of value toward -infinity.
971 filename The name of the ledger data file from whence the posting
973 came.
974 format(string) Evaluate string as format just like the --format option.
976 format_date(date, format)
978 Return the date as a string using format. Refer to
979 strftime(3) for format string details.
980 format_datetime(datetime, format)
982 Return the datetime as a string using format. Refer to
983 strftime(3) for format string details.
984 get_at(seq, index)
986 Return value at index from seq. Used internally to con‐
987 struct different reports.
988 has_meta() Return true if the posting has metadata named tag, false
990 otherwise.
991 has_tag(tag) Return true if the posting has metadata named tag, false
993 otherwise.
994 is_seq(value) Return true if value is a sequence. Used internally.
996 join(value) Replace all newlines in value with \n.
998 justify(value, first_width, latter_width, right_justify, colorize)
1000 Right or left justify the string representing value.
1001 The width of the field in the first line is given by
1002 first_width. For subsequent lines the width is given by
1003 latter_width. If latter_width is -1, first_width is
1004 used for all lines. If right_justify is true then the
1005 field is right justified within the width of the field.
1006 If it is false, then the field is left justified and
1007 padded to the full width of the field. If colorize is
1008 true, then ledger will honor color settings.
1009 market(value, datetime)
1011 Return the price of value at datetime. Note that
1012 datetime must be surrounded by brackets in order to be
1013 parsed correctly, e.g. [2012/03/23].
1014 meta() Return the value of metadata named name.
1016 note Return the note for the posting.
1018 now Return the current datetime.
1020 options A variable that allows access to the values of the given
1022 command-line options using the long option names, e.g.
1023 to see whether --daily (-D) was given use option.daily.
1024 payee Return the payee of the posting.
1026 percent(value_a, value_b)
1028 Return the percentage of value_a in relation to value_b
1029 (used as 100%).
1030 pending Return true if the posting is marked as pending, false
1032 otherwise.
1033 percent(value_a, value_b)
1035 Return the percentage of value_a in relation to value_b.
1036 print(value) Print value to stdout. Used internally for debugging.
1038 quantity(value) Return the quantity of value for values that have a per-
1040 unit cost.
1041 quoted(expression)
1043 Surround expression with double-quotes.
1044 real Return true if the transaction is real, i.e not a auto‐
1046 mated or virtual transaction, false otherwise.
1047 roundto(value, n)
1049 Return value rounded to n digits. Does not affect for‐
1050 matting.
1051 should_bold Return true if expression given to --bold-if evaluates
1053 to true. Internal use only!
1054 scrub(value) Clean value using various transformations such as round,
1056 stripping value annotations, and more.
1057 strip(value) Strip value annotation from value.
1059 tag(name) Return the value of tag named name.
1061 to_amount(value)
1063 Convert value to an amount. Internal use only!
1064 to_balance(value)
1066 Convert value to a balance. Internal use only!
1067 to_boolean(value)
1069 Convert value to a boolean. Internal use only!
1070 to_date(value) Convert value to a date. Internal use only!
1072 to_datetime(value)
1074 Convert value to a datetime. Internal use only!
1075 to_int(value) Return the integer value for value.
1077 to_mask(value) Convert value to a mask. Internal use only!
1079 to_sequence(value)
1081 Convert value to a sequence. Internal use only!
1082 to_string(value)
1084 Convert value to a character string.
1085 today Return today's date.
1087 total Return the total of the posting.
1089 total_expr Return the calculated total of the posting according to
1091 the --total option.
1092 trim(value) Trim leading and trailing whitespace from value.
1094 truncated(string, total_len, account_len)
1096 Truncate string to total_len ensuring that each account
1097 is at least account_len long.
1098 virtual Return true if the transaction is virtual, e.g auto‐
1100 mated, false otherwise.
1101
1103 In addition to the regular reporting commands, ledger also accepts sev‐
1104 eral debug commands:
1105 args [report-query]
1107 Display complete analysis of how ledger interpreted the given
1108 report-query. Useful if you want to understand how report
1109 queries are translated into value expressions.
1110 eval [value-expression]
1112 Evaluate the given value-expression and prints the result. For
1113 more on value expressions, see the section EXPRESSIONS.
1114 format [format-string]
1116 Display an analysis of how format-string was parsed, and what it
1117 would look like applied to a sample transaction. For more on
1118 format strings, see the section FORMATS.
1119 generate
1121 Generate 50 randomly composed yet valid ledger transactions.
1122 parse [value-expression]
1124 Parse the given value-expression and display an analysis of the
1125 expression tree and its evaluated value. For more on value
1126 expressions, see the section EXPRESSIONS.
1127 python [file]
1129 Invoke a Python interpreter to read the given file. What is
1130 special about this is that the ledger module is builtin, not
1131 read from disk, so it doesn't require ledger to be installed
1132 anywhere, or the shared library variants to be built.
1133 reload Reload all data files for the current session immediately. Can
1135 only be used in the REPL.
1136 template [draft-template]
1138 Display information about how draft-template was parsed. See
1139 the section on DRAFTS.
1140
1142 Every option to ledger may be set using an environment variable if the
1143 option has a long name. For example setting the environment variable
1144 LEDGER_DATE_FORMAT="%d.%m.%Y' will have the same effect as specifying
1145 --date-format '%d.%m.%Y' on the command-line. Options on the command-
1146 line always take precedence over environment variable settings, however.
1147
1149 ~/.ledgerrc
1150 Your personal ledger initializations.
1151
1153 beancount(1), hledger(1)
1154
1156 John Wiegley ⟨johnw@newartisans.com⟩
1157BSD March 23, 2012 BSD