1hledger(1) hledger User Manuals hledger(1)
3
7 hledger - a command-line accounting tool
8
10 hledger [-f FILE] COMMAND [OPTIONS] [ARGS]
11 hledger [-f FILE] ADDONCMD -- [OPTIONS] [ARGS]
12 hledger
13
15 hledger is a cross-platform program for tracking money, time, or any
16 other commodity, using double-entry accounting and a simple, editable
17 file format. hledger is inspired by and largely compatible with
18 ledger(1).
19 Tested on unix, mac, windows, hledger aims to be a reliable, practical
20 tool for daily use.
21 This is hledger's command-line interface (there are also curses and web
23 interfaces). Its basic function is to read a plain text file describ‐
24 ing financial transactions (in accounting terms, a general journal) and
25 print useful reports on standard output, or export them as CSV.
26 hledger can also read some other file formats such as CSV files, trans‐
27 lating them to journal format. Additionally, hledger lists other
28 hledger-* executables found in the user's $PATH and can invoke them as
29 subcommands.
30 hledger reads data from one or more files in hledger journal, time‐
32 clock, timedot, or CSV format specified with -f, or $LEDGER_FILE, or
33 $HOME/.hledger.journal (on windows, perhaps
34 C:/Users/USER/.hledger.journal). If using $LEDGER_FILE, note this must
35 be a real environment variable, not a shell variable. You can specify
36 standard input with -f-.
37 Transactions are dated movements of money between two (or more) named
39 accounts, and are recorded with journal entries like this:
40 2015/10/16 bought food
42 expenses:food $10
43 assets:cash
44 For more about this format, see hledger_journal(5).
46 Most users use a text editor to edit the journal, usually with an edi‐
48 tor mode such as ledger-mode for added convenience. hledger's interac‐
49 tive add command is another way to record new transactions. hledger
50 never changes existing transactions.
51 To get started, you can either save some entries like the above in
53 ~/.hledger.journal, or run hledger add and follow the prompts. Then
54 try some commands like hledger print or hledger balance. Run hledger
55 with no arguments for a list of commands.
56
58 Two simple transactions in hledger journal format:
59 2015/9/30 gift received
61 assets:cash $20
62 income:gifts
63 2015/10/16 farmers market
65 expenses:food $10
66 assets:cash
67 Some basic reports:
69 $ hledger print
71 2015/09/30 gift received
72 assets:cash $20
73 income:gifts $-20
74 2015/10/16 farmers market
76 expenses:food $10
77 assets:cash $-10
78 $ hledger accounts --tree
80 assets
81 cash
82 expenses
83 food
84 income
85 gifts
86 $ hledger balance
88 $10 assets:cash
89 $10 expenses:food
90 $-20 income:gifts
91 --------------------
92 0
93 $ hledger register cash
95 2015/09/30 gift received assets:cash $20 $20
96 2015/10/16 farmers market assets:cash $-10 $10
97 More commands:
99 $ hledger # show available commands
101 $ hledger add # add more transactions to the journal file
102 $ hledger balance # all accounts with aggregated balances
103 $ hledger balance --help # show detailed help for balance command
104 $ hledger balance --depth 1 # only top-level accounts
105 $ hledger register # show account postings, with running total
106 $ hledger reg income # show postings to/from income accounts
107 $ hledger reg 'assets:some bank:checking' # show postings to/from this checking account
108 $ hledger print desc:shop # show transactions with shop in the description
109 $ hledger activity -W # show transaction counts per week as a bar chart
110
112 General options
113 To see general usage help, including general options which are sup‐
114 ported by most hledger commands, run hledger -h.
115 General help options:
117 -h --help
119 show general usage (or after COMMAND, command usage)
120 --version
122 show version
123 --debug[=N]
125 show debug output (levels 1-9, default: 1)
126 General input options:
128 -f FILE --file=FILE
130 use a different input file. For stdin, use - (default:
131 $LEDGER_FILE or $HOME/.hledger.journal)
132 --rules-file=RULESFILE
134 Conversion rules file to use when reading CSV (default:
135 FILE.rules)
136 --separator=CHAR
138 Field separator to expect when reading CSV (default: ',')
139 --alias=OLD=NEW
141 rename accounts named OLD to NEW
142 --anon anonymize accounts and payees
144 --pivot FIELDNAME
146 use some other field or tag for the account name
147 -I --ignore-assertions
149 ignore any failing balance assertions
150 General reporting options:
152 -b --begin=DATE
154 include postings/txns on or after this date
155 -e --end=DATE
157 include postings/txns before this date
158 -D --daily
160 multiperiod/multicolumn report by day
161 -W --weekly
163 multiperiod/multicolumn report by week
164 -M --monthly
166 multiperiod/multicolumn report by month
167 -Q --quarterly
169 multiperiod/multicolumn report by quarter
170 -Y --yearly
172 multiperiod/multicolumn report by year
173 -p --period=PERIODEXP
175 set start date, end date, and/or reporting interval all at once
176 using period expressions syntax (overrides the flags above)
177 --date2
179 match the secondary date instead (see command help for other
180 effects)
181 -U --unmarked
183 include only unmarked postings/txns (can combine with -P or -C)
184 -P --pending
186 include only pending postings/txns
187 -C --cleared
189 include only cleared postings/txns
190 -R --real
192 include only non-virtual postings
193 -NUM --depth=NUM
195 hide/aggregate accounts or postings more than NUM levels deep
196 -E --empty
198 show items with zero amount, normally hidden (and vice-versa in
199 hledger-ui/hledger-web)
200 -B --cost
202 convert amounts to their cost at transaction time (using the
203 transaction price, if any)
204 -V --value
206 convert amounts to their market value on the report end date
207 (using the most recent applicable market price, if any)
208 --auto apply automated posting rules to modify transactions.
210 --forecast
212 apply periodic transaction rules to generate future transac‐
213 tions, to 6 months from now or report end date.
214 When a reporting option appears more than once in the command line, the
216 last one takes precedence.
217 Some reporting options can also be written as query arguments.
219 Command options
221 To see options for a particular command, including command-specific
222 options, run: hledger COMMAND -h.
223 Command-specific options must be written after the command name, eg:
225 hledger print -x.
226 Additionally, if the command is an addon, you may need to put its
228 options after a double-hyphen, eg: hledger ui -- --watch. Or, you can
229 run the addon executable directly: hledger-ui --watch.
230 Command arguments
232 Most hledger commands accept arguments after the command name, which
233 are often a query, filtering the data in some way.
234 Argument files
236 You can save a set of command line options/arguments in a file, one per
237 line, and then reuse them by writing @FILENAME in a command line. To
238 prevent this expansion of @-arguments, precede them with a -- argument.
239 For more, see Save frequently used options.
240 Special characters in arguments and queries
242 In shell command lines, option and argument values which contain "prob‐
243 lematic" characters, ie spaces, and also characters significant to your
244 shell such as <, >, (, ), | and $, should be escaped by enclosing them
245 in quotes or by writing backslashes before the characters. Eg:
246 hledger register -p 'last year' "accounts receivable (receiv‐
248 able|payable)" amt:\>100.
249 More escaping
251 Characters significant both to the shell and in regular expressions may
252 need one extra level of escaping. These include parentheses, the pipe
253 symbol and the dollar sign. Eg, to match the dollar symbol, bash users
254 should do:
255 hledger balance cur:'\$'
257 or:
259 hledger balance cur:\\$
261 Even more escaping
263 When hledger runs an addon executable (eg you type hledger ui, hledger
264 runs hledger-ui), it de-escapes command-line options and arguments
265 once, so you might need to triple-escape. Eg in bash, running the ui
266 command and matching the dollar sign, it's:
267 hledger ui cur:'\\$'
269 or:
271 hledger ui cur:\\\\$
273 If you asked why four slashes above, this may help:
275 unescaped: $
277 escaped: \$
278 double-escaped: \\$
279 triple-escaped: \\\\$
280 (The number of backslashes in fish shell is left as an exercise for the
282 reader.)
283 You can always avoid the extra escaping for addons by running the addon
285 directly:
286 hledger-ui cur:\\$
288 Less escaping
290 Inside an argument file, or in the search field of hledger-ui or
291 hledger-web, or at a GHCI prompt, you need one less level of escaping
292 than at the command line. And backslashes may work better than quotes.
293 Eg:
294 ghci> :main balance cur:\$
296 Command line tips
298 If in doubt, keep things simple:
299 · write options after the command (hledger CMD -OPTIONS ARGS)
301 · run add-on executables directly (hledger-ui -OPTIONS ARGS)
303 · enclose problematic args in single quotes
305 · if needed, also add a backslash to escape regexp metacharacters
307 To find out exactly how a command line is being parsed, add --debug=2
309 to troubleshoot.
310 Unicode characters
312 hledger is expected to handle unicode (non-ascii) characters, but this
313 requires a well-configured environment.
314 To handle unicode characters in the command line or input data, a sys‐
316 tem locale that can decode them must be configured (POSIX's default C
317 locale will not work). Eg in bash, you could do:
318 export LANG=en_US.UTF-8
320 See Troubleshooting for more about this.
322 Unicode characters should appear correctly in hledger's output. For
324 the hledger and hledger-ui tools, this requires that
325 · your terminal supports unicode
327 · the terminal's font includes the required unicode glyphs
329 · the terminal is configured to display "wide" characters as double
331 width (otherwise report alignment will be off)
332 Input files
334 hledger reads transactions from a data file (and the add command writes
335 to it). By default this file is $HOME/.hledger.journal (or on Windows,
336 something like C:/Users/USER/.hledger.journal). You can override this
337 with the $LEDGER_FILE environment variable:
338 $ setenv LEDGER_FILE ~/finance/2016.journal
340 $ hledger stats
341 or with the -f/--file option:
343 $ hledger -f /some/file stats
345 The file name - (hyphen) means standard input:
347 $ cat some.journal | hledger -f-
349 Usually the data file is in hledger's journal format, but it can also
351 be one of several other formats, listed below. hledger detects the
352 format automatically based on the file extension, or if that is not
353 recognised, by trying each built-in "reader" in turn:
354 Reader: Reads: Used for file extensions:
356 ─────────────────────────────────────────────────────────────────────────────
357 journal hledger's journal format, also .journal .j .hledger
358 some Ledger journals .ledger
359 timeclock timeclock files (precise time .timeclock
360 logging)
361 timedot timedot files (approximate time .timedot
362 logging)
363 csv comma-separated values (data .csv
364 interchange)
365 If needed (eg to ensure correct error messages when a file has the
367 "wrong" extension), you can force a specific reader/format by prepend‐
368 ing it to the file path with a colon. Examples:
369 $ hledger -f csv:/some/csv-file.dat stats
371 $ echo 'i 2009/13/1 08:00:00' | hledger print -ftimeclock:-
372 You can also specify multiple -f options, to read multiple files as one
374 big journal. There are some limitations with this:
375 · directives in one file will not affect the other files
377 · balance assertions will not see any account balances from previous
379 files
380 If you need those, either use the include directive, or concatenate the
382 files, eg: cat a.journal b.journal | hledger -f- CMD.
383 Smart dates
385 hledger's user interfaces accept a flexible "smart date" syntax (unlike
386 dates in the journal file). Smart dates allow some english words, can
387 be relative to today's date, and can have less-significant date parts
388 omitted (defaulting to 1).
389 Examples:
391 2004/10/1, 2004-01-01, exact date, several sepa‐
393 2004.9.1 rators allowed. Year is
394 4+ digits, month is 1-12,
395 day is 1-31
396 2004 start of year
397 2004/10 start of month
398 10/1 month and day in current
399 year
400 21 day in current month
401 october, oct start of month in current
402 year
403 yesterday, today, tomorrow -1, 0, 1 days from today
404 last/this/next day/week/month/quar‐ -1, 0, 1 periods from the
406 ter/year current period
407 20181201 8 digit YYYYMMDD with
408 valid year month and day
409 201812 6 digit YYYYMM with valid
410 year and month
411 Counterexamples - malformed digit sequences might give surprising
413 results:
414 201813 6 digits with an invalid
416 month is parsed as start
417 of 6-digit year
418 20181301 8 digits with an invalid
419 month is parsed as start
420 of 8-digit year
421 20181232 8 digits with an invalid
422 day gives an error
423 201801012 9+ digits beginning with a
424 valid YYYYMMDD gives an
425 error
426 Report start & end date
428 Most hledger reports show the full span of time represented by the
429 journal data, by default. So, the effective report start and end dates
430 will be the earliest and latest transaction or posting dates found in
431 the journal.
432 Often you will want to see a shorter time span, such as the current
434 month. You can specify a start and/or end date using -b/--begin,
435 -e/--end, -p/--period or a date: query (described below). All of these
436 accept the smart date syntax. One important thing to be aware of when
437 specifying end dates: as in Ledger, end dates are exclusive, so you
438 need to write the date after the last day you want to include.
439 Examples:
441 -b 2016/3/17 begin on St. Patrick's
443 day 2016
444 -e 12/1 end at the start of decem‐
445 ber 1st of the current
446 year (11/30 will be the
447 last date included)
448 -b thismonth all transactions on or
449 after the 1st of the cur‐
450 rent month
451 -p thismonth all transactions in the
452 current month
453 date:2016/3/17- the above written as
454 queries instead
455 date:-12/1
456 date:thismonth-
457 date:thismonth
458 Report intervals
460 A report interval can be specified so that commands like register, bal‐
461 ance and activity will divide their reports into multiple subperiods.
462 The basic intervals can be selected with one of -D/--daily,
463 -W/--weekly, -M/--monthly, -Q/--quarterly, or -Y/--yearly. More com‐
464 plex intervals may be specified with a period expression. Report
465 intervals can not be specified with a query, currently.
466 Period expressions
468 The -p/--period option accepts period expressions, a shorthand way of
469 expressing a start date, end date, and/or report interval all at once.
470 Here's a basic period expression specifying the first quarter of 2009.
472 Note, hledger always treats start dates as inclusive and end dates as
473 exclusive:
474 -p "from 2009/1/1 to 2009/4/1"
476 Keywords like "from" and "to" are optional, and so are the spaces, as
478 long as you don't run two dates together. "to" can also be written as
479 "-". These are equivalent to the above:
480 -p "2009/1/1 2009/4/1"
482 -p2009/1/1to2009/4/1
483 -p2009/1/1-2009/4/1
484 Dates are smart dates, so if the current year is 2009, the above can
486 also be written as:
487 -p "1/1 4/1"
489 -p "january-apr"
490 -p "this year to 4/1"
491 If you specify only one date, the missing start or end date will be the
493 earliest or latest transaction in your journal:
494 -p "from 2009/1/1" everything after january
496 1, 2009
497 -p "from 2009/1" the same
498 -p "from 2009" the same
499 -p "to 2009" everything before january
500 1, 2009
501 A single date with no "from" or "to" defines both the start and end
503 date like so:
504 -p "2009" the year 2009; equivalent
506 to "2009/1/1 to 2010/1/1"
507 -p "2009/1" the month of jan; equiva‐
508 lent to "2009/1/1 to
509 2009/2/1"
510 -p "2009/1/1" just that day; equivalent
511 to "2009/1/1 to 2009/1/2"
512 The argument of -p can also begin with, or be, a report interval
514 expression. The basic report intervals are daily, weekly, monthly,
515 quarterly, or yearly, which have the same effect as the -D,-W,-M,-Q, or
516 -Y flags. Between report interval and start/end dates (if any), the
517 word in is optional. Examples:
518 -p "weekly from 2009/1/1 to 2009/4/1"
520 -p "monthly in 2008"
521 -p "quarterly"
522 Note that weekly, monthly, quarterly and yearly intervals will always
524 start on the first day on week, month, quarter or year accordingly, and
525 will end on the last day of same period, even if associated period
526 expression specifies different explicit start and end date.
527 For example:
529 -p "weekly from 2009/1/1 to 2009/4/1"
531 -- starts on 2008/12/29, closest pre‐
532 ceeding Monday
533 -p "monthly in 2008/11/25" -- starts on
534 2018/11/01
535 -p "quar‐
536 terly from 2009-05-05 to 2009-06-01" -
537 starts on 2009/04/01, ends on
538 2009/06/30, which are first and last
539 days of Q2 2009
540 -p "yearly from 2009-12-29" - starts on
541 2009/01/01, first day of 2009
542 The following more complex report intervals are also supported:
544 biweekly, bimonthly, every day|week|month|quarter|year,
545 every N days|weeks|months|quarters|years.
546 All of these will start on the first day of the requested period and
548 end on the last one, as described above.
549 Examples:
551 -p "bimonthly from 2008" -- periods
553 will have boundaries on 2008/01/01,
554 2008/03/01, ...
555 -p "every 2 weeks" -- starts on closest
556 preceeding Monday
557 -p "every 5 month from 2009/03" --
558 periods will have boundaries on
559 2009/03/01, 2009/08/01, ...
560 If you want intervals that start on arbitrary day of your choosing and
562 span a week, month or year, you need to use any of the following:
563 every Nth day of week, every <weekday>, every Nth day [of month],
565 every Nth weekday [of month], every MM/DD [of year],
566 every Nth MMM [of year], every MMM Nth [of year].
567 Examples:
569 -p "every 2nd day of week" -- periods
571 will go from Tue to Tue
572 -p "every Tue" -- same
573 -p "every 15th day" -- period bound‐
574 aries will be on 15th of each month
575 -p "every 2nd Monday" -- period bound‐
576 aries will be on second Monday of each
577 month
578 -p "every 11/05" -- yearly periods with
579 boundaries on 5th of Nov
580 -p "every 5th Nov" -- same
581 -p "every Nov 5th" -- same
582 Show historical balances at end of 15th each month (N is exclusive end
584 date):
585 hledger balance -H -p "every 16th day"
587 Group postings from start of wednesday to end of next tuesday (N is
589 start date and exclusive end date):
590 hledger register checking -p "every 3rd day of week"
592 Depth limiting
594 With the --depth N option (short form: -N), commands like account, bal‐
595 ance and register will show only the uppermost accounts in the account
596 tree, down to level N. Use this when you want a summary with less
597 detail. This flag has the same effect as a depth: query argument (so
598 -2, --depth=2 or depth:2 are basically equivalent).
599 Pivoting
601 Normally hledger sums amounts, and organizes them in a hierarchy, based
602 on account name. The --pivot FIELD option causes it to sum and orga‐
603 nize hierarchy based on the value of some other field instead. FIELD
604 can be: code, description, payee, note, or the full name (case insensi‐
605 tive) of any tag. As with account names, values containing colon:sepa‐
606 rated:parts will be displayed hierarchically in reports.
607 --pivot is a general option affecting all reports; you can think of
609 hledger transforming the journal before any other processing, replacing
610 every posting's account name with the value of the specified field on
611 that posting, inheriting it from the transaction or using a blank value
612 if it's not present.
613 An example:
615 2016/02/16 Member Fee Payment
617 assets:bank account 2 EUR
618 income:member fees -2 EUR ; member: John Doe
619 Normal balance report showing account names:
621 $ hledger balance
623 2 EUR assets:bank account
624 -2 EUR income:member fees
625 --------------------
626 0
627 Pivoted balance report, using member: tag values instead:
629 $ hledger balance --pivot member
631 2 EUR
632 -2 EUR John Doe
633 --------------------
634 0
635 One way to show only amounts with a member: value (using a query,
637 described below):
638 $ hledger balance --pivot member tag:member=.
640 -2 EUR John Doe
641 --------------------
642 -2 EUR
643 Another way (the acct: query matches against the pivoted "account
645 name"):
646 $ hledger balance --pivot member acct:.
648 -2 EUR John Doe
649 --------------------
650 -2 EUR
651 Cost
653 The -B/--cost flag converts amounts to their cost at transaction time,
654 if they have a transaction price specified.
655 Market value
657 The -V/--value flag converts reported amounts to their current market
658 value.
659 Specifically, when there is a market price (P directive) for the
660 amount's commodity, dated on or before today's date (or the report end
661 date if specified), the amount will be converted to the price's commod‐
662 ity.
663 When there are multiple applicable P directives, -V chooses the most
665 recent one, or in case of equal dates, the last-parsed one.
666 For example:
668 # one euro is worth this many dollars from nov 1
670 P 2016/11/01 € $1.10
671 # purchase some euros on nov 3
673 2016/11/3
674 assets:euros €100
675 assets:checking
676 # the euro is worth fewer dollars by dec 21
678 P 2016/12/21 € $1.03
679 How many euros do I have ?
681 $ hledger -f t.j bal -N euros
683 €100 assets:euros
684 What are they worth at end of nov 3 ?
686 $ hledger -f t.j bal -N euros -V -e 2016/11/4
688 $110.00 assets:euros
689 What are they worth after 2016/12/21 ? (no report end date specified,
691 defaults to today)
692 $ hledger -f t.j bal -N euros -V
694 $103.00 assets:euros
695 Currently, hledger's -V only uses market prices recorded with P direc‐
697 tives, not transaction prices (unlike Ledger).
698 Currently, -V has a limitation in multicolumn balance reports: it uses
700 the market prices on the report end date for all columns. (Instead of
701 the prices on each column's end date.)
702 Combining -B and -V
704 Using -B/--cost and -V/--value together is currently allowed, but the
705 results are probably not meaningful. Let us know if you find a use for
706 this.
707 Output destination
709 Some commands (print, register, stats, the balance commands) can write
710 their output to a destination other than the console. This is con‐
711 trolled by the -o/--output-file option.
712 $ hledger balance -o - # write to stdout (the default)
714 $ hledger balance -o FILE # write to FILE
715 Output format
717 Some commands can write their output in other formats. Eg print and
718 register can output CSV, and the balance commands can output CSV or
719 HTML. This is controlled by the -O/--output-format option, or by spec‐
720 ifying a .csv or .html file extension with -o/--output-file.
721 $ hledger balance -O csv # write CSV to stdout
723 $ hledger balance -o FILE.csv # write CSV to FILE.csv
724 Regular expressions
726 hledger uses regular expressions in a number of places:
727 · query terms, on the command line and in the hledger-web search form:
729 REGEX, desc:REGEX, cur:REGEX, tag:...=REGEX
730 · CSV rules conditional blocks: if REGEX ...
732 · account alias directives and options: alias /REGEX/ = REPLACEMENT,
734 --alias /REGEX/=REPLACEMENT
735 hledger's regular expressions come from the regex-tdfa library. In
737 general they:
738 · are case insensitive
740 · are infix matching (do not need to match the entire thing being
742 matched)
743 · are POSIX extended regular expressions
745 · also support GNU word boundaries (\<, \>, \b, \B)
747 · and parenthesised capturing groups and numeric backreferences in
749 replacement strings
750 · do not support mode modifiers like (?s)
752 Some things to note:
754 · In the alias directive and --alias option, regular expressions must
756 be enclosed in forward slashes (/REGEX/). Elsewhere in hledger,
757 these are not required.
758 · In queries, to match a regular expression metacharacter like $ as a
760 literal character, prepend a backslash. Eg to search for amounts
761 with the dollar sign in hledger-web, write cur:\$.
762 · On the command line, some metacharacters like $ have a special mean‐
764 ing to the shell and so must be escaped at least once more. See Spe‐
765 cial characters.
766
768 One of hledger's strengths is being able to quickly report on precise
769 subsets of your data. Most commands accept an optional query expres‐
770 sion, written as arguments after the command name, to filter the data
771 by date, account name or other criteria. The syntax is similar to a
772 web search: one or more space-separated search terms, quotes to enclose
773 whitespace, prefixes to match specific fields, a not: prefix to negate
774 the match.
775 We do not yet support arbitrary boolean combinations of search terms;
777 instead most commands show transactions/postings/accounts which match
778 (or negatively match):
779 · any of the description terms AND
781 · any of the account terms AND
783 · any of the status terms AND
785 · all the other terms.
787 The print command instead shows transactions which:
789 · match any of the description terms AND
791 · have any postings matching any of the positive account terms AND
793 · have no postings matching any of the negative account terms AND
795 · match all the other terms.
797 The following kinds of search terms can be used. Remember these can
799 also be prefixed with not:, eg to exclude a particular subaccount.
800 REGEX, acct:REGEX
802 match account names by this regular expression. (With no pre‐
803 fix, acct: is assumed.)
804 same as above
805 amt:N, amt:<N, amt:<=N, amt:>N, amt:>=N
807 match postings with a single-commodity amount that is equal to,
808 less than, or greater than N. (Multi-commodity amounts are not
809 tested, and will always match.) The comparison has two modes: if
810 N is preceded by a + or - sign (or is 0), the two signed numbers
811 are compared. Otherwise, the absolute magnitudes are compared,
812 ignoring sign.
813 code:REGEX
815 match by transaction code (eg check number)
816 cur:REGEX
818 match postings or transactions including any amounts whose cur‐
819 rency/commodity symbol is fully matched by REGEX. (For a par‐
820 tial match, use .*REGEX.*). Note, to match characters which are
821 regex-significant, like the dollar sign ($), you need to prepend
822 \. And when using the command line you need to add one more
823 level of quoting to hide it from the shell, so eg do:
824 hledger print cur:'\$' or hledger print cur:\\$.
825 desc:REGEX
827 match transaction descriptions.
828 date:PERIODEXPR
830 match dates within the specified period. PERIODEXPR is a period
831 expression (with no report interval). Examples: date:2016,
832 date:thismonth, date:2000/2/1-2/15, date:lastweek-. If the
833 --date2 command line flag is present, this matches secondary
834 dates instead.
835 date2:PERIODEXPR
837 match secondary dates within the specified period.
838 depth:N
840 match (or display, depending on command) accounts at or above
841 this depth
842 note:REGEX
844 match transaction notes (part of description right of |, or
845 whole description when there's no |)
846 payee:REGEX
848 match transaction payee/payer names (part of description left of
849 |, or whole description when there's no |)
850 real:, real:0
852 match real or virtual postings respectively
853 status:, status:!, status:*
855 match unmarked, pending, or cleared transactions respectively
856 tag:REGEX[=REGEX]
858 match by tag name, and optionally also by tag value. Note a
859 tag: query is considered to match a transaction if it matches
860 any of the postings. Also remember that postings inherit the
861 tags of their parent transaction.
862 The following special search term is used automatically in hledger-web,
864 only:
865 inacct:ACCTNAME
867 tells hledger-web to show the transaction register for this
868 account. Can be filtered further with acct etc.
869 Some of these can also be expressed as command-line options (eg depth:2
871 is equivalent to --depth 2). Generally you can mix options and query
872 arguments, and the resulting query will be their intersection (perhaps
873 excluding the -p/--period option).
874
876 hledger provides a number of subcommands; hledger with no arguments
877 shows a list.
878 If you install additional hledger-* packages, or if you put programs or
880 scripts named hledger-NAME in your PATH, these will also be listed as
881 subcommands.
882 Run a subcommand by writing its name as first argument (eg
884 hledger incomestatement). You can also write one of the standard short
885 aliases displayed in parentheses in the command list (hledger b), or
886 any any unambiguous prefix of a command name (hledger inc).
887 Here are all the builtin commands in alphabetical order. See also
889 hledger for a more organised command list, and hledger CMD -h for
890 detailed command help.
891 accounts
893 accounts, a
894 Show account names.
895 This command lists account names, either declared with account direc‐
897 tives (--declared), posted to (--used), or both (the default). With
898 query arguments, only matched account names and account names refer‐
899 enced by matched postings are shown. It shows a flat list by default.
900 With --tree, it uses indentation to show the account hierarchy. In
901 flat mode you can add --drop N to omit the first few account name com‐
902 ponents. Account names can be depth-clipped with depth:N or --depth N
903 or -N.
904 Examples:
906 $ hledger accounts
908 assets:bank:checking
909 assets:bank:saving
910 assets:cash
911 expenses:food
912 expenses:supplies
913 income:gifts
914 income:salary
915 liabilities:debts
916 activity
918 activity
919 Show an ascii barchart of posting counts per interval.
920 The activity command displays an ascii histogram showing transaction
922 counts by day, week, month or other reporting interval (by day is the
923 default). With query arguments, it counts only matched transactions.
924 Examples:
926 $ hledger activity --quarterly
928 2008-01-01 **
929 2008-04-01 *******
930 2008-07-01
931 2008-10-01 **
932 add
934 add
935 Prompt for transactions and add them to the journal.
936 Many hledger users edit their journals directly with a text editor, or
938 generate them from CSV. For more interactive data entry, there is the
939 add command, which prompts interactively on the console for new trans‐
940 actions, and appends them to the journal file (if there are multiple
941 -f FILE options, the first file is used.) Existing transactions are not
942 changed. This is the only hledger command that writes to the journal
943 file.
944 To use it, just run hledger add and follow the prompts. You can add as
946 many transactions as you like; when you are finished, enter . or press
947 control-d or control-c to exit.
948 Features:
950 · add tries to provide useful defaults, using the most similar (by
952 description) recent transaction (filtered by the query, if any) as a
953 template.
954 · You can also set the initial defaults with command line arguments.
956 · Readline-style edit keys can be used during data entry.
958 · The tab key will auto-complete whenever possible - accounts, descrip‐
960 tions, dates (yesterday, today, tomorrow). If the input area is
961 empty, it will insert the default value.
962 · If the journal defines a default commodity, it will be added to any
964 bare numbers entered.
965 · A parenthesised transaction code may be entered following a date.
967 · Comments and tags may be entered following a description or amount.
969 · If you make a mistake, enter < at any prompt to restart the transac‐
971 tion.
972 · Input prompts are displayed in a different colour when the terminal
974 supports it.
975 Example (see the tutorial for a detailed explanation):
977 $ hledger add
979 Adding transactions to journal file /src/hledger/examples/sample.journal
980 Any command line arguments will be used as defaults.
981 Use tab key to complete, readline keys to edit, enter to accept defaults.
982 An optional (CODE) may follow transaction dates.
983 An optional ; COMMENT may follow descriptions or amounts.
984 If you make a mistake, enter < at any prompt to restart the transaction.
985 To end a transaction, enter . when prompted.
986 To quit, enter . at a date prompt or press control-d or control-c.
987 Date [2015/05/22]:
988 Description: supermarket
989 Account 1: expenses:food
990 Amount 1: $10
991 Account 2: assets:checking
992 Amount 2 [$-10.0]:
993 Account 3 (or . or enter to finish this transaction): .
994 2015/05/22 supermarket
995 expenses:food $10
996 assets:checking $-10.0
997 Save this transaction to the journal ? [y]:
999 Saved.
1000 Starting the next transaction (. or ctrl-D/ctrl-C to quit)
1001 Date [2015/05/22]: <CTRL-D> $
1002 balance
1004 balance, bal, b
1005 Show accounts and their balances.
1006 The balance command is hledger's most versatile command. Note, despite
1008 the name, it is not always used for showing real-world account bal‐
1009 ances; the more accounting-aware balancesheet and incomestatement may
1010 be more convenient for that.
1011 By default, it displays all accounts, and each account's change in bal‐
1013 ance during the entire period of the journal. Balance changes are cal‐
1014 culated by adding up the postings in each account. You can limit the
1015 postings matched, by a query, to see fewer accounts, changes over a
1016 different time period, changes from only cleared transactions, etc.
1017 If you include an account's complete history of postings in the report,
1019 the balance change is equivalent to the account's current ending bal‐
1020 ance. For a real-world account, typically you won't have all transac‐
1021 tions in the journal; instead you'll have all transactions after a cer‐
1022 tain date, and an "opening balances" transaction setting the correct
1023 starting balance on that date. Then the balance command will show
1024 real-world account balances. In some cases the -H/--historical flag is
1025 used to ensure this (more below).
1026 The balance command can produce several styles of report:
1028 Classic balance report
1030 This is the original balance report, as found in Ledger. It usually
1031 looks like this:
1032 $ hledger balance
1034 $-1 assets
1035 $1 bank:saving
1036 $-2 cash
1037 $2 expenses
1038 $1 food
1039 $1 supplies
1040 $-2 income
1041 $-1 gifts
1042 $-1 salary
1043 $1 liabilities:debts
1044 --------------------
1045 0
1046 By default, accounts are displayed hierarchically, with subaccounts
1048 indented below their parent. At each level of the tree, accounts are
1049 sorted by account code if any, then by account name. Or with
1050 -S/--sort-amount, by their balance amount.
1051 "Boring" accounts, which contain a single interesting subaccount and no
1053 balance of their own, are elided into the following line for more com‐
1054 pact output. (Eg above, the "liabilities" account.) Use --no-elide to
1055 prevent this.
1056 Account balances are "inclusive" - they include the balances of any
1058 subaccounts.
1059 Accounts which have zero balance (and no non-zero subaccounts) are
1061 omitted. Use -E/--empty to show them.
1062 A final total is displayed by default; use -N/--no-total to suppress
1064 it, eg:
1065 $ hledger balance -p 2008/6 expenses --no-total
1067 $2 expenses
1068 $1 food
1069 $1 supplies
1070 Customising the classic balance report
1072 You can customise the layout of classic balance reports with --for‐
1073 mat FMT:
1074 $ hledger balance --format "%20(account) %12(total)"
1076 assets $-1
1077 bank:saving $1
1078 cash $-2
1079 expenses $2
1080 food $1
1081 supplies $1
1082 income $-2
1083 gifts $-1
1084 salary $-1
1085 liabilities:debts $1
1086 ---------------------------------
1087 0
1088 The FMT format string (plus a newline) specifies the formatting applied
1090 to each account/balance pair. It may contain any suitable text, with
1091 data fields interpolated like so:
1092 %[MIN][.MAX](FIELDNAME)
1094 · MIN pads with spaces to at least this width (optional)
1096 · MAX truncates at this width (optional)
1098 · FIELDNAME must be enclosed in parentheses, and can be one of:
1100 · depth_spacer - a number of spaces equal to the account's depth, or
1102 if MIN is specified, MIN * depth spaces.
1103 · account - the account's name
1105 · total - the account's balance/posted total, right justified
1107 Also, FMT can begin with an optional prefix to control how multi-com‐
1109 modity amounts are rendered:
1110 · %_ - render on multiple lines, bottom-aligned (the default)
1112 · %^ - render on multiple lines, top-aligned
1114 · %, - render on one line, comma-separated
1116 There are some quirks. Eg in one-line mode, %(depth_spacer) has no
1118 effect, instead %(account) has indentation built in.
1119 Experimentation may be needed to get pleasing results.
1120 Some example formats:
1122 · %(total) - the account's total
1124 · %-20.20(account) - the account's name, left justified, padded to 20
1126 characters and clipped at 20 characters
1127 · %,%-50(account) %25(total) - account name padded to 50 characters,
1129 total padded to 20 characters, with multiple commodities rendered on
1130 one line
1131 · %20(total) %2(depth_spacer)%-(account) - the default format for the
1133 single-column balance report
1134 Colour support
1136 The balance command shows negative amounts in red, if:
1137 · the TERM environment variable is not set to dumb
1139 · the output is not being redirected or piped anywhere
1141 Flat mode
1143 To see a flat list instead of the default hierarchical display, use
1144 --flat. In this mode, accounts (unless depth-clipped) show their full
1145 names and "exclusive" balance, excluding any subaccount balances. In
1146 this mode, you can also use --drop N to omit the first few account name
1147 components.
1148 $ hledger balance -p 2008/6 expenses -N --flat --drop 1
1150 $1 food
1151 $1 supplies
1152 Depth limited balance reports
1154 With --depth N or depth:N or just -N, balance reports show accounts
1155 only to the specified numeric depth. This is very useful to summarise
1156 a complex set of accounts and get an overview.
1157 $ hledger balance -N -1
1159 $-1 assets
1160 $2 expenses
1161 $-2 income
1162 $1 liabilities
1163 Flat-mode balance reports, which normally show exclusive balances, show
1165 inclusive balances at the depth limit.
1166 Multicolumn balance report
1168 Multicolumn or tabular balance reports are a very useful hledger fea‐
1169 ture, and usually the preferred style. They share many of the above
1170 features, but they show the report as a table, with columns represent‐
1171 ing time periods. This mode is activated by providing a reporting
1172 interval.
1173 There are three types of multicolumn balance report, showing different
1175 information:
1176 1. By default: each column shows the sum of postings in that period, ie
1178 the account's change of balance in that period. This is useful eg
1179 for a monthly income statement:
1180 $ hledger balance --quarterly income expenses -E
1182 Balance changes in 2008:
1183 || 2008q1 2008q2 2008q3 2008q4
1185 ===================++=================================
1186 expenses:food || 0 $1 0 0
1187 expenses:supplies || 0 $1 0 0
1188 income:gifts || 0 $-1 0 0
1189 income:salary || $-1 0 0 0
1190 -------------------++---------------------------------
1191 || $-1 $1 0 0
1192 2. With --cumulative: each column shows the ending balance for that
1194 period, accumulating the changes across periods, starting from 0 at
1195 the report start date:
1196 $ hledger balance --quarterly income expenses -E --cumulative
1198 Ending balances (cumulative) in 2008:
1199 || 2008/03/31 2008/06/30 2008/09/30 2008/12/31
1201 ===================++=================================================
1202 expenses:food || 0 $1 $1 $1
1203 expenses:supplies || 0 $1 $1 $1
1204 income:gifts || 0 $-1 $-1 $-1
1205 income:salary || $-1 $-1 $-1 $-1
1206 -------------------++-------------------------------------------------
1207 || $-1 0 0 0
1208 3. With --historical/-H: each column shows the actual historical ending
1210 balance for that period, accumulating the changes across periods,
1211 starting from the actual balance at the report start date. This is
1212 useful eg for a multi-period balance sheet, and when you are showing
1213 only the data after a certain start date:
1214 $ hledger balance ^assets ^liabilities --quarterly --historical --begin 2008/4/1
1216 Ending balances (historical) in 2008/04/01-2008/12/31:
1217 || 2008/06/30 2008/09/30 2008/12/31
1219 ======================++=====================================
1220 assets:bank:checking || $1 $1 0
1221 assets:bank:saving || $1 $1 $1
1222 assets:cash || $-2 $-2 $-2
1223 liabilities:debts || 0 0 $1
1224 ----------------------++-------------------------------------
1225 || 0 0 0
1226 Multicolumn balance reports display accounts in flat mode by default;
1228 to see the hierarchy, use --tree.
1229 With a reporting interval (like --quarterly above), the report
1231 start/end dates will be adjusted if necessary so that they encompass
1232 the displayed report periods. This is so that the first and last peri‐
1233 ods will be "full" and comparable to the others.
1234 The -E/--empty flag does two things in multicolumn balance reports:
1236 first, the report will show all columns within the specified report
1237 period (without -E, leading and trailing columns with all zeroes are
1238 not shown). Second, all accounts which existed at the report start
1239 date will be considered, not just the ones with activity during the
1240 report period (use -E to include low-activity accounts which would oth‐
1241 erwise would be omitted).
1242 The -T/--row-total flag adds an additional column showing the total for
1244 each row.
1245 The -A/--average flag adds a column showing the average value in each
1247 row.
1248 Here's an example of all three:
1250 $ hledger balance -Q income expenses --tree -ETA
1252 Balance changes in 2008:
1253 || 2008q1 2008q2 2008q3 2008q4 Total Average
1255 ============++===================================================
1256 expenses || 0 $2 0 0 $2 $1
1257 food || 0 $1 0 0 $1 0
1258 supplies || 0 $1 0 0 $1 0
1259 income || $-1 $-1 0 0 $-2 $-1
1260 gifts || 0 $-1 0 0 $-1 0
1261 salary || $-1 0 0 0 $-1 0
1262 ------------++---------------------------------------------------
1263 || $-1 $1 0 0 0 0
1264 # Average is rounded to the dollar here since all journal amounts are
1266 Limitations:
1268 In multicolumn reports the -V/--value flag uses the market price on the
1270 report end date, for all columns (not the price on each column's end
1271 date).
1272 Eliding of boring parent accounts in tree mode, as in the classic bal‐
1274 ance report, is not yet supported in multicolumn reports.
1275 Budget report
1277 With --budget, extra columns are displayed showing budget goals for
1278 each account and period, if any. Budget goals are defined by periodic
1279 transactions. This is very useful for comparing planned and actual
1280 income, expenses, time usage, etc. --budget is most often combined
1281 with a report interval.
1282 For example, you can take average monthly expenses in the common
1284 expense categories to construct a minimal monthly budget:
1285 ;; Budget
1287 ~ monthly
1288 income $2000
1289 expenses:food $400
1290 expenses:bus $50
1291 expenses:movies $30
1292 assets:bank:checking
1293 ;; Two months worth of expenses
1295 2017-11-01
1296 income $1950
1297 expenses:food $396
1298 expenses:bus $49
1299 expenses:movies $30
1300 expenses:supplies $20
1301 assets:bank:checking
1302 2017-12-01
1304 income $2100
1305 expenses:food $412
1306 expenses:bus $53
1307 expenses:gifts $100
1308 assets:bank:checking
1309 You can now see a monthly budget report:
1311 $ hledger balance -M --budget
1313 Budget performance in 2017/11/01-2017/12/31:
1314 || Nov Dec
1316 ======================++====================================================
1317 assets || $-2445 [ 99% of $-2480] $-2665 [ 107% of $-2480]
1318 assets:bank || $-2445 [ 99% of $-2480] $-2665 [ 107% of $-2480]
1319 assets:bank:checking || $-2445 [ 99% of $-2480] $-2665 [ 107% of $-2480]
1320 expenses || $495 [ 103% of $480] $565 [ 118% of $480]
1321 expenses:bus || $49 [ 98% of $50] $53 [ 106% of $50]
1322 expenses:food || $396 [ 99% of $400] $412 [ 103% of $400]
1323 expenses:movies || $30 [ 100% of $30] 0 [ 0% of $30]
1324 income || $1950 [ 98% of $2000] $2100 [ 105% of $2000]
1325 ----------------------++----------------------------------------------------
1326 || 0 [ 0] 0 [ 0]
1327 Note this is different from a normal balance report in several ways:
1329 · Only accounts with budget goals during the report period are shown,
1331 by default.
1332 · In each column, in square brackets after the actual amount, budgeted
1334 amounts are shown, along with the percentage of budget used.
1335 · All parent accounts are always shown, even in flat mode. Eg assets,
1337 assets:bank, and expenses above.
1338 · Amounts always include all subaccounts, budgeted or unbudgeted, even
1340 in flat mode.
1341 This means that the numbers displayed will not always add up! Eg above,
1343 the expenses actual amount includes the gifts and supplies transac‐
1344 tions, but the expenses:gifts and expenses:supplies accounts are not
1345 shown, as they have no budget amounts declared.
1346 This can be confusing. When you need to make things clearer, use the
1348 -E/--empty flag, which will reveal all accounts including unbudgeted
1349 ones, giving the full picture. Eg:
1350 $ hledger balance -M --budget --empty
1352 Budget performance in 2017/11/01-2017/12/31:
1353 || Nov Dec
1355 ======================++====================================================
1356 assets || $-2445 [ 99% of $-2480] $-2665 [ 107% of $-2480]
1357 assets:bank || $-2445 [ 99% of $-2480] $-2665 [ 107% of $-2480]
1358 assets:bank:checking || $-2445 [ 99% of $-2480] $-2665 [ 107% of $-2480]
1359 expenses || $495 [ 103% of $480] $565 [ 118% of $480]
1360 expenses:bus || $49 [ 98% of $50] $53 [ 106% of $50]
1361 expenses:food || $396 [ 99% of $400] $412 [ 103% of $400]
1362 expenses:gifts || 0 $100
1363 expenses:movies || $30 [ 100% of $30] 0 [ 0% of $30]
1364 expenses:supplies || $20 0
1365 income || $1950 [ 98% of $2000] $2100 [ 105% of $2000]
1366 ----------------------++----------------------------------------------------
1367 || 0 [ 0] 0 [ 0]
1368 You can roll over unspent budgets to next period with --cumulative:
1370 $ hledger balance -M --budget --cumulative
1372 Budget performance in 2017/11/01-2017/12/31:
1373 || Nov Dec
1375 ======================++====================================================
1376 assets || $-2445 [ 99% of $-2480] $-5110 [ 103% of $-4960]
1377 assets:bank || $-2445 [ 99% of $-2480] $-5110 [ 103% of $-4960]
1378 assets:bank:checking || $-2445 [ 99% of $-2480] $-5110 [ 103% of $-4960]
1379 expenses || $495 [ 103% of $480] $1060 [ 110% of $960]
1380 expenses:bus || $49 [ 98% of $50] $102 [ 102% of $100]
1381 expenses:food || $396 [ 99% of $400] $808 [ 101% of $800]
1382 expenses:movies || $30 [ 100% of $30] $30 [ 50% of $60]
1383 income || $1950 [ 98% of $2000] $4050 [ 101% of $4000]
1384 ----------------------++----------------------------------------------------
1385 || 0 [ 0] 0 [ 0]
1386 For more examples, see Budgeting and Forecasting.
1388 Nested budgets
1390 You can add budgets to any account in your account hierarchy. If you
1391 have budgets on both parent account and some of its children, then bud‐
1392 get(s) of the child account(s) would be added to the budget of their
1393 parent, much like account balances behave.
1394 In the most simple case this means that once you add a budget to any
1396 account, all its parents would have budget as well.
1397 To illustrate this, consider the following budget:
1399 ~ monthly from 2019/01
1401 expenses:personal $1,000.00
1402 expenses:personal:electronics $100.00
1403 liabilities
1404 With this, monthly budget for electronics is defined to be $100 and
1406 budget for personal expenses is an additional $1000, which implicity
1407 means that budget for both expenses:personal and expenses is $1100.
1408 Transactions in expenses:personal:electronics will be counted both
1410 towards its $100 budget and $1100 of expenses:personal , and transac‐
1411 tions in any other subaccount of expenses:personal would be counted
1412 towards only towards the budget of expenses:personal.
1413 For example, let's consider these transactions:
1415 ~ monthly from 2019/01
1417 expenses:personal $1,000.00
1418 expenses:personal:electronics $100.00
1419 liabilities
1420 2019/01/01 Google home hub
1422 expenses:personal:electronics $90.00
1423 liabilities $-90.00
1424 2019/01/02 Phone screen protector
1426 expenses:personal:electronics:upgrades $10.00
1427 liabilities
1428 2019/01/02 Weekly train ticket
1430 expenses:personal:train tickets $153.00
1431 liabilities
1432 2019/01/03 Flowers
1434 expenses:personal $30.00
1435 liabilities
1436 As you can see, we have transactions in expenses:personal:electron‐
1438 ics:upgrades and expenses:personal:train tickets, and since both of
1439 these accounts are without explicitly defined budget, these transac‐
1440 tions would be counted towards budgets of expenses:personal:electronics
1441 and expenses:personal accordingly:
1442 $ hledger balance --budget -M
1444 Budget performance in 2019/01:
1445 || Jan
1447 ===============================++===============================
1448 expenses || $283.00 [ 26% of $1100.00]
1449 expenses:personal || $283.00 [ 26% of $1100.00]
1450 expenses:personal:electronics || $100.00 [ 100% of $100.00]
1451 liabilities || $-283.00 [ 26% of $-1100.00]
1452 -------------------------------++-------------------------------
1453 || 0 [ 0]
1454 And with --empty, we can get a better picture of budget allocation and
1456 consumption:
1457 $ hledger balance --budget -M --empty
1459 Budget performance in 2019/01:
1460 || Jan
1462 ========================================++===============================
1463 expenses || $283.00 [ 26% of $1100.00]
1464 expenses:personal || $283.00 [ 26% of $1100.00]
1465 expenses:personal:electronics || $100.00 [ 100% of $100.00]
1466 expenses:personal:electronics:upgrades || $10.00
1467 expenses:personal:train tickets || $153.00
1468 liabilities || $-283.00 [ 26% of $-1100.00]
1469 ----------------------------------------++-------------------------------
1470 || 0 [ 0]
1471 Output format
1473 The balance command supports output destination and output format
1474 selection.
1475 balancesheet
1477 balancesheet, bs
1478 This command displays a simple balance sheet, showing historical ending
1479 balances of asset and liability accounts (ignoring any report begin
1480 date). It assumes that these accounts are under a top-level asset or
1481 liability account (case insensitive, plural forms also allowed).
1482 Note this report shows all account balances with normal positive sign
1484 (like conventional financial statements, unlike balance/print/register)
1485 (experimental).
1486 Example:
1488 $ hledger balancesheet
1490 Balance Sheet
1491 Assets:
1493 $-1 assets
1494 $1 bank:saving
1495 $-2 cash
1496 --------------------
1497 $-1
1498 Liabilities:
1500 $1 liabilities:debts
1501 --------------------
1502 $1
1503 Total:
1505 --------------------
1506 0
1507 With a reporting interval, multiple columns will be shown, one for each
1509 report period. As with multicolumn balance reports, you can alter the
1510 report mode with --change/--cumulative/--historical. Normally bal‐
1511 ancesheet shows historical ending balances, which is what you need for
1512 a balance sheet; note this means it ignores report begin dates.
1513 This command also supports output destination and output format selec‐
1515 tion.
1516 balancesheetequity
1518 balancesheetequity, bse
1519 Just like balancesheet, but also reports Equity (which it assumes is
1520 under a top-level equity account).
1521 Example:
1523 $ hledger balancesheetequity
1525 Balance Sheet With Equity
1526 Assets:
1528 $-2 assets
1529 $1 bank:saving
1530 $-3 cash
1531 --------------------
1532 $-2
1533 Liabilities:
1535 $1 liabilities:debts
1536 --------------------
1537 $1
1538 Equity:
1540 $1 equity:owner
1541 --------------------
1542 $1
1543 Total:
1545 --------------------
1546 0
1547 cashflow
1549 cashflow, cf
1550 This command displays a simple cashflow statement, showing changes in
1551 "cash" accounts. It assumes that these accounts are under a top-level
1552 asset account (case insensitive, plural forms also allowed) and do not
1553 contain receivable or A/R in their name. Note this report shows all
1554 account balances with normal positive sign (like conventional financial
1555 statements, unlike balance/print/register) (experimental).
1556 Example:
1558 $ hledger cashflow
1560 Cashflow Statement
1561 Cash flows:
1563 $-1 assets
1564 $1 bank:saving
1565 $-2 cash
1566 --------------------
1567 $-1
1568 Total:
1570 --------------------
1571 $-1
1572 With a reporting interval, multiple columns will be shown, one for each
1574 report period. Normally cashflow shows changes in assets per period,
1575 though as with multicolumn balance reports you can alter the report
1576 mode with --change/--cumulative/--historical.
1577 This command also supports output destination and output format selec‐
1579 tion.
1580 check-dates
1582 check-dates
1583 Check that transactions are sorted by increasing date. With --date2,
1584 checks secondary dates instead. With --strict, dates must also be
1585 unique. With a query, only matched transactions' dates are checked.
1586 Reads the default journal file, or another specified with -f.
1587 check-dupes
1589 check-dupes
1590 Reports account names having the same leaf but different prefixes. In
1591 other words, two or more leaves that are categorized differently.
1592 Reads the default journal file, or another specified as an argument.
1593 An example: http://stefanorodighiero.net/software/hledger-dupes.html
1595 close
1597 close, equity
1598 Prints a "closing balances" transaction and an "opening balances"
1599 transaction that bring account balances to and from zero, respectively.
1600 Useful for bringing asset/liability balances forward into a new journal
1601 file, or for closing out revenues/expenses to retained earnings at the
1602 end of a period.
1603 The closing transaction transfers balances to "equity:closing bal‐
1605 ances". The opening transaction transfers balances from "equity:open‐
1606 ing balances". You can chose to print just one of the transactions by
1607 using the --opening or --closing flag.
1608 If you split your journal files by time (eg yearly), you will typically
1610 run this command at the end of the year, and save the closing transac‐
1611 tion as last entry of the old file, and the opening transaction as the
1612 first entry of the new file. This makes the files self contained, so
1613 that correct balances are reported no matter which of them are loaded.
1614 Ie, if you load just one file, the balances are initialised correctly;
1615 or if you load several files, the redundant closing/opening transac‐
1616 tions cancel each other out. (They will show up in print or register
1617 reports; you can exclude them with a query like not:desc:'(open‐
1618 ing|closing) balances'.)
1619 If you're running a business, you might also use this command to "close
1621 the books" at the end of an accounting period, transferring income
1622 statement account balances to retained earnings. (You may want to
1623 change the equity account name to something like "equity:retained earn‐
1624 ings".)
1625 By default, the closing transaction is dated yesterday, the balances
1627 are calculated as of end of yesterday, and the opening transaction is
1628 dated today. To close on some other date, use: hledger close -e OPEN‐
1629 INGDATE. Eg, to close/open on the 2018/2019 boundary, use -e 2019.
1630 You can also use -p or date:PERIOD (any starting date is ignored).
1631 Both transactions will include balance assertions for the
1633 closed/reopened accounts. You probably shouldn't use status or real‐
1634 ness filters (like -C or -R or status:) with this command, or the gen‐
1635 erated balance assertions will depend on these flags. Likewise, if you
1636 run this command with --auto, the balance assertions will probably
1637 always require --auto.
1638 Examples:
1640 Carrying asset/liability balances into a new file for 2019, all from
1642 command line:
1643 Warning: we use >> here to append; be careful not to type a single >
1645 which would wipe your journal!
1646 $ hledger close -f 2018.journal -e 2019 assets liabilities --opening >>2019.journal
1648 $ hledger close -f 2018.journal -e 2019 assets liabilities --closing >>2018.journal
1649 Now:
1651 $ hledger bs -f 2019.journal # one file - balances are correct
1653 $ hledger bs -f 2018.journal -f 2019.journal # two files - balances still correct
1654 $ hledger bs -f 2018.journal not:desc:closing # to see year-end balances, must exclude closing txn
1655 Transactions spanning the closing date can complicate matters, breaking
1657 balance assertions:
1658 2018/12/30 a purchase made in 2018, clearing the following year
1660 expenses:food 5
1661 assets:bank:checking -5 ; [2019/1/2]
1662 Here's one way to resolve that:
1664 ; in 2018.journal:
1666 2018/12/30 a purchase made in 2018, clearing the following year
1667 expenses:food 5
1668 liabilities:pending
1669 ; in 2019.journal:
1671 2019/1/2 clearance of last year's pending transactions
1672 liabilities:pending 5 = 0
1673 assets:checking
1674 files
1676 files
1677 List all files included in the journal. With a REGEX argument, only
1678 file names matching the regular expression (case sensitive) are shown.
1679 help
1681 help
1682 Show any of the hledger manuals.
1683 The help command displays any of the main hledger manuals, in one of
1685 several ways. Run it with no argument to list the manuals, or provide
1686 a full or partial manual name to select one.
1687 hledger manuals are available in several formats. hledger help will
1689 use the first of these display methods that it finds: info, man,
1690 $PAGER, less, stdout (or when non-interactive, just stdout). You can
1691 force a particular viewer with the --info, --man, --pager, --cat flags.
1692 Examples:
1694 $ hledger help
1696 Please choose a manual by typing "hledger help MANUAL" (a substring is ok).
1697 Manuals: hledger hledger-ui hledger-web hledger-api journal csv timeclock timedot
1698 $ hledger help h --man
1700 hledger(1) hledger User Manuals hledger(1)
1702 NAME
1704 hledger - a command-line accounting tool
1705 SYNOPSIS
1707 hledger [-f FILE] COMMAND [OPTIONS] [ARGS]
1708 hledger [-f FILE] ADDONCMD -- [OPTIONS] [ARGS]
1709 hledger
1710 DESCRIPTION
1712 hledger is a cross-platform program for tracking money, time, or any
1713 ...
1714 import
1716 import
1717 Read new transactions added to each FILE since last run, and add them
1718 to the main journal file. Or with --dry-run, just print the transac‐
1719 tions that would be added.
1720 The input files are specified as arguments - no need to write -f before
1722 each one. So eg to add new transactions from all CSV files to the main
1723 journal, it's just: hledger import *.csv
1724 New transactions are detected in the same way as print --new: by assum‐
1726 ing transactions are always added to the input files in increasing date
1727 order, and by saving .latest.FILE state files.
1728 The --dry-run output is in journal format, so you can filter it, eg to
1730 see only uncategorised transactions:
1731 $ hledger import --dry ... | hledger -f- print unknown --ignore-assertions
1733 incomestatement
1735 incomestatement, is
1736 This command displays a simple income statement, showing revenues and
1737 expenses during a period. It assumes that these accounts are under a
1738 top-level revenue or income or expense account (case insensitive, plu‐
1739 ral forms also allowed). Note this report shows all account balances
1740 with normal positive sign (like conventional financial statements,
1741 unlike balance/print/register) (experimental).
1742 This command displays a simple income statement. It currently assumes
1744 that you have top-level accounts named income (or revenue) and expense
1745 (plural forms also allowed.)
1746 $ hledger incomestatement
1748 Income Statement
1749 Revenues:
1751 $-2 income
1752 $-1 gifts
1753 $-1 salary
1754 --------------------
1755 $-2
1756 Expenses:
1758 $2 expenses
1759 $1 food
1760 $1 supplies
1761 --------------------
1762 $2
1763 Total:
1765 --------------------
1766 0
1767 With a reporting interval, multiple columns will be shown, one for each
1769 report period. Normally incomestatement shows revenues/expenses per
1770 period, though as with multicolumn balance reports you can alter the
1771 report mode with --change/--cumulative/--historical.
1772 This command also supports output destination and output format selec‐
1774 tion.
1775 prices
1777 prices
1778 Print market price directives from the journal. With --costs, also
1779 print synthetic market prices based on transaction prices. With
1780 --inverted-costs, also print inverse prices based on transaction
1781 prices. Prices (and postings providing prices) can be filtered by a
1782 query.
1783 print
1785 print, txns, p
1786 Show transaction journal entries, sorted by date.
1787 The print command displays full journal entries (transactions) from the
1789 journal file in date order, tidily formatted. With --date2, transac‐
1790 tions are sorted by secondary date instead.
1791 print's output is always a valid hledger journal.
1793 It preserves all transaction information, but it does not preserve
1794 directives or inter-transaction comments
1795 $ hledger print
1797 2008/01/01 income
1798 assets:bank:checking $1
1799 income:salary $-1
1800 2008/06/01 gift
1802 assets:bank:checking $1
1803 income:gifts $-1
1804 2008/06/02 save
1806 assets:bank:saving $1
1807 assets:bank:checking $-1
1808 2008/06/03 * eat & shop
1810 expenses:food $1
1811 expenses:supplies $1
1812 assets:cash $-2
1813 2008/12/31 * pay off
1815 liabilities:debts $1
1816 assets:bank:checking $-1
1817 Normally, the journal entry's explicit or implicit amount style is pre‐
1819 served. Ie when an amount is omitted in the journal, it will be omit‐
1820 ted in the output. You can use the -x/--explicit flag to make all
1821 amounts explicit, which can be useful for troubleshooting or for making
1822 your journal more readable and robust against data entry errors. Note,
1823 -x will cause postings with a multi-commodity amount (these can arise
1824 when a multi-commodity transaction has an implicit amount) will be
1825 split into multiple single-commodity postings, for valid journal out‐
1826 put.
1827 With -B/--cost, amounts with transaction prices are converted to cost
1829 using that price. This can be used for troubleshooting.
1830 With -m/--match and a STR argument, print will show at most one trans‐
1832 action: the one one whose description is most similar to STR, and is
1833 most recent. STR should contain at least two characters. If there is
1834 no similar-enough match, no transaction will be shown.
1835 With --new, for each FILE being read, hledger reads (and writes) a spe‐
1837 cial state file (.latest.FILE in the same directory), containing the
1838 latest transaction date(s) that were seen last time FILE was read.
1839 When this file is found, only transactions with newer dates (and new
1840 transactions on the latest date) are printed. This is useful for
1841 ignoring already-seen entries in import data, such as downloaded CSV
1842 files. Eg:
1843 $ hledger -f bank1.csv print --new
1845 # shows transactions added since last print --new on this file
1846 This assumes that transactions added to FILE always have same or
1848 increasing dates, and that transactions on the same day do not get
1849 reordered. See also the import command.
1850 This command also supports output destination and output format selec‐
1852 tion. Here's an example of print's CSV output:
1853 $ hledger print -Ocsv
1855 "txnidx","date","date2","status","code","description","comment","account","amount","commodity","credit","debit","posting-status","posting-comment"
1856 "1","2008/01/01","","","","income","","assets:bank:checking","1","$","","1","",""
1857 "1","2008/01/01","","","","income","","income:salary","-1","$","1","","",""
1858 "2","2008/06/01","","","","gift","","assets:bank:checking","1","$","","1","",""
1859 "2","2008/06/01","","","","gift","","income:gifts","-1","$","1","","",""
1860 "3","2008/06/02","","","","save","","assets:bank:saving","1","$","","1","",""
1861 "3","2008/06/02","","","","save","","assets:bank:checking","-1","$","1","","",""
1862 "4","2008/06/03","","*","","eat & shop","","expenses:food","1","$","","1","",""
1863 "4","2008/06/03","","*","","eat & shop","","expenses:supplies","1","$","","1","",""
1864 "4","2008/06/03","","*","","eat & shop","","assets:cash","-2","$","2","","",""
1865 "5","2008/12/31","","*","","pay off","","liabilities:debts","1","$","","1","",""
1866 "5","2008/12/31","","*","","pay off","","assets:bank:checking","-1","$","1","","",""
1867 · There is one CSV record per posting, with the parent transaction's
1869 fields repeated.
1870 · The "txnidx" (transaction index) field shows which postings belong to
1872 the same transaction. (This number might change if transactions are
1873 reordered within the file, files are parsed/included in a different
1874 order, etc.)
1875 · The amount is separated into "commodity" (the symbol) and "amount"
1877 (numeric quantity) fields.
1878 · The numeric amount is repeated in either the "credit" or "debit" col‐
1880 umn, for convenience. (Those names are not accurate in the account‐
1881 ing sense; it just puts negative amounts under credit and zero or
1882 greater amounts under debit.)
1883 print-unique
1885 print-unique
1886 Print transactions which do not reuse an already-seen description.
1887 Example:
1889 $ cat unique.journal
1891 1/1 test
1892 (acct:one) 1
1893 2/2 test
1894 (acct:two) 2
1895 $ LEDGER_FILE=unique.journal hledger print-unique
1896 (-f option not supported)
1897 2015/01/01 test
1898 (acct:one) 1
1899 register
1901 register, reg, r
1902 Show postings and their running total.
1903 The register command displays postings in date order, one per line, and
1905 their running total. This is typically used with a query selecting a
1906 particular account, to see that account's activity:
1907 $ hledger register checking
1909 2008/01/01 income assets:bank:checking $1 $1
1910 2008/06/01 gift assets:bank:checking $1 $2
1911 2008/06/02 save assets:bank:checking $-1 $1
1912 2008/12/31 pay off assets:bank:checking $-1 0
1913 With --date2, it shows and sorts by secondary date instead.
1915 The --historical/-H flag adds the balance from any undisplayed prior
1917 postings to the running total. This is useful when you want to see
1918 only recent activity, with a historically accurate running balance:
1919 $ hledger register checking -b 2008/6 --historical
1921 2008/06/01 gift assets:bank:checking $1 $2
1922 2008/06/02 save assets:bank:checking $-1 $1
1923 2008/12/31 pay off assets:bank:checking $-1 0
1924 The --depth option limits the amount of sub-account detail displayed.
1926 The --average/-A flag shows the running average posting amount instead
1928 of the running total (so, the final number displayed is the average for
1929 the whole report period). This flag implies --empty (see below). It
1930 is affected by --historical. It works best when showing just one
1931 account and one commodity.
1932 The --related/-r flag shows the other postings in the transactions of
1934 the postings which would normally be shown.
1935 The --invert flag negates all amounts. For example, it can be used on
1937 an income account where amounts are normally displayed as negative num‐
1938 bers. It's also useful to show postings on the checking account
1939 together with the related account:
1940 $ hledger register --related --invert assets:checking
1942 With a reporting interval, register shows summary postings, one per
1944 interval, aggregating the postings to each account:
1945 $ hledger register --monthly income
1947 2008/01 income:salary $-1 $-1
1948 2008/06 income:gifts $-1 $-2
1949 Periods with no activity, and summary postings with a zero amount, are
1951 not shown by default; use the --empty/-E flag to see them:
1952 $ hledger register --monthly income -E
1954 2008/01 income:salary $-1 $-1
1955 2008/02 0 $-1
1956 2008/03 0 $-1
1957 2008/04 0 $-1
1958 2008/05 0 $-1
1959 2008/06 income:gifts $-1 $-2
1960 2008/07 0 $-2
1961 2008/08 0 $-2
1962 2008/09 0 $-2
1963 2008/10 0 $-2
1964 2008/11 0 $-2
1965 2008/12 0 $-2
1966 Often, you'll want to see just one line per interval. The --depth
1968 option helps with this, causing subaccounts to be aggregated:
1969 $ hledger register --monthly assets --depth 1h
1971 2008/01 assets $1 $1
1972 2008/06 assets $-1 0
1973 2008/12 assets $-1 $-1
1974 Note when using report intervals, if you specify start/end dates these
1976 will be adjusted outward if necessary to contain a whole number of
1977 intervals. This ensures that the first and last intervals are full
1978 length and comparable to the others in the report.
1979 Custom register output
1981 register uses the full terminal width by default, except on windows.
1982 You can override this by setting the COLUMNS environment variable (not
1983 a bash shell variable) or by using the --width/-w option.
1984 The description and account columns normally share the space equally
1986 (about half of (width - 40) each). You can adjust this by adding a
1987 description width as part of --width's argument, comma-separated:
1988 --width W,D . Here's a diagram (won't display correctly in --help):
1989 <--------------------------------- width (W) ---------------------------------->
1991 date (10) description (D) account (W-41-D) amount (12) balance (12)
1992 DDDDDDDDDD dddddddddddddddddddd aaaaaaaaaaaaaaaaaaa AAAAAAAAAAAA AAAAAAAAAAAA
1993 and some examples:
1995 $ hledger reg # use terminal width (or 80 on windows)
1997 $ hledger reg -w 100 # use width 100
1998 $ COLUMNS=100 hledger reg # set with one-time environment variable
1999 $ export COLUMNS=100; hledger reg # set till session end (or window resize)
2000 $ hledger reg -w 100,40 # set overall width 100, description width 40
2001 $ hledger reg -w $COLUMNS,40 # use terminal width, & description width 40
2002 This command also supports output destination and output format selec‐
2004 tion.
2005 register-match
2007 register-match
2008 Print the one posting whose transaction description is closest to DESC,
2009 in the style of the register command. If there are multiple equally
2010 good matches, it shows the most recent. Query options (options, not
2011 arguments) can be used to restrict the search space. Helps
2012 ledger-autosync detect already-seen transactions when importing.
2013 rewrite
2015 rewrite
2016 Print all transactions, rewriting the postings of matched transactions.
2017 For now the only rewrite available is adding new postings, like print
2018 --auto.
2019 This is a start at a generic rewriter of transaction entries. It reads
2021 the default journal and prints the transactions, like print, but adds
2022 one or more specified postings to any transactions matching QUERY. The
2023 posting amounts can be fixed, or a multiplier of the existing transac‐
2024 tion's first posting amount.
2025 Examples:
2027 hledger-rewrite.hs ^income --add-posting '(liabilities:tax) *.33 ; income tax' --add-posting '(reserve:gifts) $100'
2029 hledger-rewrite.hs expenses:gifts --add-posting '(reserve:gifts) *-1"'
2030 hledger-rewrite.hs -f rewrites.hledger
2031 rewrites.hledger may consist of entries like:
2033 = ^income amt:<0 date:2017
2035 (liabilities:tax) *0.33 ; tax on income
2036 (reserve:grocery) *0.25 ; reserve 25% for grocery
2037 (reserve:) *0.25 ; reserve 25% for grocery
2038 Note the single quotes to protect the dollar sign from bash, and the
2040 two spaces between account and amount.
2041 More:
2043 $ hledger rewrite -- [QUERY] --add-posting "ACCT AMTEXPR" ...
2045 $ hledger rewrite -- ^income --add-posting '(liabilities:tax) *.33'
2046 $ hledger rewrite -- expenses:gifts --add-posting '(budget:gifts) *-1"'
2047 $ hledger rewrite -- ^income --add-posting '(budget:foreign currency) *0.25 JPY; diversify'
2048 Argument for --add-posting option is a usual posting of transaction
2050 with an exception for amount specification. More precisely, you can
2051 use '*' (star symbol) before the amount to indicate that that this is a
2052 factor for an amount of original matched posting. If the amount
2053 includes a commodity name, the new posting amount will be in the new
2054 commodity; otherwise, it will be in the matched posting amount's com‐
2055 modity.
2056 Re-write rules in a file
2058 During the run this tool will execute so called "Automated Transac‐
2059 tions" found in any journal it process. I.e instead of specifying this
2060 operations in command line you can put them in a journal file.
2061 $ rewrite-rules.journal
2063 Make contents look like this:
2065 = ^income
2067 (liabilities:tax) *.33
2068 = expenses:gifts
2070 budget:gifts *-1
2071 assets:budget *1
2072 Note that '=' (equality symbol) that is used instead of date in trans‐
2074 actions you usually write. It indicates the query by which you want to
2075 match the posting to add new ones.
2076 $ hledger rewrite -- -f input.journal -f rewrite-rules.journal > rewritten-tidy-output.journal
2078 This is something similar to the commands pipeline:
2080 $ hledger rewrite -- -f input.journal '^income' --add-posting '(liabilities:tax) *.33' \
2082 | hledger rewrite -- -f - expenses:gifts --add-posting 'budget:gifts *-1' \
2083 --add-posting 'assets:budget *1' \
2084 > rewritten-tidy-output.journal
2085 It is important to understand that relative order of such entries in
2087 journal is important. You can re-use result of previously added post‐
2088 ings.
2089 Diff output format
2091 To use this tool for batch modification of your journal files you may
2092 find useful output in form of unified diff.
2093 $ hledger rewrite -- --diff -f examples/sample.journal '^income' --add-posting '(liabilities:tax) *.33'
2095 Output might look like:
2097 --- /tmp/examples/sample.journal
2099 +++ /tmp/examples/sample.journal
2100 @@ -18,3 +18,4 @@
2101 2008/01/01 income
2102 - assets:bank:checking $1
2103 + assets:bank:checking $1
2104 income:salary
2105 + (liabilities:tax) 0
2106 @@ -22,3 +23,4 @@
2107 2008/06/01 gift
2108 - assets:bank:checking $1
2109 + assets:bank:checking $1
2110 income:gifts
2111 + (liabilities:tax) 0
2112 If you'll pass this through patch tool you'll get transactions contain‐
2114 ing the posting that matches your query be updated. Note that multiple
2115 files might be update according to list of input files specified via
2116 --file options and include directives inside of these files.
2117 Be careful. Whole transaction being re-formatted in a style of output
2119 from hledger print.
2120 See also:
2122 https://github.com/simonmichael/hledger/issues/99
2124 rewrite vs. print --auto
2126 This command predates print --auto, and currently does much the same
2127 thing, but with these differences:
2128 · with multiple files, rewrite lets rules in any file affect all other
2130 files. print --auto uses standard directive scoping; rules affect
2131 only child files.
2132 · rewrite's query limits which transactions can be rewritten; all are
2134 printed. print --auto's query limits which transactions are printed.
2135 · rewrite applies rules specified on command line or in the journal.
2137 print --auto applies rules specified in the journal.
2138 roi
2140 roi
2141 Shows the time-weighted (TWR) and money-weighted (IRR) rate of return
2142 on your investments.
2143 This command assumes that you have account(s) that hold nothing but
2145 your investments and whenever you record current appraisal/valuation of
2146 these investments you offset unrealized profit and loss into account(s)
2147 that, again, hold nothing but unrealized profit and loss.
2148 Any transactions affecting balance of investment account(s) and not
2150 originating from unrealized profit and loss account(s) are assumed to
2151 be your investments or withdrawals.
2152 At a minimum, you need to supply a query (which could be just an
2154 account name) to select your investments with --inv, and another query
2155 to identify your profit and loss transactions with --pnl.
2156 It will compute and display the internalized rate of return (IRR) and
2158 time-weighted rate of return (TWR) for your investments for the time
2159 period requested. Both rates of return are annualized before display,
2160 regardless of the length of reporting interval.
2161 stats
2163 stats
2164 Show some journal statistics.
2165 The stats command displays summary information for the whole journal,
2167 or a matched part of it. With a reporting interval, it shows a report
2168 for each report period.
2169 Example:
2171 $ hledger stats
2173 Main journal file : /src/hledger/examples/sample.journal
2174 Included journal files :
2175 Transactions span : 2008-01-01 to 2009-01-01 (366 days)
2176 Last transaction : 2008-12-31 (2333 days ago)
2177 Transactions : 5 (0.0 per day)
2178 Transactions last 30 days: 0 (0.0 per day)
2179 Transactions last 7 days : 0 (0.0 per day)
2180 Payees/descriptions : 5
2181 Accounts : 8 (depth 3)
2182 Commodities : 1 ($)
2183 This command also supports output destination and output format selec‐
2185 tion.
2186 tags
2188 tags
2189 List all the tag names used in the journal. With a TAGREGEX argument,
2190 only tag names matching the regular expression (case insensitive) are
2191 shown. With QUERY arguments, only transactions matching the query are
2192 considered.
2193 test
2195 test
2196 Run built-in unit tests.
2197 This command runs the unit tests built in to hledger-lib and hledger,
2199 printing test names and results on stdout. If any test fails, the exit
2200 code will be non-zero.
2201 Test names include a group prefix. If a (exact, case sensitive) group
2203 prefix, or a full test name is provided as the first argument, only
2204 that group or test is run.
2205 If a numeric second argument is provided, it will set the randomness
2207 seed, for repeatable results from tests using randomness (currently
2208 none of them).
2209 This is mainly used by developers, but it's nice to be able to san‐
2211 ity-check your installed hledger executable at any time. All tests are
2212 expected to pass - if you ever see otherwise, something has gone wrong,
2213 please report a bug!
2214
2216 hledger also searches for external add-on commands, and will include
2217 these in the commands list. These are programs or scripts in your PATH
2218 whose name starts with hledger- and ends with a recognised file exten‐
2219 sion (currently: no extension, bat,com,exe, hs,lhs,pl,py,rb,rkt,sh).
2220 Add-ons can be invoked like any hledger command, but there are a few
2222 things to be aware of. Eg if the hledger-web add-on is installed,
2223 · hledger -h web shows hledger's help, while hledger web -h shows
2225 hledger-web's help.
2226 · Flags specific to the add-on must have a preceding -- to hide them
2228 from hledger. So hledger web --serve --port 9000 will be rejected;
2229 you must use hledger web -- --serve --port 9000.
2230 · You can always run add-ons directly if preferred:
2232 hledger-web --serve --port 9000.
2233 Add-ons are a relatively easy way to add local features or experiment
2235 with new ideas. They can be written in any language, but haskell
2236 scripts have a big advantage: they can use the same hledger (and
2237 haskell) library functions that built-in commands do, for command-line
2238 options, journal parsing, reporting, etc.
2239 Here are some hledger add-ons available:
2241 Official add-ons
2243 These are maintained and released along with hledger.
2244 api
2246 hledger-api serves hledger data as a JSON web API.
2247 ui
2249 hledger-ui provides an efficient curses-style interface.
2250 web
2252 hledger-web provides a simple web interface.
2253 Third party add-ons
2255 These are maintained separately, and usually updated shortly after a
2256 hledger release.
2257 diff
2259 hledger-diff shows differences in an account's transactions between one
2260 journal file and another.
2261 iadd
2263 hledger-iadd is a curses-style, more interactive replacement for the
2264 add command.
2265 interest
2267 hledger-interest generates interest transactions for an account accord‐
2268 ing to various schemes.
2269 irr
2271 hledger-irr calculates the internal rate of return of an investment
2272 account, but it's superseded now by the built-in roi command.
2273 Experimental add-ons
2275 These are available in source form in the hledger repo's bin/ direc‐
2276 tory; installing them is pretty easy. They may be less mature and doc‐
2277 umented than built-in commands. Reading and tweaking these is a good
2278 way to start making your own!
2279 autosync
2281 hledger-autosync is a symbolic link for easily running ledger-autosync,
2282 if installed. ledger-autosync does deduplicating conversion of OFX
2283 data and some CSV formats, and can also download the data if your bank
2284 offers OFX Direct Connect.
2285 chart
2287 hledger-chart.hs is an old pie chart generator, in need of some love.
2288 check
2290 hledger-check.hs checks more powerful account balance assertions.
2291
2293 COLUMNS The screen width used by the register command. Default: the
2294 full terminal width.
2295 LEDGER_FILE The journal file path when not specified with -f. Default:
2297 ~/.hledger.journal (on windows, perhaps C:/Users/USER/.hledger.jour‐
2298 nal).
2299
2301 Reads data from one or more files in hledger journal, timeclock, time‐
2302 dot, or CSV format specified with -f, or $LEDGER_FILE, or
2303 $HOME/.hledger.journal (on windows, perhaps
2304 C:/Users/USER/.hledger.journal).
2305
2307 The need to precede addon command options with -- when invoked from
2308 hledger is awkward.
2309 When input data contains non-ascii characters, a suitable system locale
2311 must be configured (or there will be an unhelpful error). Eg on POSIX,
2312 set LANG to something other than C.
2313 In a Microsoft Windows CMD window, non-ascii characters and colours are
2315 not supported.
2316 In a Cygwin/MSYS/Mintty window, the tab key is not supported in hledger
2318 add.
2319 Not all of Ledger's journal file syntax is supported. See file format
2321 differences.
2322 On large data files, hledger is slower and uses more memory than
2324 Ledger.
2325
2327 Here are some issues you might encounter when you run hledger (and
2328 remember you can also seek help from the IRC channel, mail list or bug
2329 tracker):
2330 Successfully installed, but "No command 'hledger' found"
2332 stack and cabal install binaries into a special directory, which should
2333 be added to your PATH environment variable. Eg on unix-like systems,
2334 that is ~/.local/bin and ~/.cabal/bin respectively.
2335 I set a custom LEDGER_FILE, but hledger is still using the default file
2337 LEDGER_FILE should be a real environment variable, not just a shell
2338 variable. The command env | grep LEDGER_FILE should show it. You may
2339 need to use export. Here's an explanation.
2340 "Illegal byte sequence" or "Invalid or incomplete multibyte or wide
2342 character" errors
2343 In order to handle non-ascii letters and symbols (like £), hledger
2344 needs an appropriate locale. This is usually configured system-wide;
2345 you can also configure it temporarily. The locale may need to be one
2346 that supports UTF-8, if you built hledger with GHC < 7.2 (or possibly
2347 always, I'm not sure yet).
2348 Here's an example of setting the locale temporarily, on ubuntu
2350 gnu/linux:
2351 $ file my.journal
2353 my.journal: UTF-8 Unicode text # <- the file is UTF8-encoded
2354 $ locale -a
2355 C
2356 en_US.utf8 # <- a UTF8-aware locale is available
2357 POSIX
2358 $ LANG=en_US.utf8 hledger -f my.journal print # <- use it for this command
2359 Here's one way to set it permanently, there are probably better ways:
2361 $ echo "export LANG=en_US.UTF-8" >>~/.bash_profile
2363 $ bash --login
2364 If we preferred to use eg fr_FR.utf8, we might have to install that
2366 first:
2367 $ apt-get install language-pack-fr
2369 $ locale -a
2370 C
2371 en_US.utf8
2372 fr_BE.utf8
2373 fr_CA.utf8
2374 fr_CH.utf8
2375 fr_FR.utf8
2376 fr_LU.utf8
2377 POSIX
2378 $ LANG=fr_FR.utf8 hledger -f my.journal print
2379 Note some platforms allow variant locale spellings, but not all (ubuntu
2381 accepts fr_FR.UTF8, mac osx requires exactly fr_FR.UTF-8).
2382
2386 Report bugs at http://bugs.hledger.org (or on the #hledger IRC channel
2387 or hledger mail list)
2388
2391 Simon Michael <simon@joyful.com> and contributors
2392
2395 Copyright (C) 2007-2016 Simon Michael.
2396 Released under GNU GPL v3 or later.
2397
2400 hledger(1), hledger-ui(1), hledger-web(1), hledger-api(1),
2401 hledger_csv(5), hledger_journal(5), hledger_timeclock(5), hledger_time‐
2402 dot(5), ledger(1)
2403 http://hledger.org
2405hledger 1.14 March 2019 hledger(1)