1LEDGER(1)                 BSD General Commands Manual                LEDGER(1)
2

NAME

4     ledger — Command-line, double-entry account reporting tool
5

SYNOPSIS

7     ledger [options] [command] [arguments]
8

DESCRIPTION

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

COMMANDS

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
23     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
26     The following is a complete list of accepted reporting commands:
27
28     accounts [report-query]
29               List all accounts for postings that match the report-query.
30
31     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
47              The synonyms bal and b are also accepted.
48
49     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
57     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
64     commodities [report-query]
65              List all commodities for postings matching the report-query.
66
67     convert  Reads data from a CSV (comma-separated values) file and gener‐
68              ates ledger transactions.
69
70     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
75     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
82              The synonym xact is also accepted.
83
84     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
89     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
96     payees [report-query]
97              List all payees for postings matching the report-query.
98
99     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
104     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
109     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
114     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
120     push [options]
121              In the REPL, push a set of command-line options, so that they
122              will apply to all subsequent reports.
123
124     pop      In the REPL, pop any option settings that have been pushed.
125
126     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
132              --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
175              There are also several grouping options that can be useful:
176
177              --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
191              The synonyms reg and r are also accepted.
192
193     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
199     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
205     source   Parse a journal file and checks it for errors.  ledger will
206              return success if no errors are found.
207
208     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
221     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

OPTIONS

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
236     --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
242     --account-width INT
243              Set the width of the account column in the register report to
244              INT characters.
245
246     --actual (-L)
247              Report only real transactions, with no automated or virtual
248              transactions used.
249
250     --add-budget
251              Show only un-budgeted postings.
252
253     --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
258     --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
262     --amount-width INT
263              Set the width in characters of the amount column in the register
264              report.
265
266     --anon   Anonymize registry output, mostly for sending in bug reports.
267
268     --ansi   Use color if the terminal supports it.  Alias for --color
269
270     --args-only
271              Ignore init files and environment variables for the ledger run.
272
273     --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
278     --aux-date
279              Show auxiliary dates for all calculations.  Alias for
280              --effective
281
282     --average (-A)
283              Print average values over the number of transactions instead of
284              running totals.
285
286     --average-lot-prices
287              Report the average price at which each commodity was purchased
288              in a balance report.
289
290     --balance-format FMT
291              Specify the format to use for the balance report.
292
293     --base   Reduce convertible commodities down the bottom of the conver‐
294              sion, e.g.  display time in seconds.
295
296     --basis (-B)
297              Report the cost basis on all posting.  Alias for --cost
298
299     --begin DATE (-b)
300              Specify the start DATE of all calculations.  Transactions before
301              that date will be ignored.
302
303     --bold-if EXPR
304              Print the entire line in bold if the given value expression is
305              true.
306
307     --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
312     --budget-format FMT
313              Specify the format to use for the budget report.
314
315     --by-payee (-P)
316              Group postings in the register report by common payee names.
317
318     --check-payees
319              Enable strict and pedantic checking for payees as well as
320              accounts, commodities and tags.
321
322     --cleared (-C)
323              Display only cleared postings.
324
325     --cleared-format FMT
326              Specify the format to use for the cleared report
327
328     --collapse (-n)
329              Print only the top level accounts.
330
331     --collapse-if-zero
332              Collapse the account display only if it has a zero balance.
333
334     --color  Use color if the terminal supports it.  Alias for --ansi
335
336     --columns INT
337              Make the register report INT characters wide.  By default ledger
338              will use all available columns in your terminal.
339
340     --cost   Report the cost basis on all posting.  Alias for --basis.
341
342     --count  Direct ledger to report the number of items when appended to the
343              commodities, accounts or payees commands.
344
345     --csv-format FMT
346              Format csv report according to FMT.
347
348     --current (-c)
349              Shorthand for --limit 'date <= today'.
350
351     --daily (-D)
352              Shorthand for --period daily.
353
354     --date EXPR
355              Transform the date of the transaction using EXPR.
356
357     --date-format DATEFMT (-y)
358              Print dates using DATEFMT.  Refer to strftime(3) for details on
359              the format string syntax.
360
361     --datetime-format DATETIMEFMT
362              Print datetimes using DATETIMEFMT.  Refer to strftime(3) for
363              details on the format string syntax.
364
365     --date-width INT
366              Specify the width, in characters, of the date column in the
367              register report.
368
369     --day-break
370              Break up register report of timelog entries that span multiple
371              days by day.
372
373     --days-of-week
374              Group transactions by the days of the week.  Alias for --dow.
375
376     --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
380     --debug STR
381              If ledger has been built with debug options this will provide
382              extra data during the run.
383
384     --decimal-comma
385              Direct ledger to parse journals using the European standard
386              comma as decimal separator, vice a period.
387
388     --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
395     --detail
396              Related to convert command. Synonym to --rich-data option.
397
398     --deviation
399              Report each posting's deviation from the average.  It is only
400              meaningful in the register and prices reports.
401
402     --display EXPR (-d)
403              Display lines that satisfy the expression EXPR.
404
405     --display-amount EXPR
406              Apply a transformation to the displayed amount.  This occurs
407              after calculations occur.
408
409     --display-total EXPR
410              Apply a transformation to the displayed total.  This occurs
411              after calculations occur.
412
413     --dow    Group transactions by the days of the week.  Alias for
414              --days-of-week.
415
416     --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
425     --effective
426              Show auxiliary dates for all calculations.  Alias for
427              --aux-date.
428
429     --empty (-E)
430              Include empty accounts in report.
431
432     --end DATE (-e)
433              Constrain the report so that transactions on or after DATE are
434              not considered.
435
436     --equity
437              Related to the equity command.  Gives current account balances
438              in the form of a register report.
439
440     --exact  Report beginning and ending of periods by the date of the first
441              and last posting occurring in that period.
442
443     --exchange COMMODITY [, COMMODITY, ...] (-X)
444              Display values in terms of the given COMMODITY.  The latest
445              available price is used.
446
447     --file FILE (-f)
448              Read journal data from FILE.
449
450     --first INT
451              Print the first INT entries.  Opposite of --last INT.  Alias for
452              --head.
453
454     --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
457     --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
462     --force-pager
463              Force ledger to paginate its output.
464
465     --forecast-while EXPR
466              Continue forecasting while VEXPR is true.  Alias for --forecast.
467
468     --forecast-years INT
469              Forecast at most INT years into the future.
470
471     --format FMT (-F)
472              Use the given format string FMT to print output.
473
474     --gain (-G)
475              Report net gain or loss for commodities that have a price his‐
476              tory.
477
478     --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
483     --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
488     --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
493     --head INT
494              Print the first INT entries.  Opposite of --tail INT.  Alias for
495              --first
496
497     --help   Print this man page.
498
499     --immediate
500              Evaluate calculations immediately rather than lazily.
501
502     --import FILE
503              Import FILE as Python module.
504
505     --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
511     --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
516     --input-date-format DATEFMT
517              Specify the input date format for journal entries.
518
519     --invert
520              Change the sign of all reported values.
521
522     --last INT.
523              Report only the last INT entries.  Opposite of --first INT.
524              Only useful on a register report.  Alias for --tail.
525
526     --leeway INT (-Z)
527              Alias for --price-expr.
528
529     --limit EXPR (-l)
530              Limit postings in calculations.
531
532     --lot-dates
533              Report the date on which each commodity in a balance report was
534              purchased.
535
536     --lot-notes
537              Report the tag attached to each commodity in a balance report.
538
539     --lot-prices
540              Report the price at which each commodity in a balance report was
541              purchased.
542
543     --lots   Report the date and price at which each commodity was purchased
544              in a balance report.
545
546     --lots-actual
547              Preserve the uniqueness of commodities so they aren't merged
548              during reporting without printing the lot annotations.
549
550     --market (-V)
551              Use the latest market value for all commodities.
552
553     --master-account STR
554              Prepend all account names with STR
555
556     --meta STR
557              In the register report, prepend the transaction with the value
558              of the given tag STR.
559
560     --meta-width INT
561              Specify the width of the Meta column used for the --meta TAG
562              options.
563
564     --monthly (-M)
565              Shorthand for --period monthly.
566
567     --no-aliases
568              Aliases are completely ignored.
569
570     --no-color
571              Suppress any color TTY output.
572
573     --no-pager
574              Disables the pager on TTY output.
575
576     --no-revalued
577              Stop ledger from showing <Revalued> postings.
578
579     --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
584     --no-titles
585              Suppress the output of group titles.
586
587     --no-total
588              Suppress printing the final total line in a balance report.
589
590     --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
595     --only EXPR
596              This is a postings predicate that applies after certain trans‐
597              forms have been executed, such as periodic gathering.
598
599     --options
600              Display the options in effect for this ledger invocation, along
601              with their values and the source of those values.
602
603     --output FILE (-o)
604              Redirect the output of ledger to FILE.
605
606     --pager STR
607              Use STR as the pager program.
608
609     --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
613     --payee-width INT
614              Set the number of columns dedicated to the payee in the register
615              report to INT.
616
617     --pedantic
618              Accounts, tags or commodities not previously declared will cause
619              errors.
620
621     --pending
622              Use only postings that are marked pending.
623
624     --percent (-%)
625              Calculate the percentage value of each account in a balance
626              reports.  Only works for account that have a single commodity.
627
628     --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
635     --period-sort
636              Sort the posting within transactions using the given value
637              expression.
638
639     --permissive
640              Quiet balance assertions.
641
642     --pivot TAG
643              Produce a balance pivot report "around" the given TAG.
644
645     --plot-amount-format FMT
646              Define the output format for an amount data plot.
647
648     --plot-total-format FMT
649              Define the output format for a total data plot.
650
651     --prepend-format FMT
652              Prepend FMT to every line of the output.
653
654     --prepend-width INT
655              Reserve INT spaces at the beginning of each line of the output.
656
657     --price (-I)
658              Use the price of the commodity purchase for performing calcula‐
659              tions.
660
661     --price-db FILE
662
663     --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
671     --prices-format FMT
672              Set the format for the prices report.
673
674     --pricedb-format FMT
675              Set the format expected for the historical price file.
676
677     --primary-date
678              Show primary dates for all calculations.  Alias for
679              --actual-dates
680
681     --quantity (-O)
682              Report commodity totals (this is the default).
683
684     --quarterly
685              Shorthand for --period quarterly.
686
687     --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
692     --real (-R)
693              Account using only real transactions ignoring virtual and auto‐
694              matic transactions.
695
696     --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
701     --register-format FMT
702              Define the output format for the register report.
703
704     --related (-r)
705              In a register report show the related account.  This is the
706              other side of the transaction.
707
708     --related-all
709              Show all postings in a transaction, similar to --related but
710              show both sides of each transaction.
711
712     --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
717     --revalued-only
718              Show only <Revalued> postings.
719
720     --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
724     --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
728     --seed INT
729              Set the random seed to INT for the generate command.  Used as
730              part of development testing.
731
732     --script FILE
733              Execute a ledger script.
734
735     --sort EXPR (-S)
736              Sort the register report based on the value expression EXPR.
737
738     --sort-xacts
739              Sort the posting within transactions using the given value
740              expression.
741
742     --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
747     --strict
748              Accounts, tags or commodities not previously declared will cause
749              warnings.
750
751     --subtotal (-s)
752              Report register as a single subtotal.
753
754     --tail INT
755              Report only the last INT entries.  Only useful on a register
756              report.  Alias for --last INT
757
758     --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
763     --time-report
764              Add two columns to the balance report to show the earliest
765              checkin and checkout times for timelog entries.
766
767     --total EXPR (-T)
768              Define a value expression used to calculate the total in
769              reports.
770
771     --total-data (-J)
772              Show only dates and totals to format the output for plots.
773
774     --total-width INT
775              Set the width of the total field in the register report.
776
777     --trace INT
778              Enable tracing.  The INT specifies the level of trace desired.
779
780     --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
787     --unbudgeted
788              Show only un-budgeted postings.
789
790     --uncleared (-U)
791              Use only uncleared transactions in calculations and reports.
792
793     --unrealized
794              Show generated unrealized gain and loss accounts in the balance
795              report.
796
797     --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
802     --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
807     --unround
808              Perform all calculations without rounding and display results to
809              full precision.
810
811     --values
812              Show the values used by each tag when used in combination with
813              the tags command.
814
815     --value-expr EXPR
816              Set a global value expression annotation.
817
818     --verbose
819              Print detailed information on the execution of ledger.
820
821     --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
826     --verify-memory
827              Verify that every constructed object is properly destructed.
828              This is for debugging purposes only.
829
830     --version
831              Print version information and exit.
832
833     --weekly (-W)
834              Shorthand for --period weekly.
835
836     --wide (-w)
837              Assume 132 columns instead of the TTY width.
838
839     --yearly (-Y)
840              Shorthand for --period yearly.
841

PRE-COMMANDS

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
848     args / query
849              Evaluate the given arguments and report how ledger interprets it
850              against the following model transaction:
851
852                    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
861     eval     Evaluate the given value expression against the model transac‐
862              tion.
863
864     format   Print details of how ledger uses the given formatting descrip‐
865              tion and apply it against a model transaction.
866
867     parse / expr
868              Print details of how ledger uses the given value expression
869              description and apply it against a model transaction.
870
871     generate
872              Randomly generates syntactically valid ledger data from a seed.
873              Used by the GenerateTests harness for development testing.
874
875     period   Evaluate the given period and report how ledger interprets it.
876
877     template
878              Shows the insertion template that the xact command generates.
879              This is a debugging command.
880

QUERIES

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
886     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
890                          ledger bal asset liab
891
892     payee regex (@regex)
893                    Query on the payee, rather than the account.
894
895     tag regex (%regex)
896                    Query on tags.
897
898     note regex (=regex)
899                    Query on anything found in an item's note.
900
901     code regex (#regex)
902                    Query on the xact's optional code (which can be any string
903                    the user wishes).
904
905     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
910                          ledger reg food and @Shakee
911
912     term or term   When you wish to be more explicit, use the OR operator.
913
914     show
915
916     not term       Reverse the logical meaning of the following term.  This
917                    can be used with parentheses to great effect:
918
919                          ledger reg food and @Shakee and not dining
920
921     ( 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
926                          ledger bal \( assets or liab \) and not food
927

EXPRESSIONS

929     abs(value)       Return the absolute value of the given value.
930
931     account          Return the posting's account.
932
933     account_base     Return the base account, i.e. everything after the last
934                      account delimiter ':'.
935
936     actual           Return true if the transaction is real, i.e not an auto‐
937                      mated or virtual transaction, false otherwise.
938
939     amount           Return the amount of the posting.
940
941     amount_expr      Return the calculated amount of the posting according to
942                      the --amount option.
943
944     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
951     beg_line         Line number where entry for posting begins.
952
953     beg_pos          Character position where entry for posting begins.
954
955     ceiling(value)   Return the next integer of value toward +infinity.
956
957     cleared          Return true if the posting was cleared, false otherwise.
958
959     code             Return the transaction code, the string between the
960                      parenthesis after the date.
961
962     commodity(value)
963                      Return the commodity of value or the posting amount when
964                      value was not specified.
965
966     date             Return the date of the posting.
967
968     end_line         Line number where entry for posting ends.
969
970     end_pos          Character position where entry for posting ends.
971
972     floor(value)     Return the next integer of value toward -infinity.
973
974     filename         The name of the ledger data file from whence the posting
975                      came.
976
977     format(string)   Evaluate string as format just like the --format option.
978
979     format_date(date, format)
980                      Return the date as a string using format.  Refer to
981                      strftime(3) for format string details.
982
983     format_datetime(datetime, format)
984                      Return the datetime as a string using format.  Refer to
985                      strftime(3) for format string details.
986
987     get_at(seq, index)
988                      Return value at index from seq.  Used internally to con‐
989                      struct different reports.
990
991     has_meta(tag)    Return true if the posting has metadata named tag, false
992                      otherwise.
993
994     has_tag(tag)     Return true if the posting has metadata named tag, false
995                      otherwise.
996
997     is_seq(value)    Return true if value is a sequence. Used internally.
998
999     join(value)      Replace all newlines in value with \n.
1000
1001     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
1012     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
1017     meta(name)       Return the value of metadata named name.
1018
1019     note             Return the note for the posting.
1020
1021     now              Return the current datetime.
1022
1023     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
1027     payee            Return the payee of the posting.
1028
1029     percent(value_a, value_b)
1030                      Return the percentage of value_a in relation to value_b
1031                      (used as 100%).
1032
1033     pending          Return true if the posting is marked as pending, false
1034                      otherwise.
1035
1036     percent(value_a, value_b)
1037                      Return the percentage of value_a in relation to value_b.
1038
1039     print(value)     Print value to stdout.  Used internally for debugging.
1040
1041     quantity(value)  Return the quantity of value for values that have a per-
1042                      unit cost.
1043
1044     quoted(expression)
1045                      Surround expression with double-quotes.
1046
1047     quoted_rfc4180(expression)
1048                      Surround expression with double-quotes, compatible with
1049                      rfc 4180.
1050
1051     real             Return true if the transaction is real, i.e not an auto‐
1052                      mated or virtual transaction, false otherwise.
1053
1054     roundto(value, n)
1055                      Return value rounded to n digits.  Does not affect for‐
1056                      matting.
1057
1058     should_bold      Return true if expression given to --bold-if evaluates
1059                      to true.  Internal use only!
1060
1061     scrub(value)     Clean value using various transformations such as round,
1062                      stripping value annotations, and more.
1063
1064     strip(value)     Strip value annotation from value.
1065
1066     tag(name)        Return the value of tag named name.
1067
1068     to_amount(value)
1069                      Convert value to an amount.  Internal use only!
1070
1071     to_balance(value)
1072                      Convert value to a balance.  Internal use only!
1073
1074     to_boolean(value)
1075                      Convert value to a boolean.  Internal use only!
1076
1077     to_date(value)   Convert value to a date.  Internal use only!
1078
1079     to_datetime(value)
1080                      Convert value to a datetime.  Internal use only!
1081
1082     to_int(value)    Return the integer value for value.
1083
1084     to_mask(value)   Convert value to a mask.  Internal use only!
1085
1086     to_sequence(value)
1087                      Convert value to a sequence.  Internal use only!
1088
1089     to_string(value)
1090                      Convert value to a character string.
1091
1092     today            Return today's date.
1093
1094     total            Return the total of the posting.
1095
1096     total_expr       Return the calculated total of the posting according to
1097                      the --total option.
1098
1099     trim(value)      Trim leading and trailing whitespace from value.
1100
1101     truncated(string, total_len, account_len)
1102                      Truncate string to total_len ensuring that each account
1103                      is at least account_len long.
1104
1105     virtual          Return true if the transaction is virtual, e.g auto‐
1106                      mated, false otherwise.
1107

DEBUG COMMANDS

1109     In addition to the regular reporting commands, ledger also accepts sev‐
1110     eral debug commands:
1111
1112     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
1117     eval [value-expression]
1118              Evaluate the given value-expression and prints the result.  For
1119              more on value expressions, see the section EXPRESSIONS.
1120
1121     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
1126     generate
1127              Generate 50 randomly composed yet valid ledger transactions.
1128
1129     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
1134     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
1140     reload   Reload all data files for the current session immediately.  Can
1141              only be used in the REPL.
1142
1143     template [draft-template]
1144              Display information about how draft-template was parsed.  See
1145              the section on DRAFTS.
1146

ENVIRONMENT

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

FILES

1155     ~/.ledgerrc
1156              Your personal ledger initializations.
1157

SEE ALSO

1159     beancount(1), hledger(1)
1160
1161     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

AUTHORS

1167     John Wiegley ⟨johnw@newartisans.com⟩
1168
1169BSD                             March 15, 2019                             BSD
Impressum