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 --alias=OLD=NEW
138 rename accounts named OLD to NEW
139 --anon anonymize accounts and payees
141 --pivot FIELDNAME
143 use some other field or tag for the account name
144 -I --ignore-assertions
146 ignore any failing balance assertions
147 General reporting options:
149 -b --begin=DATE
151 include postings/txns on or after this date
152 -e --end=DATE
154 include postings/txns before this date
155 -D --daily
157 multiperiod/multicolumn report by day
158 -W --weekly
160 multiperiod/multicolumn report by week
161 -M --monthly
163 multiperiod/multicolumn report by month
164 -Q --quarterly
166 multiperiod/multicolumn report by quarter
167 -Y --yearly
169 multiperiod/multicolumn report by year
170 -p --period=PERIODEXP
172 set start date, end date, and/or reporting interval all at once
173 using period expressions syntax (overrides the flags above)
174 --date2
176 match the secondary date instead (see command help for other
177 effects)
178 -U --unmarked
180 include only unmarked postings/txns (can combine with -P or -C)
181 -P --pending
183 include only pending postings/txns
184 -C --cleared
186 include only cleared postings/txns
187 -R --real
189 include only non-virtual postings
190 -NUM --depth=NUM
192 hide/aggregate accounts or postings more than NUM levels deep
193 -E --empty
195 show items with zero amount, normally hidden
196 -B --cost
198 convert amounts to their cost at transaction time (using the
199 transaction price, if any)
200 -V --value
202 convert amounts to their market value on the report end date
203 (using the most recent applicable market price, if any)
204 --auto apply automated posting rules to modify transactions.
206 --forecast
208 apply periodic transaction rules to generate future transac‐
209 tions, to 6 months from now or report end date.
210 When a reporting option appears more than once in the command line, the
212 last one takes precedence.
213 Some reporting options can also be written as query arguments.
215 Command options
217 To see options for a particular command, including command-specific
218 options, run: hledger COMMAND -h.
219 Command-specific options must be written after the command name, eg:
221 hledger print -x.
222 Additionally, if the command is an addon, you may need to put its
224 options after a double-hyphen, eg: hledger ui -- --watch. Or, you can
225 run the addon executable directly: hledger-ui --watch.
226 Command arguments
228 Most hledger commands accept arguments after the command name, which
229 are often a query, filtering the data in some way.
230 Argument files
232 You can save a set of command line options/arguments in a file, one per
233 line, and then reuse them by writing @FILENAME in a command line. To
234 prevent this expansion of @-arguments, precede them with a -- argument.
235 For more, see Save frequently used options.
236 Special characters
238 Option and argument values which contain problematic characters should
239 be escaped with double quotes, backslashes, or (best) single quotes.
240 Problematic characters means spaces, and also characters which are sig‐
241 nificant to your command shell, such as less-than/greater-than. Eg:
242 hledger register -p 'last year' "accounts receivable (receiv‐
243 able|payable)" amt:\>100.
244 Characters which are significant both to the shell and in regular
246 expressions sometimes need to be double-escaped. These include paren‐
247 theses, the pipe symbol and the dollar sign. Eg, to match the dollar
248 symbol, bash users should do: hledger balance cur:'\$' or hledger bal‐
249 ance cur:\\$.
250 When hledger is invoking an addon executable (like hledger-ui), options
252 and arguments get de-escaped once more, so you might need triple-escap‐
253 ing. Eg: hledger ui cur:'\\$' or hledger ui cur:\\\\$ in bash. (The
254 number of backslashes in fish shell is left as an exercise for the
255 reader.)
256 Inside a file used for argument expansion, one less level of escaping
258 is enough. (And in this case, backslashes seem to work better than
259 quotes. Eg: cur:\$).
260 If in doubt, keep things simple:
262 · run add-on executables directly
264 · write options after the command
266 · enclose problematic args in single quotes
268 · if needed, also add a backslash to escape regexp metacharacters
270 If you're really stumped, add --debug=2 to troubleshoot.
272 Input files
274 hledger reads transactions from a data file (and the add command writes
275 to it). By default this file is $HOME/.hledger.journal (or on Windows,
276 something like C:/Users/USER/.hledger.journal). You can override this
277 with the $LEDGER_FILE environment variable:
278 $ setenv LEDGER_FILE ~/finance/2016.journal
280 $ hledger stats
281 or with the -f/--file option:
283 $ hledger -f /some/file stats
285 The file name - (hyphen) means standard input:
287 $ cat some.journal | hledger -f-
289 Usually the data file is in hledger's journal format, but it can also
291 be one of several other formats, listed below. hledger detects the
292 format automatically based on the file extension, or if that is not
293 recognised, by trying each built-in “reader” in turn:
294 Reader: Reads: Used for file extensions:
296 ─────────────────────────────────────────────────────────────────────────────
297 journal hledger's journal format, also .journal .j .hledger
298 some Ledger journals .ledger
299 timeclock timeclock files (precise time .timeclock
300 logging)
301 timedot timedot files (approximate time .timedot
302 logging)
303 csv comma-separated values (data .csv
304 interchange)
305 If needed (eg to ensure correct error messages when a file has the
307 “wrong” extension), you can force a specific reader/format by prepend‐
308 ing it to the file path with a colon. Examples:
309 $ hledger -f csv:/some/csv-file.dat stats
311 $ echo 'i 2009/13/1 08:00:00' | hledger print -ftimeclock:-
312 You can also specify multiple -f options, to read multiple files as one
314 big journal. There are some limitations with this:
315 · directives in one file will not affect the other files
317 · balance assertions will not see any account balances from previous
319 files
320 If you need those, either use the include directive, or concatenate the
322 files, eg: cat a.journal b.journal | hledger -f- CMD.
323 Smart dates
325 hledger's user interfaces accept a flexible “smart date” syntax (unlike
326 dates in the journal file). Smart dates allow some english words, can
327 be relative to today's date, and can have less-significant date parts
328 omitted (defaulting to 1).
329 Examples:
331 2009/1/1, 2009/01/01, simple dates, several sep‐
333 2009-1-1, 2009.1.1 arators allowed
334 2009/1, 2009 same as above - a missing
335 day or month defaults to 1
336 1/1, january, jan, relative dates, meaning
337 this year january 1 of the current
338 year
339 next year january 1 of next year
340 this month the 1st of the current
341 month
342 this week the most recent monday
343 last week the monday of the week
344 before this one
345 lastweek spaces are optional
346 today, yesterday, tomorrow
347 Report start & end date
349 Most hledger reports show the full span of time represented by the
350 journal data, by default. So, the effective report start and end dates
351 will be the earliest and latest transaction or posting dates found in
352 the journal.
353 Often you will want to see a shorter time span, such as the current
355 month. You can specify a start and/or end date using -b/--begin,
356 -e/--end, -p/--period or a date: query (described below). All of these
357 accept the smart date syntax. One important thing to be aware of when
358 specifying end dates: as in Ledger, end dates are exclusive, so you
359 need to write the date after the last day you want to include.
360 Examples:
362 -b 2016/3/17 begin on St. Patrick's day
364 2016
365 -e 12/1 end at the start of decem‐
366 ber 1st of the current
367 year (11/30 will be the
368 last date included)
369 -b thismonth all transactions on or
370 after the 1st of the cur‐
371 rent month
372 -p thismonth all transactions in the
373 current month
374 date:2016/3/17- the above written as
375 queries instead
376 date:-12/1
377 date:thismonth-
378 date:thismonth
379 Report intervals
381 A report interval can be specified so that commands like register, bal‐
382 ance and activity will divide their reports into multiple subperiods.
383 The basic intervals can be selected with one of -D/--daily,
384 -W/--weekly, -M/--monthly, -Q/--quarterly, or -Y/--yearly. More com‐
385 plex intervals may be specified with a period expression. Report
386 intervals can not be specified with a query, currently.
387 Period expressions
389 The -p/--period option accepts period expressions, a shorthand way of
390 expressing a start date, end date, and/or report interval all at once.
391 Here's a basic period expression specifying the first quarter of 2009.
393 Note, hledger always treats start dates as inclusive and end dates as
394 exclusive:
395 -p "from 2009/1/1 to 2009/4/1"
397 Keywords like “from” and “to” are optional, and so are the spaces, as
399 long as you don't run two dates together. “to” can also be written as
400 “-”. These are equivalent to the above:
401 -p "2009/1/1 2009/4/1"
403 -p2009/1/1to2009/4/1
404 -p2009/1/1-2009/4/1
405 Dates are smart dates, so if the current year is 2009, the above can
407 also be written as:
408 -p "1/1 4/1"
410 -p "january-apr"
411 -p "this year to 4/1"
412 If you specify only one date, the missing start or end date will be the
414 earliest or latest transaction in your journal:
415 -p "from 2009/1/1" everything after january
417 1, 2009
418 -p "from 2009/1" the same
419 -p "from 2009" the same
420 -p "to 2009" everything before january
421 1, 2009
422 A single date with no “from” or “to” defines both the start and end
424 date like so:
425 -p "2009" the year 2009; equivalent
427 to “2009/1/1 to 2010/1/1”
428 -p "2009/1" the month of jan; equiva‐
429 lent to “2009/1/1 to
430 2009/2/1”
431 -p "2009/1/1" just that day; equivalent
432 to “2009/1/1 to 2009/1/2”
433 The argument of -p can also begin with, or be, a report interval
435 expression. The basic report intervals are daily, weekly, monthly,
436 quarterly, or yearly, which have the same effect as the -D,-W,-M,-Q, or
437 -Y flags. Between report interval and start/end dates (if any), the
438 word in is optional. Examples:
439 -p "weekly from 2009/1/1 to 2009/4/1"
441 -p "monthly in 2008"
442 -p "quarterly"
443 Note that weekly, monthly, quarterly and yearly intervals will always
445 start on the first day on week, month, quarter or year accordingly, and
446 will end on the last day of same period, even if associated period
447 expression specifies different explicit start and end date.
448 For example:
450 -p "weekly from 2009/1/1 to 2009/4/1" –
452 starts on 2008/12/29, closest preceed‐
453 ing Monday
454 -p "monthly in 2008/11/25" – starts on
455 2018/11/01
456 -p "quar‐
457 terly from 2009-05-05 to 2009-06-01" -
458 starts on 2009/04/01, ends on
459 2009/06/30, which are first and last
460 days of Q2 2009
461 -p "yearly from 2009-12-29" - starts on
462 2009/01/01, first day of 2009
463 The following more complex report intervals are also supported:
465 biweekly, bimonthly, every day|week|month|quarter|year,
466 every N days|weeks|months|quarters|years.
467 All of these will start on the first day of the requested period and
469 end on the last one, as described above.
470 Examples:
472 -p "bimonthly from 2008" – periods will
474 have boundaries on 2008/01/01,
475 2008/03/01, ...
476 -p "every 2 weeks" – starts on closest
477 preceeding Monday
478 -p "every 5 month from 2009/03" – peri‐
479 ods will have boundaries on 2009/03/01,
480 2009/08/01, ...
481 If you want intervals that start on arbitrary day of your choosing and
483 span a week, month or year, you need to use any of the following:
484 every Nth day of week, every <weekday>, every Nth day [of month],
486 every Nth weekday [of month], every MM/DD [of year],
487 every Nth MMM [of year], every MMM Nth [of year].
488 Examples:
490 -p "every 2nd day of week" – periods
492 will go from Tue to Tue
493 -p "every Tue" – same
494 -p "every 15th day" – period boundaries
495 will be on 15th of each month
496 -p "every 2nd Monday" – period bound‐
497 aries will be on second Monday of each
498 month
499 -p "every 11/05" – yearly periods with
500 boundaries on 5th of Nov
501 -p "every 5th Nov" – same
502 -p "every Nov 5th" – same
503 Show historical balances at end of 15th each month (N is exclusive end
505 date):
506 hledger balance -H -p "every 16th day"
508 Group postings from start of wednesday to end of next tuesday (N is
510 start date and exclusive end date):
511 hledger register checking -p "every 3rd day of week"
513 Depth limiting
515 With the --depth N option (short form: -N), commands like account, bal‐
516 ance and register will show only the uppermost accounts in the account
517 tree, down to level N. Use this when you want a summary with less
518 detail. This flag has the same effect as a depth: query argument (so
519 -2, --depth=2 or depth:2 are basically equivalent).
520 Pivoting
522 Normally hledger sums amounts, and organizes them in a hierarchy, based
523 on account name. The --pivot FIELD option causes it to sum and orga‐
524 nize hierarchy based on the value of some other field instead. FIELD
525 can be: code, description, payee, note, or the full name (case insensi‐
526 tive) of any tag. As with account names, values containing colon:sepa‐
527 rated:parts will be displayed hierarchically in reports.
528 --pivot is a general option affecting all reports; you can think of
530 hledger transforming the journal before any other processing, replacing
531 every posting's account name with the value of the specified field on
532 that posting, inheriting it from the transaction or using a blank value
533 if it's not present.
534 An example:
536 2016/02/16 Member Fee Payment
538 assets:bank account 2 EUR
539 income:member fees -2 EUR ; member: John Doe
540 Normal balance report showing account names:
542 $ hledger balance
544 2 EUR assets:bank account
545 -2 EUR income:member fees
546 --------------------
547 0
548 Pivoted balance report, using member: tag values instead:
550 $ hledger balance --pivot member
552 2 EUR
553 -2 EUR John Doe
554 --------------------
555 0
556 One way to show only amounts with a member: value (using a query,
558 described below):
559 $ hledger balance --pivot member tag:member=.
561 -2 EUR John Doe
562 --------------------
563 -2 EUR
564 Another way (the acct: query matches against the pivoted “account
566 name”):
567 $ hledger balance --pivot member acct:.
569 -2 EUR John Doe
570 --------------------
571 -2 EUR
572 Cost
574 The -B/--cost flag converts amounts to their cost at transaction time,
575 if they have a transaction price specified.
576 Market value
578 The -V/--value flag converts reported amounts to their current market
579 value. Specifically, when there is a market price (P directive) for
580 the amount's commodity, dated on or before today's date (or the report
581 end date if specified), the amount will be converted to the price's
582 commodity.
583 When there are multiple applicable P directives, -V chooses the most
585 recent one, or in case of equal dates, the last-parsed one.
586 For example:
588 # one euro is worth this many dollars from nov 1
590 P 2016/11/01 € $1.10
591 # purchase some euros on nov 3
593 2016/11/3
594 assets:euros €100
595 assets:checking
596 # the euro is worth fewer dollars by dec 21
598 P 2016/12/21 € $1.03
599 How many euros do I have ?
601 $ hledger -f t.j bal euros
603 €100 assets:euros
604 What are they worth on nov 3 ? (no report end date specified, defaults
606 to the last date in the journal)
607 $ hledger -f t.j bal euros -V
609 $110.00 assets:euros
610 What are they worth on dec 21 ?
612 $ hledger -f t.j bal euros -V -e 2016/12/21
614 $103.00 assets:euros
615 Currently, hledger's -V only uses market prices recorded with P direc‐
617 tives, not transaction prices (unlike Ledger).
618 Combining -B and -V
620 Using -B/–cost and -V/–value together is currently allowed, but the
621 results are probably not meaningful. Let us know if you find a use for
622 this.
623 Regular expressions
625 hledger uses regular expressions in a number of places:
626 · query terms, on the command line and in the hledger-web search form:
628 REGEX, desc:REGEX, cur:REGEX, tag:...=REGEX
629 · CSV rules conditional blocks: if REGEX ...
631 · account alias directives and options: alias /REGEX/ = REPLACEMENT,
633 --alias /REGEX/=REPLACEMENT
634 hledger's regular expressions come from the regex-tdfa library. In
636 general they:
637 · are case insensitive
639 · are infix matching (do not need to match the entire thing being
641 matched)
642 · are POSIX extended regular expressions
644 · also support GNU word boundaries (\<, \>, \b, \B)
646 · and parenthesised capturing groups and numeric backreferences in
648 replacement strings
649 · do not support mode modifiers like (?s)
651 Some things to note:
653 · In the alias directive and --alias option, regular expressions must
655 be enclosed in forward slashes (/REGEX/). Elsewhere in hledger,
656 these are not required.
657 · In queries, to match a regular expression metacharacter like $ as a
659 literal character, prepend a backslash. Eg to search for amounts
660 with the dollar sign in hledger-web, write cur:\$.
661 · On the command line, some metacharacters like $ have a special mean‐
663 ing to the shell and so must be escaped at least once more. See Spe‐
664 cial characters.
665
667 One of hledger's strengths is being able to quickly report on precise
668 subsets of your data. Most commands accept an optional query expres‐
669 sion, written as arguments after the command name, to filter the data
670 by date, account name or other criteria. The syntax is similar to a
671 web search: one or more space-separated search terms, quotes to enclose
672 whitespace, prefixes to match specific fields, a not: prefix to negate
673 the match.
674 We do not yet support arbitrary boolean combinations of search terms;
676 instead most commands show transactions/postings/accounts which match
677 (or negatively match):
678 · any of the description terms AND
680 · any of the account terms AND
682 · any of the status terms AND
684 · all the other terms.
686 The print command instead shows transactions which:
688 · match any of the description terms AND
690 · have any postings matching any of the positive account terms AND
692 · have no postings matching any of the negative account terms AND
694 · match all the other terms.
696 The following kinds of search terms can be used. Remember these can
698 also be prefixed with not:, eg to exclude a particular subaccount.
699 REGEX match account names by this regular expression. (No prefix is
701 equivalent to acct:).
702 acct:REGEX
704 same as above
705 amt:N, amt:<N, amt:<=N, amt:>N, amt:>=N
707 match postings with a single-commodity amount that is equal to,
708 less than, or greater than N. (Multi-commodity amounts are not
709 tested, and will always match.) The comparison has two modes: if
710 N is preceded by a + or - sign (or is 0), the two signed numbers
711 are compared. Otherwise, the absolute magnitudes are compared,
712 ignoring sign.
713 code:REGEX
715 match by transaction code (eg check number)
716 cur:REGEX
718 match postings or transactions including any amounts whose cur‐
719 rency/commodity symbol is fully matched by REGEX. (For a par‐
720 tial match, use .*REGEX.*). Note, to match characters which are
721 regex-significant, like the dollar sign ($), you need to prepend
722 \. And when using the command line you need to add one more
723 level of quoting to hide it from the shell, so eg do:
724 hledger print cur:'\$' or hledger print cur:\\$.
725 desc:REGEX
727 match transaction descriptions.
728 date:PERIODEXPR
730 match dates within the specified period. PERIODEXPR is a period
731 expression (with no report interval). Examples: date:2016,
732 date:thismonth, date:2000/2/1-2/15, date:lastweek-. If the
733 --date2 command line flag is present, this matches secondary
734 dates instead.
735 date2:PERIODEXPR
737 match secondary dates within the specified period.
738 depth:N
740 match (or display, depending on command) accounts at or above
741 this depth
742 note:REGEX
744 match transaction notes (part of description right of |, or
745 whole description when there's no |)
746 payee:REGEX
748 match transaction payee/payer names (part of description left of
749 |, or whole description when there's no |)
750 real:, real:0
752 match real or virtual postings respectively
753 status:, status:!, status:*
755 match unmarked, pending, or cleared transactions respectively
756 tag:REGEX[=REGEX]
758 match by tag name, and optionally also by tag value. Note a
759 tag: query is considered to match a transaction if it matches
760 any of the postings. Also remember that postings inherit the
761 tags of their parent transaction.
762 The following special search term is used automatically in hledger-web,
764 only:
765 inacct:ACCTNAME
767 tells hledger-web to show the transaction register for this
768 account. Can be filtered further with acct etc.
769 Some of these can also be expressed as command-line options (eg depth:2
771 is equivalent to --depth 2). Generally you can mix options and query
772 arguments, and the resulting query will be their intersection (perhaps
773 excluding the -p/--period option).
774
776 hledger provides a number of subcommands; hledger with no arguments
777 shows a list.
778 If you install additional hledger-* packages, or if you put programs or
780 scripts named hledger-NAME in your PATH, these will also be listed as
781 subcommands.
782 Run a subcommand by writing its name as first argument (eg
784 hledger incomestatement). You can also write one of the standard short
785 aliases displayed in parentheses in the command list (hledger b), or
786 any any unambiguous prefix of a command name (hledger inc).
787 Here are all the builtin commands in alphabetical order. See also
789 hledger for a more organised command list, and hledger CMD -h for
790 detailed command help.
791 accounts
793 Show account names. Alias: a.
794 --tree show short account names, as a tree
796 --flat show full account names, as a list (default)
798 --drop=N
800 in flat mode: omit N leading account name parts
801 This command lists all account names that are in use (ie, all the
803 accounts which have at least one transaction posting to them). With
804 query arguments, only matched account names are shown.
805 It shows a flat list by default. With --tree, it uses indentation to
807 show the account hierarchy.
808 In flat mode you can add --drop N to omit the first few account name
810 components.
811 Examples:
813 $ hledger accounts --tree
815 assets
816 bank
817 checking
818 saving
819 cash
820 expenses
821 food
822 supplies
823 income
824 gifts
825 salary
826 liabilities
827 debts
828 $ hledger accounts --drop 1
830 bank:checking
831 bank:saving
832 cash
833 food
834 supplies
835 gifts
836 salary
837 debts
838 $ hledger accounts
840 assets:bank:checking
841 assets:bank:saving
842 assets:cash
843 expenses:food
844 expenses:supplies
845 income:gifts
846 income:salary
847 liabilities:debts
848 activity
850 Show an ascii barchart of posting counts per interval.
851 The activity command displays an ascii histogram showing transaction
853 counts by day, week, month or other reporting interval (by day is the
854 default). With query arguments, it counts only matched transactions.
855 $ hledger activity --quarterly
857 2008-01-01 **
858 2008-04-01 *******
859 2008-07-01
860 2008-10-01 **
861 add
863 Prompt for transactions and add them to the journal.
864 --no-new-accounts
866 don't allow creating new accounts; helps prevent typos when
867 entering account names
868 Many hledger users edit their journals directly with a text editor, or
870 generate them from CSV. For more interactive data entry, there is the
871 add command, which prompts interactively on the console for new trans‐
872 actions, and appends them to the journal file (if there are multiple
873 -f FILE options, the first file is used.) Existing transactions are not
874 changed. This is the only hledger command that writes to the journal
875 file.
876 To use it, just run hledger add and follow the prompts. You can add as
878 many transactions as you like; when you are finished, enter . or press
879 control-d or control-c to exit.
880 Features:
882 · add tries to provide useful defaults, using the most similar recent
884 transaction (by description) as a template.
885 · You can also set the initial defaults with command line arguments.
887 · Readline-style edit keys can be used during data entry.
889 · The tab key will auto-complete whenever possible - accounts, descrip‐
891 tions, dates (yesterday, today, tomorrow). If the input area is
892 empty, it will insert the default value.
893 · If the journal defines a default commodity, it will be added to any
895 bare numbers entered.
896 · A parenthesised transaction code may be entered following a date.
898 · Comments and tags may be entered following a description or amount.
900 · If you make a mistake, enter < at any prompt to restart the transac‐
902 tion.
903 · Input prompts are displayed in a different colour when the terminal
905 supports it.
906 Example (see the tutorial for a detailed explanation):
908 $ hledger add
910 Adding transactions to journal file /src/hledger/examples/sample.journal
911 Any command line arguments will be used as defaults.
912 Use tab key to complete, readline keys to edit, enter to accept defaults.
913 An optional (CODE) may follow transaction dates.
914 An optional ; COMMENT may follow descriptions or amounts.
915 If you make a mistake, enter < at any prompt to restart the transaction.
916 To end a transaction, enter . when prompted.
917 To quit, enter . at a date prompt or press control-d or control-c.
918 Date [2015/05/22]:
919 Description: supermarket
920 Account 1: expenses:food
921 Amount 1: $10
922 Account 2: assets:checking
923 Amount 2 [$-10.0]:
924 Account 3 (or . or enter to finish this transaction): .
925 2015/05/22 supermarket
926 expenses:food $10
927 assets:checking $-10.0
928 Save this transaction to the journal ? [y]:
930 Saved.
931 Starting the next transaction (. or ctrl-D/ctrl-C to quit)
932 Date [2015/05/22]: <CTRL-D> $
933 balance
935 Show accounts and their balances. Aliases: b, bal.
936 --change
938 show balance change in each period (default)
939 --cumulative
941 show balance change accumulated across periods (in multicolumn
942 reports)
943 -H --historical
945 show historical ending balance in each period (includes postings
946 before report start date)
947 --tree show accounts as a tree; amounts include subaccounts (default in
949 simple reports)
950 --flat show accounts as a list; amounts exclude subaccounts except when
952 account is depth-clipped (default in multicolumn reports)
953 -A --average
955 show a row average column (in multicolumn mode)
956 -T --row-total
958 show a row total column (in multicolumn mode)
959 -N --no-total
961 don't show the final total row
962 --drop=N
964 omit N leading account name parts (in flat mode)
965 --no-elide
967 don't squash boring parent accounts (in tree mode)
968 --format=LINEFORMAT
970 in single-column balance reports: use this custom line format
971 -O FMT --output-format=FMT
973 select the output format. Supported formats: txt, csv.
974 -o FILE --output-file=FILE
976 write output to FILE. A file extension matching one of the
977 above formats selects that format.
978 --pretty-tables
980 use unicode to display prettier tables.
981 --sort-amount
983 sort by amount instead of account name (in flat mode). With
984 multiple columns, sorts by the row total, or by row average if
985 that is displayed.
986 --budget
988 show performance compared to budget goals defined by periodic
989 transactions
990 --show-unbudgeted
992 with –budget, show unbudgeted accounts also
993 The balance command displays accounts and balances. It is hledger's
995 most featureful and versatile command.
996 $ hledger balance
998 $-1 assets
999 $1 bank:saving
1000 $-2 cash
1001 $2 expenses
1002 $1 food
1003 $1 supplies
1004 $-2 income
1005 $-1 gifts
1006 $-1 salary
1007 $1 liabilities:debts
1008 --------------------
1009 0
1010 More precisely, the balance command shows the change to each account's
1012 balance caused by all (matched) postings. In the common case where you
1013 do not filter by date and your journal sets the correct opening bal‐
1014 ances, this is the same as the account's ending balance.
1015 By default, accounts are displayed hierarchically, with subaccounts
1017 indented below their parent. “Boring” accounts, which contain a single
1018 interesting subaccount and no balance of their own, are elided into the
1019 following line for more compact output. (Use --no-elide to prevent
1020 this. Eliding of boring accounts is not yet supported in multicolumn
1021 reports.)
1022 Each account's balance is the “inclusive” balance - it includes the
1024 balances of any subaccounts.
1025 Accounts which have zero balance (and no non-zero subaccounts) are
1027 omitted. Use -E/--empty to show them.
1028 A final total is displayed by default; use -N/--no-total to suppress
1030 it:
1031 $ hledger balance -p 2008/6 expenses --no-total
1033 $2 expenses
1034 $1 food
1035 $1 supplies
1036 Flat mode
1038 To see a flat list of full account names instead of the default hierar‐
1039 chical display, use --flat. In this mode, accounts (unless
1040 depth-clipped) show their “exclusive” balance, excluding any subaccount
1041 balances. In this mode, you can also use --drop N to omit the first
1042 few account name components.
1043 $ hledger balance -p 2008/6 expenses -N --flat --drop 1
1045 $1 food
1046 $1 supplies
1047 Depth limited balance reports
1049 With --depth N, balance shows accounts only to the specified depth.
1050 This is very useful to show a complex charts of accounts in less
1051 detail. In flat mode, balances from accounts below the depth limit
1052 will be shown as part of a parent account at the depth limit.
1053 $ hledger balance -N --depth 1
1055 $-1 assets
1056 $2 expenses
1057 $-2 income
1058 $1 liabilities
1059 Multicolumn balance reports
1061 With a reporting interval, multiple balance columns will be shown, one
1062 for each report period. There are three types of multi-column balance
1063 report, showing different information:
1064 1. By default: each column shows the sum of postings in that period, ie
1066 the account's change of balance in that period. This is useful eg
1067 for a monthly income statement:
1068 $ hledger balance --quarterly income expenses -E
1070 Balance changes in 2008:
1071 || 2008q1 2008q2 2008q3 2008q4
1073 ===================++=================================
1074 expenses:food || 0 $1 0 0
1075 expenses:supplies || 0 $1 0 0
1076 income:gifts || 0 $-1 0 0
1077 income:salary || $-1 0 0 0
1078 -------------------++---------------------------------
1079 || $-1 $1 0 0
1080 2. With --cumulative: each column shows the ending balance for that
1082 period, accumulating the changes across periods, starting from 0 at
1083 the report start date:
1084 $ hledger balance --quarterly income expenses -E --cumulative
1086 Ending balances (cumulative) in 2008:
1087 || 2008/03/31 2008/06/30 2008/09/30 2008/12/31
1089 ===================++=================================================
1090 expenses:food || 0 $1 $1 $1
1091 expenses:supplies || 0 $1 $1 $1
1092 income:gifts || 0 $-1 $-1 $-1
1093 income:salary || $-1 $-1 $-1 $-1
1094 -------------------++-------------------------------------------------
1095 || $-1 0 0 0
1096 3. With --historical/-H: each column shows the actual historical ending
1098 balance for that period, accumulating the changes across periods,
1099 starting from the actual balance at the report start date. This is
1100 useful eg for a multi-period balance sheet, and when you are showing
1101 only the data after a certain start date:
1102 $ hledger balance ^assets ^liabilities --quarterly --historical --begin 2008/4/1
1104 Ending balances (historical) in 2008/04/01-2008/12/31:
1105 || 2008/06/30 2008/09/30 2008/12/31
1107 ======================++=====================================
1108 assets:bank:checking || $1 $1 0
1109 assets:bank:saving || $1 $1 $1
1110 assets:cash || $-2 $-2 $-2
1111 liabilities:debts || 0 0 $1
1112 ----------------------++-------------------------------------
1113 || 0 0 0
1114 Multi-column balance reports display accounts in flat mode by default;
1116 to see the hierarchy, use --tree.
1117 With a reporting interval (like --quarterly above), the report
1119 start/end dates will be adjusted if necessary so that they encompass
1120 the displayed report periods. This is so that the first and last peri‐
1121 ods will be “full” and comparable to the others.
1122 The -E/--empty flag does two things in multicolumn balance reports:
1124 first, the report will show all columns within the specified report
1125 period (without -E, leading and trailing columns with all zeroes are
1126 not shown). Second, all accounts which existed at the report start
1127 date will be considered, not just the ones with activity during the
1128 report period (use -E to include low-activity accounts which would oth‐
1129 erwise would be omitted).
1130 The -T/--row-total flag adds an additional column showing the total for
1132 each row.
1133 The -A/--average flag adds a column showing the average value in each
1135 row.
1136 Here's an example of all three:
1138 $ hledger balance -Q income expenses --tree -ETA
1140 Balance changes in 2008:
1141 || 2008q1 2008q2 2008q3 2008q4 Total Average
1143 ============++===================================================
1144 expenses || 0 $2 0 0 $2 $1
1145 food || 0 $1 0 0 $1 0
1146 supplies || 0 $1 0 0 $1 0
1147 income || $-1 $-1 0 0 $-2 $-1
1148 gifts || 0 $-1 0 0 $-1 0
1149 salary || $-1 0 0 0 $-1 0
1150 ------------++---------------------------------------------------
1151 || $-1 $1 0 0 0 0
1152 # Average is rounded to the dollar here since all journal amounts are
1154 Budgets
1156 With --budget and a report interval, all periodic transactions in your
1157 journal with that interval, active during the requested report period,
1158 are interpreted as recurring budget goals for the specified accounts
1159 (and subaccounts), and the report will show the difference between
1160 actual and budgeted balances.
1161 For example, you can take average monthly expenses in the common
1163 expense categories to construct a minimal monthly budget:
1164 ;; Budget
1166 ~ monthly
1167 income $2000
1168 expenses:food $400
1169 expenses:bus $50
1170 expenses:movies $30
1171 assets:bank:checking
1172 ;; Two months worth of expenses
1174 2017-11-01
1175 income $1950
1176 expenses:food $396
1177 expenses:bus $49
1178 expenses:movies $30
1179 expenses:supplies $20
1180 assets:bank:checking
1181 2017-12-01
1183 income $2100
1184 expenses:food $412
1185 expenses:bus $53
1186 expenses:gifts $100
1187 assets:bank:checking
1188 You can now see a monthly budget performance report:
1190 $ hledger balance -M --budget
1192 Balance changes in 2017/11/01-2017/12/31:
1193 || 2017/11 2017/12
1195 =======================++=================================================
1196 <unbudgeted>:expenses || $20 $100
1197 assets:bank:checking || $-2445 [99% of $-2480] $-2665 [107% of $-2480]
1198 expenses:bus || $49 [98% of $50] $53 [106% of $50]
1199 expenses:food || $396 [99% of $400] $412 [103% of $400]
1200 expenses:movies || $30 [100% of $30] 0 [0% of $30]
1201 income || $1950 [98% of $2000] $2100 [105% of $2000]
1202 -----------------------++-------------------------------------------------
1203 || 0 0
1204 You can roll over unspent budgets to next period with --cumulative:
1206 $ hledger balance -M --budget --cumulative
1208 Ending balances (cumulative) in 2017/11/01-2017/12/31:
1209 || 2017/11/30 2017/12/31
1211 =======================++=================================================
1212 <unbudgeted>:expenses || $20 $120
1213 assets:bank:checking || $-2445 [99% of $-2480] $-5110 [103% of $-4960]
1214 expenses:bus || $49 [98% of $50] $102 [102% of $100]
1215 expenses:food || $396 [99% of $400] $808 [101% of $800]
1216 expenses:movies || $30 [100% of $30] $30 [50% of $60]
1217 income || $1950 [98% of $2000] $4050 [101% of $4000]
1218 -----------------------++-------------------------------------------------
1219 || 0 0
1220 Accounts with no budget goals (not mentioned in the periodic transac‐
1222 tions) will be aggregated under <unbudgeted>, unless you add the
1223 --show-unbudgeted flag to display them normally:
1224 $ hledger balance --budget --show-unbudgeted
1226 Balance changes in 2017/11/01-2017/12/31:
1227 || 2017/11 2017/12
1229 ======================++=================================================
1230 assets:bank:checking || $-2445 [99% of $-2480] $-2665 [107% of $-2480]
1231 expenses:bus || $49 [98% of $50] $53 [106% of $50]
1232 expenses:food || $396 [99% of $400] $412 [103% of $400]
1233 expenses:gifts || 0 $100
1234 expenses:movies || $30 [100% of $30] 0 [0% of $30]
1235 expenses:supplies || $20 0
1236 income || $1950 [98% of $2000] $2100 [105% of $2000]
1237 ----------------------++-------------------------------------------------
1238 || 0 0
1239 For more examples and details, see Budgeting and Forecasting.
1241 Custom balance output
1243 In simple (non-multi-column) balance reports, you can customise the
1244 output with --format FMT:
1245 $ hledger balance --format "%20(account) %12(total)"
1247 assets $-1
1248 bank:saving $1
1249 cash $-2
1250 expenses $2
1251 food $1
1252 supplies $1
1253 income $-2
1254 gifts $-1
1255 salary $-1
1256 liabilities:debts $1
1257 ---------------------------------
1258 0
1259 The FMT format string (plus a newline) specifies the formatting applied
1261 to each account/balance pair. It may contain any suitable text, with
1262 data fields interpolated like so:
1263 %[MIN][.MAX](FIELDNAME)
1265 · MIN pads with spaces to at least this width (optional)
1267 · MAX truncates at this width (optional)
1269 · FIELDNAME must be enclosed in parentheses, and can be one of:
1271 · depth_spacer - a number of spaces equal to the account's depth, or
1273 if MIN is specified, MIN * depth spaces.
1274 · account - the account's name
1276 · total - the account's balance/posted total, right justified
1278 Also, FMT can begin with an optional prefix to control how multi-com‐
1280 modity amounts are rendered:
1281 · %_ - render on multiple lines, bottom-aligned (the default)
1283 · %^ - render on multiple lines, top-aligned
1285 · %, - render on one line, comma-separated
1287 There are some quirks. Eg in one-line mode, %(depth_spacer) has no
1289 effect, instead %(account) has indentation built in.
1290 Experimentation may be needed to get pleasing results.
1291 Some example formats:
1293 · %(total) - the account's total
1295 · %-20.20(account) - the account's name, left justified, padded to 20
1297 characters and clipped at 20 characters
1298 · %,%-50(account) %25(total) - account name padded to 50 characters,
1300 total padded to 20 characters, with multiple commodities rendered on
1301 one line
1302 · %20(total) %2(depth_spacer)%-(account) - the default format for the
1304 single-column balance report
1305 Colour support
1307 The balance command shows negative amounts in red, if:
1308 · the TERM environment variable is not set to dumb
1310 · the output is not being redirected or piped anywhere
1312 Output destination
1314 The balance, print, register and stats commands can write their output
1315 to a destination other than the console. This is controlled by the
1316 -o/--output-file option.
1317 $ hledger balance -o - # write to stdout (the default)
1319 $ hledger balance -o FILE # write to FILE
1320 CSV output
1322 The balance, print and register commands can write their output as CSV.
1323 This is useful for exporting data to other applications, eg to make
1324 charts in a spreadsheet. This is controlled by the -O/--output-format
1325 option, or by specifying a .csv file extension with -o/--output-file.
1326 $ hledger balance -O csv # write CSV to stdout
1328 $ hledger balance -o FILE.csv # write CSV to FILE.csv
1329 balancesheet
1331 Show a balance sheet. Alias: bs.
1332 --change
1334 show balance change in each period, instead of historical ending
1335 balances
1336 --cumulative
1338 show balance change accumulated across periods (in multicolumn
1339 reports), instead of historical ending balances
1340 -H --historical
1342 show historical ending balance in each period (includes postings
1343 before report start date) (default)
1344 --tree show accounts as a tree; amounts include subaccounts (default in
1346 simple reports)
1347 --flat show accounts as a list; amounts exclude subaccounts except when
1349 account is depth-clipped (default in multicolumn reports)
1350 -A --average
1352 show a row average column (in multicolumn mode)
1353 -T --row-total
1355 show a row total column (in multicolumn mode)
1356 -N --no-total
1358 don't show the final total row
1359 --drop=N
1361 omit N leading account name parts (in flat mode)
1362 --no-elide
1364 don't squash boring parent accounts (in tree mode)
1365 --format=LINEFORMAT
1367 in single-column balance reports: use this custom line format
1368 --sort-amount
1370 sort by amount instead of account name
1371 This command displays a simple balance sheet. It currently assumes
1373 that you have top-level accounts named asset and liability (plural
1374 forms also allowed.)
1375 $ hledger balancesheet
1377 Balance Sheet
1378 Assets:
1380 $-1 assets
1381 $1 bank:saving
1382 $-2 cash
1383 --------------------
1384 $-1
1385 Liabilities:
1387 $1 liabilities:debts
1388 --------------------
1389 $1
1390 Total:
1392 --------------------
1393 0
1394 With a reporting interval, multiple columns will be shown, one for each
1396 report period. As with multicolumn balance reports, you can alter the
1397 report mode with --change/--cumulative/--historical. Normally bal‐
1398 ancesheet shows historical ending balances, which is what you need for
1399 a balance sheet; note this means it ignores report begin dates.
1400 balancesheetequity
1402 Show a balance sheet including equity. Alias: bse.
1403 Other than showing the equity accounts, this command is exactly the
1405 same as the command balancesheet. Please refer to it for the available
1406 options.
1407 This command displays a balancesheet. It currently assumes that you
1409 have top-level accounts named asset, liability and equity (plural forms
1410 also allowed.)
1411 $ hledger balancesheetequity
1413 Balance Sheet With Equity
1414 Assets:
1416 $-2 assets
1417 $1 bank:saving
1418 $-3 cash
1419 --------------------
1420 $-2
1421 Liabilities:
1423 $1 liabilities:debts
1424 --------------------
1425 $1
1426 Equity:
1428 $1 equity:owner
1429 --------------------
1430 $1
1431 Total:
1433 --------------------
1434 0
1435 cashflow
1437 Show a cashflow statement. Alias: cf.
1438 --change
1440 show balance change in each period (default)
1441 --cumulative
1443 show balance change accumulated across periods (in multicolumn
1444 reports), instead of changes during periods
1445 -H --historical
1447 show historical ending balance in each period (includes postings
1448 before report start date), instead of changes during each period
1449 --tree show accounts as a tree; amounts include subaccounts (default in
1451 simple reports)
1452 --flat show accounts as a list; amounts exclude subaccounts except when
1454 account is depth-clipped (default in multicolumn reports)
1455 -A --average
1457 show a row average column (in multicolumn mode)
1458 -T --row-total
1460 show a row total column (in multicolumn mode)
1461 -N --no-total
1463 don't show the final total row (in simple reports)
1464 --drop=N
1466 omit N leading account name parts (in flat mode)
1467 --no-elide
1469 don't squash boring parent accounts (in tree mode)
1470 --format=LINEFORMAT
1472 in single-column balance reports: use this custom line format
1473 --sort-amount
1475 sort by amount instead of account name
1476 This command displays a simple cashflow statement It shows the change
1478 in all “cash” (ie, liquid assets) accounts for the period. It cur‐
1479 rently assumes that cash accounts are under a top-level account named
1480 asset and do not contain receivable, :A/R or :fixed.
1481 $ hledger cashflow
1483 Cashflow Statement
1484 Cash flows:
1486 $-1 assets
1487 $1 bank:saving
1488 $-2 cash
1489 --------------------
1490 $-1
1491 Total:
1493 --------------------
1494 $-1
1495 With a reporting interval, multiple columns will be shown, one for each
1497 report period. Normally cashflow shows changes in assets per period,
1498 though as with multicolumn balance reports you can alter the report
1499 mode with --change/--cumulative/--historical.
1500 check-dates
1502 Check that transactions are sorted by increasing date. With a query,
1503 only matched transactions' dates are checked.
1504 check-dupes
1506 Report account names having the same leaf but different prefixes. An
1507 example: http://stefanorodighiero.net/software/hledger-dupes.html
1508 equity
1510 Print closing/opening transactions that bring some or all account bal‐
1511 ances to zero and back. Can be useful for bringing account balances
1512 across file boundaries.
1513 help
1515 Show any of the hledger manuals.
1516 The help command displays any of the main hledger manuals, in one of
1518 several ways. Run it with no argument to list the manuals, or provide
1519 a full or partial manual name to select one.
1520 hledger manuals are available in several formats. hledger help will
1522 use the first of these display methods that it finds: info, man,
1523 $PAGER, less, stdout (or when non-interactive, just stdout). You can
1524 force a particular viewer with the --info, --man, --pager, --cat flags.
1525 $ hledger help
1527 Please choose a manual by typing "hledger help MANUAL" (a substring is ok).
1528 Manuals: hledger hledger-ui hledger-web hledger-api journal csv timeclock timedot
1529 $ hledger help h --man
1531 hledger(1) hledger User Manuals hledger(1)
1533 NAME
1535 hledger - a command-line accounting tool
1536 SYNOPSIS
1538 hledger [-f FILE] COMMAND [OPTIONS] [ARGS]
1539 hledger [-f FILE] ADDONCMD -- [OPTIONS] [ARGS]
1540 hledger
1541 DESCRIPTION
1543 hledger is a cross-platform program for tracking money, time, or any
1544 ...
1545 import
1547 Read new transactions added to each FILE since last run, and add them
1548 to the main journal file.
1549 --dry-run
1551 just show the transactions to be imported
1552 The input files are specified as arguments - no need to write -f before
1554 each one. So eg to add new transactions from all CSV files to the main
1555 journal, it's just: hledger import *.csv
1556 New transactions are detected in the same way as print –new: by assum‐
1558 ing transactions are always added to the input files in increasing date
1559 order, and by saving .latest.FILE state files.
1560 The –dry-run output is in journal format, so you can filter it, eg to
1562 see only uncategorised transactions:
1563 $ hledger import --dry ... | hledger -f- print unknown --ignore-assertions
1565 incomestatement
1567 Show an income statement. Alias: is.
1568 --change
1570 show balance change in each period (default)
1571 --cumulative
1573 show balance change accumulated across periods (in multicolumn
1574 reports), instead of changes during periods
1575 -H --historical
1577 show historical ending balance in each period (includes postings
1578 before report start date), instead of changes during each period
1579 --tree show accounts as a tree; amounts include subaccounts (default in
1581 simple reports)
1582 --flat show accounts as a list; amounts exclude subaccounts except when
1584 account is depth-clipped (default in multicolumn reports)
1585 -A --average
1587 show a row average column (in multicolumn mode)
1588 -T --row-total
1590 show a row total column (in multicolumn mode)
1591 -N --no-total
1593 don't show the final total row
1594 --drop=N
1596 omit N leading account name parts (in flat mode)
1597 --no-elide
1599 don't squash boring parent accounts (in tree mode)
1600 --format=LINEFORMAT
1602 in single-column balance reports: use this custom line format
1603 --sort-amount
1605 sort by amount instead of account name
1606 This command displays a simple income statement. It currently assumes
1608 that you have top-level accounts named income (or revenue) and expense
1609 (plural forms also allowed.)
1610 $ hledger incomestatement
1612 Income Statement
1613 Revenues:
1615 $-2 income
1616 $-1 gifts
1617 $-1 salary
1618 --------------------
1619 $-2
1620 Expenses:
1622 $2 expenses
1623 $1 food
1624 $1 supplies
1625 --------------------
1626 $2
1627 Total:
1629 --------------------
1630 0
1631 With a reporting interval, multiple columns will be shown, one for each
1633 report period. Normally incomestatement shows revenues/expenses per
1634 period, though as with multicolumn balance reports you can alter the
1635 report mode with --change/--cumulative/--historical.
1636 prices
1638 Print all market prices from the journal.
1639 print
1641 Show transactions from the journal. Aliases: p, txns.
1642 -m STR --match=STR
1644 show the transaction whose description is most similar to STR,
1645 and is most recent
1646 --new show only newer-dated transactions added in each file since last
1648 run
1649 -x --explicit
1651 show all amounts explicitly
1652 -O FMT --output-format=FMT
1654 select the output format. Supported formats: txt, csv.
1655 -o FILE --output-file=FILE
1657 write output to FILE. A file extension matching one of the
1658 above formats selects that format.
1659 $ hledger print
1661 2008/01/01 income
1662 assets:bank:checking $1
1663 income:salary $-1
1664 2008/06/01 gift
1666 assets:bank:checking $1
1667 income:gifts $-1
1668 2008/06/02 save
1670 assets:bank:saving $1
1671 assets:bank:checking $-1
1672 2008/06/03 * eat & shop
1674 expenses:food $1
1675 expenses:supplies $1
1676 assets:cash $-2
1677 2008/12/31 * pay off
1679 liabilities:debts $1
1680 assets:bank:checking $-1
1681 The print command displays full journal entries (transactions) from the
1683 journal file in date order, tidily formatted. print's output is always
1684 a valid hledger journal. It preserves all transaction information, but
1685 it does not preserve directives or inter-transaction comments
1686 Normally, the journal entry's explicit or implicit amount style is pre‐
1688 served. Ie when an amount is omitted in the journal, it will be omit‐
1689 ted in the output. You can use the -x/--explicit flag to make all
1690 amounts explicit, which can be useful for troubleshooting or for making
1691 your journal more readable and robust against data entry errors. Note,
1692 -x will cause postings with a multi-commodity amount (these can arise
1693 when a multi-commodity transaction has an implicit amount) will be
1694 split into multiple single-commodity postings, for valid journal out‐
1695 put.
1696 With -B/--cost, amounts with transaction prices are converted to cost
1698 using that price. This can be used for troubleshooting.
1699 With -m/--match and a STR argument, print will show at most one trans‐
1701 action: the one one whose description is most similar to STR, and is
1702 most recent. STR should contain at least two characters. If there is
1703 no similar-enough match, no transaction will be shown.
1704 With --new, for each FILE being read, hledger reads (and writes) a spe‐
1706 cial state file (.latest.FILE in the same directory), containing the
1707 latest transaction date(s) that were seen last time FILE was read.
1708 When this file is found, only transactions with newer dates (and new
1709 transactions on the latest date) are printed. This is useful for
1710 ignoring already-seen entries in import data, such as downloaded CSV
1711 files. Eg:
1712 $ hledger -f bank1.csv print --new
1714 # shows transactions added since last print --new on this file
1715 This assumes that transactions added to FILE always have same or
1717 increasing dates, and that transactions on the same day do not get
1718 reordered. See also the import command.
1719 The print command also supports output destination and CSV output.
1721 Here's an example of print's CSV output:
1722 $ hledger print -Ocsv
1724 "txnidx","date","date2","status","code","description","comment","account","amount","commodity","credit","debit","posting-status","posting-comment"
1725 "1","2008/01/01","","","","income","","assets:bank:checking","1","$","","1","",""
1726 "1","2008/01/01","","","","income","","income:salary","-1","$","1","","",""
1727 "2","2008/06/01","","","","gift","","assets:bank:checking","1","$","","1","",""
1728 "2","2008/06/01","","","","gift","","income:gifts","-1","$","1","","",""
1729 "3","2008/06/02","","","","save","","assets:bank:saving","1","$","","1","",""
1730 "3","2008/06/02","","","","save","","assets:bank:checking","-1","$","1","","",""
1731 "4","2008/06/03","","*","","eat & shop","","expenses:food","1","$","","1","",""
1732 "4","2008/06/03","","*","","eat & shop","","expenses:supplies","1","$","","1","",""
1733 "4","2008/06/03","","*","","eat & shop","","assets:cash","-2","$","2","","",""
1734 "5","2008/12/31","","*","","pay off","","liabilities:debts","1","$","","1","",""
1735 "5","2008/12/31","","*","","pay off","","assets:bank:checking","-1","$","1","","",""
1736 · There is one CSV record per posting, with the parent transaction's
1738 fields repeated.
1739 · The “txnidx” (transaction index) field shows which postings belong to
1741 the same transaction. (This number might change if transactions are
1742 reordered within the file, files are parsed/included in a different
1743 order, etc.)
1744 · The amount is separated into “commodity” (the symbol) and “amount”
1746 (numeric quantity) fields.
1747 · The numeric amount is repeated in either the “credit” or “debit” col‐
1749 umn, for convenience. (Those names are not accurate in the account‐
1750 ing sense; it just puts negative amounts under credit and zero or
1751 greater amounts under debit.)
1752 print-unique
1754 Print transactions which do not reuse an already-seen description.
1755 register
1757 Show postings and their running total. Aliases: r, reg.
1758 --cumulative
1760 show running total from report start date (default)
1761 -H --historical
1763 show historical running total/balance (includes postings before
1764 report start date)
1765 -A --average
1767 show running average of posting amounts instead of total
1768 (implies –empty)
1769 -r --related
1771 show postings' siblings instead
1772 -w N --width=N
1774 set output width (default: terminal width or COLUMNS. -wN,M
1775 sets description width as well)
1776 -O FMT --output-format=FMT
1778 select the output format. Supported formats: txt, csv.
1779 -o FILE --output-file=FILE
1781 write output to FILE. A file extension matching one of the
1782 above formats selects that format.
1783 The register command displays postings, one per line, and their running
1785 total. This is typically used with a query selecting a particular
1786 account, to see that account's activity:
1787 $ hledger register checking
1789 2008/01/01 income assets:bank:checking $1 $1
1790 2008/06/01 gift assets:bank:checking $1 $2
1791 2008/06/02 save assets:bank:checking $-1 $1
1792 2008/12/31 pay off assets:bank:checking $-1 0
1793 The --historical/-H flag adds the balance from any undisplayed prior
1795 postings to the running total. This is useful when you want to see
1796 only recent activity, with a historically accurate running balance:
1797 $ hledger register checking -b 2008/6 --historical
1799 2008/06/01 gift assets:bank:checking $1 $2
1800 2008/06/02 save assets:bank:checking $-1 $1
1801 2008/12/31 pay off assets:bank:checking $-1 0
1802 The --depth option limits the amount of sub-account detail displayed.
1804 The --average/-A flag shows the running average posting amount instead
1806 of the running total (so, the final number displayed is the average for
1807 the whole report period). This flag implies --empty (see below). It
1808 is affected by --historical. It works best when showing just one
1809 account and one commodity.
1810 The --related/-r flag shows the other postings in the transactions of
1812 the postings which would normally be shown.
1813 With a reporting interval, register shows summary postings, one per
1815 interval, aggregating the postings to each account:
1816 $ hledger register --monthly income
1818 2008/01 income:salary $-1 $-1
1819 2008/06 income:gifts $-1 $-2
1820 Periods with no activity, and summary postings with a zero amount, are
1822 not shown by default; use the --empty/-E flag to see them:
1823 $ hledger register --monthly income -E
1825 2008/01 income:salary $-1 $-1
1826 2008/02 0 $-1
1827 2008/03 0 $-1
1828 2008/04 0 $-1
1829 2008/05 0 $-1
1830 2008/06 income:gifts $-1 $-2
1831 2008/07 0 $-2
1832 2008/08 0 $-2
1833 2008/09 0 $-2
1834 2008/10 0 $-2
1835 2008/11 0 $-2
1836 2008/12 0 $-2
1837 Often, you'll want to see just one line per interval. The --depth
1839 option helps with this, causing subaccounts to be aggregated:
1840 $ hledger register --monthly assets --depth 1h
1842 2008/01 assets $1 $1
1843 2008/06 assets $-1 0
1844 2008/12 assets $-1 $-1
1845 Note when using report intervals, if you specify start/end dates these
1847 will be adjusted outward if necessary to contain a whole number of
1848 intervals. This ensures that the first and last intervals are full
1849 length and comparable to the others in the report.
1850 Custom register output
1852 register uses the full terminal width by default, except on windows.
1853 You can override this by setting the COLUMNS environment variable (not
1854 a bash shell variable) or by using the --width/-w option.
1855 The description and account columns normally share the space equally
1857 (about half of (width - 40) each). You can adjust this by adding a
1858 description width as part of –width's argument, comma-separated:
1859 --width W,D . Here's a diagram:
1860 <--------------------------------- width (W) ---------------------------------->
1862 date (10) description (D) account (W-41-D) amount (12) balance (12)
1863 DDDDDDDDDD dddddddddddddddddddd aaaaaaaaaaaaaaaaaaa AAAAAAAAAAAA AAAAAAAAAAAA
1864 and some examples:
1866 $ hledger reg # use terminal width (or 80 on windows)
1868 $ hledger reg -w 100 # use width 100
1869 $ COLUMNS=100 hledger reg # set with one-time environment variable
1870 $ export COLUMNS=100; hledger reg # set till session end (or window resize)
1871 $ hledger reg -w 100,40 # set overall width 100, description width 40
1872 $ hledger reg -w $COLUMNS,40 # use terminal width, and set description width
1873 The register command also supports the -o/--output-file and -O/--out‐
1875 put-format options for controlling output destination and CSV output.
1876 register-match
1878 Print the one posting whose transaction description is closest to DESC,
1879 in the style of the register command. Helps ledger-autosync detect
1880 already-seen transactions when importing.
1881 rewrite
1883 Print all transactions, adding custom postings to the matched ones.
1884 stats
1886 Show some journal statistics.
1887 -o FILE --output-file=FILE
1889 write output to FILE. A file extension matching one of the
1890 above formats selects that format.
1891 $ hledger stats
1893 Main journal file : /src/hledger/examples/sample.journal
1894 Included journal files :
1895 Transactions span : 2008-01-01 to 2009-01-01 (366 days)
1896 Last transaction : 2008-12-31 (2333 days ago)
1897 Transactions : 5 (0.0 per day)
1898 Transactions last 30 days: 0 (0.0 per day)
1899 Transactions last 7 days : 0 (0.0 per day)
1900 Payees/descriptions : 5
1901 Accounts : 8 (depth 3)
1902 Commodities : 1 ($)
1903 The stats command displays summary information for the whole journal,
1905 or a matched part of it. With a reporting interval, it shows a report
1906 for each report period.
1907 The stats command also supports -o/--output-file for controlling output
1909 destination.
1910 tags
1912 List all the tag names used in the journal. With a TAGREGEX argument,
1913 only tag names matching the regular expression (case insensitive) are
1914 shown. With additional QUERY arguments, only transactions matching the
1915 query are considered.
1916 test
1918 Run built-in unit tests.
1919 $ hledger test
1921 Cases: 74 Tried: 74 Errors: 0 Failures: 0
1922 This command runs hledger's built-in unit tests and displays a quick
1924 report. With a regular expression argument, it selects only tests with
1925 matching names. It's mainly used in development, but it's also nice to
1926 be able to check your hledger executable for smoke at any time.
1927
1929 hledger also searches for external add-on commands, and will include
1930 these in the commands list. These are programs or scripts in your PATH
1931 whose name starts with hledger- and ends with a recognised file exten‐
1932 sion (currently: no extension, bat,com,exe, hs,lhs,pl,py,rb,rkt,sh).
1933 Add-ons can be invoked like any hledger command, but there are a few
1935 things to be aware of. Eg if the hledger-web add-on is installed,
1936 · hledger -h web shows hledger's help, while hledger web -h shows
1938 hledger-web's help.
1939 · Flags specific to the add-on must have a preceding -- to hide them
1941 from hledger. So hledger web --serve --port 9000 will be rejected;
1942 you must use hledger web -- --serve --port 9000.
1943 · You can always run add-ons directly if preferred:
1945 hledger-web --serve --port 9000.
1946 Add-ons are a relatively easy way to add local features or experiment
1948 with new ideas. They can be written in any language, but haskell
1949 scripts have a big advantage: they can use the same hledger (and
1950 haskell) library functions that built-in commands do, for command-line
1951 options, journal parsing, reporting, etc.
1952 Here are some hledger add-ons available:
1954 Official add-ons
1956 These are maintained and released along with hledger.
1957 api
1959 hledger-api serves hledger data as a JSON web API.
1960 ui
1962 hledger-ui provides an efficient curses-style interface.
1963 web
1965 hledger-web provides a simple web interface.
1966 Third party add-ons
1968 These are maintained separately, and usually updated shortly after a
1969 hledger release.
1970 diff
1972 hledger-diff shows differences in an account's transactions between one
1973 journal file and another.
1974 iadd
1976 hledger-iadd is a curses-style, more interactive replacement for the
1977 add command.
1978 interest
1980 hledger-interest generates interest transactions for an account accord‐
1981 ing to various schemes.
1982 irr
1984 hledger-irr calculates the internal rate of return of an investment
1985 account.
1986 Experimental add-ons
1988 These are available in source form in the hledger repo's bin/ direc‐
1989 tory; installing them is pretty easy. They may be less mature and doc‐
1990 umented than built-in commands. Reading and tweaking these is a good
1991 way to start making your own!
1992 autosync
1994 hledger-autosync is a symbolic link for easily running ledger-autosync,
1995 if installed. ledger-autosync does deduplicating conversion of OFX
1996 data and some CSV formats, and can also download the data if your bank
1997 offers OFX Direct Connect.
1998 budget
2000 hledger-budget.hs adds more budget-tracking features to hledger.
2001 chart
2003 hledger-chart.hs is an old pie chart generator, in need of some love.
2004 check
2006 hledger-check.hs checks more powerful account balance assertions.
2007
2009 COLUMNS The screen width used by the register command. Default: the
2010 full terminal width.
2011 LEDGER_FILE The journal file path when not specified with -f. Default:
2013 ~/.hledger.journal (on windows, perhaps C:/Users/USER/.hledger.jour‐
2014 nal).
2015
2017 Reads data from one or more files in hledger journal, timeclock, time‐
2018 dot, or CSV format specified with -f, or $LEDGER_FILE, or
2019 $HOME/.hledger.journal (on windows, perhaps
2020 C:/Users/USER/.hledger.journal).
2021
2023 The need to precede addon command options with -- when invoked from
2024 hledger is awkward.
2025 When input data contains non-ascii characters, a suitable system locale
2027 must be configured (or there will be an unhelpful error). Eg on POSIX,
2028 set LANG to something other than C.
2029 In a Microsoft Windows CMD window, non-ascii characters and colours are
2031 not supported.
2032 In a Cygwin/MSYS/Mintty window, the tab key is not supported in hledger
2034 add.
2035 Not all of Ledger's journal file syntax is supported. See file format
2037 differences.
2038 On large data files, hledger is slower and uses more memory than
2040 Ledger.
2041
2043 Here are some issues you might encounter when you run hledger (and
2044 remember you can also seek help from the IRC channel, mail list or bug
2045 tracker):
2046 Successfully installed, but “No command `hledger' found”
2048 stack and cabal install binaries into a special directory, which should
2049 be added to your PATH environment variable. Eg on unix-like systems,
2050 that is ~/.local/bin and ~/.cabal/bin respectively.
2051 I set a custom LEDGER_FILE, but hledger is still using the default file
2053 LEDGER_FILE should be a real environment variable, not just a shell
2054 variable. The command env | grep LEDGER_FILE should show it. You may
2055 need to use export. Here's an explanation.
2056 “Illegal byte sequence” or “Invalid or incomplete multibyte or wide
2058 character” errors
2059 In order to handle non-ascii letters and symbols (like £), hledger
2060 needs an appropriate locale. This is usually configured system-wide;
2061 you can also configure it temporarily. The locale may need to be one
2062 that supports UTF-8, if you built hledger with GHC < 7.2 (or possibly
2063 always, I'm not sure yet).
2064 Here's an example of setting the locale temporarily, on ubuntu
2066 gnu/linux:
2067 $ file my.journal
2069 my.journal: UTF-8 Unicode text # <- the file is UTF8-encoded
2070 $ locale -a
2071 C
2072 en_US.utf8 # <- a UTF8-aware locale is available
2073 POSIX
2074 $ LANG=en_US.utf8 hledger -f my.journal print # <- use it for this command
2075 Here's one way to set it permanently, there are probably better ways:
2077 $ echo "export LANG=en_US.UTF-8" >>~/.bash_profile
2079 $ bash --login
2080 If we preferred to use eg fr_FR.utf8, we might have to install that
2082 first:
2083 $ apt-get install language-pack-fr
2085 $ locale -a
2086 C
2087 en_US.utf8
2088 fr_BE.utf8
2089 fr_CA.utf8
2090 fr_CH.utf8
2091 fr_FR.utf8
2092 fr_LU.utf8
2093 POSIX
2094 $ LANG=fr_FR.utf8 hledger -f my.journal print
2095 Note some platforms allow variant locale spellings, but not all (ubuntu
2097 accepts fr_FR.UTF8, mac osx requires exactly fr_FR.UTF-8).
2098
2102 Report bugs at http://bugs.hledger.org (or on the #hledger IRC channel
2103 or hledger mail list)
2104
2107 Simon Michael <simon@joyful.com> and contributors
2108
2111 Copyright (C) 2007-2016 Simon Michael.
2112 Released under GNU GPL v3 or later.
2113
2116 hledger(1), hledger-ui(1), hledger-web(1), hledger-api(1),
2117 hledger_csv(5), hledger_journal(5), hledger_timeclock(5), hledger_time‐
2118 dot(5), ledger(1)
2119 http://hledger.org
2121hledger 1.5 December 2017 hledger(1)