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 day
443 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 preceed‐
532 ing 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 will
553 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" – peri‐
558 ods will have boundaries on 2009/03/01,
559 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 boundaries
574 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 Show account names. Alias: a.
894 --declared
896 show account names declared with account directives
897 --used show account names posted to by transactions
899 --tree show short account names and their parents, as a tree
901 --flat show full account names, as a list (default)
903 --drop=N
905 in flat mode: omit N leading account name parts
906 This command lists account names, either declared with account direc‐
908 tives (–declared), posted to (–used), or both (default). With query
909 arguments, only matched account names and account names referenced by
910 matched postings are shown. It shows a flat list by default. With
911 --tree, it uses indentation to show the account hierarchy. In flat
912 mode you can add --drop N to omit the first few account name compo‐
913 nents. Account names can be depth-clipped with --depth N or depth:N.
914 Examples:
916 $ hledger accounts --tree
918 assets
919 bank
920 checking
921 saving
922 cash
923 expenses
924 food
925 supplies
926 income
927 gifts
928 salary
929 liabilities
930 debts
931 $ hledger accounts --drop 1
933 bank:checking
934 bank:saving
935 cash
936 food
937 supplies
938 gifts
939 salary
940 debts
941 $ hledger accounts
943 assets:bank:checking
944 assets:bank:saving
945 assets:cash
946 expenses:food
947 expenses:supplies
948 income:gifts
949 income:salary
950 liabilities:debts
951 activity
953 Show an ascii barchart of posting counts per interval.
954 The activity command displays an ascii histogram showing transaction
956 counts by day, week, month or other reporting interval (by day is the
957 default). With query arguments, it counts only matched transactions.
958 $ hledger activity --quarterly
960 2008-01-01 **
961 2008-04-01 *******
962 2008-07-01
963 2008-10-01 **
964 add
966 Prompt for transactions and add them to the journal.
967 --no-new-accounts
969 don't allow creating new accounts; helps prevent typos when
970 entering account names
971 Many hledger users edit their journals directly with a text editor, or
973 generate them from CSV. For more interactive data entry, there is the
974 add command, which prompts interactively on the console for new trans‐
975 actions, and appends them to the journal file (if there are multiple
976 -f FILE options, the first file is used.) Existing transactions are not
977 changed. This is the only hledger command that writes to the journal
978 file.
979 To use it, just run hledger add and follow the prompts. You can add as
981 many transactions as you like; when you are finished, enter . or press
982 control-d or control-c to exit.
983 Features:
985 · add tries to provide useful defaults, using the most similar recent
987 transaction (by description) as a template.
988 · You can also set the initial defaults with command line arguments.
990 · Readline-style edit keys can be used during data entry.
992 · The tab key will auto-complete whenever possible - accounts, descrip‐
994 tions, dates (yesterday, today, tomorrow). If the input area is
995 empty, it will insert the default value.
996 · If the journal defines a default commodity, it will be added to any
998 bare numbers entered.
999 · A parenthesised transaction code may be entered following a date.
1001 · Comments and tags may be entered following a description or amount.
1003 · If you make a mistake, enter < at any prompt to restart the transac‐
1005 tion.
1006 · Input prompts are displayed in a different colour when the terminal
1008 supports it.
1009 Example (see the tutorial for a detailed explanation):
1011 $ hledger add
1013 Adding transactions to journal file /src/hledger/examples/sample.journal
1014 Any command line arguments will be used as defaults.
1015 Use tab key to complete, readline keys to edit, enter to accept defaults.
1016 An optional (CODE) may follow transaction dates.
1017 An optional ; COMMENT may follow descriptions or amounts.
1018 If you make a mistake, enter < at any prompt to restart the transaction.
1019 To end a transaction, enter . when prompted.
1020 To quit, enter . at a date prompt or press control-d or control-c.
1021 Date [2015/05/22]:
1022 Description: supermarket
1023 Account 1: expenses:food
1024 Amount 1: $10
1025 Account 2: assets:checking
1026 Amount 2 [$-10.0]:
1027 Account 3 (or . or enter to finish this transaction): .
1028 2015/05/22 supermarket
1029 expenses:food $10
1030 assets:checking $-10.0
1031 Save this transaction to the journal ? [y]:
1033 Saved.
1034 Starting the next transaction (. or ctrl-D/ctrl-C to quit)
1035 Date [2015/05/22]: <CTRL-D> $
1036 balance
1038 Show accounts and their balances. Aliases: b, bal.
1039 --change
1041 show balance change in each period (default)
1042 --cumulative
1044 show balance change accumulated across periods (in multicolumn
1045 reports)
1046 -H --historical
1048 show historical ending balance in each period (includes postings
1049 before report start date)
1050 --tree show accounts as a tree; amounts include subaccounts (default in
1052 simple reports)
1053 --flat show accounts as a list; amounts exclude subaccounts except when
1055 account is depth-clipped (default in multicolumn reports)
1056 -A --average
1058 show a row average column (in multicolumn mode)
1059 -T --row-total
1061 show a row total column (in multicolumn mode)
1062 -N --no-total
1064 don't show the final total row
1065 --drop=N
1067 omit N leading account name parts (in flat mode)
1068 --no-elide
1070 don't squash boring parent accounts (in tree mode)
1071 --format=LINEFORMAT
1073 in single-column balance reports: use this custom line format
1074 -O FMT --output-format=FMT
1076 select the output format. Supported formats: txt, csv, html.
1077 -o FILE --output-file=FILE
1079 write output to FILE. A file extension matching one of the
1080 above formats selects that format.
1081 --pretty-tables
1083 use unicode to display prettier tables.
1084 --sort-amount
1086 sort by amount instead of account code/name (in flat mode).
1087 With multiple columns, sorts by the row total, or by row average
1088 if that is displayed.
1089 --invert
1091 display all amounts with reversed sign
1092 --budget
1094 show performance compared to budget goals defined by periodic
1095 transactions
1096 --show-unbudgeted
1098 with –budget, show unbudgeted accounts also
1099 The balance command is hledger's most versatile command. Note, despite
1101 the name, it is not always used for showing real-world account bal‐
1102 ances; the more accounting-aware balancesheet and incomestatement may
1103 be more convenient for that.
1104 By default, it displays all accounts, and each account's change in bal‐
1106 ance during the entire period of the journal. Balance changes are cal‐
1107 culated by adding up the postings in each account. You can limit the
1108 postings matched, by a query, to see fewer accounts, changes over a
1109 different time period, changes from only cleared transactions, etc.
1110 If you include an account's complete history of postings in the report,
1112 the balance change is equivalent to the account's current ending bal‐
1113 ance. For a real-world account, typically you won't have all transac‐
1114 tions in the journal; instead you'll have all transactions after a cer‐
1115 tain date, and an “opening balances” transaction setting the correct
1116 starting balance on that date. Then the balance command will show
1117 real-world account balances. In some cases the -H/–historical flag is
1118 used to ensure this (more below).
1119 The balance command can produce several styles of report:
1121 Classic balance report
1123 This is the original balance report, as found in Ledger. It usually
1124 looks like this:
1125 $ hledger balance
1127 $-1 assets
1128 $1 bank:saving
1129 $-2 cash
1130 $2 expenses
1131 $1 food
1132 $1 supplies
1133 $-2 income
1134 $-1 gifts
1135 $-1 salary
1136 $1 liabilities:debts
1137 --------------------
1138 0
1139 By default, accounts are displayed hierarchically, with subaccounts
1141 indented below their parent. At each level of the tree, accounts are
1142 sorted by account code if any, then by account name. Or with
1143 -S/--sort-amount, by their balance amount.
1144 “Boring” accounts, which contain a single interesting subaccount and no
1146 balance of their own, are elided into the following line for more com‐
1147 pact output. (Eg above, the “liabilities” account.) Use --no-elide to
1148 prevent this.
1149 Account balances are “inclusive” - they include the balances of any
1151 subaccounts.
1152 Accounts which have zero balance (and no non-zero subaccounts) are
1154 omitted. Use -E/--empty to show them.
1155 A final total is displayed by default; use -N/--no-total to suppress
1157 it, eg:
1158 $ hledger balance -p 2008/6 expenses --no-total
1160 $2 expenses
1161 $1 food
1162 $1 supplies
1163 Customising the classic balance report
1165 You can customise the layout of classic balance reports with --for‐
1166 mat FMT:
1167 $ hledger balance --format "%20(account) %12(total)"
1169 assets $-1
1170 bank:saving $1
1171 cash $-2
1172 expenses $2
1173 food $1
1174 supplies $1
1175 income $-2
1176 gifts $-1
1177 salary $-1
1178 liabilities:debts $1
1179 ---------------------------------
1180 0
1181 The FMT format string (plus a newline) specifies the formatting applied
1183 to each account/balance pair. It may contain any suitable text, with
1184 data fields interpolated like so:
1185 %[MIN][.MAX](FIELDNAME)
1187 · MIN pads with spaces to at least this width (optional)
1189 · MAX truncates at this width (optional)
1191 · FIELDNAME must be enclosed in parentheses, and can be one of:
1193 · depth_spacer - a number of spaces equal to the account's depth, or
1195 if MIN is specified, MIN * depth spaces.
1196 · account - the account's name
1198 · total - the account's balance/posted total, right justified
1200 Also, FMT can begin with an optional prefix to control how multi-com‐
1202 modity amounts are rendered:
1203 · %_ - render on multiple lines, bottom-aligned (the default)
1205 · %^ - render on multiple lines, top-aligned
1207 · %, - render on one line, comma-separated
1209 There are some quirks. Eg in one-line mode, %(depth_spacer) has no
1211 effect, instead %(account) has indentation built in.
1212 Experimentation may be needed to get pleasing results.
1213 Some example formats:
1215 · %(total) - the account's total
1217 · %-20.20(account) - the account's name, left justified, padded to 20
1219 characters and clipped at 20 characters
1220 · %,%-50(account) %25(total) - account name padded to 50 characters,
1222 total padded to 20 characters, with multiple commodities rendered on
1223 one line
1224 · %20(total) %2(depth_spacer)%-(account) - the default format for the
1226 single-column balance report
1227 Colour support
1229 The balance command shows negative amounts in red, if:
1230 · the TERM environment variable is not set to dumb
1232 · the output is not being redirected or piped anywhere
1234 Flat mode
1236 To see a flat list instead of the default hierarchical display, use
1237 --flat. In this mode, accounts (unless depth-clipped) show their full
1238 names and “exclusive” balance, excluding any subaccount balances. In
1239 this mode, you can also use --drop N to omit the first few account name
1240 components.
1241 $ hledger balance -p 2008/6 expenses -N --flat --drop 1
1243 $1 food
1244 $1 supplies
1245 Depth limited balance reports
1247 With --depth N or depth:N or just -N, balance reports show accounts
1248 only to the specified numeric depth. This is very useful to summarise
1249 a complex set of accounts and get an overview.
1250 $ hledger balance -N -1
1252 $-1 assets
1253 $2 expenses
1254 $-2 income
1255 $1 liabilities
1256 Flat-mode balance reports, which normally show exclusive balances, show
1258 inclusive balances at the depth limit.
1259 Multicolumn balance report
1261 Multicolumn or tabular balance reports are a very useful hledger fea‐
1262 ture, and usually the preferred style. They share many of the above
1263 features, but they show the report as a table, with columns represent‐
1264 ing time periods. This mode is activated by providing a reporting
1265 interval.
1266 There are three types of multicolumn balance report, showing different
1268 information:
1269 1. By default: each column shows the sum of postings in that period, ie
1271 the account's change of balance in that period. This is useful eg
1272 for a monthly income statement:
1273 $ hledger balance --quarterly income expenses -E
1275 Balance changes in 2008:
1276 || 2008q1 2008q2 2008q3 2008q4
1278 ===================++=================================
1279 expenses:food || 0 $1 0 0
1280 expenses:supplies || 0 $1 0 0
1281 income:gifts || 0 $-1 0 0
1282 income:salary || $-1 0 0 0
1283 -------------------++---------------------------------
1284 || $-1 $1 0 0
1285 2. With --cumulative: each column shows the ending balance for that
1287 period, accumulating the changes across periods, starting from 0 at
1288 the report start date:
1289 $ hledger balance --quarterly income expenses -E --cumulative
1291 Ending balances (cumulative) in 2008:
1292 || 2008/03/31 2008/06/30 2008/09/30 2008/12/31
1294 ===================++=================================================
1295 expenses:food || 0 $1 $1 $1
1296 expenses:supplies || 0 $1 $1 $1
1297 income:gifts || 0 $-1 $-1 $-1
1298 income:salary || $-1 $-1 $-1 $-1
1299 -------------------++-------------------------------------------------
1300 || $-1 0 0 0
1301 3. With --historical/-H: each column shows the actual historical ending
1303 balance for that period, accumulating the changes across periods,
1304 starting from the actual balance at the report start date. This is
1305 useful eg for a multi-period balance sheet, and when you are showing
1306 only the data after a certain start date:
1307 $ hledger balance ^assets ^liabilities --quarterly --historical --begin 2008/4/1
1309 Ending balances (historical) in 2008/04/01-2008/12/31:
1310 || 2008/06/30 2008/09/30 2008/12/31
1312 ======================++=====================================
1313 assets:bank:checking || $1 $1 0
1314 assets:bank:saving || $1 $1 $1
1315 assets:cash || $-2 $-2 $-2
1316 liabilities:debts || 0 0 $1
1317 ----------------------++-------------------------------------
1318 || 0 0 0
1319 Multicolumn balance reports display accounts in flat mode by default;
1321 to see the hierarchy, use --tree.
1322 With a reporting interval (like --quarterly above), the report
1324 start/end dates will be adjusted if necessary so that they encompass
1325 the displayed report periods. This is so that the first and last peri‐
1326 ods will be “full” and comparable to the others.
1327 The -E/--empty flag does two things in multicolumn balance reports:
1329 first, the report will show all columns within the specified report
1330 period (without -E, leading and trailing columns with all zeroes are
1331 not shown). Second, all accounts which existed at the report start
1332 date will be considered, not just the ones with activity during the
1333 report period (use -E to include low-activity accounts which would oth‐
1334 erwise would be omitted).
1335 The -T/--row-total flag adds an additional column showing the total for
1337 each row.
1338 The -A/--average flag adds a column showing the average value in each
1340 row.
1341 Here's an example of all three:
1343 $ hledger balance -Q income expenses --tree -ETA
1345 Balance changes in 2008:
1346 || 2008q1 2008q2 2008q3 2008q4 Total Average
1348 ============++===================================================
1349 expenses || 0 $2 0 0 $2 $1
1350 food || 0 $1 0 0 $1 0
1351 supplies || 0 $1 0 0 $1 0
1352 income || $-1 $-1 0 0 $-2 $-1
1353 gifts || 0 $-1 0 0 $-1 0
1354 salary || $-1 0 0 0 $-1 0
1355 ------------++---------------------------------------------------
1356 || $-1 $1 0 0 0 0
1357 # Average is rounded to the dollar here since all journal amounts are
1359 Limitations:
1361 In multicolumn reports the -V/--value flag uses the market price on the
1363 report end date, for all columns (not the price on each column's end
1364 date).
1365 Eliding of boring parent accounts in tree mode, as in the classic bal‐
1367 ance report, is not yet supported in multicolumn reports.
1368 Budget report
1370 With --budget, extra columns are displayed showing budget goals for
1371 each account and period, if any. Budget goals are defined by periodic
1372 transactions. This is very useful for comparing planned and actual
1373 income, expenses, time usage, etc. –budget is most often combined with
1374 a report interval.
1375 For example, you can take average monthly expenses in the common
1377 expense categories to construct a minimal monthly budget:
1378 ;; Budget
1380 ~ monthly
1381 income $2000
1382 expenses:food $400
1383 expenses:bus $50
1384 expenses:movies $30
1385 assets:bank:checking
1386 ;; Two months worth of expenses
1388 2017-11-01
1389 income $1950
1390 expenses:food $396
1391 expenses:bus $49
1392 expenses:movies $30
1393 expenses:supplies $20
1394 assets:bank:checking
1395 2017-12-01
1397 income $2100
1398 expenses:food $412
1399 expenses:bus $53
1400 expenses:gifts $100
1401 assets:bank:checking
1402 You can now see a monthly budget report:
1404 $ hledger balance -M --budget
1406 Budget performance in 2017/11/01-2017/12/31:
1407 || 2017/11 2017/12
1409 ======================++=================================================
1410 <unbudgeted> || $20 $100
1411 assets:bank:checking || $-2445 [99% of $-2480] $-2665 [107% of $-2480]
1412 expenses:bus || $49 [98% of $50] $53 [106% of $50]
1413 expenses:food || $396 [99% of $400] $412 [103% of $400]
1414 expenses:movies || $30 [100% of $30] 0 [0% of $30]
1415 income || $1950 [98% of $2000] $2100 [105% of $2000]
1416 ----------------------++-------------------------------------------------
1417 || 0 0
1418 By default, only accounts with budget goals during the report period
1420 are shown. --show-unbudgeted shows unbudgeted accounts as well.
1421 Top-level accounts with no budget goals anywhere below them are grouped
1422 under <unbudgeted>.
1423 You can roll over unspent budgets to next period with --cumulative:
1425 $ hledger balance -M --budget --cumulative
1427 Budget performance in 2017/11/01-2017/12/31:
1428 || 2017/11/30 2017/12/31
1430 ======================++=================================================
1431 <unbudgeted> || $20 $120
1432 assets:bank:checking || $-2445 [99% of $-2480] $-5110 [103% of $-4960]
1433 expenses:bus || $49 [98% of $50] $102 [102% of $100]
1434 expenses:food || $396 [99% of $400] $808 [101% of $800]
1435 expenses:movies || $30 [100% of $30] $30 [50% of $60]
1436 income || $1950 [98% of $2000] $4050 [101% of $4000]
1437 ----------------------++-------------------------------------------------
1438 || 0 0
1439 Note, the -S/--sort-amount flag is not yet fully supported with --bud‐
1441 get.
1442 For more examples, see Budgeting and Forecasting.
1444 Output format
1446 The balance command supports output destination and output format
1447 selection.
1448 balancesheet
1450 This command displays a simple balance sheet, showing historical ending
1451 balances of asset and liability accounts (ignoring any report begin
1452 date). It assumes that these accounts are under a top-level asset or
1453 liability account (case insensitive, plural forms also allowed). Note
1454 this report shows all account balances with normal positive sign (like
1455 conventional financial statements, unlike balance/print/register)
1456 (experimental). (bs)
1457 --change
1459 show balance change in each period, instead of historical ending
1460 balances
1461 --cumulative
1463 show balance change accumulated across periods (in multicolumn
1464 reports), instead of historical ending balances
1465 -H --historical
1467 show historical ending balance in each period (includes postings
1468 before report start date) (default)
1469 --tree show accounts as a tree; amounts include subaccounts (default in
1471 simple reports)
1472 --flat show accounts as a list; amounts exclude subaccounts except when
1474 account is depth-clipped (default in multicolumn reports)
1475 -A --average
1477 show a row average column (in multicolumn mode)
1478 -T --row-total
1480 show a row total column (in multicolumn mode)
1481 -N --no-total
1483 don't show the final total row
1484 --drop=N
1486 omit N leading account name parts (in flat mode)
1487 --no-elide
1489 don't squash boring parent accounts (in tree mode)
1490 --format=LINEFORMAT
1492 in single-column balance reports: use this custom line format
1493 --sort-amount
1495 sort by amount instead of account code/name
1496 Example:
1498 $ hledger balancesheet
1500 Balance Sheet
1501 Assets:
1503 $-1 assets
1504 $1 bank:saving
1505 $-2 cash
1506 --------------------
1507 $-1
1508 Liabilities:
1510 $1 liabilities:debts
1511 --------------------
1512 $1
1513 Total:
1515 --------------------
1516 0
1517 With a reporting interval, multiple columns will be shown, one for each
1519 report period. As with multicolumn balance reports, you can alter the
1520 report mode with --change/--cumulative/--historical. Normally bal‐
1521 ancesheet shows historical ending balances, which is what you need for
1522 a balance sheet; note this means it ignores report begin dates.
1523 This command also supports output destination and output format selec‐
1525 tion.
1526 balancesheetequity
1528 Just like balancesheet, but also reports Equity (which it assumes is
1529 under a top-level equity account).
1530 Example:
1532 $ hledger balancesheetequity
1534 Balance Sheet With Equity
1535 Assets:
1537 $-2 assets
1538 $1 bank:saving
1539 $-3 cash
1540 --------------------
1541 $-2
1542 Liabilities:
1544 $1 liabilities:debts
1545 --------------------
1546 $1
1547 Equity:
1549 $1 equity:owner
1550 --------------------
1551 $1
1552 Total:
1554 --------------------
1555 0
1556 cashflow
1558 This command displays a simple cashflow statement, showing changes in
1559 “cash” accounts. It assumes that these accounts are under a top-level
1560 asset account (case insensitive, plural forms also allowed) and do not
1561 contain receivable or A/R in their name. Note this report shows all
1562 account balances with normal positive sign (like conventional financial
1563 statements, unlike balance/print/register) (experimental). (cf)
1564 --change
1566 show balance change in each period (default)
1567 --cumulative
1569 show balance change accumulated across periods (in multicolumn
1570 reports), instead of changes during periods
1571 -H --historical
1573 show historical ending balance in each period (includes postings
1574 before report start date), instead of changes during each period
1575 --tree show accounts as a tree; amounts include subaccounts (default in
1577 simple reports)
1578 --flat show accounts as a list; amounts exclude subaccounts except when
1580 account is depth-clipped (default in multicolumn reports)
1581 -A --average
1583 show a row average column (in multicolumn mode)
1584 -T --row-total
1586 show a row total column (in multicolumn mode)
1587 -N --no-total
1589 don't show the final total row (in simple reports)
1590 --drop=N
1592 omit N leading account name parts (in flat mode)
1593 --no-elide
1595 don't squash boring parent accounts (in tree mode)
1596 --format=LINEFORMAT
1598 in single-column balance reports: use this custom line format
1599 --sort-amount
1601 sort by amount instead of account code/name
1602 Example:
1604 $ hledger cashflow
1606 Cashflow Statement
1607 Cash flows:
1609 $-1 assets
1610 $1 bank:saving
1611 $-2 cash
1612 --------------------
1613 $-1
1614 Total:
1616 --------------------
1617 $-1
1618 With a reporting interval, multiple columns will be shown, one for each
1620 report period. Normally cashflow shows changes in assets per period,
1621 though as with multicolumn balance reports you can alter the report
1622 mode with --change/--cumulative/--historical.
1623 This command also supports output destination and output format selec‐
1625 tion.
1626 check-dates
1628 Check that transactions are sorted by increasing date. With a query,
1629 only matched transactions' dates are checked.
1630 check-dupes
1632 Report account names having the same leaf but different prefixes. An
1633 example: http://stefanorodighiero.net/software/hledger-dupes.html
1634 close
1636 Print closing/opening transactions that bring some or all account bal‐
1637 ances to zero and back. Can be useful for bringing asset/liability
1638 balances across file boundaries, or for closing out income/expenses for
1639 a period. This was formerly called “equity”, as in Ledger, and that
1640 alias is also accepted. See close –help for more.
1641 files
1643 List all files included in the journal. With a REGEX argument, only
1644 file names matching the regular expression (case sensitive) are shown.
1645 help
1647 Show any of the hledger manuals.
1648 The help command displays any of the main hledger manuals, in one of
1650 several ways. Run it with no argument to list the manuals, or provide
1651 a full or partial manual name to select one.
1652 hledger manuals are available in several formats. hledger help will
1654 use the first of these display methods that it finds: info, man,
1655 $PAGER, less, stdout (or when non-interactive, just stdout). You can
1656 force a particular viewer with the --info, --man, --pager, --cat flags.
1657 $ hledger help
1659 Please choose a manual by typing "hledger help MANUAL" (a substring is ok).
1660 Manuals: hledger hledger-ui hledger-web hledger-api journal csv timeclock timedot
1661 $ hledger help h --man
1663 hledger(1) hledger User Manuals hledger(1)
1665 NAME
1667 hledger - a command-line accounting tool
1668 SYNOPSIS
1670 hledger [-f FILE] COMMAND [OPTIONS] [ARGS]
1671 hledger [-f FILE] ADDONCMD -- [OPTIONS] [ARGS]
1672 hledger
1673 DESCRIPTION
1675 hledger is a cross-platform program for tracking money, time, or any
1676 ...
1677 import
1679 Read new transactions added to each FILE since last run, and add them
1680 to the main journal file.
1681 --dry-run
1683 just show the transactions to be imported
1684 The input files are specified as arguments - no need to write -f before
1686 each one. So eg to add new transactions from all CSV files to the main
1687 journal, it's just: hledger import *.csv
1688 New transactions are detected in the same way as print –new: by assum‐
1690 ing transactions are always added to the input files in increasing date
1691 order, and by saving .latest.FILE state files.
1692 The –dry-run output is in journal format, so you can filter it, eg to
1694 see only uncategorised transactions:
1695 $ hledger import --dry ... | hledger -f- print unknown --ignore-assertions
1697 incomestatement
1699 This command displays a simple income statement, showing revenues and
1700 expenses during a period. It assumes that these accounts are under a
1701 top-level revenue or income or expense account (case insensitive, plu‐
1702 ral forms also allowed). Note this report shows all account balances
1703 with normal positive sign (like conventional financial statements,
1704 unlike balance/print/register) (experimental). (is)
1705 --change
1707 show balance change in each period (default)
1708 --cumulative
1710 show balance change accumulated across periods (in multicolumn
1711 reports), instead of changes during periods
1712 -H --historical
1714 show historical ending balance in each period (includes postings
1715 before report start date), instead of changes during each period
1716 --tree show accounts as a tree; amounts include subaccounts (default in
1718 simple reports)
1719 --flat show accounts as a list; amounts exclude subaccounts except when
1721 account is depth-clipped (default in multicolumn reports)
1722 -A --average
1724 show a row average column (in multicolumn mode)
1725 -T --row-total
1727 show a row total column (in multicolumn mode)
1728 -N --no-total
1730 don't show the final total row
1731 --drop=N
1733 omit N leading account name parts (in flat mode)
1734 --no-elide
1736 don't squash boring parent accounts (in tree mode)
1737 --format=LINEFORMAT
1739 in single-column balance reports: use this custom line format
1740 --sort-amount
1742 sort by amount instead of account code/name
1743 This command displays a simple income statement. It currently assumes
1745 that you have top-level accounts named income (or revenue) and expense
1746 (plural forms also allowed.)
1747 $ hledger incomestatement
1749 Income Statement
1750 Revenues:
1752 $-2 income
1753 $-1 gifts
1754 $-1 salary
1755 --------------------
1756 $-2
1757 Expenses:
1759 $2 expenses
1760 $1 food
1761 $1 supplies
1762 --------------------
1763 $2
1764 Total:
1766 --------------------
1767 0
1768 With a reporting interval, multiple columns will be shown, one for each
1770 report period. Normally incomestatement shows revenues/expenses per
1771 period, though as with multicolumn balance reports you can alter the
1772 report mode with --change/--cumulative/--historical.
1773 This command also supports output destination and output format selec‐
1775 tion.
1776 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 prices.
1781 Prices (and postings providing prices) can be filtered by a query.
1782 print
1784 Show transactions from the journal. Aliases: p, txns.
1785 -m STR --match=STR
1787 show the transaction whose description is most similar to STR,
1788 and is most recent
1789 --new show only newer-dated transactions added in each file since last
1791 run
1792 -x --explicit
1794 show all amounts explicitly
1795 -O FMT --output-format=FMT
1797 select the output format. Supported formats: txt, csv.
1798 -o FILE --output-file=FILE
1800 write output to FILE. A file extension matching one of the
1801 above formats selects that format.
1802 $ hledger print
1804 2008/01/01 income
1805 assets:bank:checking $1
1806 income:salary $-1
1807 2008/06/01 gift
1809 assets:bank:checking $1
1810 income:gifts $-1
1811 2008/06/02 save
1813 assets:bank:saving $1
1814 assets:bank:checking $-1
1815 2008/06/03 * eat & shop
1817 expenses:food $1
1818 expenses:supplies $1
1819 assets:cash $-2
1820 2008/12/31 * pay off
1822 liabilities:debts $1
1823 assets:bank:checking $-1
1824 The print command displays full journal entries (transactions) from the
1826 journal file in date order, tidily formatted. print's output is always
1827 a valid hledger journal. It preserves all transaction information, but
1828 it does not preserve directives or inter-transaction comments
1829 Normally, the journal entry's explicit or implicit amount style is pre‐
1831 served. Ie when an amount is omitted in the journal, it will be omit‐
1832 ted in the output. You can use the -x/--explicit flag to make all
1833 amounts explicit, which can be useful for troubleshooting or for making
1834 your journal more readable and robust against data entry errors. Note,
1835 -x will cause postings with a multi-commodity amount (these can arise
1836 when a multi-commodity transaction has an implicit amount) will be
1837 split into multiple single-commodity postings, for valid journal out‐
1838 put.
1839 With -B/--cost, amounts with transaction prices are converted to cost
1841 using that price. This can be used for troubleshooting.
1842 With -m/--match and a STR argument, print will show at most one trans‐
1844 action: the one one whose description is most similar to STR, and is
1845 most recent. STR should contain at least two characters. If there is
1846 no similar-enough match, no transaction will be shown.
1847 With --new, for each FILE being read, hledger reads (and writes) a spe‐
1849 cial state file (.latest.FILE in the same directory), containing the
1850 latest transaction date(s) that were seen last time FILE was read.
1851 When this file is found, only transactions with newer dates (and new
1852 transactions on the latest date) are printed. This is useful for
1853 ignoring already-seen entries in import data, such as downloaded CSV
1854 files. Eg:
1855 $ hledger -f bank1.csv print --new
1857 # shows transactions added since last print --new on this file
1858 This assumes that transactions added to FILE always have same or
1860 increasing dates, and that transactions on the same day do not get
1861 reordered. See also the import command.
1862 This command also supports output destination and output format selec‐
1864 tion. Here's an example of print's CSV output:
1865 $ hledger print -Ocsv
1867 "txnidx","date","date2","status","code","description","comment","account","amount","commodity","credit","debit","posting-status","posting-comment"
1868 "1","2008/01/01","","","","income","","assets:bank:checking","1","$","","1","",""
1869 "1","2008/01/01","","","","income","","income:salary","-1","$","1","","",""
1870 "2","2008/06/01","","","","gift","","assets:bank:checking","1","$","","1","",""
1871 "2","2008/06/01","","","","gift","","income:gifts","-1","$","1","","",""
1872 "3","2008/06/02","","","","save","","assets:bank:saving","1","$","","1","",""
1873 "3","2008/06/02","","","","save","","assets:bank:checking","-1","$","1","","",""
1874 "4","2008/06/03","","*","","eat & shop","","expenses:food","1","$","","1","",""
1875 "4","2008/06/03","","*","","eat & shop","","expenses:supplies","1","$","","1","",""
1876 "4","2008/06/03","","*","","eat & shop","","assets:cash","-2","$","2","","",""
1877 "5","2008/12/31","","*","","pay off","","liabilities:debts","1","$","","1","",""
1878 "5","2008/12/31","","*","","pay off","","assets:bank:checking","-1","$","1","","",""
1879 · There is one CSV record per posting, with the parent transaction's
1881 fields repeated.
1882 · The “txnidx” (transaction index) field shows which postings belong to
1884 the same transaction. (This number might change if transactions are
1885 reordered within the file, files are parsed/included in a different
1886 order, etc.)
1887 · The amount is separated into “commodity” (the symbol) and “amount”
1889 (numeric quantity) fields.
1890 · The numeric amount is repeated in either the “credit” or “debit” col‐
1892 umn, for convenience. (Those names are not accurate in the account‐
1893 ing sense; it just puts negative amounts under credit and zero or
1894 greater amounts under debit.)
1895 print-unique
1897 Print transactions which do not reuse an already-seen description.
1898 register
1900 Show postings and their running total. Aliases: r, reg.
1901 --cumulative
1903 show running total from report start date (default)
1904 -H --historical
1906 show historical running total/balance (includes postings before
1907 report start date)
1908 -A --average
1910 show running average of posting amounts instead of total
1911 (implies –empty)
1912 -r --related
1914 show postings' siblings instead
1915 -w N --width=N
1917 set output width (default: terminal width or COLUMNS. -wN,M
1918 sets description width as well)
1919 -O FMT --output-format=FMT
1921 select the output format. Supported formats: txt, csv.
1922 -o FILE --output-file=FILE
1924 write output to FILE. A file extension matching one of the
1925 above formats selects that format.
1926 The register command displays postings, one per line, and their running
1928 total. This is typically used with a query selecting a particular
1929 account, to see that account's activity:
1930 $ hledger register checking
1932 2008/01/01 income assets:bank:checking $1 $1
1933 2008/06/01 gift assets:bank:checking $1 $2
1934 2008/06/02 save assets:bank:checking $-1 $1
1935 2008/12/31 pay off assets:bank:checking $-1 0
1936 The --historical/-H flag adds the balance from any undisplayed prior
1938 postings to the running total. This is useful when you want to see
1939 only recent activity, with a historically accurate running balance:
1940 $ hledger register checking -b 2008/6 --historical
1942 2008/06/01 gift assets:bank:checking $1 $2
1943 2008/06/02 save assets:bank:checking $-1 $1
1944 2008/12/31 pay off assets:bank:checking $-1 0
1945 The --depth option limits the amount of sub-account detail displayed.
1947 The --average/-A flag shows the running average posting amount instead
1949 of the running total (so, the final number displayed is the average for
1950 the whole report period). This flag implies --empty (see below). It
1951 is affected by --historical. It works best when showing just one
1952 account and one commodity.
1953 The --related/-r flag shows the other postings in the transactions of
1955 the postings which would normally be shown.
1956 With a reporting interval, register shows summary postings, one per
1958 interval, aggregating the postings to each account:
1959 $ hledger register --monthly income
1961 2008/01 income:salary $-1 $-1
1962 2008/06 income:gifts $-1 $-2
1963 Periods with no activity, and summary postings with a zero amount, are
1965 not shown by default; use the --empty/-E flag to see them:
1966 $ hledger register --monthly income -E
1968 2008/01 income:salary $-1 $-1
1969 2008/02 0 $-1
1970 2008/03 0 $-1
1971 2008/04 0 $-1
1972 2008/05 0 $-1
1973 2008/06 income:gifts $-1 $-2
1974 2008/07 0 $-2
1975 2008/08 0 $-2
1976 2008/09 0 $-2
1977 2008/10 0 $-2
1978 2008/11 0 $-2
1979 2008/12 0 $-2
1980 Often, you'll want to see just one line per interval. The --depth
1982 option helps with this, causing subaccounts to be aggregated:
1983 $ hledger register --monthly assets --depth 1h
1985 2008/01 assets $1 $1
1986 2008/06 assets $-1 0
1987 2008/12 assets $-1 $-1
1988 Note when using report intervals, if you specify start/end dates these
1990 will be adjusted outward if necessary to contain a whole number of
1991 intervals. This ensures that the first and last intervals are full
1992 length and comparable to the others in the report.
1993 Custom register output
1995 register uses the full terminal width by default, except on windows.
1996 You can override this by setting the COLUMNS environment variable (not
1997 a bash shell variable) or by using the --width/-w option.
1998 The description and account columns normally share the space equally
2000 (about half of (width - 40) each). You can adjust this by adding a
2001 description width as part of –width's argument, comma-separated:
2002 --width W,D . Here's a diagram:
2003 <--------------------------------- width (W) ---------------------------------->
2005 date (10) description (D) account (W-41-D) amount (12) balance (12)
2006 DDDDDDDDDD dddddddddddddddddddd aaaaaaaaaaaaaaaaaaa AAAAAAAAAAAA AAAAAAAAAAAA
2007 and some examples:
2009 $ hledger reg # use terminal width (or 80 on windows)
2011 $ hledger reg -w 100 # use width 100
2012 $ COLUMNS=100 hledger reg # set with one-time environment variable
2013 $ export COLUMNS=100; hledger reg # set till session end (or window resize)
2014 $ hledger reg -w 100,40 # set overall width 100, description width 40
2015 $ hledger reg -w $COLUMNS,40 # use terminal width, and set description width
2016 This command also supports output destination and output format selec‐
2018 tion.
2019 register-match
2021 Print the one posting whose transaction description is closest to DESC,
2022 in the style of the register command. Helps ledger-autosync detect
2023 already-seen transactions when importing.
2024 rewrite
2026 Print all transactions, adding custom postings to the matched ones.
2027 roi
2029 Shows time-weighted (TWR) and money-weighted (IRR) rate of return on
2030 your investments. See roi --help for more.
2031 stats
2033 Show some journal statistics.
2034 -o FILE --output-file=FILE
2036 write output to FILE. A file extension matching one of the
2037 above formats selects that format.
2038 $ hledger stats
2040 Main journal file : /src/hledger/examples/sample.journal
2041 Included journal files :
2042 Transactions span : 2008-01-01 to 2009-01-01 (366 days)
2043 Last transaction : 2008-12-31 (2333 days ago)
2044 Transactions : 5 (0.0 per day)
2045 Transactions last 30 days: 0 (0.0 per day)
2046 Transactions last 7 days : 0 (0.0 per day)
2047 Payees/descriptions : 5
2048 Accounts : 8 (depth 3)
2049 Commodities : 1 ($)
2050 The stats command displays summary information for the whole journal,
2052 or a matched part of it. With a reporting interval, it shows a report
2053 for each report period.
2054 This command also supports output destination and output format selec‐
2056 tion.
2057 tags
2059 List all the tag names used in the journal. With a TAGREGEX argument,
2060 only tag names matching the regular expression (case insensitive) are
2061 shown. With additional QUERY arguments, only transactions matching the
2062 query are considered.
2063 test
2065 Run built-in unit tests.
2066 Prints test names and their results on stdout. If any test fails or
2068 gives an error, the exit code will be non-zero.
2069 Test names include a group prefix. If a (exact, case sensitive) group
2071 prefix, or a full test name is provided as the first argument, only
2072 that group or test is run.
2073 If a numeric second argument is provided, it will set the randomness
2075 seed, for repeatable results from tests using randomness (currently
2076 none of them).
2077 This is mainly used by developers, but it's nice to be able to san‐
2079 ity-check your installed hledger executable at any time. All tests are
2080 expected to pass - if you ever see otherwise, something has gone wrong,
2081 please report a bug!
2082
2084 hledger also searches for external add-on commands, and will include
2085 these in the commands list. These are programs or scripts in your PATH
2086 whose name starts with hledger- and ends with a recognised file exten‐
2087 sion (currently: no extension, bat,com,exe, hs,lhs,pl,py,rb,rkt,sh).
2088 Add-ons can be invoked like any hledger command, but there are a few
2090 things to be aware of. Eg if the hledger-web add-on is installed,
2091 · hledger -h web shows hledger's help, while hledger web -h shows
2093 hledger-web's help.
2094 · Flags specific to the add-on must have a preceding -- to hide them
2096 from hledger. So hledger web --serve --port 9000 will be rejected;
2097 you must use hledger web -- --serve --port 9000.
2098 · You can always run add-ons directly if preferred:
2100 hledger-web --serve --port 9000.
2101 Add-ons are a relatively easy way to add local features or experiment
2103 with new ideas. They can be written in any language, but haskell
2104 scripts have a big advantage: they can use the same hledger (and
2105 haskell) library functions that built-in commands do, for command-line
2106 options, journal parsing, reporting, etc.
2107 Here are some hledger add-ons available:
2109 Official add-ons
2111 These are maintained and released along with hledger.
2112 api
2114 hledger-api serves hledger data as a JSON web API.
2115 ui
2117 hledger-ui provides an efficient curses-style interface.
2118 web
2120 hledger-web provides a simple web interface.
2121 Third party add-ons
2123 These are maintained separately, and usually updated shortly after a
2124 hledger release.
2125 diff
2127 hledger-diff shows differences in an account's transactions between one
2128 journal file and another.
2129 iadd
2131 hledger-iadd is a curses-style, more interactive replacement for the
2132 add command.
2133 interest
2135 hledger-interest generates interest transactions for an account accord‐
2136 ing to various schemes.
2137 irr
2139 hledger-irr calculates the internal rate of return of an investment
2140 account, but it's superseded now by the built-in roi command.
2141 Experimental add-ons
2143 These are available in source form in the hledger repo's bin/ direc‐
2144 tory; installing them is pretty easy. They may be less mature and doc‐
2145 umented than built-in commands. Reading and tweaking these is a good
2146 way to start making your own!
2147 autosync
2149 hledger-autosync is a symbolic link for easily running ledger-autosync,
2150 if installed. ledger-autosync does deduplicating conversion of OFX
2151 data and some CSV formats, and can also download the data if your bank
2152 offers OFX Direct Connect.
2153 chart
2155 hledger-chart.hs is an old pie chart generator, in need of some love.
2156 check
2158 hledger-check.hs checks more powerful account balance assertions.
2159
2161 COLUMNS The screen width used by the register command. Default: the
2162 full terminal width.
2163 LEDGER_FILE The journal file path when not specified with -f. Default:
2165 ~/.hledger.journal (on windows, perhaps C:/Users/USER/.hledger.jour‐
2166 nal).
2167
2169 Reads data from one or more files in hledger journal, timeclock, time‐
2170 dot, or CSV format specified with -f, or $LEDGER_FILE, or
2171 $HOME/.hledger.journal (on windows, perhaps
2172 C:/Users/USER/.hledger.journal).
2173
2175 The need to precede addon command options with -- when invoked from
2176 hledger is awkward.
2177 When input data contains non-ascii characters, a suitable system locale
2179 must be configured (or there will be an unhelpful error). Eg on POSIX,
2180 set LANG to something other than C.
2181 In a Microsoft Windows CMD window, non-ascii characters and colours are
2183 not supported.
2184 In a Cygwin/MSYS/Mintty window, the tab key is not supported in hledger
2186 add.
2187 Not all of Ledger's journal file syntax is supported. See file format
2189 differences.
2190 On large data files, hledger is slower and uses more memory than
2192 Ledger.
2193
2195 Here are some issues you might encounter when you run hledger (and
2196 remember you can also seek help from the IRC channel, mail list or bug
2197 tracker):
2198 Successfully installed, but “No command `hledger' found”
2200 stack and cabal install binaries into a special directory, which should
2201 be added to your PATH environment variable. Eg on unix-like systems,
2202 that is ~/.local/bin and ~/.cabal/bin respectively.
2203 I set a custom LEDGER_FILE, but hledger is still using the default file
2205 LEDGER_FILE should be a real environment variable, not just a shell
2206 variable. The command env | grep LEDGER_FILE should show it. You may
2207 need to use export. Here's an explanation.
2208 “Illegal byte sequence” or “Invalid or incomplete multibyte or wide
2210 character” errors
2211 In order to handle non-ascii letters and symbols (like £), hledger
2212 needs an appropriate locale. This is usually configured system-wide;
2213 you can also configure it temporarily. The locale may need to be one
2214 that supports UTF-8, if you built hledger with GHC < 7.2 (or possibly
2215 always, I'm not sure yet).
2216 Here's an example of setting the locale temporarily, on ubuntu
2218 gnu/linux:
2219 $ file my.journal
2221 my.journal: UTF-8 Unicode text # <- the file is UTF8-encoded
2222 $ locale -a
2223 C
2224 en_US.utf8 # <- a UTF8-aware locale is available
2225 POSIX
2226 $ LANG=en_US.utf8 hledger -f my.journal print # <- use it for this command
2227 Here's one way to set it permanently, there are probably better ways:
2229 $ echo "export LANG=en_US.UTF-8" >>~/.bash_profile
2231 $ bash --login
2232 If we preferred to use eg fr_FR.utf8, we might have to install that
2234 first:
2235 $ apt-get install language-pack-fr
2237 $ locale -a
2238 C
2239 en_US.utf8
2240 fr_BE.utf8
2241 fr_CA.utf8
2242 fr_CH.utf8
2243 fr_FR.utf8
2244 fr_LU.utf8
2245 POSIX
2246 $ LANG=fr_FR.utf8 hledger -f my.journal print
2247 Note some platforms allow variant locale spellings, but not all (ubuntu
2249 accepts fr_FR.UTF8, mac osx requires exactly fr_FR.UTF-8).
2250
2254 Report bugs at http://bugs.hledger.org (or on the #hledger IRC channel
2255 or hledger mail list)
2256
2259 Simon Michael <simon@joyful.com> and contributors
2260
2263 Copyright (C) 2007-2016 Simon Michael.
2264 Released under GNU GPL v3 or later.
2265
2268 hledger(1), hledger-ui(1), hledger-web(1), hledger-api(1),
2269 hledger_csv(5), hledger_journal(5), hledger_timeclock(5), hledger_time‐
2270 dot(5), ledger(1)
2271 http://hledger.org
2273hledger 1.12 December 2018 hledger(1)