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 (and vice-versa in
196 hledger-ui/hledger-web)
197 -B --cost
199 convert amounts to their cost at transaction time (using the
200 transaction price, if any)
201 -V --value
203 convert amounts to their market value on the report end date
204 (using the most recent applicable market price, if any)
205 --auto apply automated posting rules to modify transactions.
207 --forecast
209 apply periodic transaction rules to generate future transac‐
210 tions, to 6 months from now or report end date.
211 When a reporting option appears more than once in the command line, the
213 last one takes precedence.
214 Some reporting options can also be written as query arguments.
216 Command options
218 To see options for a particular command, including command-specific
219 options, run: hledger COMMAND -h.
220 Command-specific options must be written after the command name, eg:
222 hledger print -x.
223 Additionally, if the command is an addon, you may need to put its
225 options after a double-hyphen, eg: hledger ui -- --watch. Or, you can
226 run the addon executable directly: hledger-ui --watch.
227 Command arguments
229 Most hledger commands accept arguments after the command name, which
230 are often a query, filtering the data in some way.
231 Argument files
233 You can save a set of command line options/arguments in a file, one per
234 line, and then reuse them by writing @FILENAME in a command line. To
235 prevent this expansion of @-arguments, precede them with a -- argument.
236 For more, see Save frequently used options.
237 Special characters
239 Option and argument values which contain problematic characters should
240 be escaped with double quotes, backslashes, or (best) single quotes.
241 Problematic characters means spaces, and also characters which are sig‐
242 nificant to your command shell, such as less-than/greater-than. Eg:
243 hledger register -p 'last year' "accounts receivable (receiv‐
244 able|payable)" amt:\>100.
245 Characters which are significant both to the shell and in regular
247 expressions sometimes need to be double-escaped. These include paren‐
248 theses, the pipe symbol and the dollar sign. Eg, to match the dollar
249 symbol, bash users should do: hledger balance cur:'\$' or hledger bal‐
250 ance cur:\\$.
251 When hledger is invoking an addon executable (like hledger-ui), options
253 and arguments get de-escaped once more, so you might need triple-escap‐
254 ing. Eg: hledger ui cur:'\\$' or hledger ui cur:\\\\$ in bash. (The
255 number of backslashes in fish shell is left as an exercise for the
256 reader.)
257 Inside a file used for argument expansion, one less level of escaping
259 is enough. (And in this case, backslashes seem to work better than
260 quotes. Eg: cur:\$).
261 If in doubt, keep things simple:
263 · run add-on executables directly
265 · write options after the command
267 · enclose problematic args in single quotes
269 · if needed, also add a backslash to escape regexp metacharacters
271 If you're really stumped, add --debug=2 to troubleshoot.
273 Input files
275 hledger reads transactions from a data file (and the add command writes
276 to it). By default this file is $HOME/.hledger.journal (or on Windows,
277 something like C:/Users/USER/.hledger.journal). You can override this
278 with the $LEDGER_FILE environment variable:
279 $ setenv LEDGER_FILE ~/finance/2016.journal
281 $ hledger stats
282 or with the -f/--file option:
284 $ hledger -f /some/file stats
286 The file name - (hyphen) means standard input:
288 $ cat some.journal | hledger -f-
290 Usually the data file is in hledger's journal format, but it can also
292 be one of several other formats, listed below. hledger detects the
293 format automatically based on the file extension, or if that is not
294 recognised, by trying each built-in “reader” in turn:
295 Reader: Reads: Used for file extensions:
297 ─────────────────────────────────────────────────────────────────────────────
298 journal hledger's journal format, also .journal .j .hledger
299 some Ledger journals .ledger
300 timeclock timeclock files (precise time .timeclock
301 logging)
302 timedot timedot files (approximate time .timedot
303 logging)
304 csv comma-separated values (data .csv
305 interchange)
306 If needed (eg to ensure correct error messages when a file has the
308 “wrong” extension), you can force a specific reader/format by prepend‐
309 ing it to the file path with a colon. Examples:
310 $ hledger -f csv:/some/csv-file.dat stats
312 $ echo 'i 2009/13/1 08:00:00' | hledger print -ftimeclock:-
313 You can also specify multiple -f options, to read multiple files as one
315 big journal. There are some limitations with this:
316 · directives in one file will not affect the other files
318 · balance assertions will not see any account balances from previous
320 files
321 If you need those, either use the include directive, or concatenate the
323 files, eg: cat a.journal b.journal | hledger -f- CMD.
324 Smart dates
326 hledger's user interfaces accept a flexible “smart date” syntax (unlike
327 dates in the journal file). Smart dates allow some english words, can
328 be relative to today's date, and can have less-significant date parts
329 omitted (defaulting to 1).
330 Examples:
332 2004/10/1, 2004-01-01, exact date, several sepa‐
334 2004.9.1 rators allowed. Year is
335 4+ digits, month is 1-12,
336 day is 1-31
337 2004 start of year
338 2004/10 start of month
340 10/1 month and day in current
341 year
342 21 day in current month
343 october, oct start of month in current
344 year
345 yesterday, today, tomorrow -1, 0, 1 days from today
346 last/this/next day/week/month/quar‐ -1, 0, 1 periods from the
347 ter/year current period
348 20181201 8 digit YYYYMMDD with
349 valid year month and day
350 201812 6 digit YYYYMM with valid
351 year and month
352 Counterexamples - malformed digit sequences might give surprising
354 results:
355 201813 6 digits with an invalid
357 month is parsed as start
358 of 6-digit year
359 20181301 8 digits with an invalid
360 month is parsed as start
361 of 8-digit year
362 20181232 8 digits with an invalid
363 day gives an error
364 201801012 9+ digits beginning with a
365 valid YYYYMMDD gives an
366 error
367 Report start & end date
369 Most hledger reports show the full span of time represented by the
370 journal data, by default. So, the effective report start and end dates
371 will be the earliest and latest transaction or posting dates found in
372 the journal.
373 Often you will want to see a shorter time span, such as the current
375 month. You can specify a start and/or end date using -b/--begin,
376 -e/--end, -p/--period or a date: query (described below). All of these
377 accept the smart date syntax. One important thing to be aware of when
378 specifying end dates: as in Ledger, end dates are exclusive, so you
379 need to write the date after the last day you want to include.
380 Examples:
382 -b 2016/3/17 begin on St. Patrick's day
384 2016
385 -e 12/1 end at the start of decem‐
386 ber 1st of the current
387 year (11/30 will be the
388 last date included)
389 -b thismonth all transactions on or
390 after the 1st of the cur‐
391 rent month
392 -p thismonth all transactions in the
393 current month
394 date:2016/3/17- the above written as
395 queries instead
396 date:-12/1
397 date:thismonth-
398 date:thismonth
399 Report intervals
401 A report interval can be specified so that commands like register, bal‐
402 ance and activity will divide their reports into multiple subperiods.
403 The basic intervals can be selected with one of -D/--daily,
404 -W/--weekly, -M/--monthly, -Q/--quarterly, or -Y/--yearly. More com‐
405 plex intervals may be specified with a period expression. Report
406 intervals can not be specified with a query, currently.
407 Period expressions
409 The -p/--period option accepts period expressions, a shorthand way of
410 expressing a start date, end date, and/or report interval all at once.
411 Here's a basic period expression specifying the first quarter of 2009.
413 Note, hledger always treats start dates as inclusive and end dates as
414 exclusive:
415 -p "from 2009/1/1 to 2009/4/1"
417 Keywords like “from” and “to” are optional, and so are the spaces, as
419 long as you don't run two dates together. “to” can also be written as
420 “-”. These are equivalent to the above:
421 -p "2009/1/1 2009/4/1"
423 -p2009/1/1to2009/4/1
424 -p2009/1/1-2009/4/1
425 Dates are smart dates, so if the current year is 2009, the above can
427 also be written as:
428 -p "1/1 4/1"
430 -p "january-apr"
431 -p "this year to 4/1"
432 If you specify only one date, the missing start or end date will be the
434 earliest or latest transaction in your journal:
435 -p "from 2009/1/1" everything after january
437 1, 2009
438 -p "from 2009/1" the same
439 -p "from 2009" the same
440 -p "to 2009" everything before january
441 1, 2009
442 A single date with no “from” or “to” defines both the start and end
444 date like so:
445 -p "2009" the year 2009; equivalent
447 to “2009/1/1 to 2010/1/1”
448 -p "2009/1" the month of jan; equiva‐
449 lent to “2009/1/1 to
450 2009/2/1”
451 -p "2009/1/1" just that day; equivalent
452 to “2009/1/1 to 2009/1/2”
453 The argument of -p can also begin with, or be, a report interval
455 expression. The basic report intervals are daily, weekly, monthly,
456 quarterly, or yearly, which have the same effect as the -D,-W,-M,-Q, or
457 -Y flags. Between report interval and start/end dates (if any), the
458 word in is optional. Examples:
459 -p "weekly from 2009/1/1 to 2009/4/1"
461 -p "monthly in 2008"
462 -p "quarterly"
463 Note that weekly, monthly, quarterly and yearly intervals will always
465 start on the first day on week, month, quarter or year accordingly, and
466 will end on the last day of same period, even if associated period
467 expression specifies different explicit start and end date.
468 For example:
470 -p "weekly from 2009/1/1 to 2009/4/1" –
472 starts on 2008/12/29, closest preceed‐
473 ing Monday
474 -p "monthly in 2008/11/25" – starts on
475 2018/11/01
476 -p "quar‐
478 terly from 2009-05-05 to 2009-06-01" -
479 starts on 2009/04/01, ends on
480 2009/06/30, which are first and last
481 days of Q2 2009
482 -p "yearly from 2009-12-29" - starts on
483 2009/01/01, first day of 2009
484 The following more complex report intervals are also supported:
486 biweekly, bimonthly, every day|week|month|quarter|year,
487 every N days|weeks|months|quarters|years.
488 All of these will start on the first day of the requested period and
490 end on the last one, as described above.
491 Examples:
493 -p "bimonthly from 2008" – periods will
495 have boundaries on 2008/01/01,
496 2008/03/01, ...
497 -p "every 2 weeks" – starts on closest
498 preceeding Monday
499 -p "every 5 month from 2009/03" – peri‐
500 ods will have boundaries on 2009/03/01,
501 2009/08/01, ...
502 If you want intervals that start on arbitrary day of your choosing and
504 span a week, month or year, you need to use any of the following:
505 every Nth day of week, every <weekday>, every Nth day [of month],
507 every Nth weekday [of month], every MM/DD [of year],
508 every Nth MMM [of year], every MMM Nth [of year].
509 Examples:
511 -p "every 2nd day of week" – periods
513 will go from Tue to Tue
514 -p "every Tue" – same
515 -p "every 15th day" – period boundaries
516 will be on 15th of each month
517 -p "every 2nd Monday" – period bound‐
518 aries will be on second Monday of each
519 month
520 -p "every 11/05" – yearly periods with
521 boundaries on 5th of Nov
522 -p "every 5th Nov" – same
523 -p "every Nov 5th" – same
524 Show historical balances at end of 15th each month (N is exclusive end
526 date):
527 hledger balance -H -p "every 16th day"
529 Group postings from start of wednesday to end of next tuesday (N is
531 start date and exclusive end date):
532 hledger register checking -p "every 3rd day of week"
534 Depth limiting
536 With the --depth N option (short form: -N), commands like account, bal‐
537 ance and register will show only the uppermost accounts in the account
538 tree, down to level N. Use this when you want a summary with less
539 detail. This flag has the same effect as a depth: query argument (so
540 -2, --depth=2 or depth:2 are basically equivalent).
541 Pivoting
543 Normally hledger sums amounts, and organizes them in a hierarchy, based
544 on account name. The --pivot FIELD option causes it to sum and orga‐
545 nize hierarchy based on the value of some other field instead. FIELD
546 can be: code, description, payee, note, or the full name (case insensi‐
547 tive) of any tag. As with account names, values containing colon:sepa‐
548 rated:parts will be displayed hierarchically in reports.
549 --pivot is a general option affecting all reports; you can think of
551 hledger transforming the journal before any other processing, replacing
552 every posting's account name with the value of the specified field on
553 that posting, inheriting it from the transaction or using a blank value
554 if it's not present.
555 An example:
557 2016/02/16 Member Fee Payment
559 assets:bank account 2 EUR
560 income:member fees -2 EUR ; member: John Doe
561 Normal balance report showing account names:
563 $ hledger balance
565 2 EUR assets:bank account
566 -2 EUR income:member fees
567 --------------------
568 0
569 Pivoted balance report, using member: tag values instead:
571 $ hledger balance --pivot member
573 2 EUR
574 -2 EUR John Doe
575 --------------------
576 0
577 One way to show only amounts with a member: value (using a query,
579 described below):
580 $ hledger balance --pivot member tag:member=.
582 -2 EUR John Doe
583 --------------------
584 -2 EUR
585 Another way (the acct: query matches against the pivoted “account
587 name”):
588 $ hledger balance --pivot member acct:.
590 -2 EUR John Doe
591 --------------------
592 -2 EUR
593 Cost
595 The -B/--cost flag converts amounts to their cost at transaction time,
596 if they have a transaction price specified.
597 Market value
599 The -V/--value flag converts reported amounts to their current market
600 value.
601 Specifically, when there is a market price (P directive) for the
602 amount's commodity, dated on or before today's date (or the report end
603 date if specified), the amount will be converted to the price's commod‐
604 ity.
605 When there are multiple applicable P directives, -V chooses the most
607 recent one, or in case of equal dates, the last-parsed one.
608 For example:
610 # one euro is worth this many dollars from nov 1
612 P 2016/11/01 € $1.10
613 # purchase some euros on nov 3
615 2016/11/3
616 assets:euros €100
617 assets:checking
618 # the euro is worth fewer dollars by dec 21
620 P 2016/12/21 € $1.03
621 How many euros do I have ?
623 $ hledger -f t.j bal -N euros
625 €100 assets:euros
626 What are they worth at end of nov 3 ?
628 $ hledger -f t.j bal -N euros -V -e 2016/11/4
630 $110.00 assets:euros
631 What are they worth after 2016/12/21 ? (no report end date specified,
633 defaults to today)
634 $ hledger -f t.j bal -N euros -V
636 $103.00 assets:euros
637 Currently, hledger's -V only uses market prices recorded with P direc‐
639 tives, not transaction prices (unlike Ledger).
640 Currently, -V has a limitation in multicolumn balance reports: it uses
642 the market prices on the report end date for all columns. (Instead of
643 the prices on each column's end date.)
644 Combining -B and -V
646 Using -B/–cost and -V/–value together is currently allowed, but the
647 results are probably not meaningful. Let us know if you find a use for
648 this.
649 Output destination
651 Some commands (print, register, stats, the balance commands) can write
652 their output to a destination other than the console. This is con‐
653 trolled by the -o/--output-file option.
654 $ hledger balance -o - # write to stdout (the default)
656 $ hledger balance -o FILE # write to FILE
657 Output format
659 Some commands can write their output in other formats. Eg print and
660 register can output CSV, and the balance commands can output CSV or
661 HTML. This is controlled by the -O/--output-format option, or by spec‐
662 ifying a .csv or .html file extension with -o/--output-file.
663 $ hledger balance -O csv # write CSV to stdout
665 $ hledger balance -o FILE.csv # write CSV to FILE.csv
666 Regular expressions
668 hledger uses regular expressions in a number of places:
669 · query terms, on the command line and in the hledger-web search form:
671 REGEX, desc:REGEX, cur:REGEX, tag:...=REGEX
672 · CSV rules conditional blocks: if REGEX ...
674 · account alias directives and options: alias /REGEX/ = REPLACEMENT,
676 --alias /REGEX/=REPLACEMENT
677 hledger's regular expressions come from the regex-tdfa library. In
679 general they:
680 · are case insensitive
682 · are infix matching (do not need to match the entire thing being
684 matched)
685 · are POSIX extended regular expressions
687 · also support GNU word boundaries (\<, \>, \b, \B)
689 · and parenthesised capturing groups and numeric backreferences in
691 replacement strings
692 · do not support mode modifiers like (?s)
694 Some things to note:
696 · In the alias directive and --alias option, regular expressions must
698 be enclosed in forward slashes (/REGEX/). Elsewhere in hledger,
699 these are not required.
700 · In queries, to match a regular expression metacharacter like $ as a
702 literal character, prepend a backslash. Eg to search for amounts
703 with the dollar sign in hledger-web, write cur:\$.
704 · On the command line, some metacharacters like $ have a special mean‐
706 ing to the shell and so must be escaped at least once more. See Spe‐
707 cial characters.
708
710 One of hledger's strengths is being able to quickly report on precise
711 subsets of your data. Most commands accept an optional query expres‐
712 sion, written as arguments after the command name, to filter the data
713 by date, account name or other criteria. The syntax is similar to a
714 web search: one or more space-separated search terms, quotes to enclose
715 whitespace, prefixes to match specific fields, a not: prefix to negate
716 the match.
717 We do not yet support arbitrary boolean combinations of search terms;
719 instead most commands show transactions/postings/accounts which match
720 (or negatively match):
721 · any of the description terms AND
723 · any of the account terms AND
725 · any of the status terms AND
727 · all the other terms.
729 The print command instead shows transactions which:
731 · match any of the description terms AND
733 · have any postings matching any of the positive account terms AND
735 · have no postings matching any of the negative account terms AND
737 · match all the other terms.
739 The following kinds of search terms can be used. Remember these can
741 also be prefixed with not:, eg to exclude a particular subaccount.
742 REGEX, acct:REGEX
744 match account names by this regular expression. (With no pre‐
745 fix, acct: is assumed.)
746 same as above
747 amt:N, amt:<N, amt:<=N, amt:>N, amt:>=N
749 match postings with a single-commodity amount that is equal to,
750 less than, or greater than N. (Multi-commodity amounts are not
751 tested, and will always match.) The comparison has two modes: if
752 N is preceded by a + or - sign (or is 0), the two signed numbers
753 are compared. Otherwise, the absolute magnitudes are compared,
754 ignoring sign.
755 code:REGEX
757 match by transaction code (eg check number)
758 cur:REGEX
760 match postings or transactions including any amounts whose cur‐
761 rency/commodity symbol is fully matched by REGEX. (For a par‐
762 tial match, use .*REGEX.*). Note, to match characters which are
763 regex-significant, like the dollar sign ($), you need to prepend
764 \. And when using the command line you need to add one more
765 level of quoting to hide it from the shell, so eg do:
766 hledger print cur:'\$' or hledger print cur:\\$.
767 desc:REGEX
769 match transaction descriptions.
770 date:PERIODEXPR
772 match dates within the specified period. PERIODEXPR is a period
773 expression (with no report interval). Examples: date:2016,
774 date:thismonth, date:2000/2/1-2/15, date:lastweek-. If the
775 --date2 command line flag is present, this matches secondary
776 dates instead.
777 date2:PERIODEXPR
779 match secondary dates within the specified period.
780 depth:N
782 match (or display, depending on command) accounts at or above
783 this depth
784 note:REGEX
786 match transaction notes (part of description right of |, or
787 whole description when there's no |)
788 payee:REGEX
790 match transaction payee/payer names (part of description left of
791 |, or whole description when there's no |)
792 real:, real:0
794 match real or virtual postings respectively
795 status:, status:!, status:*
797 match unmarked, pending, or cleared transactions respectively
798 tag:REGEX[=REGEX]
800 match by tag name, and optionally also by tag value. Note a
801 tag: query is considered to match a transaction if it matches
802 any of the postings. Also remember that postings inherit the
803 tags of their parent transaction.
804 The following special search term is used automatically in hledger-web,
806 only:
807 inacct:ACCTNAME
809 tells hledger-web to show the transaction register for this
810 account. Can be filtered further with acct etc.
811 Some of these can also be expressed as command-line options (eg depth:2
813 is equivalent to --depth 2). Generally you can mix options and query
814 arguments, and the resulting query will be their intersection (perhaps
815 excluding the -p/--period option).
816
818 hledger provides a number of subcommands; hledger with no arguments
819 shows a list.
820 If you install additional hledger-* packages, or if you put programs or
822 scripts named hledger-NAME in your PATH, these will also be listed as
823 subcommands.
824 Run a subcommand by writing its name as first argument (eg
826 hledger incomestatement). You can also write one of the standard short
827 aliases displayed in parentheses in the command list (hledger b), or
828 any any unambiguous prefix of a command name (hledger inc).
829 Here are all the builtin commands in alphabetical order. See also
831 hledger for a more organised command list, and hledger CMD -h for
832 detailed command help.
833 accounts
835 Show account names. Alias: a.
836 --declared
838 show account names declared with account directives
839 --used show account names posted to by transactions
841 --tree show short account names and their parents, as a tree
843 --flat show full account names, as a list (default)
845 --drop=N
847 in flat mode: omit N leading account name parts
848 This command lists account names, either declared with account direc‐
850 tives (–declared), posted to (–used), or both (default). With query
851 arguments, only matched account names and account names referenced by
852 matched postings are shown. It shows a flat list by default. With
853 --tree, it uses indentation to show the account hierarchy. In flat
854 mode you can add --drop N to omit the first few account name compo‐
855 nents. Account names can be depth-clipped with --depth N or depth:N.
856 Examples:
858 $ hledger accounts --tree
860 assets
861 bank
862 checking
863 saving
864 cash
865 expenses
866 food
867 supplies
868 income
869 gifts
870 salary
871 liabilities
872 debts
873 $ hledger accounts --drop 1
875 bank:checking
876 bank:saving
877 cash
878 food
879 supplies
880 gifts
881 salary
882 debts
883 $ hledger accounts
885 assets:bank:checking
886 assets:bank:saving
887 assets:cash
888 expenses:food
889 expenses:supplies
890 income:gifts
891 income:salary
892 liabilities:debts
893 activity
895 Show an ascii barchart of posting counts per interval.
896 The activity command displays an ascii histogram showing transaction
898 counts by day, week, month or other reporting interval (by day is the
899 default). With query arguments, it counts only matched transactions.
900 $ hledger activity --quarterly
902 2008-01-01 **
903 2008-04-01 *******
904 2008-07-01
905 2008-10-01 **
906 add
908 Prompt for transactions and add them to the journal.
909 --no-new-accounts
911 don't allow creating new accounts; helps prevent typos when
912 entering account names
913 Many hledger users edit their journals directly with a text editor, or
915 generate them from CSV. For more interactive data entry, there is the
916 add command, which prompts interactively on the console for new trans‐
917 actions, and appends them to the journal file (if there are multiple
918 -f FILE options, the first file is used.) Existing transactions are not
919 changed. This is the only hledger command that writes to the journal
920 file.
921 To use it, just run hledger add and follow the prompts. You can add as
923 many transactions as you like; when you are finished, enter . or press
924 control-d or control-c to exit.
925 Features:
927 · add tries to provide useful defaults, using the most similar recent
929 transaction (by description) as a template.
930 · You can also set the initial defaults with command line arguments.
932 · Readline-style edit keys can be used during data entry.
934 · The tab key will auto-complete whenever possible - accounts, descrip‐
936 tions, dates (yesterday, today, tomorrow). If the input area is
937 empty, it will insert the default value.
938 · If the journal defines a default commodity, it will be added to any
940 bare numbers entered.
941 · A parenthesised transaction code may be entered following a date.
943 · Comments and tags may be entered following a description or amount.
945 · If you make a mistake, enter < at any prompt to restart the transac‐
947 tion.
948 · Input prompts are displayed in a different colour when the terminal
950 supports it.
951 Example (see the tutorial for a detailed explanation):
953 $ hledger add
955 Adding transactions to journal file /src/hledger/examples/sample.journal
956 Any command line arguments will be used as defaults.
957 Use tab key to complete, readline keys to edit, enter to accept defaults.
958 An optional (CODE) may follow transaction dates.
959 An optional ; COMMENT may follow descriptions or amounts.
960 If you make a mistake, enter < at any prompt to restart the transaction.
961 To end a transaction, enter . when prompted.
962 To quit, enter . at a date prompt or press control-d or control-c.
963 Date [2015/05/22]:
964 Description: supermarket
965 Account 1: expenses:food
966 Amount 1: $10
967 Account 2: assets:checking
968 Amount 2 [$-10.0]:
969 Account 3 (or . or enter to finish this transaction): .
970 2015/05/22 supermarket
971 expenses:food $10
972 assets:checking $-10.0
973 Save this transaction to the journal ? [y]:
975 Saved.
976 Starting the next transaction (. or ctrl-D/ctrl-C to quit)
977 Date [2015/05/22]: <CTRL-D> $
978 balance
980 Show accounts and their balances. Aliases: b, bal.
981 --change
983 show balance change in each period (default)
984 --cumulative
986 show balance change accumulated across periods (in multicolumn
987 reports)
988 -H --historical
990 show historical ending balance in each period (includes postings
991 before report start date)
992 --tree show accounts as a tree; amounts include subaccounts (default in
994 simple reports)
995 --flat show accounts as a list; amounts exclude subaccounts except when
997 account is depth-clipped (default in multicolumn reports)
998 -A --average
1000 show a row average column (in multicolumn mode)
1001 -T --row-total
1003 show a row total column (in multicolumn mode)
1004 -N --no-total
1006 don't show the final total row
1007 --drop=N
1009 omit N leading account name parts (in flat mode)
1010 --no-elide
1012 don't squash boring parent accounts (in tree mode)
1013 --format=LINEFORMAT
1015 in single-column balance reports: use this custom line format
1016 -O FMT --output-format=FMT
1018 select the output format. Supported formats: txt, csv, html.
1019 -o FILE --output-file=FILE
1021 write output to FILE. A file extension matching one of the
1022 above formats selects that format.
1023 --pretty-tables
1025 use unicode to display prettier tables.
1026 --sort-amount
1028 sort by amount instead of account code/name (in flat mode).
1029 With multiple columns, sorts by the row total, or by row average
1030 if that is displayed.
1031 --invert
1033 display all amounts with reversed sign
1034 --budget
1036 show performance compared to budget goals defined by periodic
1037 transactions
1038 --show-unbudgeted
1040 with –budget, show unbudgeted accounts also
1041 The balance command is hledger's most versatile command. Note, despite
1043 the name, it is not always used for showing real-world account bal‐
1044 ances; the more accounting-aware balancesheet and incomestatement may
1045 be more convenient for that.
1046 By default, it displays all accounts, and each account's change in bal‐
1048 ance during the entire period of the journal. Balance changes are cal‐
1049 culated by adding up the postings in each account. You can limit the
1050 postings matched, by a query, to see fewer accounts, changes over a
1051 different time period, changes from only cleared transactions, etc.
1052 If you include an account's complete history of postings in the report,
1054 the balance change is equivalent to the account's current ending bal‐
1055 ance. For a real-world account, typically you won't have all transac‐
1056 tions in the journal; instead you'll have all transactions after a cer‐
1057 tain date, and an “opening balances” transaction setting the correct
1058 starting balance on that date. Then the balance command will show
1059 real-world account balances. In some cases the -H/–historical flag is
1060 used to ensure this (more below).
1061 The balance command can produce several styles of report:
1063 Classic balance report
1065 This is the original balance report, as found in Ledger. It usually
1066 looks like this:
1067 $ hledger balance
1069 $-1 assets
1070 $1 bank:saving
1071 $-2 cash
1072 $2 expenses
1073 $1 food
1074 $1 supplies
1075 $-2 income
1076 $-1 gifts
1077 $-1 salary
1078 $1 liabilities:debts
1079 --------------------
1080 0
1081 By default, accounts are displayed hierarchically, with subaccounts
1083 indented below their parent. At each level of the tree, accounts are
1084 sorted by account code if any, then by account name. Or with
1085 -S/--sort-amount, by their balance amount.
1086 “Boring” accounts, which contain a single interesting subaccount and no
1088 balance of their own, are elided into the following line for more com‐
1089 pact output. (Eg above, the “liabilities” account.) Use --no-elide to
1090 prevent this.
1091 Account balances are “inclusive” - they include the balances of any
1093 subaccounts.
1094 Accounts which have zero balance (and no non-zero subaccounts) are
1096 omitted. Use -E/--empty to show them.
1097 A final total is displayed by default; use -N/--no-total to suppress
1099 it, eg:
1100 $ hledger balance -p 2008/6 expenses --no-total
1102 $2 expenses
1103 $1 food
1104 $1 supplies
1105 Customising the classic balance report
1107 You can customise the layout of classic balance reports with --for‐
1108 mat FMT:
1109 $ hledger balance --format "%20(account) %12(total)"
1111 assets $-1
1112 bank:saving $1
1113 cash $-2
1114 expenses $2
1115 food $1
1116 supplies $1
1117 income $-2
1118 gifts $-1
1119 salary $-1
1120 liabilities:debts $1
1121 ---------------------------------
1122 0
1123 The FMT format string (plus a newline) specifies the formatting applied
1125 to each account/balance pair. It may contain any suitable text, with
1126 data fields interpolated like so:
1127 %[MIN][.MAX](FIELDNAME)
1129 · MIN pads with spaces to at least this width (optional)
1131 · MAX truncates at this width (optional)
1133 · FIELDNAME must be enclosed in parentheses, and can be one of:
1135 · depth_spacer - a number of spaces equal to the account's depth, or
1137 if MIN is specified, MIN * depth spaces.
1138 · account - the account's name
1140 · total - the account's balance/posted total, right justified
1142 Also, FMT can begin with an optional prefix to control how multi-com‐
1144 modity amounts are rendered:
1145 · %_ - render on multiple lines, bottom-aligned (the default)
1147 · %^ - render on multiple lines, top-aligned
1149 · %, - render on one line, comma-separated
1151 There are some quirks. Eg in one-line mode, %(depth_spacer) has no
1153 effect, instead %(account) has indentation built in.
1154 Experimentation may be needed to get pleasing results.
1155 Some example formats:
1157 · %(total) - the account's total
1159 · %-20.20(account) - the account's name, left justified, padded to 20
1161 characters and clipped at 20 characters
1162 · %,%-50(account) %25(total) - account name padded to 50 characters,
1164 total padded to 20 characters, with multiple commodities rendered on
1165 one line
1166 · %20(total) %2(depth_spacer)%-(account) - the default format for the
1168 single-column balance report
1169 Colour support
1171 The balance command shows negative amounts in red, if:
1172 · the TERM environment variable is not set to dumb
1174 · the output is not being redirected or piped anywhere
1176 Flat mode
1178 To see a flat list instead of the default hierarchical display, use
1179 --flat. In this mode, accounts (unless depth-clipped) show their full
1180 names and “exclusive” balance, excluding any subaccount balances. In
1181 this mode, you can also use --drop N to omit the first few account name
1182 components.
1183 $ hledger balance -p 2008/6 expenses -N --flat --drop 1
1185 $1 food
1186 $1 supplies
1187 Depth limited balance reports
1189 With --depth N or depth:N or just -N, balance reports show accounts
1190 only to the specified numeric depth. This is very useful to summarise
1191 a complex set of accounts and get an overview.
1192 $ hledger balance -N -1
1194 $-1 assets
1195 $2 expenses
1196 $-2 income
1197 $1 liabilities
1198 Flat-mode balance reports, which normally show exclusive balances, show
1200 inclusive balances at the depth limit.
1201 Multicolumn balance report
1203 Multicolumn or tabular balance reports are a very useful hledger fea‐
1204 ture, and usually the preferred style. They share many of the above
1205 features, but they show the report as a table, with columns represent‐
1206 ing time periods. This mode is activated by providing a reporting
1207 interval.
1208 There are three types of multicolumn balance report, showing different
1210 information:
1211 1. By default: each column shows the sum of postings in that period, ie
1213 the account's change of balance in that period. This is useful eg
1214 for a monthly income statement:
1215 $ hledger balance --quarterly income expenses -E
1217 Balance changes in 2008:
1218 || 2008q1 2008q2 2008q3 2008q4
1220 ===================++=================================
1221 expenses:food || 0 $1 0 0
1222 expenses:supplies || 0 $1 0 0
1223 income:gifts || 0 $-1 0 0
1224 income:salary || $-1 0 0 0
1225 -------------------++---------------------------------
1226 || $-1 $1 0 0
1227 2. With --cumulative: each column shows the ending balance for that
1229 period, accumulating the changes across periods, starting from 0 at
1230 the report start date:
1231 $ hledger balance --quarterly income expenses -E --cumulative
1233 Ending balances (cumulative) in 2008:
1234 || 2008/03/31 2008/06/30 2008/09/30 2008/12/31
1236 ===================++=================================================
1237 expenses:food || 0 $1 $1 $1
1238 expenses:supplies || 0 $1 $1 $1
1239 income:gifts || 0 $-1 $-1 $-1
1240 income:salary || $-1 $-1 $-1 $-1
1241 -------------------++-------------------------------------------------
1242 || $-1 0 0 0
1243 3. With --historical/-H: each column shows the actual historical ending
1245 balance for that period, accumulating the changes across periods,
1246 starting from the actual balance at the report start date. This is
1247 useful eg for a multi-period balance sheet, and when you are showing
1248 only the data after a certain start date:
1249 $ hledger balance ^assets ^liabilities --quarterly --historical --begin 2008/4/1
1251 Ending balances (historical) in 2008/04/01-2008/12/31:
1252 || 2008/06/30 2008/09/30 2008/12/31
1254 ======================++=====================================
1255 assets:bank:checking || $1 $1 0
1256 assets:bank:saving || $1 $1 $1
1257 assets:cash || $-2 $-2 $-2
1258 liabilities:debts || 0 0 $1
1259 ----------------------++-------------------------------------
1260 || 0 0 0
1261 Multicolumn balance reports display accounts in flat mode by default;
1263 to see the hierarchy, use --tree.
1264 With a reporting interval (like --quarterly above), the report
1266 start/end dates will be adjusted if necessary so that they encompass
1267 the displayed report periods. This is so that the first and last peri‐
1268 ods will be “full” and comparable to the others.
1269 The -E/--empty flag does two things in multicolumn balance reports:
1271 first, the report will show all columns within the specified report
1272 period (without -E, leading and trailing columns with all zeroes are
1273 not shown). Second, all accounts which existed at the report start
1274 date will be considered, not just the ones with activity during the
1275 report period (use -E to include low-activity accounts which would oth‐
1276 erwise would be omitted).
1277 The -T/--row-total flag adds an additional column showing the total for
1279 each row.
1280 The -A/--average flag adds a column showing the average value in each
1282 row.
1283 Here's an example of all three:
1285 $ hledger balance -Q income expenses --tree -ETA
1287 Balance changes in 2008:
1288 || 2008q1 2008q2 2008q3 2008q4 Total Average
1290 ============++===================================================
1291 expenses || 0 $2 0 0 $2 $1
1292 food || 0 $1 0 0 $1 0
1293 supplies || 0 $1 0 0 $1 0
1294 income || $-1 $-1 0 0 $-2 $-1
1295 gifts || 0 $-1 0 0 $-1 0
1296 salary || $-1 0 0 0 $-1 0
1297 ------------++---------------------------------------------------
1298 || $-1 $1 0 0 0 0
1299 # Average is rounded to the dollar here since all journal amounts are
1301 Limitations:
1303 In multicolumn reports the -V/--value flag uses the market price on the
1305 report end date, for all columns (not the price on each column's end
1306 date).
1307 Eliding of boring parent accounts in tree mode, as in the classic bal‐
1309 ance report, is not yet supported in multicolumn reports.
1310 Budget report
1312 With --budget, extra columns are displayed showing budget goals for
1313 each account and period, if any. Budget goals are defined by periodic
1314 transactions. This is very useful for comparing planned and actual
1315 income, expenses, time usage, etc. –budget is most often combined with
1316 a report interval.
1317 For example, you can take average monthly expenses in the common
1319 expense categories to construct a minimal monthly budget:
1320 ;; Budget
1322 ~ monthly
1323 income $2000
1324 expenses:food $400
1325 expenses:bus $50
1326 expenses:movies $30
1327 assets:bank:checking
1328 ;; Two months worth of expenses
1330 2017-11-01
1331 income $1950
1332 expenses:food $396
1333 expenses:bus $49
1334 expenses:movies $30
1335 expenses:supplies $20
1336 assets:bank:checking
1337 2017-12-01
1339 income $2100
1340 expenses:food $412
1341 expenses:bus $53
1342 expenses:gifts $100
1343 assets:bank:checking
1344 You can now see a monthly budget report:
1346 $ hledger balance -M --budget
1348 Budget performance in 2017/11/01-2017/12/31:
1349 || 2017/11 2017/12
1351 ======================++=================================================
1352 <unbudgeted> || $20 $100
1353 assets:bank:checking || $-2445 [99% of $-2480] $-2665 [107% of $-2480]
1354 expenses:bus || $49 [98% of $50] $53 [106% of $50]
1355 expenses:food || $396 [99% of $400] $412 [103% of $400]
1356 expenses:movies || $30 [100% of $30] 0 [0% of $30]
1357 income || $1950 [98% of $2000] $2100 [105% of $2000]
1358 ----------------------++-------------------------------------------------
1359 || 0 0
1360 By default, only accounts with budget goals during the report period
1362 are shown. --show-unbudgeted shows unbudgeted accounts as well.
1363 Top-level accounts with no budget goals anywhere below them are grouped
1364 under <unbudgeted>.
1365 You can roll over unspent budgets to next period with --cumulative:
1367 $ hledger balance -M --budget --cumulative
1369 Budget performance in 2017/11/01-2017/12/31:
1370 || 2017/11/30 2017/12/31
1372 ======================++=================================================
1373 <unbudgeted> || $20 $120
1374 assets:bank:checking || $-2445 [99% of $-2480] $-5110 [103% of $-4960]
1375 expenses:bus || $49 [98% of $50] $102 [102% of $100]
1376 expenses:food || $396 [99% of $400] $808 [101% of $800]
1377 expenses:movies || $30 [100% of $30] $30 [50% of $60]
1378 income || $1950 [98% of $2000] $4050 [101% of $4000]
1379 ----------------------++-------------------------------------------------
1380 || 0 0
1381 Note, the -S/--sort-amount flag is not yet fully supported with --bud‐
1383 get.
1384 For more examples, see Budgeting and Forecasting.
1386 Output format
1388 The balance command supports output destination and output format
1389 selection.
1390 balancesheet
1392 This command displays a simple balance sheet, showing historical ending
1393 balances of asset and liability accounts (ignoring any report begin
1394 date). It assumes that these accounts are under a top-level asset or
1395 liability account (case insensitive, plural forms also allowed). Note
1396 this report shows all account balances with normal positive sign (like
1397 conventional financial statements, unlike balance/print/register)
1398 (experimental). (bs)
1399 --change
1401 show balance change in each period, instead of historical ending
1402 balances
1403 --cumulative
1405 show balance change accumulated across periods (in multicolumn
1406 reports), instead of historical ending balances
1407 -H --historical
1409 show historical ending balance in each period (includes postings
1410 before report start date) (default)
1411 --tree show accounts as a tree; amounts include subaccounts (default in
1413 simple reports)
1414 --flat show accounts as a list; amounts exclude subaccounts except when
1416 account is depth-clipped (default in multicolumn reports)
1417 -A --average
1419 show a row average column (in multicolumn mode)
1420 -T --row-total
1422 show a row total column (in multicolumn mode)
1423 -N --no-total
1425 don't show the final total row
1426 --drop=N
1428 omit N leading account name parts (in flat mode)
1429 --no-elide
1431 don't squash boring parent accounts (in tree mode)
1432 --format=LINEFORMAT
1434 in single-column balance reports: use this custom line format
1435 --sort-amount
1437 sort by amount instead of account code/name
1438 Example:
1440 $ hledger balancesheet
1442 Balance Sheet
1443 Assets:
1445 $-1 assets
1446 $1 bank:saving
1447 $-2 cash
1448 --------------------
1449 $-1
1450 Liabilities:
1452 $1 liabilities:debts
1453 --------------------
1454 $1
1455 Total:
1457 --------------------
1458 0
1459 With a reporting interval, multiple columns will be shown, one for each
1461 report period. As with multicolumn balance reports, you can alter the
1462 report mode with --change/--cumulative/--historical. Normally bal‐
1463 ancesheet shows historical ending balances, which is what you need for
1464 a balance sheet; note this means it ignores report begin dates.
1465 This command also supports output destination and output format selec‐
1467 tion.
1468 balancesheetequity
1470 Just like balancesheet, but also reports Equity (which it assumes is
1471 under a top-level equity account).
1472 Example:
1474 $ hledger balancesheetequity
1476 Balance Sheet With Equity
1477 Assets:
1479 $-2 assets
1480 $1 bank:saving
1481 $-3 cash
1482 --------------------
1483 $-2
1484 Liabilities:
1486 $1 liabilities:debts
1487 --------------------
1488 $1
1489 Equity:
1491 $1 equity:owner
1492 --------------------
1493 $1
1494 Total:
1496 --------------------
1497 0
1498 cashflow
1500 This command displays a simple cashflow statement, showing changes in
1501 “cash” accounts. It assumes that these accounts are under a top-level
1502 asset account (case insensitive, plural forms also allowed) and do not
1503 contain receivable or A/R in their name. Note this report shows all
1504 account balances with normal positive sign (like conventional financial
1505 statements, unlike balance/print/register) (experimental). (cf)
1506 --change
1508 show balance change in each period (default)
1509 --cumulative
1511 show balance change accumulated across periods (in multicolumn
1512 reports), instead of changes during periods
1513 -H --historical
1515 show historical ending balance in each period (includes postings
1516 before report start date), instead of changes during each period
1517 --tree show accounts as a tree; amounts include subaccounts (default in
1519 simple reports)
1520 --flat show accounts as a list; amounts exclude subaccounts except when
1522 account is depth-clipped (default in multicolumn reports)
1523 -A --average
1525 show a row average column (in multicolumn mode)
1526 -T --row-total
1528 show a row total column (in multicolumn mode)
1529 -N --no-total
1531 don't show the final total row (in simple reports)
1532 --drop=N
1534 omit N leading account name parts (in flat mode)
1535 --no-elide
1537 don't squash boring parent accounts (in tree mode)
1538 --format=LINEFORMAT
1540 in single-column balance reports: use this custom line format
1541 --sort-amount
1543 sort by amount instead of account code/name
1544 Example:
1546 $ hledger cashflow
1548 Cashflow Statement
1549 Cash flows:
1551 $-1 assets
1552 $1 bank:saving
1553 $-2 cash
1554 --------------------
1555 $-1
1556 Total:
1558 --------------------
1559 $-1
1560 With a reporting interval, multiple columns will be shown, one for each
1562 report period. Normally cashflow shows changes in assets per period,
1563 though as with multicolumn balance reports you can alter the report
1564 mode with --change/--cumulative/--historical.
1565 This command also supports output destination and output format selec‐
1567 tion.
1568 check-dates
1570 Check that transactions are sorted by increasing date. With a query,
1571 only matched transactions' dates are checked.
1572 check-dupes
1574 Report account names having the same leaf but different prefixes. An
1575 example: http://stefanorodighiero.net/software/hledger-dupes.html
1576 close
1578 Print closing/opening transactions that bring some or all account bal‐
1579 ances to zero and back. Can be useful for bringing asset/liability
1580 balances across file boundaries, or for closing out income/expenses for
1581 a period. This was formerly called “equity”, as in Ledger, and that
1582 alias is also accepted. See close –help for more.
1583 help
1585 Show any of the hledger manuals.
1586 The help command displays any of the main hledger manuals, in one of
1588 several ways. Run it with no argument to list the manuals, or provide
1589 a full or partial manual name to select one.
1590 hledger manuals are available in several formats. hledger help will
1592 use the first of these display methods that it finds: info, man,
1593 $PAGER, less, stdout (or when non-interactive, just stdout). You can
1594 force a particular viewer with the --info, --man, --pager, --cat flags.
1595 $ hledger help
1597 Please choose a manual by typing "hledger help MANUAL" (a substring is ok).
1598 Manuals: hledger hledger-ui hledger-web hledger-api journal csv timeclock timedot
1599 $ hledger help h --man
1601 hledger(1) hledger User Manuals hledger(1)
1603 NAME
1605 hledger - a command-line accounting tool
1606 SYNOPSIS
1608 hledger [-f FILE] COMMAND [OPTIONS] [ARGS]
1609 hledger [-f FILE] ADDONCMD -- [OPTIONS] [ARGS]
1610 hledger
1611 DESCRIPTION
1613 hledger is a cross-platform program for tracking money, time, or any
1614 ...
1615 import
1617 Read new transactions added to each FILE since last run, and add them
1618 to the main journal file.
1619 --dry-run
1621 just show the transactions to be imported
1622 The input files are specified as arguments - no need to write -f before
1624 each one. So eg to add new transactions from all CSV files to the main
1625 journal, it's just: hledger import *.csv
1626 New transactions are detected in the same way as print –new: by assum‐
1628 ing transactions are always added to the input files in increasing date
1629 order, and by saving .latest.FILE state files.
1630 The –dry-run output is in journal format, so you can filter it, eg to
1632 see only uncategorised transactions:
1633 $ hledger import --dry ... | hledger -f- print unknown --ignore-assertions
1635 incomestatement
1637 This command displays a simple income statement, showing revenues and
1638 expenses during a period. It assumes that these accounts are under a
1639 top-level revenue or income or expense account (case insensitive, plu‐
1640 ral forms also allowed). Note this report shows all account balances
1641 with normal positive sign (like conventional financial statements,
1642 unlike balance/print/register) (experimental). (is)
1643 --change
1645 show balance change in each period (default)
1646 --cumulative
1648 show balance change accumulated across periods (in multicolumn
1649 reports), instead of changes during periods
1650 -H --historical
1652 show historical ending balance in each period (includes postings
1653 before report start date), instead of changes during each period
1654 --tree show accounts as a tree; amounts include subaccounts (default in
1656 simple reports)
1657 --flat show accounts as a list; amounts exclude subaccounts except when
1659 account is depth-clipped (default in multicolumn reports)
1660 -A --average
1662 show a row average column (in multicolumn mode)
1663 -T --row-total
1665 show a row total column (in multicolumn mode)
1666 -N --no-total
1668 don't show the final total row
1669 --drop=N
1671 omit N leading account name parts (in flat mode)
1672 --no-elide
1674 don't squash boring parent accounts (in tree mode)
1675 --format=LINEFORMAT
1677 in single-column balance reports: use this custom line format
1678 --sort-amount
1680 sort by amount instead of account code/name
1681 This command displays a simple income statement. It currently assumes
1683 that you have top-level accounts named income (or revenue) and expense
1684 (plural forms also allowed.)
1685 $ hledger incomestatement
1687 Income Statement
1688 Revenues:
1690 $-2 income
1691 $-1 gifts
1692 $-1 salary
1693 --------------------
1694 $-2
1695 Expenses:
1697 $2 expenses
1698 $1 food
1699 $1 supplies
1700 --------------------
1701 $2
1702 Total:
1704 --------------------
1705 0
1706 With a reporting interval, multiple columns will be shown, one for each
1708 report period. Normally incomestatement shows revenues/expenses per
1709 period, though as with multicolumn balance reports you can alter the
1710 report mode with --change/--cumulative/--historical.
1711 This command also supports output destination and output format selec‐
1713 tion.
1714 prices
1716 Print all market prices from the journal.
1717 print
1719 Show transactions from the journal. Aliases: p, txns.
1720 -m STR --match=STR
1722 show the transaction whose description is most similar to STR,
1723 and is most recent
1724 --new show only newer-dated transactions added in each file since last
1726 run
1727 -x --explicit
1729 show all amounts explicitly
1730 -O FMT --output-format=FMT
1732 select the output format. Supported formats: txt, csv.
1733 -o FILE --output-file=FILE
1735 write output to FILE. A file extension matching one of the
1736 above formats selects that format.
1737 $ hledger print
1739 2008/01/01 income
1740 assets:bank:checking $1
1741 income:salary $-1
1742 2008/06/01 gift
1744 assets:bank:checking $1
1745 income:gifts $-1
1746 2008/06/02 save
1748 assets:bank:saving $1
1749 assets:bank:checking $-1
1750 2008/06/03 * eat & shop
1752 expenses:food $1
1753 expenses:supplies $1
1754 assets:cash $-2
1755 2008/12/31 * pay off
1757 liabilities:debts $1
1758 assets:bank:checking $-1
1759 The print command displays full journal entries (transactions) from the
1761 journal file in date order, tidily formatted. print's output is always
1762 a valid hledger journal. It preserves all transaction information, but
1763 it does not preserve directives or inter-transaction comments
1764 Normally, the journal entry's explicit or implicit amount style is pre‐
1766 served. Ie when an amount is omitted in the journal, it will be omit‐
1767 ted in the output. You can use the -x/--explicit flag to make all
1768 amounts explicit, which can be useful for troubleshooting or for making
1769 your journal more readable and robust against data entry errors. Note,
1770 -x will cause postings with a multi-commodity amount (these can arise
1771 when a multi-commodity transaction has an implicit amount) will be
1772 split into multiple single-commodity postings, for valid journal out‐
1773 put.
1774 With -B/--cost, amounts with transaction prices are converted to cost
1776 using that price. This can be used for troubleshooting.
1777 With -m/--match and a STR argument, print will show at most one trans‐
1779 action: the one one whose description is most similar to STR, and is
1780 most recent. STR should contain at least two characters. If there is
1781 no similar-enough match, no transaction will be shown.
1782 With --new, for each FILE being read, hledger reads (and writes) a spe‐
1784 cial state file (.latest.FILE in the same directory), containing the
1785 latest transaction date(s) that were seen last time FILE was read.
1786 When this file is found, only transactions with newer dates (and new
1787 transactions on the latest date) are printed. This is useful for
1788 ignoring already-seen entries in import data, such as downloaded CSV
1789 files. Eg:
1790 $ hledger -f bank1.csv print --new
1792 # shows transactions added since last print --new on this file
1793 This assumes that transactions added to FILE always have same or
1795 increasing dates, and that transactions on the same day do not get
1796 reordered. See also the import command.
1797 This command also supports output destination and output format selec‐
1799 tion. Here's an example of print's CSV output:
1800 $ hledger print -Ocsv
1802 "txnidx","date","date2","status","code","description","comment","account","amount","commodity","credit","debit","posting-status","posting-comment"
1803 "1","2008/01/01","","","","income","","assets:bank:checking","1","$","","1","",""
1804 "1","2008/01/01","","","","income","","income:salary","-1","$","1","","",""
1805 "2","2008/06/01","","","","gift","","assets:bank:checking","1","$","","1","",""
1806 "2","2008/06/01","","","","gift","","income:gifts","-1","$","1","","",""
1807 "3","2008/06/02","","","","save","","assets:bank:saving","1","$","","1","",""
1808 "3","2008/06/02","","","","save","","assets:bank:checking","-1","$","1","","",""
1809 "4","2008/06/03","","*","","eat & shop","","expenses:food","1","$","","1","",""
1810 "4","2008/06/03","","*","","eat & shop","","expenses:supplies","1","$","","1","",""
1811 "4","2008/06/03","","*","","eat & shop","","assets:cash","-2","$","2","","",""
1812 "5","2008/12/31","","*","","pay off","","liabilities:debts","1","$","","1","",""
1813 "5","2008/12/31","","*","","pay off","","assets:bank:checking","-1","$","1","","",""
1814 · There is one CSV record per posting, with the parent transaction's
1816 fields repeated.
1817 · The “txnidx” (transaction index) field shows which postings belong to
1819 the same transaction. (This number might change if transactions are
1820 reordered within the file, files are parsed/included in a different
1821 order, etc.)
1822 · The amount is separated into “commodity” (the symbol) and “amount”
1824 (numeric quantity) fields.
1825 · The numeric amount is repeated in either the “credit” or “debit” col‐
1827 umn, for convenience. (Those names are not accurate in the account‐
1828 ing sense; it just puts negative amounts under credit and zero or
1829 greater amounts under debit.)
1830 print-unique
1832 Print transactions which do not reuse an already-seen description.
1833 register
1835 Show postings and their running total. Aliases: r, reg.
1836 --cumulative
1838 show running total from report start date (default)
1839 -H --historical
1841 show historical running total/balance (includes postings before
1842 report start date)
1843 -A --average
1845 show running average of posting amounts instead of total
1846 (implies –empty)
1847 -r --related
1849 show postings' siblings instead
1850 -w N --width=N
1852 set output width (default: terminal width or COLUMNS. -wN,M
1853 sets description width as well)
1854 -O FMT --output-format=FMT
1856 select the output format. Supported formats: txt, csv.
1857 -o FILE --output-file=FILE
1859 write output to FILE. A file extension matching one of the
1860 above formats selects that format.
1861 The register command displays postings, one per line, and their running
1863 total. This is typically used with a query selecting a particular
1864 account, to see that account's activity:
1865 $ hledger register checking
1867 2008/01/01 income assets:bank:checking $1 $1
1868 2008/06/01 gift assets:bank:checking $1 $2
1869 2008/06/02 save assets:bank:checking $-1 $1
1870 2008/12/31 pay off assets:bank:checking $-1 0
1871 The --historical/-H flag adds the balance from any undisplayed prior
1873 postings to the running total. This is useful when you want to see
1874 only recent activity, with a historically accurate running balance:
1875 $ hledger register checking -b 2008/6 --historical
1877 2008/06/01 gift assets:bank:checking $1 $2
1878 2008/06/02 save assets:bank:checking $-1 $1
1879 2008/12/31 pay off assets:bank:checking $-1 0
1880 The --depth option limits the amount of sub-account detail displayed.
1882 The --average/-A flag shows the running average posting amount instead
1884 of the running total (so, the final number displayed is the average for
1885 the whole report period). This flag implies --empty (see below). It
1886 is affected by --historical. It works best when showing just one
1887 account and one commodity.
1888 The --related/-r flag shows the other postings in the transactions of
1890 the postings which would normally be shown.
1891 With a reporting interval, register shows summary postings, one per
1893 interval, aggregating the postings to each account:
1894 $ hledger register --monthly income
1896 2008/01 income:salary $-1 $-1
1897 2008/06 income:gifts $-1 $-2
1898 Periods with no activity, and summary postings with a zero amount, are
1900 not shown by default; use the --empty/-E flag to see them:
1901 $ hledger register --monthly income -E
1903 2008/01 income:salary $-1 $-1
1904 2008/02 0 $-1
1905 2008/03 0 $-1
1906 2008/04 0 $-1
1907 2008/05 0 $-1
1908 2008/06 income:gifts $-1 $-2
1909 2008/07 0 $-2
1910 2008/08 0 $-2
1911 2008/09 0 $-2
1912 2008/10 0 $-2
1913 2008/11 0 $-2
1914 2008/12 0 $-2
1915 Often, you'll want to see just one line per interval. The --depth
1917 option helps with this, causing subaccounts to be aggregated:
1918 $ hledger register --monthly assets --depth 1h
1920 2008/01 assets $1 $1
1921 2008/06 assets $-1 0
1922 2008/12 assets $-1 $-1
1923 Note when using report intervals, if you specify start/end dates these
1925 will be adjusted outward if necessary to contain a whole number of
1926 intervals. This ensures that the first and last intervals are full
1927 length and comparable to the others in the report.
1928 Custom register output
1930 register uses the full terminal width by default, except on windows.
1931 You can override this by setting the COLUMNS environment variable (not
1932 a bash shell variable) or by using the --width/-w option.
1933 The description and account columns normally share the space equally
1935 (about half of (width - 40) each). You can adjust this by adding a
1936 description width as part of –width's argument, comma-separated:
1937 --width W,D . Here's a diagram:
1938 <--------------------------------- width (W) ---------------------------------->
1940 date (10) description (D) account (W-41-D) amount (12) balance (12)
1941 DDDDDDDDDD dddddddddddddddddddd aaaaaaaaaaaaaaaaaaa AAAAAAAAAAAA AAAAAAAAAAAA
1942 and some examples:
1944 $ hledger reg # use terminal width (or 80 on windows)
1946 $ hledger reg -w 100 # use width 100
1947 $ COLUMNS=100 hledger reg # set with one-time environment variable
1948 $ export COLUMNS=100; hledger reg # set till session end (or window resize)
1949 $ hledger reg -w 100,40 # set overall width 100, description width 40
1950 $ hledger reg -w $COLUMNS,40 # use terminal width, and set description width
1951 This command also supports output destination and output format selec‐
1953 tion.
1954 register-match
1956 Print the one posting whose transaction description is closest to DESC,
1957 in the style of the register command. Helps ledger-autosync detect
1958 already-seen transactions when importing.
1959 rewrite
1961 Print all transactions, adding custom postings to the matched ones.
1962 stats
1964 Show some journal statistics.
1965 -o FILE --output-file=FILE
1967 write output to FILE. A file extension matching one of the
1968 above formats selects that format.
1969 $ hledger stats
1971 Main journal file : /src/hledger/examples/sample.journal
1972 Included journal files :
1973 Transactions span : 2008-01-01 to 2009-01-01 (366 days)
1974 Last transaction : 2008-12-31 (2333 days ago)
1975 Transactions : 5 (0.0 per day)
1976 Transactions last 30 days: 0 (0.0 per day)
1977 Transactions last 7 days : 0 (0.0 per day)
1978 Payees/descriptions : 5
1979 Accounts : 8 (depth 3)
1980 Commodities : 1 ($)
1981 The stats command displays summary information for the whole journal,
1983 or a matched part of it. With a reporting interval, it shows a report
1984 for each report period.
1985 This command also supports output destination and output format selec‐
1987 tion.
1988 tags
1990 List all the tag names used in the journal. With a TAGREGEX argument,
1991 only tag names matching the regular expression (case insensitive) are
1992 shown. With additional QUERY arguments, only transactions matching the
1993 query are considered.
1994 test
1996 Run built-in unit tests.
1997 $ hledger test
1999 Cases: 74 Tried: 74 Errors: 0 Failures: 0
2000 This command runs hledger's built-in unit tests and displays a quick
2002 report. With a regular expression argument, it selects only tests with
2003 matching names. It's mainly used in development, but it's also nice to
2004 be able to check your hledger executable for smoke at any time.
2005
2007 hledger also searches for external add-on commands, and will include
2008 these in the commands list. These are programs or scripts in your PATH
2009 whose name starts with hledger- and ends with a recognised file exten‐
2010 sion (currently: no extension, bat,com,exe, hs,lhs,pl,py,rb,rkt,sh).
2011 Add-ons can be invoked like any hledger command, but there are a few
2013 things to be aware of. Eg if the hledger-web add-on is installed,
2014 · hledger -h web shows hledger's help, while hledger web -h shows
2016 hledger-web's help.
2017 · Flags specific to the add-on must have a preceding -- to hide them
2019 from hledger. So hledger web --serve --port 9000 will be rejected;
2020 you must use hledger web -- --serve --port 9000.
2021 · You can always run add-ons directly if preferred:
2023 hledger-web --serve --port 9000.
2024 Add-ons are a relatively easy way to add local features or experiment
2026 with new ideas. They can be written in any language, but haskell
2027 scripts have a big advantage: they can use the same hledger (and
2028 haskell) library functions that built-in commands do, for command-line
2029 options, journal parsing, reporting, etc.
2030 Here are some hledger add-ons available:
2032 Official add-ons
2034 These are maintained and released along with hledger.
2035 api
2037 hledger-api serves hledger data as a JSON web API.
2038 ui
2040 hledger-ui provides an efficient curses-style interface.
2041 web
2043 hledger-web provides a simple web interface.
2044 Third party add-ons
2046 These are maintained separately, and usually updated shortly after a
2047 hledger release.
2048 diff
2050 hledger-diff shows differences in an account's transactions between one
2051 journal file and another.
2052 iadd
2054 hledger-iadd is a curses-style, more interactive replacement for the
2055 add command.
2056 interest
2058 hledger-interest generates interest transactions for an account accord‐
2059 ing to various schemes.
2060 irr
2062 hledger-irr calculates the internal rate of return of an investment
2063 account.
2064 Experimental add-ons
2066 These are available in source form in the hledger repo's bin/ direc‐
2067 tory; installing them is pretty easy. They may be less mature and doc‐
2068 umented than built-in commands. Reading and tweaking these is a good
2069 way to start making your own!
2070 autosync
2072 hledger-autosync is a symbolic link for easily running ledger-autosync,
2073 if installed. ledger-autosync does deduplicating conversion of OFX
2074 data and some CSV formats, and can also download the data if your bank
2075 offers OFX Direct Connect.
2076 chart
2078 hledger-chart.hs is an old pie chart generator, in need of some love.
2079 check
2081 hledger-check.hs checks more powerful account balance assertions.
2082
2084 COLUMNS The screen width used by the register command. Default: the
2085 full terminal width.
2086 LEDGER_FILE The journal file path when not specified with -f. Default:
2088 ~/.hledger.journal (on windows, perhaps C:/Users/USER/.hledger.jour‐
2089 nal).
2090
2092 Reads data from one or more files in hledger journal, timeclock, time‐
2093 dot, or CSV format specified with -f, or $LEDGER_FILE, or
2094 $HOME/.hledger.journal (on windows, perhaps
2095 C:/Users/USER/.hledger.journal).
2096
2098 The need to precede addon command options with -- when invoked from
2099 hledger is awkward.
2100 When input data contains non-ascii characters, a suitable system locale
2102 must be configured (or there will be an unhelpful error). Eg on POSIX,
2103 set LANG to something other than C.
2104 In a Microsoft Windows CMD window, non-ascii characters and colours are
2106 not supported.
2107 In a Cygwin/MSYS/Mintty window, the tab key is not supported in hledger
2109 add.
2110 Not all of Ledger's journal file syntax is supported. See file format
2112 differences.
2113 On large data files, hledger is slower and uses more memory than
2115 Ledger.
2116
2118 Here are some issues you might encounter when you run hledger (and
2119 remember you can also seek help from the IRC channel, mail list or bug
2120 tracker):
2121 Successfully installed, but “No command `hledger' found”
2123 stack and cabal install binaries into a special directory, which should
2124 be added to your PATH environment variable. Eg on unix-like systems,
2125 that is ~/.local/bin and ~/.cabal/bin respectively.
2126 I set a custom LEDGER_FILE, but hledger is still using the default file
2128 LEDGER_FILE should be a real environment variable, not just a shell
2129 variable. The command env | grep LEDGER_FILE should show it. You may
2130 need to use export. Here's an explanation.
2131 “Illegal byte sequence” or “Invalid or incomplete multibyte or wide
2133 character” errors
2134 In order to handle non-ascii letters and symbols (like £), hledger
2135 needs an appropriate locale. This is usually configured system-wide;
2136 you can also configure it temporarily. The locale may need to be one
2137 that supports UTF-8, if you built hledger with GHC < 7.2 (or possibly
2138 always, I'm not sure yet).
2139 Here's an example of setting the locale temporarily, on ubuntu
2141 gnu/linux:
2142 $ file my.journal
2144 my.journal: UTF-8 Unicode text # <- the file is UTF8-encoded
2145 $ locale -a
2146 C
2147 en_US.utf8 # <- a UTF8-aware locale is available
2148 POSIX
2149 $ LANG=en_US.utf8 hledger -f my.journal print # <- use it for this command
2150 Here's one way to set it permanently, there are probably better ways:
2152 $ echo "export LANG=en_US.UTF-8" >>~/.bash_profile
2154 $ bash --login
2155 If we preferred to use eg fr_FR.utf8, we might have to install that
2157 first:
2158 $ apt-get install language-pack-fr
2160 $ locale -a
2161 C
2162 en_US.utf8
2163 fr_BE.utf8
2164 fr_CA.utf8
2165 fr_CH.utf8
2166 fr_FR.utf8
2167 fr_LU.utf8
2168 POSIX
2169 $ LANG=fr_FR.utf8 hledger -f my.journal print
2170 Note some platforms allow variant locale spellings, but not all (ubuntu
2172 accepts fr_FR.UTF8, mac osx requires exactly fr_FR.UTF-8).
2173
2177 Report bugs at http://bugs.hledger.org (or on the #hledger IRC channel
2178 or hledger mail list)
2179
2182 Simon Michael <simon@joyful.com> and contributors
2183
2186 Copyright (C) 2007-2016 Simon Michael.
2187 Released under GNU GPL v3 or later.
2188
2191 hledger(1), hledger-ui(1), hledger-web(1), hledger-api(1),
2192 hledger_csv(5), hledger_journal(5), hledger_timeclock(5), hledger_time‐
2193 dot(5), ledger(1)
2194 http://hledger.org
2196hledger 1.9.99 June 2018 hledger(1)