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 reliable, cross-platform set of programs for tracking
16 money, time, or any other commodity, using double-entry accounting and
17 a simple, editable file format. hledger is inspired by and largely
18 compatible with ledger(1).
19 This is hledger’s command-line interface (there are also terminal and
21 web interfaces). Its basic function is to read a plain text file
22 describing financial transactions (in accounting terms, a general jour‐
23 nal) and print useful reports on standard output, or export them as
24 CSV. hledger can also read some other file formats such as CSV files,
25 translating them to journal format. Additionally, hledger lists other
26 hledger-* executables found in the user’s $PATH and can invoke them as
27 subcommands.
28 hledger reads data from one or more files in hledger journal, time‐
30 clock, timedot, or CSV format specified with -f, or $LEDGER_FILE, or
31 $HOME/.hledger.journal (on windows, perhaps
32 C:/Users/USER/.hledger.journal). If using $LEDGER_FILE, note this must
33 be a real environment variable, not a shell variable. You can specify
34 standard input with -f-.
35 Transactions are dated movements of money between two (or more) named
37 accounts, and are recorded with journal entries like this:
38 2015/10/16 bought food
40 expenses:food $10
41 assets:cash
42 For more about this format, see hledger_journal(5).
44 Most users use a text editor to edit the journal, usually with an edi‐
46 tor mode such as ledger-mode for added convenience. hledger’s interac‐
47 tive add command is another way to record new transactions. hledger
48 never changes existing transactions.
49 To get started, you can either save some entries like the above in
51 ~/.hledger.journal, or run hledger add and follow the prompts. Then
52 try some commands like hledger print or hledger balance. Run hledger
53 with no arguments for a list of commands.
54
56 Here are some quick examples of how to do some basic tasks with
57 hledger. For more details, see the reference section below, the
58 hledger_journal(5) manual, or the more extensive docs at
59 https://hledger.org.
60 Getting help
62 $ hledger # show available commands
63 $ hledger --help # show common options
64 $ hledger CMD --help # show common and command options, and command help
65 $ hledger help # show available manuals/topics
66 $ hledger help hledger # show hledger manual as info/man/text (auto-chosen)
67 $ hledger help journal --man # show the journal manual as a man page
68 $ hledger help --help # show more detailed help for the help command
69 Find more docs, chat, mail list, reddit, issue tracker:
71 https://hledger.org#help-feedback
72 Constructing command lines
74 hledger has an extensive and powerful command line interface. We
75 strive to keep it simple and ergonomic, but you may run into one of the
76 confusing real world details described in OPTIONS, below. If that hap‐
77 pens, here are some tips that may help:
78 · command-specific options must go after the command (it's fine to put
80 all options there) (hledger CMD OPTS ARGS)
81 · running add-on executables directly simplifies command line parsing
83 (hledger-ui OPTS ARGS)
84 · enclose "problematic" args in single quotes
86 · if needed, also add a backslash to hide regular expression metachar‐
88 acters from the shell
89 · to see how a misbehaving command is being parsed, add --debug=2.
91 Starting a journal file
93 hledger looks for your accounting data in a journal file,
94 $HOME/.hledger.journal by default:
95 $ hledger stats
97 The hledger journal file "/Users/simon/.hledger.journal" was not found.
98 Please create it first, eg with "hledger add" or a text editor.
99 Or, specify an existing journal file with -f or LEDGER_FILE.
100 You can override this by setting the LEDGER_FILE environment variable.
102 It's a good practice to keep this important file under version control,
103 and to start a new file each year. So you could do something like
104 this:
105 $ mkdir ~/finance
107 $ cd ~/finance
108 $ git init
109 Initialized empty Git repository in /Users/simon/finance/.git/
110 $ touch 2020.journal
111 $ echo "export LEDGER_FILE=$HOME/finance/2020.journal" >> ~/.bashrc
112 $ source ~/.bashrc
113 $ hledger stats
114 Main file : /Users/simon/finance/2020.journal
115 Included files :
116 Transactions span : to (0 days)
117 Last transaction : none
118 Transactions : 0 (0.0 per day)
119 Transactions last 30 days: 0 (0.0 per day)
120 Transactions last 7 days : 0 (0.0 per day)
121 Payees/descriptions : 0
122 Accounts : 0 (depth 0)
123 Commodities : 0 ()
124 Market prices : 0 ()
125 Setting opening balances
127 Pick a starting date for which you can look up the balances of some
128 real-world assets (bank accounts, wallet..) and liabilities (credit
129 cards..).
130 To avoid a lot of data entry, you may want to start with just one or
132 two accounts, like your checking account or cash wallet; and pick a
133 recent starting date, like today or the start of the week. You can
134 always come back later and add more accounts and older transactions, eg
135 going back to january 1st.
136 Add an opening balances transaction to the journal, declaring the bal‐
138 ances on this date. Here are two ways to do it:
139 · The first way: open the journal in any text editor and save an entry
141 like this:
142 2020-01-01 * opening balances
144 assets:bank:checking $1000 = $1000
145 assets:bank:savings $2000 = $2000
146 assets:cash $100 = $100
147 liabilities:creditcard $-50 = $-50
148 equity:opening/closing balances
149 These are start-of-day balances, ie whatever was in the account at
151 the end of the previous day.
152 The * after the date is an optional status flag. Here it means
154 "cleared & confirmed".
155 The currency symbols are optional, but usually a good idea as you'll
157 be dealing with multiple currencies sooner or later.
158 The = amounts are optional balance assertions, providing extra error
160 checking.
161 · The second way: run hledger add and follow the prompts to record a
163 similar transaction:
164 $ hledger add
166 Adding transactions to journal file /Users/simon/finance/2020.journal
167 Any command line arguments will be used as defaults.
168 Use tab key to complete, readline keys to edit, enter to accept defaults.
169 An optional (CODE) may follow transaction dates.
170 An optional ; COMMENT may follow descriptions or amounts.
171 If you make a mistake, enter < at any prompt to go one step backward.
172 To end a transaction, enter . when prompted.
173 To quit, enter . at a date prompt or press control-d or control-c.
174 Date [2020-02-07]: 2020-01-01
175 Description: * opening balances
176 Account 1: assets:bank:checking
177 Amount 1: $1000
178 Account 2: assets:bank:savings
179 Amount 2 [$-1000]: $2000
180 Account 3: assets:cash
181 Amount 3 [$-3000]: $100
182 Account 4: liabilities:creditcard
183 Amount 4 [$-3100]: $-50
184 Account 5: equity:opening/closing balances
185 Amount 5 [$-3050]:
186 Account 6 (or . or enter to finish this transaction): .
187 2020-01-01 * opening balances
188 assets:bank:checking $1000
189 assets:bank:savings $2000
190 assets:cash $100
191 liabilities:creditcard $-50
192 equity:opening/closing balances $-3050
193 Save this transaction to the journal ? [y]:
195 Saved.
196 Starting the next transaction (. or ctrl-D/ctrl-C to quit)
197 Date [2020-01-01]: .
198 If you're using version control, this could be a good time to commit
200 the journal. Eg:
201 $ git commit -m 'initial balances' 2020.journal
203 Recording transactions
205 As you spend or receive money, you can record these transactions using
206 one of the methods above (text editor, hledger add) or by using the
207 hledger-iadd or hledger-web add-ons, or by using the import command to
208 convert CSV data downloaded from your bank.
209 Here are some simple transactions, see the hledger_journal(5) manual
211 and hledger.org for more ideas:
212 2020/1/10 * gift received
214 assets:cash $20
215 income:gifts
216 2020.1.12 * farmers market
218 expenses:food $13
219 assets:cash
220 2020-01-15 paycheck
222 income:salary
223 assets:bank:checking $1000
224 Reconciling
226 Periodically you should reconcile - compare your hledger-reported bal‐
227 ances against external sources of truth, like bank statements or your
228 bank's website - to be sure that your ledger accurately represents the
229 real-world balances (and, that the real-world institutions have not
230 made a mistake!). This gets easy and fast with (1) practice and (2)
231 frequency. If you do it daily, it can take 2-10 minutes. If you let
232 it pile up, expect it to take longer as you hunt down errors and dis‐
233 crepancies.
234 A typical workflow:
236 1. Reconcile cash. Count what's in your wallet. Compare with what
238 hledger reports (hledger bal cash). If they are different, try to
239 remember the missing transaction, or look for the error in the
240 already-recorded transactions. A register report can be helpful
241 (hledger reg cash). If you can't find the error, add an adjustment
242 transaction. Eg if you have $105 after the above, and can't explain
243 the missing $2, it could be:
244 2020-01-16 * adjust cash
246 assets:cash $-2 = $105
247 expenses:misc
248 2. Reconcile checking. Log in to your bank's website. Compare today's
250 (cleared) balance with hledger's cleared balance (hledger bal check‐
251 ing -C). If they are different, track down the error or record the
252 missing transaction(s) or add an adjustment transaction, similar to
253 the above. Unlike the cash case, you can usually compare the trans‐
254 action history and running balance from your bank with the one
255 reported by hledger reg checking -C. This will be easier if you
256 generally record transaction dates quite similar to your bank's
257 clearing dates.
258 3. Repeat for other asset/liability accounts.
260 Tip: instead of the register command, use hledger-ui to see a live-
262 updating register while you edit the journal: hledger-ui --watch --reg‐
263 ister checking -C
264 After reconciling, it could be a good time to mark the reconciled
266 transactions' status as "cleared and confirmed", if you want to track
267 that, by adding the * marker. Eg in the paycheck transaction above,
268 insert * between 2020-01-15 and paycheck
269 If you're using version control, this can be another good time to com‐
271 mit:
272 $ git commit -m 'txns' 2020.journal
274 Reporting
276 Here are some basic reports.
277 Show all transactions:
279 $ hledger print
281 2020-01-01 * opening balances
282 assets:bank:checking $1000
283 assets:bank:savings $2000
284 assets:cash $100
285 liabilities:creditcard $-50
286 equity:opening/closing balances $-3050
287 2020-01-10 * gift received
289 assets:cash $20
290 income:gifts
291 2020-01-12 * farmers market
293 expenses:food $13
294 assets:cash
295 2020-01-15 * paycheck
297 income:salary
298 assets:bank:checking $1000
299 2020-01-16 * adjust cash
301 assets:cash $-2 = $105
302 expenses:misc
303 Show account names, and their hierarchy:
305 $ hledger accounts --tree
307 assets
308 bank
309 checking
310 savings
311 cash
312 equity
313 opening/closing balances
314 expenses
315 food
316 misc
317 income
318 gifts
319 salary
320 liabilities
321 creditcard
322 Show all account totals:
324 $ hledger balance
326 $4105 assets
327 $4000 bank
328 $2000 checking
329 $2000 savings
330 $105 cash
331 $-3050 equity:opening/closing balances
332 $15 expenses
333 $13 food
334 $2 misc
335 $-1020 income
336 $-20 gifts
337 $-1000 salary
338 $-50 liabilities:creditcard
339 --------------------
340 0
341 Show only asset and liability balances, as a flat list, limited to
343 depth 2:
344 $ hledger bal assets liabilities --flat -2
346 $4000 assets:bank
347 $105 assets:cash
348 $-50 liabilities:creditcard
349 --------------------
350 $4055
351 Show the same thing without negative numbers, formatted as a simple
353 balance sheet:
354 $ hledger bs --flat -2
356 Balance Sheet 2020-01-16
357 || 2020-01-16
359 ========================++============
360 Assets ||
361 ------------------------++------------
362 assets:bank || $4000
363 assets:cash || $105
364 ------------------------++------------
365 || $4105
366 ========================++============
367 Liabilities ||
368 ------------------------++------------
369 liabilities:creditcard || $50
370 ------------------------++------------
371 || $50
372 ========================++============
373 Net: || $4055
374 The final total is your "net worth" on the end date. (Or use bse for a
376 full balance sheet with equity.)
377 Show income and expense totals, formatted as an income statement:
379 hledger is
381 Income Statement 2020-01-01-2020-01-16
382 || 2020-01-01-2020-01-16
384 ===============++=======================
385 Revenues ||
386 ---------------++-----------------------
387 income:gifts || $20
388 income:salary || $1000
389 ---------------++-----------------------
390 || $1020
391 ===============++=======================
392 Expenses ||
393 ---------------++-----------------------
394 expenses:food || $13
395 expenses:misc || $2
396 ---------------++-----------------------
397 || $15
398 ===============++=======================
399 Net: || $1005
400 The final total is your net income during this period.
402 Show transactions affecting your wallet, with running total:
404 $ hledger register cash
406 2020-01-01 opening balances assets:cash $100 $100
407 2020-01-10 gift received assets:cash $20 $120
408 2020-01-12 farmers market assets:cash $-13 $107
409 2020-01-16 adjust cash assets:cash $-2 $105
410 Show weekly posting counts as a bar chart:
412 $ hledger activity -W
414 2019-12-30 *****
415 2020-01-06 ****
416 2020-01-13 ****
417 Migrating to a new file
419 At the end of the year, you may want to continue your journal in a new
420 file, so that old transactions don't slow down or clutter your reports,
421 and to help ensure the integrity of your accounting history. See the
422 close command.
423 If using version control, don't forget to git add the new file.
425
427 General options
428 To see general usage help, including general options which are sup‐
429 ported by most hledger commands, run hledger -h.
430 General help options:
432 -h --help
434 show general usage (or after COMMAND, command usage)
435 --version
437 show version
438 --debug[=N]
440 show debug output (levels 1-9, default: 1)
441 General input options:
443 -f FILE --file=FILE
445 use a different input file. For stdin, use - (default:
446 $LEDGER_FILE or $HOME/.hledger.journal)
447 --rules-file=RULESFILE
449 Conversion rules file to use when reading CSV (default:
450 FILE.rules)
451 --separator=CHAR
453 Field separator to expect when reading CSV (default: ',')
454 --alias=OLD=NEW
456 rename accounts named OLD to NEW
457 --anon anonymize accounts and payees
459 --pivot FIELDNAME
461 use some other field or tag for the account name
462 -I --ignore-assertions
464 disable balance assertion checks (note: does not disable balance
465 assignments)
466 General reporting options:
468 -b --begin=DATE
470 include postings/txns on or after this date
471 -e --end=DATE
473 include postings/txns before this date
474 -D --daily
476 multiperiod/multicolumn report by day
477 -W --weekly
479 multiperiod/multicolumn report by week
480 -M --monthly
482 multiperiod/multicolumn report by month
483 -Q --quarterly
485 multiperiod/multicolumn report by quarter
486 -Y --yearly
488 multiperiod/multicolumn report by year
489 -p --period=PERIODEXP
491 set start date, end date, and/or reporting interval all at once
492 using period expressions syntax
493 --date2
495 match the secondary date instead (see command help for other
496 effects)
497 -U --unmarked
499 include only unmarked postings/txns (can combine with -P or -C)
500 -P --pending
502 include only pending postings/txns
503 -C --cleared
505 include only cleared postings/txns
506 -R --real
508 include only non-virtual postings
509 -NUM --depth=NUM
511 hide/aggregate accounts or postings more than NUM levels deep
512 -E --empty
514 show items with zero amount, normally hidden (and vice-versa in
515 hledger-ui/hledger-web)
516 -B --cost
518 convert amounts to their cost/selling amount at transaction time
519 -V --market
521 convert amounts to their market value in default valuation com‐
522 modities
523 -X --exchange=COMM
525 convert amounts to their market value in commodity COMM
526 --value
528 convert amounts to cost or market value, more flexibly than
529 -B/-V/-X
530 --infer-value
532 with -V/-X/--value, also infer market prices from transactions
533 --auto apply automated posting rules to modify transactions.
535 --forecast
537 generate future transactions from periodic transaction rules,
538 for the next 6 months or till report end date. In hledger-ui,
539 also make ordinary future transactions visible.
540 When a reporting option appears more than once in the command line, the
542 last one takes precedence.
543 Some reporting options can also be written as query arguments.
545 Command options
547 To see options for a particular command, including command-specific
548 options, run: hledger COMMAND -h.
549 Command-specific options must be written after the command name, eg:
551 hledger print -x.
552 Additionally, if the command is an addon, you may need to put its
554 options after a double-hyphen, eg: hledger ui -- --watch. Or, you can
555 run the addon executable directly: hledger-ui --watch.
556 Command arguments
558 Most hledger commands accept arguments after the command name, which
559 are often a query, filtering the data in some way.
560 You can save a set of command line options/arguments in a file, and
562 then reuse them by writing @FILENAME as a command line argument. Eg:
563 hledger bal @foo.args. (To prevent this, eg if you have an argument
564 that begins with a literal @, precede it with --, eg: hledger bal --
565 @ARG).
566 Inside the argument file, each line should contain just one option or
568 argument. Avoid the use of spaces, except inside quotes (or you'll see
569 a confusing error). Between a flag and its argument, use = (or noth‐
570 ing). Bad:
571 assets depth:2
573 -X USD
574 Good:
576 assets
578 depth:2
579 -X=USD
580 For special characters (see below), use one less level of quoting than
582 you would at the command prompt. Bad:
583 -X"$"
585 Good:
587 -X$
589 See also: Save frequently used options.
591 Queries
593 One of hledger's strengths is being able to quickly report on precise
594 subsets of your data. Most commands accept an optional query expres‐
595 sion, written as arguments after the command name, to filter the data
596 by date, account name or other criteria. The syntax is similar to a
597 web search: one or more space-separated search terms, quotes to enclose
598 whitespace, prefixes to match specific fields, a not: prefix to negate
599 the match.
600 We do not yet support arbitrary boolean combinations of search terms;
602 instead most commands show transactions/postings/accounts which match
603 (or negatively match):
604 · any of the description terms AND
606 · any of the account terms AND
608 · any of the status terms AND
610 · all the other terms.
612 The print command instead shows transactions which:
614 · match any of the description terms AND
616 · have any postings matching any of the positive account terms AND
618 · have no postings matching any of the negative account terms AND
620 · match all the other terms.
622 The following kinds of search terms can be used. Remember these can
624 also be prefixed with not:, eg to exclude a particular subaccount.
625 REGEX, acct:REGEX
627 match account names by this regular expression. (With no pre‐
628 fix, acct: is assumed.) same as above
629 amt:N, amt:<N, amt:<=N, amt:>N, amt:>=N
631 match postings with a single-commodity amount that is equal to,
632 less than, or greater than N. (Multi-commodity amounts are not
633 tested, and will always match.) The comparison has two modes: if
634 N is preceded by a + or - sign (or is 0), the two signed numbers
635 are compared. Otherwise, the absolute magnitudes are compared,
636 ignoring sign.
637 code:REGEX
639 match by transaction code (eg check number)
640 cur:REGEX
642 match postings or transactions including any amounts whose cur‐
643 rency/commodity symbol is fully matched by REGEX. (For a par‐
644 tial match, use .*REGEX.*). Note, to match characters which are
645 regex-significant, like the dollar sign ($), you need to prepend
646 \. And when using the command line you need to add one more
647 level of quoting to hide it from the shell, so eg do: hledger
648 print cur:'\$' or hledger print cur:\\$.
649 desc:REGEX
651 match transaction descriptions.
652 date:PERIODEXPR
654 match dates within the specified period. PERIODEXPR is a period
655 expression (with no report interval). Examples: date:2016,
656 date:thismonth, date:2000/2/1-2/15, date:lastweek-. If the
657 --date2 command line flag is present, this matches secondary
658 dates instead.
659 date2:PERIODEXPR
661 match secondary dates within the specified period.
662 depth:N
664 match (or display, depending on command) accounts at or above
665 this depth
666 note:REGEX
668 match transaction notes (part of description right of |, or
669 whole description when there's no |)
670 payee:REGEX
672 match transaction payee/payer names (part of description left of
673 |, or whole description when there's no |)
674 real:, real:0
676 match real or virtual postings respectively
677 status:, status:!, status:*
679 match unmarked, pending, or cleared transactions respectively
680 tag:REGEX[=REGEX]
682 match by tag name, and optionally also by tag value. Note a
683 tag: query is considered to match a transaction if it matches
684 any of the postings. Also remember that postings inherit the
685 tags of their parent transaction.
686 The following special search term is used automatically in hledger-web,
688 only:
689 inacct:ACCTNAME
691 tells hledger-web to show the transaction register for this
692 account. Can be filtered further with acct etc.
693 Some of these can also be expressed as command-line options (eg depth:2
695 is equivalent to --depth 2). Generally you can mix options and query
696 arguments, and the resulting query will be their intersection (perhaps
697 excluding the -p/--period option).
698 Special characters in arguments and queries
700 In shell command lines, option and argument values which contain "prob‐
701 lematic" characters, ie spaces, and also characters significant to your
702 shell such as <, >, (, ), | and $, should be escaped by enclosing them
703 in quotes or by writing backslashes before the characters. Eg:
704 hledger register -p 'last year' "accounts receivable (receiv‐
706 able|payable)" amt:\>100.
707 More escaping
709 Characters significant both to the shell and in regular expressions may
710 need one extra level of escaping. These include parentheses, the pipe
711 symbol and the dollar sign. Eg, to match the dollar symbol, bash users
712 should do:
713 hledger balance cur:'\$'
715 or:
717 hledger balance cur:\\$
719 Even more escaping
721 When hledger runs an addon executable (eg you type hledger ui, hledger
722 runs hledger-ui), it de-escapes command-line options and arguments
723 once, so you might need to triple-escape. Eg in bash, running the ui
724 command and matching the dollar sign, it's:
725 hledger ui cur:'\\$'
727 or:
729 hledger ui cur:\\\\$
731 If you asked why four slashes above, this may help:
733 unescaped: $
735 escaped: \$
736 double-escaped: \\$
737 triple-escaped: \\\\$
738 (The number of backslashes in fish shell is left as an exercise for the
740 reader.)
741 You can always avoid the extra escaping for addons by running the addon
743 directly:
744 hledger-ui cur:\\$
746 Less escaping
748 Inside an argument file, or in the search field of hledger-ui or
749 hledger-web, or at a GHCI prompt, you need one less level of escaping
750 than at the command line. And backslashes may work better than quotes.
751 Eg:
752 ghci> :main balance cur:\$
754 Unicode characters
756 hledger is expected to handle non-ascii characters correctly:
757 · they should be parsed correctly in input files and on the command
759 line, by all hledger tools (add, iadd, hledger-web's search/add/edit
760 forms, etc.)
761 · they should be displayed correctly by all hledger tools, and on-
763 screen alignment should be preserved.
764 This requires a well-configured environment. Here are some tips:
766 · A system locale must be configured, and it must be one that can
768 decode the characters being used. In bash, you can set a locale like
769 this: export LANG=en_US.UTF-8. There are some more details in Trou‐
770 bleshooting. This step is essential - without it, hledger will quit
771 on encountering a non-ascii character (as with all GHC-compiled pro‐
772 grams).
773 · your terminal software (eg Terminal.app, iTerm, CMD.exe, xterm..)
775 must support unicode
776 · the terminal must be using a font which includes the required unicode
778 glyphs
779 · the terminal should be configured to display wide characters as dou‐
781 ble width (for report alignment)
782 · on Windows, for best results you should run hledger in the same kind
784 of environment in which it was built. Eg hledger built in the stan‐
785 dard CMD.EXE environment (like the binaries on our download page)
786 might show display problems when run in a cygwin or msys terminal,
787 and vice versa. (See eg #961).
788 Input files
790 hledger reads transactions from a data file (and the add command writes
791 to it). By default this file is $HOME/.hledger.journal (or on Windows,
792 something like C:/Users/USER/.hledger.journal). You can override this
793 with the $LEDGER_FILE environment variable:
794 $ setenv LEDGER_FILE ~/finance/2016.journal
796 $ hledger stats
797 or with the -f/--file option:
799 $ hledger -f /some/file stats
801 The file name - (hyphen) means standard input:
803 $ cat some.journal | hledger -f-
805 Usually the data file is in hledger's journal format, but it can also
807 be one of several other formats, listed below. hledger detects the
808 format automatically based on the file extension, or if that is not
809 recognised, by trying each built-in "reader" in turn:
810 Reader: Reads: Used for file extensions:
812 ─────────────────────────────────────────────────────────────────────────────
813 journal hledger's journal format, also .journal .j .hledger .ledger
814 some Ledger journals
815 time‐ timeclock files (precise time .timeclock
816 clock logging)
817 timedot timedot files (approximate time .timedot
818 logging)
819 csv comma-separated values (data .csv
820 interchange)
821 If needed (eg to ensure correct error messages when a file has the
823 "wrong" extension), you can force a specific reader/format by prepend‐
824 ing it to the file path with a colon. Examples:
825 $ hledger -f csv:/some/csv-file.dat stats
827 $ echo 'i 2009/13/1 08:00:00' | hledger print -ftimeclock:-
828 You can also specify multiple -f options, to read multiple files as one
830 big journal. There are some limitations with this:
831 · directives in one file will not affect the other files
833 · balance assertions will not see any account balances from previous
835 files
836 If you need those, either use the include directive, or concatenate the
838 files, eg: cat a.journal b.journal | hledger -f- CMD.
839 Output destination
841 hledger commands send their output to the terminal by default. You can
842 of course redirect this, eg into a file, using standard shell syntax:
843 $ hledger print > foo.txt
845 Some commands (print, register, stats, the balance commands) also pro‐
847 vide the -o/--output-file option, which does the same thing without
848 needing the shell. Eg:
849 $ hledger print -o foo.txt
851 $ hledger print -o - # write to stdout (the default)
852 Output format
854 Some commands (print, register, the balance commands) offer a choice of
855 output format. In addition to the usual plain text format (txt), there
856 are CSV (csv), HTML (html) and JSON (json). This is controlled by the
857 -O/--output-format option:
858 $ hledger print -O csv
860 or, by a file extension specified with -o/--output-file:
862 $ hledger balancesheet -o foo.html # write HTML to foo.html
864 The -O option can be used to override the file extension if needed:
866 $ hledger balancesheet -o foo.txt -O html # write HTML to foo.txt
868 Some notes about JSON output:
870 · This feature is marked experimental, and not yet much used; you
872 should expect our JSON to evolve. Real-world feedback is welcome.
873 · Our JSON is rather large and verbose, as it is quite a faithful rep‐
875 resentation of hledger's internal data types. To understand the
876 JSON, read the Haskell type definitions, which are mostly in
877 https://github.com/simonmichael/hledger/blob/master/hledger-
878 lib/Hledger/Data/Types.hs.
879 · hledger represents quantities as Decimal values storing up to 255
881 significant digits, eg for repeating decimals. Such numbers can
882 arise in practice (from automatically-calculated transaction prices),
883 and would break most JSON consumers. So in JSON, we show quantities
884 as simple Numbers with at most 10 decimal places. We don't limit the
885 number of integer digits, but that part is under your control. We
886 hope this approach will not cause problems in practice; if you find
887 otherwise, please let us know. (Cf #1195)
888 Regular expressions
890 hledger uses regular expressions in a number of places:
891 · query terms, on the command line and in the hledger-web search form:
893 REGEX, desc:REGEX, cur:REGEX, tag:...=REGEX
894 · CSV rules conditional blocks: if REGEX ...
896 · account alias directives and options: alias /REGEX/ = REPLACEMENT,
898 --alias /REGEX/=REPLACEMENT
899 hledger's regular expressions come from the regex-tdfa library. If
901 they're not doing what you expect, it's important to know exactly what
902 they support:
903 1. they are case insensitive
905 2. they are infix matching (they do not need to match the entire thing
907 being matched)
908 3. they are POSIX ERE (extended regular expressions)
910 4. they also support GNU word boundaries (\b, \B, \<, \>)
912 5. they do not support backreferences; if you write \1, it will match
914 the digit 1. Except when doing text replacement, eg in account
915 aliases, where backreferences can be used in the replacement string
916 to reference capturing groups in the search regexp.
917 6. they do not support mode modifiers ((?s)), character classes (\w,
919 \d), or anything else not mentioned above.
920 Some things to note:
922 · In the alias directive and --alias option, regular expressions must
924 be enclosed in forward slashes (/REGEX/). Elsewhere in hledger,
925 these are not required.
926 · In queries, to match a regular expression metacharacter like $ as a
928 literal character, prepend a backslash. Eg to search for amounts
929 with the dollar sign in hledger-web, write cur:\$.
930 · On the command line, some metacharacters like $ have a special mean‐
932 ing to the shell and so must be escaped at least once more. See Spe‐
933 cial characters.
934 Smart dates
936 hledger's user interfaces accept a flexible "smart date" syntax (unlike
937 dates in the journal file). Smart dates allow some english words, can
938 be relative to today's date, and can have less-significant date parts
939 omitted (defaulting to 1).
940 Examples:
942 2004/10/1, 2004-01-01, exact date, several separators allowed. Year
944 2004.9.1 is 4+ digits, month is 1-12, day is 1-31
945 2004 start of year
946 2004/10 start of month
947 10/1 month and day in current year
948 21 day in current month
949 october, oct start of month in current year
950 yesterday, today, tomor‐ -1, 0, 1 days from today
951 row
952 last/this/next -1, 0, 1 periods from the current period
953 day/week/month/quar‐
954 ter/year
955 20181201 8 digit YYYYMMDD with valid year month and day
956 201812 6 digit YYYYMM with valid year and month
957 Counterexamples - malformed digit sequences might give surprising
959 results:
960 201813 6 digits with an invalid month is parsed as start of
962 6-digit year
963 20181301 8 digits with an invalid month is parsed as start of
964 8-digit year
965 20181232 8 digits with an invalid day gives an error
966 201801012 9+ digits beginning with a valid YYYYMMDD gives an error
967 Report start & end date
969 Most hledger reports show the full span of time represented by the
970 journal data, by default. So, the effective report start and end dates
971 will be the earliest and latest transaction or posting dates found in
972 the journal.
973 Often you will want to see a shorter time span, such as the current
975 month. You can specify a start and/or end date using -b/--begin,
976 -e/--end, -p/--period or a date: query (described below). All of these
977 accept the smart date syntax.
978 Some notes:
980 · As in Ledger, end dates are exclusive, so you need to write the date
982 after the last day you want to include.
983 · As noted in reporting options: among start/end dates specified with
985 options, the last (i.e. right-most) option takes precedence.
986 · The effective report start and end dates are the intersection of the
988 start/end dates from options and that from date: queries. That is,
989 date:2019-01 date:2019 -p'2000 to 2030' yields January 2019, the
990 smallest common time span.
991 Examples:
993 -b 2016/3/17 begin on St. Patrick’s day 2016
995 -e 12/1 end at the start of december 1st of the current year
996 (11/30 will be the last date included)
997 -b thismonth all transactions on or after the 1st of the current month
998 -p thismonth all transactions in the current month
999 date:2016/3/17.. the above written as queries instead (.. can also be
1000 replaced with -)
1001 date:..12/1
1002 date:thismonth..
1003 date:thismonth
1004 Report intervals
1006 A report interval can be specified so that commands like register, bal‐
1007 ance and activity will divide their reports into multiple subperiods.
1008 The basic intervals can be selected with one of -D/--daily,
1009 -W/--weekly, -M/--monthly, -Q/--quarterly, or -Y/--yearly. More com‐
1010 plex intervals may be specified with a period expression. Report
1011 intervals can not be specified with a query.
1012 Period expressions
1014 The -p/--period option accepts period expressions, a shorthand way of
1015 expressing a start date, end date, and/or report interval all at once.
1016 Here's a basic period expression specifying the first quarter of 2009.
1018 Note, hledger always treats start dates as inclusive and end dates as
1019 exclusive:
1020 -p "from 2009/1/1 to 2009/4/1"
1022 Keywords like "from" and "to" are optional, and so are the spaces, as
1024 long as you don't run two dates together. "to" can also be written as
1025 ".." or "-". These are equivalent to the above:
1026 -p "2009/1/1 2009/4/1"
1028 -p2009/1/1to2009/4/1
1029 -p2009/1/1..2009/4/1
1030 Dates are smart dates, so if the current year is 2009, the above can
1032 also be written as:
1033 -p "1/1 4/1"
1035 -p "january-apr"
1036 -p "this year to 4/1"
1037 If you specify only one date, the missing start or end date will be the
1039 earliest or latest transaction in your journal:
1040 -p "from 2009/1/1" everything after january
1042 1, 2009
1043 -p "from 2009/1" the same
1044 -p "from 2009" the same
1045 -p "to 2009" everything before january
1046 1, 2009
1047 A single date with no "from" or "to" defines both the start and end
1049 date like so:
1050 -p "2009" the year 2009; equivalent
1052 to “2009/1/1 to 2010/1/1”
1053 -p "2009/1" the month of jan; equiva‐
1054 lent to “2009/1/1 to
1055 2009/2/1”
1056 -p "2009/1/1" just that day; equivalent
1057 to “2009/1/1 to 2009/1/2”
1058 The argument of -p can also begin with, or be, a report interval
1060 expression. The basic report intervals are daily, weekly, monthly,
1061 quarterly, or yearly, which have the same effect as the -D,-W,-M,-Q, or
1062 -Y flags. Between report interval and start/end dates (if any), the
1063 word in is optional. Examples:
1064 -p "weekly from 2009/1/1 to 2009/4/1"
1066 -p "monthly in 2008"
1067 -p "quarterly"
1068 Note that weekly, monthly, quarterly and yearly intervals will always
1070 start on the first day on week, month, quarter or year accordingly, and
1071 will end on the last day of same period, even if associated period
1072 expression specifies different explicit start and end date.
1073 For example:
1075 -p "weekly from 2009/1/1 starts on 2008/12/29, closest preceding Mon‐
1077 to 2009/4/1" day
1078 -p "monthly in starts on 2018/11/01
1081 2008/11/25"
1082 -p "quarterly from starts on 2009/04/01, ends on 2009/06/30,
1083 2009-05-05 to 2009-06-01" which are first and last days of Q2 2009
1084 -p "yearly from starts on 2009/01/01, first day of 2009
1085 2009-12-29"
1086 The following more complex report intervals are also supported:
1088 biweekly, bimonthly, every day|week|month|quarter|year, every N
1089 days|weeks|months|quarters|years.
1090 All of these will start on the first day of the requested period and
1092 end on the last one, as described above.
1093 Examples:
1095 -p "bimonthly from 2008" periods will have boundaries on 2008/01/01,
1097 2008/03/01, ...
1098 -p "every 2 weeks" starts on closest preceding Monday
1099 -p "every 5 month from periods will have boundaries on 2009/03/01,
1100 2009/03" 2009/08/01, ...
1101 If you want intervals that start on arbitrary day of your choosing and
1103 span a week, month or year, you need to use any of the following:
1104 every Nth day of week, every <weekday>, every Nth day [of month], every
1106 Nth weekday [of month], every MM/DD [of year], every Nth MMM [of year],
1107 every MMM Nth [of year].
1108 Examples:
1110 -p "every 2nd day of periods will go from Tue to Tue
1112 week"
1113 -p "every Tue" same
1114 -p "every 15th day" period boundaries will be on 15th of each
1115 month
1116 -p "every 2nd Monday" period boundaries will be on second Monday of
1117 each month
1118 -p "every 11/05" yearly periods with boundaries on 5th of Nov
1119 -p "every 5th Nov" same
1120 -p "every Nov 5th" same
1121 Show historical balances at end of 15th each month (N is exclusive end
1123 date):
1124 hledger balance -H -p "every 16th day"
1126 Group postings from start of wednesday to end of next tuesday (N is
1128 start date and exclusive end date):
1129 hledger register checking -p "every 3rd day of week"
1131 Depth limiting
1133 With the --depth N option (short form: -N), commands like account, bal‐
1134 ance and register will show only the uppermost accounts in the account
1135 tree, down to level N. Use this when you want a summary with less
1136 detail. This flag has the same effect as a depth: query argument (so
1137 -2, --depth=2 or depth:2 are equivalent).
1138 Pivoting
1140 Normally hledger sums amounts, and organizes them in a hierarchy, based
1141 on account name. The --pivot FIELD option causes it to sum and orga‐
1142 nize hierarchy based on the value of some other field instead. FIELD
1143 can be: code, description, payee, note, or the full name (case insensi‐
1144 tive) of any tag. As with account names, values containing colon:sepa‐
1145 rated:parts will be displayed hierarchically in reports.
1146 --pivot is a general option affecting all reports; you can think of
1148 hledger transforming the journal before any other processing, replacing
1149 every posting's account name with the value of the specified field on
1150 that posting, inheriting it from the transaction or using a blank value
1151 if it's not present.
1152 An example:
1154 2016/02/16 Member Fee Payment
1156 assets:bank account 2 EUR
1157 income:member fees -2 EUR ; member: John Doe
1158 Normal balance report showing account names:
1160 $ hledger balance
1162 2 EUR assets:bank account
1163 -2 EUR income:member fees
1164 --------------------
1165 0
1166 Pivoted balance report, using member: tag values instead:
1168 $ hledger balance --pivot member
1170 2 EUR
1171 -2 EUR John Doe
1172 --------------------
1173 0
1174 One way to show only amounts with a member: value (using a query,
1176 described below):
1177 $ hledger balance --pivot member tag:member=.
1179 -2 EUR John Doe
1180 --------------------
1181 -2 EUR
1182 Another way (the acct: query matches against the pivoted "account
1184 name"):
1185 $ hledger balance --pivot member acct:.
1187 -2 EUR John Doe
1188 --------------------
1189 -2 EUR
1190 Valuation
1192 Instead of reporting amounts in their original commodity, hledger can
1193 convert them to cost/sale amount (using the conversion rate recorded in
1194 the transaction), or to market value (using some market price on a cer‐
1195 tain date). This is controlled by the --value=TYPE[,COMMODITY] option,
1196 but we also provide the simpler -B/-V/-X flags, and usually one of
1197 those is all you need.
1198 -B: Cost
1200 The -B/--cost flag converts amounts to their cost or sale amount at
1201 transaction time, if they have a transaction price specified.
1202 -V: Value
1204 The -V/--market flag converts amounts to market value in their default
1205 valuation commodity, using the market prices in effect on the valuation
1206 date(s), if any. More on these in a minute.
1207 -X: Value in specified commodity
1209 The -X/--exchange=COMM option is like -V, except you tell it which cur‐
1210 rency you want to convert to, and it tries to convert everything to
1211 that.
1212 Valuation date
1214 Since market prices can change from day to day, market value reports
1215 have a valuation date (or more than one), which determines which market
1216 prices will be used.
1217 For single period reports, if an explicit report end date is specified,
1219 that will be used as the valuation date; otherwise the valuation date
1220 is "today".
1221 For multiperiod reports, each column/period is valued on the last day
1223 of the period.
1224 Market prices
1226 (experimental)
1227 To convert a commodity A to its market value in another commodity B,
1229 hledger looks for a suitable market price (exchange rate) as follows,
1230 in this order of preference :
1231 1. A declared market price or inferred market price: A's latest market
1233 price in B on or before the valuation date as declared by a P direc‐
1234 tive, or (if the --infer-value flag is used) inferred from transac‐
1235 tion prices.
1236 2. A reverse market price: the inverse of a declared or inferred market
1238 price from B to A.
1239 3. A chained market price: a synthetic price formed by combining the
1241 shortest chain of market prices (any of the above types) leading
1242 from A to B.
1243 Amounts for which no applicable market price can be found, are not con‐
1245 verted.
1246 --infer-value: market prices from transactions
1248 (experimental)
1249 Normally, market value in hledger is fully controlled by, and requires,
1251 P directives in your journal. Since adding and updating those can be a
1252 chore, and since transactions usually take place at close to market
1253 value, why not use the recorded transaction prices as additional market
1254 prices (as Ledger does) ? We could produce value reports without need‐
1255 ing P directives at all.
1256 Adding the --infer-value flag to -V, -X or --value enables this. So
1258 for example, hledger bs -V --infer-value will get market prices both
1259 from P directives and from transactions.
1260 There is a downside: value reports can sometimes be affected in confus‐
1262 ing/undesired ways by your journal entries. If this happens to you,
1263 read all of this Valuation section carefully, and try adding --debug or
1264 --debug=2 to troubleshoot.
1265 --infer-value can infer market prices from:
1267 · multicommodity transactions with explicit prices (@/@@)
1269 · multicommodity transactions with implicit prices (no @, two commodi‐
1271 ties, unbalanced). (With these, the order of postings matters.
1272 hledger print -x can be useful for troubleshooting.)
1273 · but not, currently, from "more correct" multicommodity transactions
1275 (no @, multiple commodities, balanced).
1276 Valuation commodity
1278 (experimental)
1279 When you specify a valuation commodity (-X COMM or --value TYPE,COMM):
1281 hledger will convert all amounts to COMM, wherever it can find a suit‐
1282 able market price (including by reversing or chaining prices).
1283 When you leave the valuation commodity unspecified (-V or --value
1285 TYPE):
1286 For each commodity A, hledger picks a default valuation commodity as
1287 follows, in this order of preference:
1288 1. The price commodity from the latest P-declared market price for A on
1290 or before valuation date.
1291 2. The price commodity from the latest P-declared market price for A on
1293 any date. (Allows conversion to proceed when there are inferred
1294 prices before the valuation date.)
1295 3. If there are no P directives at all (any commodity or date) and the
1297 --infer-value flag is used: the price commodity from the latest
1298 transaction-inferred price for A on or before valuation date.
1299 This means:
1301 · If you have P directives, they determine which commodities -V will
1303 convert, and to what.
1304 · If you have no P directives, and use the --infer-value flag, transac‐
1306 tion prices determine it.
1307 Amounts for which no valuation commodity can be found are not con‐
1309 verted.
1310 Simple valuation examples
1312 Here are some quick examples of -V:
1313 ; one euro is worth this many dollars from nov 1
1315 P 2016/11/01 € $1.10
1316 ; purchase some euros on nov 3
1318 2016/11/3
1319 assets:euros €100
1320 assets:checking
1321 ; the euro is worth fewer dollars by dec 21
1323 P 2016/12/21 € $1.03
1324 How many euros do I have ?
1326 $ hledger -f t.j bal -N euros
1328 €100 assets:euros
1329 What are they worth at end of nov 3 ?
1331 $ hledger -f t.j bal -N euros -V -e 2016/11/4
1333 $110.00 assets:euros
1334 What are they worth after 2016/12/21 ? (no report end date specified,
1336 defaults to today)
1337 $ hledger -f t.j bal -N euros -V
1339 $103.00 assets:euros
1340 --value: Flexible valuation
1342 -B, -V and -X are special cases of the more general --value option:
1343 --value=TYPE[,COMM] TYPE is cost, then, end, now or YYYY-MM-DD.
1345 COMM is an optional commodity symbol.
1346 Shows amounts converted to:
1347 - cost commodity using transaction prices (then optionally to COMM using market prices at period end(s))
1348 - default valuation commodity (or COMM) using market prices at posting dates
1349 - default valuation commodity (or COMM) using market prices at period end(s)
1350 - default valuation commodity (or COMM) using current market prices
1351 - default valuation commodity (or COMM) using market prices at some date
1352 The TYPE part selects cost or value and valuation date:
1354 --value=cost
1356 Convert amounts to cost, using the prices recorded in transac‐
1357 tions.
1358 --value=then
1360 Convert amounts to their value in the default valuation commod‐
1361 ity, using market prices on each posting's date. This is cur‐
1362 rently supported only by the print and register commands.
1363 --value=end
1365 Convert amounts to their value in the default valuation commod‐
1366 ity, using market prices on the last day of the report period
1367 (or if unspecified, the journal's end date); or in multiperiod
1368 reports, market prices on the last day of each subperiod.
1369 --value=now
1371 Convert amounts to their value in the default valuation commod‐
1372 ity using current market prices (as of when report is gener‐
1373 ated).
1374 --value=YYYY-MM-DD
1376 Convert amounts to their value in the default valuation commod‐
1377 ity using market prices on this date.
1378 To select a different valuation commodity, add the optional ,COMM part:
1380 a comma, then the target commodity's symbol. Eg: --value=now,EUR.
1381 hledger will do its best to convert amounts to this commodity, deducing
1382 market prices as described above.
1383 More valuation examples
1385 Here are some examples showing the effect of --value, as seen with
1386 print:
1387 P 2000-01-01 A 1 B
1389 P 2000-02-01 A 2 B
1390 P 2000-03-01 A 3 B
1391 P 2000-04-01 A 4 B
1392 2000-01-01
1394 (a) 1 A @ 5 B
1395 2000-02-01
1397 (a) 1 A @ 6 B
1398 2000-03-01
1400 (a) 1 A @ 7 B
1401 Show the cost of each posting:
1403 $ hledger -f- print --value=cost
1405 2000-01-01
1406 (a) 5 B
1407 2000-02-01
1409 (a) 6 B
1410 2000-03-01
1412 (a) 7 B
1413 Show the value as of the last day of the report period (2000-02-29):
1415 $ hledger -f- print --value=end date:2000/01-2000/03
1417 2000-01-01
1418 (a) 2 B
1419 2000-02-01
1421 (a) 2 B
1422 With no report period specified, that shows the value as of the last
1424 day of the journal (2000-03-01):
1425 $ hledger -f- print --value=end
1427 2000-01-01
1428 (a) 3 B
1429 2000-02-01
1431 (a) 3 B
1432 2000-03-01
1434 (a) 3 B
1435 Show the current value (the 2000-04-01 price is still in effect today):
1437 $ hledger -f- print --value=now
1439 2000-01-01
1440 (a) 4 B
1441 2000-02-01
1443 (a) 4 B
1444 2000-03-01
1446 (a) 4 B
1447 Show the value on 2000/01/15:
1449 $ hledger -f- print --value=2000-01-15
1451 2000-01-01
1452 (a) 1 B
1453 2000-02-01
1455 (a) 1 B
1456 2000-03-01
1458 (a) 1 B
1459 You may need to explicitly set a commodity's display style, when
1461 reverse prices are used. Eg this output might be surprising:
1462 P 2000-01-01 A 2B
1464 2000-01-01
1466 a 1B
1467 b
1468 $ hledger print -x -X A
1470 2000-01-01
1471 a 0
1472 b 0
1473 Explanation: because there's no amount or commodity directive specify‐
1475 ing a display style for A, 0.5A gets the default style, which shows no
1476 decimal digits. Because the displayed amount looks like zero, the com‐
1477 modity symbol and minus sign are not displayed either. Adding a com‐
1478 modity directive sets a more useful display style for A:
1479 P 2000-01-01 A 2B
1481 commodity 0.00A
1482 2000-01-01
1484 a 1B
1485 b
1486 $ hledger print -X A
1488 2000-01-01
1489 a 0.50A
1490 b -0.50A
1491 Effect of valuation on reports
1493 Here is a reference for how valuation is supposed to affect each part
1494 of hledger's reports (and a glossary). (It's wide, you'll have to
1495 scroll sideways.) It may be useful when troubleshooting. If you find
1496 problems, please report them, ideally with a reproducible example.
1497 Related: #329, #1083.
1498 Report type -B, -V, -X --value=then --value=end --value=DATE,
1500 --value=cost --value=now
1501 ──────────────────────────────────────────────────────────────────────────────────────────
1502 print
1503 posting cost value at value at value at value at
1504 amounts report end posting date report or DATE/today
1505 or today journal end
1506 balance unchanged unchanged unchanged unchanged unchanged
1507 assertions /
1508 assignments
1509 register
1511 starting cost value at day not supported value at day value at
1512 balance before before DATE/today
1513 (with -H) report or report or
1514 journal journal
1515 start start
1516 posting cost value at value at value at value at
1517 amounts (no report end posting date report or DATE/today
1518 report or today journal end
1519 interval)
1520 summary summarised value at sum of post‐ value at value at
1521 posting cost period ends ings in period ends DATE/today
1522 amounts interval,
1523 (with report valued at
1524 interval) interval
1525 start
1526 running sum/average sum/average sum/average sum/average sum/average
1527 total/aver‐ of displayed of displayed of displayed of displayed of displayed
1528 age values values values values values
1529 balance (bs,
1531 bse, cf,
1532 is..)
1533 balances (no sums of value at not supported value at value at
1534 report costs report end report or DATE/today of
1535 interval) or today of journal end sums of post‐
1536 sums of of sums of ings
1537 postings postings
1538 balances sums of value at not supported value at value at
1539 (with report costs period ends period ends DATE/today of
1540 interval) of sums of of sums of sums of post‐
1541 postings postings ings
1542 starting sums of sums of not supported sums of sums of post‐
1543 balances costs of postings postings ings before
1544 (with report postings before before report start
1545 interval and before report start report start
1546 -H) report start
1547 budget like bal‐ like bal‐ not supported like bal‐ like balances
1548 amounts with ances ances ances
1549 --budget
1550 grand total sum of dis‐ sum of dis‐ not supported sum of dis‐ sum of dis‐
1551 (no report played val‐ played val‐ played val‐ played values
1552 interval) ues ues ues
1553 row sums/aver‐ sums/aver‐ not supported sums/aver‐ sums/averages
1554 totals/aver‐ ages of dis‐ ages of dis‐ ages of dis‐ of displayed
1555 ages (with played val‐ played val‐ played val‐ values
1556 report ues ues ues
1557 interval)
1558 column sums of dis‐ sums of dis‐ not supported sums of dis‐ sums of dis‐
1559 totals played val‐ played val‐ played val‐ played values
1560 ues ues ues
1561 grand sum/average sum/average not supported sum/average sum/average
1562 total/aver‐ of column of column of column of column
1563 age totals totals totals totals
1564 Glossary:
1567 cost calculated using price(s) recorded in the transaction(s).
1569 value market value using available market price declarations, or the
1571 unchanged amount if no conversion rate can be found.
1572 report start
1574 the first day of the report period specified with -b or -p or
1575 date:, otherwise today.
1576 report or journal start
1578 the first day of the report period specified with -b or -p or
1579 date:, otherwise the earliest transaction date in the journal,
1580 otherwise today.
1581 report end
1583 the last day of the report period specified with -e or -p or
1584 date:, otherwise today.
1585 report or journal end
1587 the last day of the report period specified with -e or -p or
1588 date:, otherwise the latest transaction date in the journal,
1589 otherwise today.
1590 report interval
1592 a flag (-D/-W/-M/-Q/-Y) or period expression that activates the
1593 report's multi-period mode (whether showing one or many subperi‐
1594 ods).
1595
1597 hledger provides a number of subcommands; hledger with no arguments
1598 shows a list.
1599 If you install additional hledger-* packages, or if you put programs or
1601 scripts named hledger-NAME in your PATH, these will also be listed as
1602 subcommands.
1603 Run a subcommand by writing its name as first argument (eg hledger
1605 incomestatement). You can also write one of the standard short aliases
1606 displayed in parentheses in the command list (hledger b), or any any
1607 unambiguous prefix of a command name (hledger inc).
1608 Here are all the builtin commands in alphabetical order. See also
1610 hledger for a more organised command list, and hledger CMD -h for
1611 detailed command help.
1612 accounts
1614 accounts, a
1615 Show account names.
1616 This command lists account names, either declared with account direc‐
1618 tives (--declared), posted to (--used), or both (the default). With
1619 query arguments, only matched account names and account names refer‐
1620 enced by matched postings are shown. It shows a flat list by default.
1621 With --tree, it uses indentation to show the account hierarchy. In
1622 flat mode you can add --drop N to omit the first few account name com‐
1623 ponents. Account names can be depth-clipped with depth:N or --depth N
1624 or -N.
1625 Examples:
1627 $ hledger accounts
1629 assets:bank:checking
1630 assets:bank:saving
1631 assets:cash
1632 expenses:food
1633 expenses:supplies
1634 income:gifts
1635 income:salary
1636 liabilities:debts
1637 activity
1639 activity
1640 Show an ascii barchart of posting counts per interval.
1641 The activity command displays an ascii histogram showing transaction
1643 counts by day, week, month or other reporting interval (by day is the
1644 default). With query arguments, it counts only matched transactions.
1645 Examples:
1647 $ hledger activity --quarterly
1649 2008-01-01 **
1650 2008-04-01 *******
1651 2008-07-01
1652 2008-10-01 **
1653 add
1655 add
1656 Prompt for transactions and add them to the journal.
1657 Many hledger users edit their journals directly with a text editor, or
1659 generate them from CSV. For more interactive data entry, there is the
1660 add command, which prompts interactively on the console for new trans‐
1661 actions, and appends them to the journal file (if there are multiple -f
1662 FILE options, the first file is used.) Existing transactions are not
1663 changed. This is the only hledger command that writes to the journal
1664 file.
1665 To use it, just run hledger add and follow the prompts. You can add as
1667 many transactions as you like; when you are finished, enter . or press
1668 control-d or control-c to exit.
1669 Features:
1671 · add tries to provide useful defaults, using the most similar (by
1673 description) recent transaction (filtered by the query, if any) as a
1674 template.
1675 · You can also set the initial defaults with command line arguments.
1677 · Readline-style edit keys can be used during data entry.
1679 · The tab key will auto-complete whenever possible - accounts, descrip‐
1681 tions, dates (yesterday, today, tomorrow). If the input area is
1682 empty, it will insert the default value.
1683 · If the journal defines a default commodity, it will be added to any
1685 bare numbers entered.
1686 · A parenthesised transaction code may be entered following a date.
1688 · Comments and tags may be entered following a description or amount.
1690 · If you make a mistake, enter < at any prompt to go one step backward.
1692 · Input prompts are displayed in a different colour when the terminal
1694 supports it.
1695 Example (see the tutorial for a detailed explanation):
1697 $ hledger add
1699 Adding transactions to journal file /src/hledger/examples/sample.journal
1700 Any command line arguments will be used as defaults.
1701 Use tab key to complete, readline keys to edit, enter to accept defaults.
1702 An optional (CODE) may follow transaction dates.
1703 An optional ; COMMENT may follow descriptions or amounts.
1704 If you make a mistake, enter < at any prompt to go one step backward.
1705 To end a transaction, enter . when prompted.
1706 To quit, enter . at a date prompt or press control-d or control-c.
1707 Date [2015/05/22]:
1708 Description: supermarket
1709 Account 1: expenses:food
1710 Amount 1: $10
1711 Account 2: assets:checking
1712 Amount 2 [$-10.0]:
1713 Account 3 (or . or enter to finish this transaction): .
1714 2015/05/22 supermarket
1715 expenses:food $10
1716 assets:checking $-10.0
1717 Save this transaction to the journal ? [y]:
1719 Saved.
1720 Starting the next transaction (. or ctrl-D/ctrl-C to quit)
1721 Date [2015/05/22]: <CTRL-D> $
1722 On Microsoft Windows, the add command makes sure that no part of the
1724 file path ends with a period, as it can cause data loss on that plat‐
1725 form (cf #1056).
1726 balance
1728 balance, bal, b
1729 Show accounts and their balances.
1730 The balance command is hledger's most versatile command. Note, despite
1732 the name, it is not always used for showing real-world account bal‐
1733 ances; the more accounting-aware balancesheet and incomestatement may
1734 be more convenient for that.
1735 By default, it displays all accounts, and each account's change in bal‐
1737 ance during the entire period of the journal. Balance changes are cal‐
1738 culated by adding up the postings in each account. You can limit the
1739 postings matched, by a query, to see fewer accounts, changes over a
1740 different time period, changes from only cleared transactions, etc.
1741 If you include an account's complete history of postings in the report,
1743 the balance change is equivalent to the account's current ending bal‐
1744 ance. For a real-world account, typically you won't have all transac‐
1745 tions in the journal; instead you'll have all transactions after a cer‐
1746 tain date, and an "opening balances" transaction setting the correct
1747 starting balance on that date. Then the balance command will show
1748 real-world account balances. In some cases the -H/--historical flag is
1749 used to ensure this (more below).
1750 The balance command can produce several styles of report:
1752 Classic balance report
1754 This is the original balance report, as found in Ledger. It usually
1755 looks like this:
1756 $ hledger balance
1758 $-1 assets
1759 $1 bank:saving
1760 $-2 cash
1761 $2 expenses
1762 $1 food
1763 $1 supplies
1764 $-2 income
1765 $-1 gifts
1766 $-1 salary
1767 $1 liabilities:debts
1768 --------------------
1769 0
1770 By default, accounts are displayed hierarchically, with subaccounts
1772 indented below their parent. At each level of the tree, accounts are
1773 sorted by account code if any, then by account name. Or with
1774 -S/--sort-amount, by their balance amount.
1775 "Boring" accounts, which contain a single interesting subaccount and no
1777 balance of their own, are elided into the following line for more com‐
1778 pact output. (Eg above, the "liabilities" account.) Use --no-elide to
1779 prevent this.
1780 Account balances are "inclusive" - they include the balances of any
1782 subaccounts.
1783 Accounts which have zero balance (and no non-zero subaccounts) are
1785 omitted. Use -E/--empty to show them.
1786 A final total is displayed by default; use -N/--no-total to suppress
1788 it, eg:
1789 $ hledger balance -p 2008/6 expenses --no-total
1791 $2 expenses
1792 $1 food
1793 $1 supplies
1794 Customising the classic balance report
1796 You can customise the layout of classic balance reports with --format
1797 FMT:
1798 $ hledger balance --format "%20(account) %12(total)"
1800 assets $-1
1801 bank:saving $1
1802 cash $-2
1803 expenses $2
1804 food $1
1805 supplies $1
1806 income $-2
1807 gifts $-1
1808 salary $-1
1809 liabilities:debts $1
1810 ---------------------------------
1811 0
1812 The FMT format string (plus a newline) specifies the formatting applied
1814 to each account/balance pair. It may contain any suitable text, with
1815 data fields interpolated like so:
1816 %[MIN][.MAX](FIELDNAME)
1818 · MIN pads with spaces to at least this width (optional)
1820 · MAX truncates at this width (optional)
1822 · FIELDNAME must be enclosed in parentheses, and can be one of:
1824 · depth_spacer - a number of spaces equal to the account's depth, or
1826 if MIN is specified, MIN * depth spaces.
1827 · account - the account's name
1829 · total - the account's balance/posted total, right justified
1831 Also, FMT can begin with an optional prefix to control how multi-com‐
1833 modity amounts are rendered:
1834 · %_ - render on multiple lines, bottom-aligned (the default)
1836 · %^ - render on multiple lines, top-aligned
1838 · %, - render on one line, comma-separated
1840 There are some quirks. Eg in one-line mode, %(depth_spacer) has no
1842 effect, instead %(account) has indentation built in. Experimentation
1843 may be needed to get pleasing results.
1844 Some example formats:
1846 · %(total) - the account's total
1848 · %-20.20(account) - the account's name, left justified, padded to 20
1850 characters and clipped at 20 characters
1851 · %,%-50(account) %25(total) - account name padded to 50 characters,
1853 total padded to 20 characters, with multiple commodities rendered on
1854 one line
1855 · %20(total) %2(depth_spacer)%-(account) - the default format for the
1857 single-column balance report
1858 Colour support
1860 The balance command shows negative amounts in red, if:
1861 · the TERM environment variable is not set to dumb
1863 · the output is not being redirected or piped anywhere
1865 Flat mode
1867 To see a flat list instead of the default hierarchical display, use
1868 --flat. In this mode, accounts (unless depth-clipped) show their full
1869 names and "exclusive" balance, excluding any subaccount balances. In
1870 this mode, you can also use --drop N to omit the first few account name
1871 components.
1872 $ hledger balance -p 2008/6 expenses -N --flat --drop 1
1874 $1 food
1875 $1 supplies
1876 Depth limited balance reports
1878 With --depth N or depth:N or just -N, balance reports show accounts
1879 only to the specified numeric depth. This is very useful to summarise
1880 a complex set of accounts and get an overview.
1881 $ hledger balance -N -1
1883 $-1 assets
1884 $2 expenses
1885 $-2 income
1886 $1 liabilities
1887 Flat-mode balance reports, which normally show exclusive balances, show
1889 inclusive balances at the depth limit.
1890 Percentages
1892 With -% or --percent, balance reports show each account's value
1893 expressed as a percentage of the column's total. This is useful to get
1894 an overview of the relative sizes of account balances. For example to
1895 obtain an overview of expenses:
1896 $ hledger balance expenses -%
1898 100.0 % expenses
1899 50.0 % food
1900 50.0 % supplies
1901 --------------------
1902 100.0 %
1903 Note that --tree does not have an effect on -%. The percentages are
1905 always relative to the total sum of each column, they are never rela‐
1906 tive to the parent account.
1907 Since the percentages are relative to the columns sum, it is usually
1909 not useful to calculate percentages if the signs of the amounts are
1910 mixed. Although the results are technically correct, they are most
1911 likely useless. Especially in a balance report that sums up to zero
1912 (eg hledger balance -B) all percentage values will be zero.
1913 This flag does not work if the report contains any mixed commodity
1915 accounts. If there are mixed commodity accounts in the report be sure
1916 to use -V or -B to coerce the report into using a single commodity.
1917 Multicolumn balance report
1919 Multicolumn or tabular balance reports are a very useful hledger fea‐
1920 ture, and usually the preferred style. They share many of the above
1921 features, but they show the report as a table, with columns represent‐
1922 ing time periods. This mode is activated by providing a reporting
1923 interval.
1924 There are three types of multicolumn balance report, showing different
1926 information:
1927 1. By default: each column shows the sum of postings in that period, ie
1929 the account's change of balance in that period. This is useful eg
1930 for a monthly income statement:
1931 $ hledger balance --quarterly income expenses -E
1933 Balance changes in 2008:
1934 || 2008q1 2008q2 2008q3 2008q4
1936 ===================++=================================
1937 expenses:food || 0 $1 0 0
1938 expenses:supplies || 0 $1 0 0
1939 income:gifts || 0 $-1 0 0
1940 income:salary || $-1 0 0 0
1941 -------------------++---------------------------------
1942 || $-1 $1 0 0
1943 2. With --cumulative: each column shows the ending balance for that
1945 period, accumulating the changes across periods, starting from 0 at
1946 the report start date:
1947 $ hledger balance --quarterly income expenses -E --cumulative
1949 Ending balances (cumulative) in 2008:
1950 || 2008/03/31 2008/06/30 2008/09/30 2008/12/31
1952 ===================++=================================================
1953 expenses:food || 0 $1 $1 $1
1954 expenses:supplies || 0 $1 $1 $1
1955 income:gifts || 0 $-1 $-1 $-1
1956 income:salary || $-1 $-1 $-1 $-1
1957 -------------------++-------------------------------------------------
1958 || $-1 0 0 0
1959 3. With --historical/-H: each column shows the actual historical ending
1961 balance for that period, accumulating the changes across periods,
1962 starting from the actual balance at the report start date. This is
1963 useful eg for a multi-period balance sheet, and when you are showing
1964 only the data after a certain start date:
1965 $ hledger balance ^assets ^liabilities --quarterly --historical --begin 2008/4/1
1967 Ending balances (historical) in 2008/04/01-2008/12/31:
1968 || 2008/06/30 2008/09/30 2008/12/31
1970 ======================++=====================================
1971 assets:bank:checking || $1 $1 0
1972 assets:bank:saving || $1 $1 $1
1973 assets:cash || $-2 $-2 $-2
1974 liabilities:debts || 0 0 $1
1975 ----------------------++-------------------------------------
1976 || 0 0 0
1977 Note that --cumulative or --historical/-H disable --row-total/-T, since
1979 summing end balances generally does not make sense.
1980 Multicolumn balance reports display accounts in flat mode by default;
1982 to see the hierarchy, use --tree.
1983 With a reporting interval (like --quarterly above), the report
1985 start/end dates will be adjusted if necessary so that they encompass
1986 the displayed report periods. This is so that the first and last peri‐
1987 ods will be "full" and comparable to the others.
1988 The -E/--empty flag does two things in multicolumn balance reports:
1990 first, the report will show all columns within the specified report
1991 period (without -E, leading and trailing columns with all zeroes are
1992 not shown). Second, all accounts which existed at the report start
1993 date will be considered, not just the ones with activity during the
1994 report period (use -E to include low-activity accounts which would oth‐
1995 erwise would be omitted).
1996 The -T/--row-total flag adds an additional column showing the total for
1998 each row.
1999 The -A/--average flag adds a column showing the average value in each
2001 row.
2002 Here's an example of all three:
2004 $ hledger balance -Q income expenses --tree -ETA
2006 Balance changes in 2008:
2007 || 2008q1 2008q2 2008q3 2008q4 Total Average
2009 ============++===================================================
2010 expenses || 0 $2 0 0 $2 $1
2011 food || 0 $1 0 0 $1 0
2012 supplies || 0 $1 0 0 $1 0
2013 income || $-1 $-1 0 0 $-2 $-1
2014 gifts || 0 $-1 0 0 $-1 0
2015 salary || $-1 0 0 0 $-1 0
2016 ------------++---------------------------------------------------
2017 || $-1 $1 0 0 0 0
2018 (Average is rounded to the dollar here since all journal amounts are)
2020 A limitation of multicolumn balance reports: eliding of boring parent
2022 accounts in tree mode, as in the classic balance report, is not yet
2023 supported.
2024 The --transpose flag can be used to exchange the rows and columns of a
2026 multicolumn report.
2027 Budget report
2029 With --budget, extra columns are displayed showing budget goals for
2030 each account and period, if any. Budget goals are defined by periodic
2031 transactions. This is very useful for comparing planned and actual
2032 income, expenses, time usage, etc. --budget is most often combined
2033 with a report interval.
2034 For example, you can take average monthly expenses in the common
2036 expense categories to construct a minimal monthly budget:
2037 ;; Budget
2039 ~ monthly
2040 income $2000
2041 expenses:food $400
2042 expenses:bus $50
2043 expenses:movies $30
2044 assets:bank:checking
2045 ;; Two months worth of expenses
2047 2017-11-01
2048 income $1950
2049 expenses:food $396
2050 expenses:bus $49
2051 expenses:movies $30
2052 expenses:supplies $20
2053 assets:bank:checking
2054 2017-12-01
2056 income $2100
2057 expenses:food $412
2058 expenses:bus $53
2059 expenses:gifts $100
2060 assets:bank:checking
2061 You can now see a monthly budget report:
2063 $ hledger balance -M --budget
2065 Budget performance in 2017/11/01-2017/12/31:
2066 || Nov Dec
2068 ======================++====================================================
2069 assets || $-2445 [ 99% of $-2480] $-2665 [ 107% of $-2480]
2070 assets:bank || $-2445 [ 99% of $-2480] $-2665 [ 107% of $-2480]
2071 assets:bank:checking || $-2445 [ 99% of $-2480] $-2665 [ 107% of $-2480]
2072 expenses || $495 [ 103% of $480] $565 [ 118% of $480]
2073 expenses:bus || $49 [ 98% of $50] $53 [ 106% of $50]
2074 expenses:food || $396 [ 99% of $400] $412 [ 103% of $400]
2075 expenses:movies || $30 [ 100% of $30] 0 [ 0% of $30]
2076 income || $1950 [ 98% of $2000] $2100 [ 105% of $2000]
2077 ----------------------++----------------------------------------------------
2078 || 0 [ 0] 0 [ 0]
2079 This is different from a normal balance report in several ways:
2081 · Only accounts with budget goals during the report period are shown,
2083 by default.
2084 · In each column, in square brackets after the actual amount, budget
2086 goal amounts are shown, and the actual/goal percentage. (Note: bud‐
2087 get goals should be in the same commodity as the actual amount.)
2088 · All parent accounts are always shown, even in flat mode. Eg assets,
2090 assets:bank, and expenses above.
2091 · Amounts always include all subaccounts, budgeted or unbudgeted, even
2093 in flat mode.
2094 This means that the numbers displayed will not always add up! Eg above,
2096 the expenses actual amount includes the gifts and supplies transac‐
2097 tions, but the expenses:gifts and expenses:supplies accounts are not
2098 shown, as they have no budget amounts declared.
2099 This can be confusing. When you need to make things clearer, use the
2101 -E/--empty flag, which will reveal all accounts including unbudgeted
2102 ones, giving the full picture. Eg:
2103 $ hledger balance -M --budget --empty
2105 Budget performance in 2017/11/01-2017/12/31:
2106 || Nov Dec
2108 ======================++====================================================
2109 assets || $-2445 [ 99% of $-2480] $-2665 [ 107% of $-2480]
2110 assets:bank || $-2445 [ 99% of $-2480] $-2665 [ 107% of $-2480]
2111 assets:bank:checking || $-2445 [ 99% of $-2480] $-2665 [ 107% of $-2480]
2112 expenses || $495 [ 103% of $480] $565 [ 118% of $480]
2113 expenses:bus || $49 [ 98% of $50] $53 [ 106% of $50]
2114 expenses:food || $396 [ 99% of $400] $412 [ 103% of $400]
2115 expenses:gifts || 0 $100
2116 expenses:movies || $30 [ 100% of $30] 0 [ 0% of $30]
2117 expenses:supplies || $20 0
2118 income || $1950 [ 98% of $2000] $2100 [ 105% of $2000]
2119 ----------------------++----------------------------------------------------
2120 || 0 [ 0] 0 [ 0]
2121 You can roll over unspent budgets to next period with --cumulative:
2123 $ hledger balance -M --budget --cumulative
2125 Budget performance in 2017/11/01-2017/12/31:
2126 || Nov Dec
2128 ======================++====================================================
2129 assets || $-2445 [ 99% of $-2480] $-5110 [ 103% of $-4960]
2130 assets:bank || $-2445 [ 99% of $-2480] $-5110 [ 103% of $-4960]
2131 assets:bank:checking || $-2445 [ 99% of $-2480] $-5110 [ 103% of $-4960]
2132 expenses || $495 [ 103% of $480] $1060 [ 110% of $960]
2133 expenses:bus || $49 [ 98% of $50] $102 [ 102% of $100]
2134 expenses:food || $396 [ 99% of $400] $808 [ 101% of $800]
2135 expenses:movies || $30 [ 100% of $30] $30 [ 50% of $60]
2136 income || $1950 [ 98% of $2000] $4050 [ 101% of $4000]
2137 ----------------------++----------------------------------------------------
2138 || 0 [ 0] 0 [ 0]
2139 For more examples, see Budgeting and Forecasting.
2141 Nested budgets
2143 You can add budgets to any account in your account hierarchy. If you
2144 have budgets on both parent account and some of its children, then bud‐
2145 get(s) of the child account(s) would be added to the budget of their
2146 parent, much like account balances behave.
2147 In the most simple case this means that once you add a budget to any
2149 account, all its parents would have budget as well.
2150 To illustrate this, consider the following budget:
2152 ~ monthly from 2019/01
2154 expenses:personal $1,000.00
2155 expenses:personal:electronics $100.00
2156 liabilities
2157 With this, monthly budget for electronics is defined to be $100 and
2159 budget for personal expenses is an additional $1000, which implicitly
2160 means that budget for both expenses:personal and expenses is $1100.
2161 Transactions in expenses:personal:electronics will be counted both
2163 towards its $100 budget and $1100 of expenses:personal , and transac‐
2164 tions in any other subaccount of expenses:personal would be counted
2165 towards only towards the budget of expenses:personal.
2166 For example, let's consider these transactions:
2168 ~ monthly from 2019/01
2170 expenses:personal $1,000.00
2171 expenses:personal:electronics $100.00
2172 liabilities
2173 2019/01/01 Google home hub
2175 expenses:personal:electronics $90.00
2176 liabilities $-90.00
2177 2019/01/02 Phone screen protector
2179 expenses:personal:electronics:upgrades $10.00
2180 liabilities
2181 2019/01/02 Weekly train ticket
2183 expenses:personal:train tickets $153.00
2184 liabilities
2185 2019/01/03 Flowers
2187 expenses:personal $30.00
2188 liabilities
2189 As you can see, we have transactions in expenses:personal:electron‐
2191 ics:upgrades and expenses:personal:train tickets, and since both of
2192 these accounts are without explicitly defined budget, these transac‐
2193 tions would be counted towards budgets of expenses:personal:electronics
2194 and expenses:personal accordingly:
2195 $ hledger balance --budget -M
2197 Budget performance in 2019/01:
2198 || Jan
2200 ===============================++===============================
2201 expenses || $283.00 [ 26% of $1100.00]
2202 expenses:personal || $283.00 [ 26% of $1100.00]
2203 expenses:personal:electronics || $100.00 [ 100% of $100.00]
2204 liabilities || $-283.00 [ 26% of $-1100.00]
2205 -------------------------------++-------------------------------
2206 || 0 [ 0]
2207 And with --empty, we can get a better picture of budget allocation and
2209 consumption:
2210 $ hledger balance --budget -M --empty
2212 Budget performance in 2019/01:
2213 || Jan
2215 ========================================++===============================
2216 expenses || $283.00 [ 26% of $1100.00]
2217 expenses:personal || $283.00 [ 26% of $1100.00]
2218 expenses:personal:electronics || $100.00 [ 100% of $100.00]
2219 expenses:personal:electronics:upgrades || $10.00
2220 expenses:personal:train tickets || $153.00
2221 liabilities || $-283.00 [ 26% of $-1100.00]
2222 ----------------------------------------++-------------------------------
2223 || 0 [ 0]
2224 Output format
2226 This command also supports the output destination and output format
2227 options The output formats supported are txt, csv, (multicolumn non-
2228 budget reports only) html, and (experimental) json.
2229 balancesheet
2231 balancesheet, bs
2232 This command displays a simple balance sheet, showing historical ending
2233 balances of asset and liability accounts (ignoring any report begin
2234 date). It assumes that these accounts are under a top-level asset or
2235 liability account (case insensitive, plural forms also allowed).
2236 Note this report shows all account balances with normal positive sign
2238 (like conventional financial statements, unlike balance/print/register)
2239 (experimental).
2240 Example:
2242 $ hledger balancesheet
2244 Balance Sheet
2245 Assets:
2247 $-1 assets
2248 $1 bank:saving
2249 $-2 cash
2250 --------------------
2251 $-1
2252 Liabilities:
2254 $1 liabilities:debts
2255 --------------------
2256 $1
2257 Total:
2259 --------------------
2260 0
2261 With a reporting interval, multiple columns will be shown, one for each
2263 report period. As with multicolumn balance reports, you can alter the
2264 report mode with --change/--cumulative/--historical. Normally bal‐
2265 ancesheet shows historical ending balances, which is what you need for
2266 a balance sheet; note this means it ignores report begin dates (and
2267 -T/--row-total, since summing end balances generally does not make
2268 sense). Instead of absolute values percentages can be displayed with
2269 -%.
2270 This command also supports the output destination and output format
2272 options The output formats supported are txt, csv, html, and (experi‐
2273 mental) json.
2274 balancesheetequity
2276 balancesheetequity, bse
2277 Just like balancesheet, but also reports Equity (which it assumes is
2278 under a top-level equity account).
2279 Example:
2281 $ hledger balancesheetequity
2283 Balance Sheet With Equity
2284 Assets:
2286 $-2 assets
2287 $1 bank:saving
2288 $-3 cash
2289 --------------------
2290 $-2
2291 Liabilities:
2293 $1 liabilities:debts
2294 --------------------
2295 $1
2296 Equity:
2298 $1 equity:owner
2299 --------------------
2300 $1
2301 Total:
2303 --------------------
2304 0
2305 This command also supports the output destination and output format
2307 options The output formats supported are txt, csv, html, and (experi‐
2308 mental) json.
2309 cashflow
2311 cashflow, cf
2312 This command displays a simple cashflow statement, showing changes in
2313 "cash" accounts. It assumes that these accounts are under a top-level
2314 asset account (case insensitive, plural forms also allowed) and do not
2315 contain receivable or A/R in their name. Note this report shows all
2316 account balances with normal positive sign (like conventional financial
2317 statements, unlike balance/print/register) (experimental).
2318 Example:
2320 $ hledger cashflow
2322 Cashflow Statement
2323 Cash flows:
2325 $-1 assets
2326 $1 bank:saving
2327 $-2 cash
2328 --------------------
2329 $-1
2330 Total:
2332 --------------------
2333 $-1
2334 With a reporting interval, multiple columns will be shown, one for each
2336 report period. Normally cashflow shows changes in assets per period,
2337 though as with multicolumn balance reports you can alter the report
2338 mode with --change/--cumulative/--historical. Instead of absolute val‐
2339 ues percentages can be displayed with -%.
2340 This command also supports the output destination and output format
2342 options The output formats supported are txt, csv, html, and (experi‐
2343 mental) json.
2344 check-dates
2346 check-dates
2347 Check that transactions are sorted by increasing date. With --date2,
2348 checks secondary dates instead. With --strict, dates must also be
2349 unique. With a query, only matched transactions' dates are checked.
2350 Reads the default journal file, or another specified with -f.
2351 check-dupes
2353 check-dupes
2354 Reports account names having the same leaf but different prefixes. In
2355 other words, two or more leaves that are categorized differently.
2356 Reads the default journal file, or another specified as an argument.
2357 An example: http://stefanorodighiero.net/software/hledger-dupes.html
2359 close
2361 close, equity
2362 Prints a "closing balances" transaction and an "opening balances"
2363 transaction that bring account balances to and from zero, respectively.
2364 These can be added to your journal file(s), eg to bring asset/liability
2365 balances forward into a new journal file, or to close out rev‐
2366 enues/expenses to retained earnings at the end of a period.
2367 You can print just one of these transactions by using the --close or
2369 --open flag. You can customise their descriptions with the --close-
2370 desc and --open-desc options.
2371 One amountless posting to "equity:opening/closing balances" is added to
2373 balance the transactions, by default. You can customise this account
2374 name with --close-acct and --open-acct; if you specify only one of
2375 these, it will be used for both.
2376 With --x/--explicit, the equity posting's amount will be shown. And if
2378 it involves multiple commodities, a posting for each commodity will be
2379 shown, as with the print command.
2380 With --interleaved, the equity postings are shown next to the postings
2382 they balance, which makes troubleshooting easier.
2383 By default, transaction prices in the journal are ignored when generat‐
2385 ing the closing/opening transactions. With --show-costs, this cost
2386 information is preserved (balance -B reports will be unchanged after
2387 the transition). Separate postings are generated for each cost in each
2388 commodity. Note this can generate very large journal entries, if you
2389 have many foreign currency or investment transactions.
2390 close usage
2392 If you split your journal files by time (eg yearly), you will typically
2393 run this command at the end of the year, and save the closing transac‐
2394 tion as last entry of the old file, and the opening transaction as the
2395 first entry of the new file. This makes the files self contained, so
2396 that correct balances are reported no matter which of them are loaded.
2397 Ie, if you load just one file, the balances are initialised correctly;
2398 or if you load several files, the redundant closing/opening transac‐
2399 tions cancel each other out. (They will show up in print or register
2400 reports; you can exclude them with a query like not:desc:'(open‐
2401 ing|closing) balances'.)
2402 If you're running a business, you might also use this command to "close
2404 the books" at the end of an accounting period, transferring income
2405 statement account balances to retained earnings. (You may want to
2406 change the equity account name to something like "equity:retained earn‐
2407 ings".)
2408 By default, the closing transaction is dated yesterday, the balances
2410 are calculated as of end of yesterday, and the opening transaction is
2411 dated today. To close on some other date, use: hledger close -e OPEN‐
2412 INGDATE. Eg, to close/open on the 2018/2019 boundary, use -e 2019.
2413 You can also use -p or date:PERIOD (any starting date is ignored).
2414 Both transactions will include balance assertions for the
2416 closed/reopened accounts. You probably shouldn't use status or real‐
2417 ness filters (like -C or -R or status:) with this command, or the gen‐
2418 erated balance assertions will depend on these flags. Likewise, if you
2419 run this command with --auto, the balance assertions will probably
2420 always require --auto.
2421 Examples:
2423 Carrying asset/liability balances into a new file for 2019:
2425 $ hledger close -f 2018.journal -e 2019 assets liabilities --open
2427 # (copy/paste the output to the start of your 2019 journal file)
2428 $ hledger close -f 2018.journal -e 2019 assets liabilities --close
2429 # (copy/paste the output to the end of your 2018 journal file)
2430 Now:
2432 $ hledger bs -f 2019.journal # one file - balances are correct
2434 $ hledger bs -f 2018.journal -f 2019.journal # two files - balances still correct
2435 $ hledger bs -f 2018.journal not:desc:closing # to see year-end balances, must exclude closing txn
2436 Transactions spanning the closing date can complicate matters, breaking
2438 balance assertions:
2439 2018/12/30 a purchase made in 2018, clearing the following year
2441 expenses:food 5
2442 assets:bank:checking -5 ; [2019/1/2]
2443 Here's one way to resolve that:
2445 ; in 2018.journal:
2447 2018/12/30 a purchase made in 2018, clearing the following year
2448 expenses:food 5
2449 liabilities:pending
2450 ; in 2019.journal:
2452 2019/1/2 clearance of last year's pending transactions
2453 liabilities:pending 5 = 0
2454 assets:checking
2455 commodities
2457 commodities
2458 List all commodity/currency symbols used or declared in the journal.
2459 descriptions
2461 descriptions Show descriptions.
2462 This command lists all descriptions that appear in transactions.
2464 Examples:
2466 $ hledger descriptions
2468 Store Name
2469 Gas Station | Petrol
2470 Person A
2471 diff
2473 diff
2474 Compares a particular account's transactions in two input files. It
2475 shows any transactions to this account which are in one file but not in
2476 the other.
2477 More precisely, for each posting affecting this account in either file,
2479 it looks for a corresponding posting in the other file which posts the
2480 same amount to the same account (ignoring date, description, etc.)
2481 Since postings not transactions are compared, this also works when mul‐
2482 tiple bank transactions have been combined into a single journal entry.
2483 This is useful eg if you have downloaded an account's transactions from
2485 your bank (eg as CSV data). When hledger and your bank disagree about
2486 the account balance, you can compare the bank data with your journal to
2487 find out the cause.
2488 Examples:
2490 $ hledger diff -f $LEDGER_FILE -f bank.csv assets:bank:giro
2492 These transactions are in the first file only:
2493 2014/01/01 Opening Balances
2495 assets:bank:giro EUR ...
2496 ...
2497 equity:opening balances EUR -...
2498 These transactions are in the second file only:
2500 files
2502 files
2503 List all files included in the journal. With a REGEX argument, only
2504 file names matching the regular expression (case sensitive) are shown.
2505 help
2507 help
2508 Show any of the hledger manuals.
2509 The help command displays any of the main hledger manuals, in one of
2511 several ways. Run it with no argument to list the manuals, or provide
2512 a full or partial manual name to select one.
2513 hledger manuals are available in several formats. hledger help will
2515 use the first of these display methods that it finds: info, man,
2516 $PAGER, less, stdout (or when non-interactive, just stdout). You can
2517 force a particular viewer with the --info, --man, --pager, --cat flags.
2518 Examples:
2520 $ hledger help
2522 Please choose a manual by typing "hledger help MANUAL" (a substring is ok).
2523 Manuals: hledger hledger-ui hledger-web journal csv timeclock timedot
2524 $ hledger help h --man
2526 hledger(1) hledger User Manuals hledger(1)
2528 NAME
2530 hledger - a command-line accounting tool
2531 SYNOPSIS
2533 hledger [-f FILE] COMMAND [OPTIONS] [ARGS]
2534 hledger [-f FILE] ADDONCMD -- [OPTIONS] [ARGS]
2535 hledger
2536 DESCRIPTION
2538 hledger is a cross-platform program for tracking money, time, or any
2539 ...
2540 import
2542 import
2543 Read new transactions added to each FILE since last run, and add them
2544 to the main journal file. Or with --dry-run, just print the transac‐
2545 tions that would be added. Or with --catchup, just mark all of the
2546 FILEs' transactions as imported, without actually importing any.
2547 The input files are specified as arguments - no need to write -f before
2549 each one. So eg to add new transactions from all CSV files to the main
2550 journal, it's just: hledger import *.csv
2551 New transactions are detected in the same way as print --new: by assum‐
2553 ing transactions are always added to the input files in increasing date
2554 order, and by saving .latest.FILE state files.
2555 The --dry-run output is in journal format, so you can filter it, eg to
2557 see only uncategorised transactions:
2558 $ hledger import --dry ... | hledger -f- print unknown --ignore-assertions
2560 Importing balance assignments
2562 Entries added by import will have their posting amounts made explicit
2563 (like hledger print -x). This means that any balance assignments in
2564 imported files must be evaluated; but, imported files don't get to see
2565 the main file's account balances. As a result, importing entries with
2566 balance assignments (eg from an institution that provides only balances
2567 and not posting amounts) will probably generate incorrect posting
2568 amounts. To avoid this problem, use print instead of import:
2569 $ hledger print IMPORTFILE [--new] >> $LEDGER_FILE
2571 (If you think import should leave amounts implicit like print does,
2573 please test it and send a pull request.)
2574 incomestatement
2576 incomestatement, is
2577 This command displays a simple income statement, showing revenues and
2578 expenses during a period. It assumes that these accounts are under a
2579 top-level revenue or income or expense account (case insensitive, plu‐
2580 ral forms also allowed). Note this report shows all account balances
2581 with normal positive sign (like conventional financial statements,
2582 unlike balance/print/register) (experimental).
2583 This command displays a simple income statement. It currently assumes
2585 that you have top-level accounts named income (or revenue) and expense
2586 (plural forms also allowed.)
2587 $ hledger incomestatement
2589 Income Statement
2590 Revenues:
2592 $-2 income
2593 $-1 gifts
2594 $-1 salary
2595 --------------------
2596 $-2
2597 Expenses:
2599 $2 expenses
2600 $1 food
2601 $1 supplies
2602 --------------------
2603 $2
2604 Total:
2606 --------------------
2607 0
2608 With a reporting interval, multiple columns will be shown, one for each
2610 report period. Normally incomestatement shows revenues/expenses per
2611 period, though as with multicolumn balance reports you can alter the
2612 report mode with --change/--cumulative/--historical. Instead of abso‐
2613 lute values percentages can be displayed with -%.
2614 This command also supports the output destination and output format
2616 options The output formats supported are txt, csv, html, and (experi‐
2617 mental) json.
2618 notes
2620 notes Show notes.
2621 This command lists all notes that appear in transactions.
2623 Examples:
2625 $ hledger notes
2627 Petrol
2628 Snacks
2629 payees
2631 payees Show payee names.
2632 This command lists all payee names that appear in transactions.
2634 Examples:
2636 $ hledger payees
2638 Store Name
2639 Gas Station
2640 Person A
2641 prices
2643 prices
2644 Print market price directives from the journal. With --costs, also
2645 print synthetic market prices based on transaction prices. With
2646 --inverted-costs, also print inverse prices based on transaction
2647 prices. Prices (and postings providing prices) can be filtered by a
2648 query. Price amounts are always displayed with their full precision.
2649 print
2651 print, txns, p
2652 Show transaction journal entries, sorted by date.
2653 The print command displays full journal entries (transactions) from the
2655 journal file in date order, tidily formatted. With --date2, transac‐
2656 tions are sorted by secondary date instead.
2657 print's output is always a valid hledger journal.
2659 It preserves all transaction information, but it does not preserve
2660 directives or inter-transaction comments
2661 $ hledger print
2663 2008/01/01 income
2664 assets:bank:checking $1
2665 income:salary $-1
2666 2008/06/01 gift
2668 assets:bank:checking $1
2669 income:gifts $-1
2670 2008/06/02 save
2672 assets:bank:saving $1
2673 assets:bank:checking $-1
2674 2008/06/03 * eat & shop
2676 expenses:food $1
2677 expenses:supplies $1
2678 assets:cash $-2
2679 2008/12/31 * pay off
2681 liabilities:debts $1
2682 assets:bank:checking $-1
2683 Normally, the journal entry's explicit or implicit amount style is pre‐
2685 served. For example, when an amount is omitted in the journal, it will
2686 not appear in the output. Similarly, when a transaction price is
2687 implied but not written, it will not appear in the output. You can use
2688 the -x/--explicit flag to make all amounts and transaction prices
2689 explicit, which can be useful for troubleshooting or for making your
2690 journal more readable and robust against data entry errors. -x is also
2691 implied by using any of -B,-V,-X,--value.
2692 Note, -x/--explicit will cause postings with a multi-commodity amount
2694 (these can arise when a multi-commodity transaction has an implicit
2695 amount) to be split into multiple single-commodity postings, keeping
2696 the output parseable.
2697 With -B/--cost, amounts with transaction prices are converted to cost
2699 using that price. This can be used for troubleshooting.
2700 With -m/--match and a STR argument, print will show at most one trans‐
2702 action: the one one whose description is most similar to STR, and is
2703 most recent. STR should contain at least two characters. If there is
2704 no similar-enough match, no transaction will be shown.
2705 With --new, for each FILE being read, hledger reads (and writes) a spe‐
2707 cial state file (.latest.FILE in the same directory), containing the
2708 latest transaction date(s) that were seen last time FILE was read.
2709 When this file is found, only transactions with newer dates (and new
2710 transactions on the latest date) are printed. This is useful for
2711 ignoring already-seen entries in import data, such as downloaded CSV
2712 files. Eg:
2713 $ hledger -f bank1.csv print --new
2715 (shows transactions added since last print --new on this file)
2716 This assumes that transactions added to FILE always have same or
2718 increasing dates, and that transactions on the same day do not get
2719 reordered. See also the import command.
2720 This command also supports the output destination and output format
2722 options The output formats supported are txt, csv, and (experimental)
2723 json.
2724 Here's an example of print's CSV output:
2726 $ hledger print -Ocsv
2728 "txnidx","date","date2","status","code","description","comment","account","amount","commodity","credit","debit","posting-status","posting-comment"
2729 "1","2008/01/01","","","","income","","assets:bank:checking","1","$","","1","",""
2730 "1","2008/01/01","","","","income","","income:salary","-1","$","1","","",""
2731 "2","2008/06/01","","","","gift","","assets:bank:checking","1","$","","1","",""
2732 "2","2008/06/01","","","","gift","","income:gifts","-1","$","1","","",""
2733 "3","2008/06/02","","","","save","","assets:bank:saving","1","$","","1","",""
2734 "3","2008/06/02","","","","save","","assets:bank:checking","-1","$","1","","",""
2735 "4","2008/06/03","","*","","eat & shop","","expenses:food","1","$","","1","",""
2736 "4","2008/06/03","","*","","eat & shop","","expenses:supplies","1","$","","1","",""
2737 "4","2008/06/03","","*","","eat & shop","","assets:cash","-2","$","2","","",""
2738 "5","2008/12/31","","*","","pay off","","liabilities:debts","1","$","","1","",""
2739 "5","2008/12/31","","*","","pay off","","assets:bank:checking","-1","$","1","","",""
2740 · There is one CSV record per posting, with the parent transaction's
2742 fields repeated.
2743 · The "txnidx" (transaction index) field shows which postings belong to
2745 the same transaction. (This number might change if transactions are
2746 reordered within the file, files are parsed/included in a different
2747 order, etc.)
2748 · The amount is separated into "commodity" (the symbol) and "amount"
2750 (numeric quantity) fields.
2751 · The numeric amount is repeated in either the "credit" or "debit" col‐
2753 umn, for convenience. (Those names are not accurate in the account‐
2754 ing sense; it just puts negative amounts under credit and zero or
2755 greater amounts under debit.)
2756 print-unique
2758 print-unique
2759 Print transactions which do not reuse an already-seen description.
2760 Example:
2762 $ cat unique.journal
2764 1/1 test
2765 (acct:one) 1
2766 2/2 test
2767 (acct:two) 2
2768 $ LEDGER_FILE=unique.journal hledger print-unique
2769 (-f option not supported)
2770 2015/01/01 test
2771 (acct:one) 1
2772 register
2774 register, reg, r
2775 Show postings and their running total.
2776 The register command displays postings in date order, one per line, and
2778 their running total. This is typically used with a query selecting a
2779 particular account, to see that account's activity:
2780 $ hledger register checking
2782 2008/01/01 income assets:bank:checking $1 $1
2783 2008/06/01 gift assets:bank:checking $1 $2
2784 2008/06/02 save assets:bank:checking $-1 $1
2785 2008/12/31 pay off assets:bank:checking $-1 0
2786 With --date2, it shows and sorts by secondary date instead.
2788 The --historical/-H flag adds the balance from any undisplayed prior
2790 postings to the running total. This is useful when you want to see
2791 only recent activity, with a historically accurate running balance:
2792 $ hledger register checking -b 2008/6 --historical
2794 2008/06/01 gift assets:bank:checking $1 $2
2795 2008/06/02 save assets:bank:checking $-1 $1
2796 2008/12/31 pay off assets:bank:checking $-1 0
2797 The --depth option limits the amount of sub-account detail displayed.
2799 The --average/-A flag shows the running average posting amount instead
2801 of the running total (so, the final number displayed is the average for
2802 the whole report period). This flag implies --empty (see below). It
2803 is affected by --historical. It works best when showing just one
2804 account and one commodity.
2805 The --related/-r flag shows the other postings in the transactions of
2807 the postings which would normally be shown.
2808 The --invert flag negates all amounts. For example, it can be used on
2810 an income account where amounts are normally displayed as negative num‐
2811 bers. It's also useful to show postings on the checking account
2812 together with the related account:
2813 $ hledger register --related --invert assets:checking
2815 With a reporting interval, register shows summary postings, one per
2817 interval, aggregating the postings to each account:
2818 $ hledger register --monthly income
2820 2008/01 income:salary $-1 $-1
2821 2008/06 income:gifts $-1 $-2
2822 Periods with no activity, and summary postings with a zero amount, are
2824 not shown by default; use the --empty/-E flag to see them:
2825 $ hledger register --monthly income -E
2827 2008/01 income:salary $-1 $-1
2828 2008/02 0 $-1
2829 2008/03 0 $-1
2830 2008/04 0 $-1
2831 2008/05 0 $-1
2832 2008/06 income:gifts $-1 $-2
2833 2008/07 0 $-2
2834 2008/08 0 $-2
2835 2008/09 0 $-2
2836 2008/10 0 $-2
2837 2008/11 0 $-2
2838 2008/12 0 $-2
2839 Often, you'll want to see just one line per interval. The --depth
2841 option helps with this, causing subaccounts to be aggregated:
2842 $ hledger register --monthly assets --depth 1h
2844 2008/01 assets $1 $1
2845 2008/06 assets $-1 0
2846 2008/12 assets $-1 $-1
2847 Note when using report intervals, if you specify start/end dates these
2849 will be adjusted outward if necessary to contain a whole number of
2850 intervals. This ensures that the first and last intervals are full
2851 length and comparable to the others in the report.
2852 Custom register output
2854 register uses the full terminal width by default, except on windows.
2855 You can override this by setting the COLUMNS environment variable (not
2856 a bash shell variable) or by using the --width/-w option.
2857 The description and account columns normally share the space equally
2859 (about half of (width - 40) each). You can adjust this by adding a
2860 description width as part of --width's argument, comma-separated:
2861 --width W,D . Here's a diagram (won't display correctly in --help):
2862 <--------------------------------- width (W) ---------------------------------->
2864 date (10) description (D) account (W-41-D) amount (12) balance (12)
2865 DDDDDDDDDD dddddddddddddddddddd aaaaaaaaaaaaaaaaaaa AAAAAAAAAAAA AAAAAAAAAAAA
2866 and some examples:
2868 $ hledger reg # use terminal width (or 80 on windows)
2870 $ hledger reg -w 100 # use width 100
2871 $ COLUMNS=100 hledger reg # set with one-time environment variable
2872 $ export COLUMNS=100; hledger reg # set till session end (or window resize)
2873 $ hledger reg -w 100,40 # set overall width 100, description width 40
2874 $ hledger reg -w $COLUMNS,40 # use terminal width, & description width 40
2875 This command also supports the output destination and output format
2877 options The output formats supported are txt, csv, and (experimental)
2878 json.
2879 register-match
2881 register-match
2882 Print the one posting whose transaction description is closest to DESC,
2883 in the style of the register command. If there are multiple equally
2884 good matches, it shows the most recent. Query options (options, not
2885 arguments) can be used to restrict the search space. Helps ledger-
2886 autosync detect already-seen transactions when importing.
2887 rewrite
2889 rewrite
2890 Print all transactions, rewriting the postings of matched transactions.
2891 For now the only rewrite available is adding new postings, like print
2892 --auto.
2893 This is a start at a generic rewriter of transaction entries. It reads
2895 the default journal and prints the transactions, like print, but adds
2896 one or more specified postings to any transactions matching QUERY. The
2897 posting amounts can be fixed, or a multiplier of the existing transac‐
2898 tion's first posting amount.
2899 Examples:
2901 $ hledger-rewrite.hs ^income --add-posting '(liabilities:tax) *.33 ; income tax' --add-posting '(reserve:gifts) $100'
2903 $ hledger-rewrite.hs expenses:gifts --add-posting '(reserve:gifts) *-1"'
2904 $ hledger-rewrite.hs -f rewrites.hledger
2905 rewrites.hledger may consist of entries like:
2907 = ^income amt:<0 date:2017
2909 (liabilities:tax) *0.33 ; tax on income
2910 (reserve:grocery) *0.25 ; reserve 25% for grocery
2911 (reserve:) *0.25 ; reserve 25% for grocery
2912 Note the single quotes to protect the dollar sign from bash, and the
2914 two spaces between account and amount.
2915 More:
2917 $ hledger rewrite -- [QUERY] --add-posting "ACCT AMTEXPR" ...
2919 $ hledger rewrite -- ^income --add-posting '(liabilities:tax) *.33'
2920 $ hledger rewrite -- expenses:gifts --add-posting '(budget:gifts) *-1"'
2921 $ hledger rewrite -- ^income --add-posting '(budget:foreign currency) *0.25 JPY; diversify'
2922 Argument for --add-posting option is a usual posting of transaction
2924 with an exception for amount specification. More precisely, you can
2925 use '*' (star symbol) before the amount to indicate that that this is a
2926 factor for an amount of original matched posting. If the amount
2927 includes a commodity name, the new posting amount will be in the new
2928 commodity; otherwise, it will be in the matched posting amount's com‐
2929 modity.
2930 Re-write rules in a file
2932 During the run this tool will execute so called "Automated Transac‐
2933 tions" found in any journal it process. I.e instead of specifying this
2934 operations in command line you can put them in a journal file.
2935 $ rewrite-rules.journal
2937 Make contents look like this:
2939 = ^income
2941 (liabilities:tax) *.33
2942 = expenses:gifts
2944 budget:gifts *-1
2945 assets:budget *1
2946 Note that '=' (equality symbol) that is used instead of date in trans‐
2948 actions you usually write. It indicates the query by which you want to
2949 match the posting to add new ones.
2950 $ hledger rewrite -- -f input.journal -f rewrite-rules.journal > rewritten-tidy-output.journal
2952 This is something similar to the commands pipeline:
2954 $ hledger rewrite -- -f input.journal '^income' --add-posting '(liabilities:tax) *.33' \
2956 | hledger rewrite -- -f - expenses:gifts --add-posting 'budget:gifts *-1' \
2957 --add-posting 'assets:budget *1' \
2958 > rewritten-tidy-output.journal
2959 It is important to understand that relative order of such entries in
2961 journal is important. You can re-use result of previously added post‐
2962 ings.
2963 Diff output format
2965 To use this tool for batch modification of your journal files you may
2966 find useful output in form of unified diff.
2967 $ hledger rewrite -- --diff -f examples/sample.journal '^income' --add-posting '(liabilities:tax) *.33'
2969 Output might look like:
2971 --- /tmp/examples/sample.journal
2973 +++ /tmp/examples/sample.journal
2974 @@ -18,3 +18,4 @@
2975 2008/01/01 income
2976 - assets:bank:checking $1
2977 + assets:bank:checking $1
2978 income:salary
2979 + (liabilities:tax) 0
2980 @@ -22,3 +23,4 @@
2981 2008/06/01 gift
2982 - assets:bank:checking $1
2983 + assets:bank:checking $1
2984 income:gifts
2985 + (liabilities:tax) 0
2986 If you'll pass this through patch tool you'll get transactions contain‐
2988 ing the posting that matches your query be updated. Note that multiple
2989 files might be update according to list of input files specified via
2990 --file options and include directives inside of these files.
2991 Be careful. Whole transaction being re-formatted in a style of output
2993 from hledger print.
2994 See also:
2996 https://github.com/simonmichael/hledger/issues/99
2998 rewrite vs. print --auto
3000 This command predates print --auto, and currently does much the same
3001 thing, but with these differences:
3002 · with multiple files, rewrite lets rules in any file affect all other
3004 files. print --auto uses standard directive scoping; rules affect
3005 only child files.
3006 · rewrite's query limits which transactions can be rewritten; all are
3008 printed. print --auto's query limits which transactions are printed.
3009 · rewrite applies rules specified on command line or in the journal.
3011 print --auto applies rules specified in the journal.
3012 roi
3014 roi
3015 Shows the time-weighted (TWR) and money-weighted (IRR) rate of return
3016 on your investments.
3017 This command assumes that you have account(s) that hold nothing but
3019 your investments and whenever you record current appraisal/valuation of
3020 these investments you offset unrealized profit and loss into account(s)
3021 that, again, hold nothing but unrealized profit and loss.
3022 Any transactions affecting balance of investment account(s) and not
3024 originating from unrealized profit and loss account(s) are assumed to
3025 be your investments or withdrawals.
3026 At a minimum, you need to supply a query (which could be just an
3028 account name) to select your investments with --inv, and another query
3029 to identify your profit and loss transactions with --pnl.
3030 It will compute and display the internalized rate of return (IRR) and
3032 time-weighted rate of return (TWR) for your investments for the time
3033 period requested. Both rates of return are annualized before display,
3034 regardless of the length of reporting interval.
3035 stats
3037 stats
3038 Show some journal statistics.
3039 The stats command displays summary information for the whole journal,
3041 or a matched part of it. With a reporting interval, it shows a report
3042 for each report period.
3043 Example:
3045 $ hledger stats
3047 Main journal file : /src/hledger/examples/sample.journal
3048 Included journal files :
3049 Transactions span : 2008-01-01 to 2009-01-01 (366 days)
3050 Last transaction : 2008-12-31 (2333 days ago)
3051 Transactions : 5 (0.0 per day)
3052 Transactions last 30 days: 0 (0.0 per day)
3053 Transactions last 7 days : 0 (0.0 per day)
3054 Payees/descriptions : 5
3055 Accounts : 8 (depth 3)
3056 Commodities : 1 ($)
3057 Market prices : 12 ($)
3058 This command also supports output destination and output format selec‐
3060 tion.
3061 tags
3063 tags
3064 List all the tag names used in the journal. With a TAGREGEX argument,
3065 only tag names matching the regular expression (case insensitive) are
3066 shown. With QUERY arguments, only transactions matching the query are
3067 considered. With --values flag, the tags' unique values are listed
3068 instead.
3069 test
3071 test
3072 Run built-in unit tests.
3073 This command runs the unit tests built in to hledger and hledger-lib,
3075 printing the results on stdout. If any test fails, the exit code will
3076 be non-zero.
3077 This is mainly used by hledger developers, but you can also use it to
3079 sanity-check the installed hledger executable on your platform. All
3080 tests are expected to pass - if you ever see a failure, please report
3081 as a bug!
3082 This command also accepts tasty test runner options, written after a --
3084 (double hyphen). Eg to run only the tests in Hledger.Data.Amount, with
3085 ANSI colour codes disabled:
3086 $ hledger test -- -pData.Amount --color=never
3088 For help on these, see https://github.com/feuerbach/tasty#options (--
3090 --help currently doesn't show them).
3091 Add-on commands
3093 hledger also searches for external add-on commands, and will include
3094 these in the commands list. These are programs or scripts in your PATH
3095 whose name starts with hledger- and ends with a recognised file exten‐
3096 sion (currently: no extension, bat,com,exe, hs,lhs,pl,py,rb,rkt,sh).
3097 Add-ons can be invoked like any hledger command, but there are a few
3099 things to be aware of. Eg if the hledger-web add-on is installed,
3100 · hledger -h web shows hledger's help, while hledger web -h shows
3102 hledger-web's help.
3103 · Flags specific to the add-on must have a preceding -- to hide them
3105 from hledger. So hledger web --serve --port 9000 will be rejected;
3106 you must use hledger web -- --serve --port 9000.
3107 · You can always run add-ons directly if preferred: hledger-web --serve
3109 --port 9000.
3110 Add-ons are a relatively easy way to add local features or experiment
3112 with new ideas. They can be written in any language, but haskell
3113 scripts have a big advantage: they can use the same hledger (and
3114 haskell) library functions that built-in commands do, for command-line
3115 options, journal parsing, reporting, etc.
3116 Two important add-ons are the hledger-ui and hledger-web user inter‐
3118 faces. These are maintained and released along with hledger:
3119 ui
3121 hledger-ui provides an efficient terminal interface.
3122 web
3124 hledger-web provides a simple web interface.
3125 Third party add-ons, maintained separately from hledger, include:
3127 iadd
3129 hledger-iadd is a more interactive, terminal UI replacement for the add
3130 command.
3131 interest
3133 hledger-interest generates interest transactions for an account accord‐
3134 ing to various schemes.
3135 A few more experimental or old add-ons can be found in hledger's bin/
3137 directory. These are typically prototypes and not guaranteed to work.
3138
3140 COLUMNS The screen width used by the register command. Default: the
3141 full terminal width.
3142 LEDGER_FILE The journal file path when not specified with -f. Default:
3144 ~/.hledger.journal (on windows, perhaps C:/Users/USER/.hledger.jour‐
3145 nal).
3146 A typical value is ~/DIR/YYYY.journal, where DIR is a version-con‐
3148 trolled finance directory and YYYY is the current year. Or ~/DIR/cur‐
3149 rent.journal, where current.journal is a symbolic link to YYYY.journal.
3150 On Mac computers, you can set this and other environment variables in a
3152 more thorough way that also affects applications started from the GUI
3153 (say, an Emacs dock icon). Eg on MacOS Catalina I have a
3154 ~/.MacOSX/environment.plist file containing
3155 {
3157 "LEDGER_FILE" : "~/finance/current.journal"
3158 }
3159 To see the effect you may need to killall Dock, or reboot.
3161
3163 Reads data from one or more files in hledger journal, timeclock, time‐
3164 dot, or CSV format specified with -f, or $LEDGER_FILE, or
3165 $HOME/.hledger.journal (on windows, perhaps
3166 C:/Users/USER/.hledger.journal).
3167
3169 The need to precede addon command options with -- when invoked from
3170 hledger is awkward.
3171 When input data contains non-ascii characters, a suitable system locale
3173 must be configured (or there will be an unhelpful error). Eg on POSIX,
3174 set LANG to something other than C.
3175 In a Microsoft Windows CMD window, non-ascii characters and colours are
3177 not supported.
3178 On Windows, non-ascii characters may not display correctly when running
3180 a hledger built in CMD in MSYS/CYGWIN, or vice-versa.
3181 In a Cygwin/MSYS/Mintty window, the tab key is not supported in hledger
3183 add.
3184 Not all of Ledger's journal file syntax is supported. See file format
3186 differences.
3187 On large data files, hledger is slower and uses more memory than
3189 Ledger.
3190
3192 Here are some issues you might encounter when you run hledger (and
3193 remember you can also seek help from the IRC channel, mail list or bug
3194 tracker):
3195 Successfully installed, but "No command 'hledger' found"
3197 stack and cabal install binaries into a special directory, which should
3198 be added to your PATH environment variable. Eg on unix-like systems,
3199 that is ~/.local/bin and ~/.cabal/bin respectively.
3200 I set a custom LEDGER_FILE, but hledger is still using the default file
3202 LEDGER_FILE should be a real environment variable, not just a shell
3203 variable. The command env | grep LEDGER_FILE should show it. You may
3204 need to use export. Here's an explanation.
3205 Getting errors like "Illegal byte sequence" or "Invalid or incomplete
3207 multibyte or wide character" or "commitAndReleaseBuffer: invalid argu‐
3208 ment (invalid character)"
3209 Programs compiled with GHC (hledger, haskell build tools, etc.) need to
3210 have a UTF-8-aware locale configured in the environment, otherwise they
3211 will fail with these kinds of errors when they encounter non-ascii
3212 characters.
3213 To fix it, set the LANG environment variable to some locale which sup‐
3215 ports UTF-8. The locale you choose must be installed on your system.
3216 Here's an example of setting LANG temporarily, on Ubuntu GNU/Linux:
3218 $ file my.journal
3220 my.journal: UTF-8 Unicode text # the file is UTF8-encoded
3221 $ echo $LANG
3222 C # LANG is set to the default locale, which does not support UTF8
3223 $ locale -a # which locales are installed ?
3224 C
3225 en_US.utf8 # here's a UTF8-aware one we can use
3226 POSIX
3227 $ LANG=en_US.utf8 hledger -f my.journal print # ensure it is used for this command
3228 If available, C.UTF-8 will also work. If your preferred locale isn't
3230 listed by locale -a, you might need to install it. Eg on
3231 Ubuntu/Debian:
3232 $ apt-get install language-pack-fr
3234 $ locale -a
3235 C
3236 en_US.utf8
3237 fr_BE.utf8
3238 fr_CA.utf8
3239 fr_CH.utf8
3240 fr_FR.utf8
3241 fr_LU.utf8
3242 POSIX
3243 $ LANG=fr_FR.utf8 hledger -f my.journal print
3244 Here's how you could set it permanently, if you use a bash shell:
3246 $ echo "export LANG=en_US.utf8" >>~/.bash_profile
3248 $ bash --login
3249 Exact spelling and capitalisation may be important. Note the differ‐
3251 ence on MacOS (UTF-8, not utf8). Some platforms (eg ubuntu) allow
3252 variant spellings, but others (eg macos) require it to be exact:
3253 $ locale -a | grep -iE en_us.*utf
3255 en_US.UTF-8
3256 $ LANG=en_US.UTF-8 hledger -f my.journal print
3257
3261 Report bugs at http://bugs.hledger.org (or on the #hledger IRC channel
3262 or hledger mail list)
3263
3266 Simon Michael <simon@joyful.com> and contributors
3267
3270 Copyright (C) 2007-2019 Simon Michael.
3271 Released under GNU GPL v3 or later.
3272
3275 hledger(1), hledger-ui(1), hledger-web(1), hledger-api(1),
3276 hledger_csv(5), hledger_journal(5), hledger_timeclock(5), hledger_time‐
3277 dot(5), ledger(1)
3278 http://hledger.org
3280hledger 1.18.1 June 2020 hledger(1)