/
hledger.txt
9093 lines (6827 loc) · 395 KB
/
hledger.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
HLEDGER(1) hledger User Manuals HLEDGER(1)
NAME
hledger - robust, friendly plain text accounting (CLI version)
SYNOPSIS
hledger
hledger COMMAND [OPTS] [ARGS]
hledger ADDONCMD -- [OPTS] [ARGS]
DESCRIPTION
hledger is a robust, user-friendly, cross-platform set of programs for
tracking money, time, or any other commodity, using double-entry ac-
counting and a simple, editable file format. hledger is inspired by
and largely compatible with ledger(1), and largely interconvertible
with beancount(1).
This manual is for hledger's command line interface, version 1.32.99.
It also describes the common options, file formats and concepts used by
all hledger programs. It might accidentally teach you some bookkeep-
ing/accounting as well! You don't need to know everything in here to
use hledger productively, but when you have a question about function-
ality, this doc should answer it. It is detailed, so do skip ahead or
skim when needed. You can read it on hledger.org, or as an info manual
or man page on your system. You can also get it from hledger itself
with
hledger --man, hledger --info or hledger help [TOPIC].
The main function of the hledger CLI is to read plain text files de-
scribing financial transactions, crunch the numbers, and print a useful
report on the terminal (or save it as HTML, CSV, JSON or SQL). Many
reports are available, as subcommands. hledger will also detect other
hledger-* executables as extra subcommands.
hledger usually reads from (and appends to) a journal file specified by
the LEDGER_FILE environment variable (defaulting to
$HOME/.hledger.journal); or you can specify files with -f options. It
can also read timeclock files, timedot files, or any CSV/SSV/TSV file
with a date field.
Here is a small journal file describing one transaction:
2015-10-16 bought food
expenses:food $10
assets:cash
Transactions are dated movements of money (etc.) between two or more
accounts: bank accounts, your wallet, revenue/expense categories, peo-
ple, etc. You can choose any account names you wish, using : to indi-
cate subaccounts. There must be at least two spaces between account
name and amount. Positive amounts are inflow to that account (debit),
negatives are outflow from it (credit). (Some reports show revenue,
liability and equity account balances as negative numbers as a result;
this is normal.)
hledger's add command can help you add transactions, or you can install
other data entry UIs like hledger-web or hledger-iadd. For more exten-
sive/efficient changes, use a text editor: Emacs + ledger-mode, VIM +
vim-ledger, or VS Code + hledger-vscode are some good choices (see
https://hledger.org/editors.html).
To get started, run hledger add and follow the prompts, or save some
entries like the above in $HOME/.hledger.journal, then try commands
like:
$ hledger print -x
$ hledger aregister assets
$ hledger balance
$ hledger balancesheet
$ hledger incomestatement
Run hledger to list the commands. See also the "Starting a journal
file" and "Setting opening balances" sections in PART 5: COMMON TASKS.
PART 1: USER INTERFACE
Input
hledger reads one or more data files, each time you run it. You can
specify a file with -f, like so
$ hledger -f FILE print
Files are most often in hledger's journal format, with the .journal
file extension (.hledger or .j also work); these files describe trans-
actions, like an accounting general journal.
When no file is specified, hledger looks for .hledger.journal in your
home directory.
But most people prefer to keep financial files in a dedicated folder,
perhaps with version control. Also, starting a new journal file each
year is common (it's not required, but helps keep things fast and or-
ganised). So we usually configure a different journal file, by setting
the LEDGER_FILE environment variable, to something like ~/fi-
nance/2023.journal. For more about how to do that on your system, see
Common tasks > Setting LEDGER_FILE.
Text encoding
Data files containing non-ascii characters must use UTF-8 encoding.
Also, your system should be configured with a locale that can decode
UTF-8 text. On some unix systems, you may need set the LANG environ-
ment variable, eg. You can read more about this in Unicode characters,
below.
On unix systems you can check a file's encoding with the file command.
If you need to import from a UTF-16-encoded CSV file, say, you can con-
vert it to UTF-8 with the iconv command.
Data formats
Usually the data file is in hledger's journal format, but it can be in
any of the supported file formats, which currently are:
Reader: Reads: Automatically used for
files with extensions:
-----------------------------------------------------------------------------
journal hledger journal files and some .journal .j .hledger
Ledger journals, for transactions .ledger
timeclock timeclock files, for precise time .timeclock
logging
timedot timedot files, for approximate .timedot
time logging
csv Comma or other character sepa- .csv
rated values, for data import
ssv Semicolon separated values .ssv
tsv Tab separated values .tsv
rules CSV/SSV/TSV/other separated val- .rules
ues, alternate way
These formats are described in more detail below.
hledger detects the format automatically based on the file extensions
shown above. If it can't recognise the file extension, it assumes
journal format. So for non-journal files, it's important to use a
recognised file extension, so as to either read successfully or to show
relevant error messages.
You can also force a specific reader/format by prefixing the file path
with the format and a colon. Eg, to read a .dat file containing tab
separated values:
$ hledger -f tsv:/some/file.dat stats
Standard input
The file name - means standard input:
$ cat FILE | hledger -f- print
If reading non-journal data in this way, you'll need to add a file for-
mat prefix, like:
$ echo 'i 2009/13/1 08:00:00' | hledger print -f timeclock:-
Multiple files
You can specify multiple -f options, to read multiple files as one big
journal. When doing this, note that certain features (described below)
will be affected:
o Balance assertions will not see the effect of transactions in previ-
ous files. (Usually this doesn't matter as each file will set the
corresponding opening balances.)
o Some directives will not affect previous or subsequent files.
If needed, you can work around these by using a single parent file
which includes the others, or concatenating the files into one, eg: cat
a.journal b.journal | hledger -f- CMD.
Strict mode
hledger checks input files for valid data. By default, the most impor-
tant errors are detected, while still accepting easy journal files
without a lot of declarations:
o Are the input files parseable, with valid syntax ?
o Are all transactions balanced ?
o Do all balance assertions pass ?
With the -s/--strict flag, additional checks are performed:
o Are all accounts posted to, declared with an account directive ?
(Account error checking)
o Are all commodities declared with a commodity directive ? (Commodity
error checking)
o Are all commodity conversions declared explicitly ?
You can use the check command to run individual checks -- the ones
listed above and some more.
Commands
hledger provides various subcommands for getting things done. Most of
these commands do not change the journal file; they just read it and
output a report. A few commands assist with adding data and file man-
agement.
To show the commands list, run hledger with no arguments. The commands
are described in detail in PART 4: COMMANDS, below.
To use a particular command, run hledger CMD [CMDOPTS] [CMDARGS],
o CMD is the full command name, or its standard abbreviation shown in
the commands list, or any unambiguous prefix of the name.
o CMDOPTS are command-specific options, if any. Command-specific op-
tions must be written after the command name. Eg: hledger print -x.
o CMDARGS are additional arguments to the command, if any. Most
hledger commands accept arguments representing a query, to limit the
data in some way. Eg: hledger reg assets:checking.
To list a command's options, arguments, and documentation in the termi-
nal, run hledger CMD -h. Eg: hledger bal -h.
Add-on commands
In addition to the built-in commands, you can install add-on commands:
programs or scripts named "hledger-SOMETHING", which will also appear
in hledger's commands list. If you used the hledger-install script,
you will have several add-ons installed already. Some more can be
found in hledger's bin/ directory, documented at
https://hledger.org/scripts.html.
More precisely, add-on commands are programs or scripts in your shell's
PATH, whose name starts with "hledger-" and ends with no extension or a
recognised extension (".bat", ".com", ".exe", ".hs", ".js", ".lhs",
".lua", ".php", ".pl", ".py", ".rb", ".rkt", or ".sh"), and (on unix
and mac) which has executable permission for the current user.
You can run add-on commands using hledger, much like built-in commands:
hledger ADDONCMD [-- ADDONCMDOPTS] [ADDONCMDARGS]. But note the double
hyphen argument, required before add-on-specific options. Eg: hledger
ui -- --watch or hledger web -- --serve. If this causes difficulty,
you can always run the add-on directly, without using hledger:
hledger-ui --watch or hledger-web --serve.
Options
Run hledger -h to see general command line help, and general options
which are common to most hledger commands. These options can be writ-
ten anywhere on the command line. They can be grouped into help, in-
put, and reporting options:
General help options
-h --help
show general or COMMAND help
--man show general or COMMAND user manual with man
--info show general or COMMAND user manual with info
--version
show general or ADDONCMD version
--debug[=N]
show debug output (levels 1-9, default: 1)
General input options
-f FILE --file=FILE
use a different input file. For stdin, use - (default:
$LEDGER_FILE or $HOME/.hledger.journal)
--rules-file=RULESFILE
Conversion rules file to use when reading CSV (default:
FILE.rules)
--separator=CHAR
Field separator to expect when reading CSV (default: ',')
--alias=OLD=NEW
rename accounts named OLD to NEW
--pivot FIELDNAME
use some other field or tag for the account name
-I --ignore-assertions
disable balance assertion checks (note: does not disable balance
assignments)
-s --strict
do extra error checking (check that all posted accounts are de-
clared)
General reporting options
-b --begin=DATE
include postings/txns on or after this date (will be adjusted to
preceding subperiod start when using a report interval)
-e --end=DATE
include postings/txns before this date (will be adjusted to fol-
lowing subperiod end when using a report interval)
-D --daily
multiperiod/multicolumn report by day
-W --weekly
multiperiod/multicolumn report by week
-M --monthly
multiperiod/multicolumn report by month
-Q --quarterly
multiperiod/multicolumn report by quarter
-Y --yearly
multiperiod/multicolumn report by year
-p --period=PERIODEXP
set start date, end date, and/or reporting interval all at once
using period expressions syntax
--date2
match the secondary date instead (see command help for other ef-
fects)
--today=DATE
override today's date (affects relative smart dates, for
tests/examples)
-U --unmarked
include only unmarked postings/txns (can combine with -P or -C)
-P --pending
include only pending postings/txns
-C --cleared
include only cleared postings/txns
-R --real
include only non-virtual postings
-NUM --depth=NUM
hide/aggregate accounts or postings more than NUM levels deep
-E --empty
show items with zero amount, normally hidden (and vice-versa in
hledger-ui/hledger-web)
-B --cost
convert amounts to their cost/selling amount at transaction time
-V --market
convert amounts to their market value in default valuation com-
modities
-X --exchange=COMM
convert amounts to their market value in commodity COMM
--value
convert amounts to cost or market value, more flexibly than
-B/-V/-X
--infer-equity
infer conversion equity postings from costs
--infer-costs
infer costs from conversion equity postings
--infer-market-prices
use costs as additional market prices, as if they were P direc-
tives
--forecast
generate transactions from periodic rules, between the latest
recorded txn and 6 months from today, or during the specified
PERIOD (= is required). Auto posting rules will be applied to
these transactions as well. Also, in hledger-ui make fu-
ture-dated transactions visible.
--auto generate extra postings by applying auto posting rules to all
txns (not just forecast txns)
--verbose-tags
add visible tags indicating transactions or postings which have
been generated/modified
--commodity-style
Override the commodity style in the output for the specified
commodity. For example 'EUR1.000,00'.
--color=WHEN (or --colour=WHEN)
Should color-supporting commands use ANSI color codes in text
output. 'auto' (default): whenever stdout seems to be a
color-supporting terminal. 'always' or 'yes': always, useful eg
when piping output into 'less -R'. 'never' or 'no': never. A
NO_COLOR environment variable overrides this.
--pretty[=WHEN]
Show prettier output, e.g. using unicode box-drawing charac-
ters. Accepts 'yes' (the default) or 'no' ('y', 'n', 'always',
'never' also work). If you provide an argument you must use
'=', e.g. '--pretty=yes'.
When a reporting option appears more than once in the command line, the
last one takes precedence.
Some reporting options can also be written as query arguments.
Command line tips
Here are some details useful to know about for hledger command lines
(and elsewhere). Feel free to skip this section until you need it.
Option repetition
If options are repeated in a command line, hledger will generally use
the last (right-most) occurence.
Special characters
Single escaping (shell metacharacters)
In shell command lines, characters significant to your shell - such as
spaces, <, >, (, ), |, $ and \ - should be "shell-escaped" if you want
hledger to see them. This is done by enclosing them in single or dou-
ble quotes, or by writing a backslash before them. Eg to match an ac-
count name containing a space:
$ hledger register 'credit card'
or:
$ hledger register credit\ card
Windows users should keep in mind that cmd treats single quote as a
regular character, so you should be using double quotes exclusively.
PowerShell treats both single and double quotes as quotes.
Double escaping (regular expression metacharacters)
Characters significant in regular expressions (described below) - such
as ., ^, $, [, ], (, ), |, and \ - may need to be "regex-escaped" if
you don't want them to be interpreted by hledger's regular expression
engine. This is done by writing backslashes before them, but since
backslash is typically also a shell metacharacter, both shell-escaping
and regex-escaping will be needed. Eg to match a literal $ sign while
using the bash shell:
$ hledger balance cur:'\$'
or:
$ hledger balance cur:\\$
Triple escaping (for add-on commands)
When you use hledger to run an external add-on command (described be-
low), one level of shell-escaping is lost from any options or arguments
intended for by the add-on command, so those need an extra level of
shell-escaping. Eg to match a literal $ sign while using the bash
shell and running an add-on command (ui):
$ hledger ui cur:'\\$'
or:
$ hledger ui cur:\\\\$
If you wondered why four backslashes, perhaps this helps:
unescaped: $
escaped: \$
double-escaped: \\$
triple-escaped: \\\\$
Or, you can avoid the extra escaping by running the add-on executable
directly:
$ hledger-ui cur:\\$
Less escaping
Options and arguments are sometimes used in places other than the shell
command line, where shell-escaping is not needed, so there you should
use one less level of escaping. Those places include:
o an @argumentfile
o hledger-ui's filter field
o hledger-web's search form
o GHCI's prompt (used by developers).
Unicode characters
hledger is expected to handle non-ascii characters correctly:
o they should be parsed correctly in input files and on the command
line, by all hledger tools (add, iadd, hledger-web's search/add/edit
forms, etc.)
o they should be displayed correctly by all hledger tools, and
on-screen alignment should be preserved.
This requires a well-configured environment. Here are some tips:
o A system locale must be configured, and it must be one that can de-
code the characters being used. In bash, you can set a locale like
this: export LANG=en_US.UTF-8. There are some more details in Trou-
bleshooting. This step is essential - without it, hledger will quit
on encountering a non-ascii character (as with all GHC-compiled pro-
grams).
o your terminal software (eg Terminal.app, iTerm, CMD.exe, xterm..)
must support unicode
o the terminal must be using a font which includes the required unicode
glyphs
o the terminal should be configured to display wide characters as dou-
ble width (for report alignment)
o on Windows, for best results you should run hledger in the same kind
of environment in which it was built. Eg hledger built in the stan-
dard CMD.EXE environment (like the binaries on our download page)
might show display problems when run in a cygwin or msys terminal,
and vice versa. (See eg #961).
Regular expressions
A regular expression (regexp) is a small piece of text where certain
characters (like ., ^, $, +, *, (), |, [], \) have special meanings,
forming a tiny language for matching text precisely - very useful in
hledger and elsewhere. To learn all about them, visit regular-expres-
sions.info.
hledger supports regexps whenever you are entering a pattern to match
something, eg in query arguments, account aliases, CSV if rules,
hledger-web's search form, hledger-ui's / search, etc. You may need to
wrap them in quotes, especially at the command line (see Special char-
acters above). Here are some examples:
Account name queries (quoted for command line use):
Regular expression: Matches:
------------------- ------------------------------------------------------------
bank assets:bank, assets:bank:savings, expenses:art:banksy, ...
:bank assets:bank:savings, expenses:art:banksy
:bank: assets:bank:savings
'^bank' none of those ( ^ matches beginning of text )
'bank$' assets:bank ( $ matches end of text )
'big \$ bank' big $ bank ( \ disables following character's special meaning )
'\bbank\b' assets:bank, assets:bank:savings ( \b matches word boundaries )
'(sav|check)ing' saving or checking ( (|) matches either alternative )
'saving|checking' saving or checking ( outer parentheses are not needed )
'savings?' saving or savings ( ? matches 0 or 1 of the preceding thing )
'my +bank' my bank, my bank, ... ( + matches 1 or more of the preceding thing )
'my *bank' mybank, my bank, my bank, ... ( * matches 0 or more of the preceding thing )
'b.nk' bank, bonk, b nk, ... ( . matches any character )
Some other queries:
desc:'amazon|amzn|audible' Amazon transactions
cur:EUR amounts with commodity symbol containing EUR
cur:'\$' amounts with commodity symbol containing $
cur:'^\$$' only $ amounts, not eg AU$ or CA$
cur:....? amounts with 4-or-more-character symbols
tag:.=202[1-3] things with any tag whose value contains 2021, 2022 or 2023
Account name aliases: accept . instead of : as account separator:
alias /\./=: replaces all periods in account names with colons
Show multiple top-level accounts combined as one:
--alias='/^[^:]+/=combined' ( [^:] matches any character other than : )
Show accounts with the second-level part removed:
--alias '/^([^:]+):[^:]+/ = \1'
match a top-level account and a second-level account
and replace those with just the top-level account
( \1 in the replacement text means "whatever was matched
by the first parenthesised part of the regexp"
CSV rules: match CSV records containing dining-related MCC codes:
if \?MCC581[124]
Match CSV records with a specific amount around the end/start of month:
if %amount \b3\.99
& %date (29|30|31|01|02|03)$
hledger's regular expressions
hledger's regular expressions come from the regex-tdfa library. If
they're not doing what you expect, it's important to know exactly what
they support:
1. they are case insensitive
2. they are infix matching (they do not need to match the entire thing
being matched)
3. they are POSIX ERE (extended regular expressions)
4. they also support GNU word boundaries (\b, \B, \<, \>)
5. backreferences are supported when doing text replacement in account
aliases or CSV rules, where backreferences can be used in the re-
placement string to reference capturing groups in the search regexp.
Otherwise, if you write \1, it will match the digit 1.
6. they do not support mode modifiers ((?s)), character classes (\w,
\d), or anything else not mentioned above.
Some things to note:
o In the alias directive and --alias option, regular expressions must
be enclosed in forward slashes (/REGEX/). Elsewhere in hledger,
these are not required.
o In queries, to match a regular expression metacharacter like $ as a
literal character, prepend a backslash. Eg to search for amounts
with the dollar sign in hledger-web, write cur:\$.
o On the command line, some metacharacters like $ have a special mean-
ing to the shell and so must be escaped at least once more. See Spe-
cial characters.
Argument files
You can save a set of command line options and arguments in a file, and
then reuse them by writing @FILENAME as a command line argument. Eg:
hledger bal @foo.args.
Inside the argument file, each line should contain just one option or
argument. Don't use spaces except inside quotes (or you'll see a con-
fusing error); write = (or nothing) between a flag and its argument.
For the special characters mentioned above, use one less level of quot-
ing than you would at the command prompt.
Output
Output destination
hledger commands send their output to the terminal by default. You can
of course redirect this, eg into a file, using standard shell syntax:
$ hledger print > foo.txt
Some commands (print, register, stats, the balance commands) also pro-
vide the -o/--output-file option, which does the same thing without
needing the shell. Eg:
$ hledger print -o foo.txt
$ hledger print -o - # write to stdout (the default)
Output format
Some commands offer other kinds of output, not just text on the termi-
nal. Here are those commands and the formats currently supported:
- txt csv/tsv html json sql
--------------------------------------------------------------------------------------
aregister Y Y Y Y
balance Y 1 Y 1 Y 1,2 Y
balancesheet Y 1 Y 1 Y 1 Y
balancesheete- Y 1 Y 1 Y 1 Y
quity
cashflow Y 1 Y 1 Y 1 Y
incomestatement Y 1 Y 1 Y 1 Y
print Y Y Y Y
register Y Y Y
o 1 Also affected by the balance commands' --layout option.
o 2 balance does not support html output without a report interval or
with --budget.
The output format is selected by the -O/--output-format=FMT option:
$ hledger print -O csv # print CSV on stdout
or by the filename extension of an output file specified with the
-o/--output-file=FILE.FMT option:
$ hledger balancesheet -o foo.csv # write CSV to foo.csv
The -O option can be combined with -o to override the file extension,
if needed:
$ hledger balancesheet -o foo.txt -O csv # write CSV to foo.txt
Some notes about the various output formats:
CSV output
o In CSV output, digit group marks (such as thousands separators) are
disabled automatically.
HTML output
o HTML output can be styled by an optional hledger.css file in the same
directory.
JSON output
o This is not yet much used; real-world feedback is welcome.
o Our JSON is rather large and verbose, since it is a faithful repre-
sentation of hledger's internal data types. To understand the JSON,
read the Haskell type definitions, which are mostly in
https://github.com/simonmichael/hledger/blob/mas-
ter/hledger-lib/Hledger/Data/Types.hs.
o hledger represents quantities as Decimal values storing up to 255
significant digits, eg for repeating decimals. Such numbers can
arise in practice (from automatically-calculated transaction prices),
and would break most JSON consumers. So in JSON, we show quantities
as simple Numbers with at most 10 decimal places. We don't limit the
number of integer digits, but that part is under your control. We
hope this approach will not cause problems in practice; if you find
otherwise, please let us know. (Cf #1195)
SQL output
o This is not yet much used; real-world feedback is welcome.
o SQL output is expected to work at least with SQLite, MySQL and Post-
gres.
o For SQLite, it will be more useful if you modify the generated id
field to be a PRIMARY KEY. Eg:
$ hledger print -O sql | sed 's/id serial/id INTEGER PRIMARY KEY AUTOINCREMENT NOT NULL/g' | ...
o SQL output is structured with the expectations that statements will
be executed in the empty database. If you already have tables cre-
ated via SQL output of hledger, you would probably want to either
clear tables of existing data (via delete or truncate SQL statements)
or drop tables completely as otherwise your postings will be duped.
Commodity styles
When displaying amounts, hledger infers a standard display style for
each commodity/currency, as described below in Commodity display style.
If needed, this can be overridden by a -c/--commodity-style option (ex-
cept for cost amounts and amounts displayed by the print command, which
are always displayed with all decimal digits). For example, the fol-
lowing will force dollar amounts to be displayed as shown:
$ hledger print -c '$1.000,0'
This option can repeated to set the display style for multiple commodi-
ties/currencies. Its argument is as described in the commodity direc-
tive.
In some cases hledger will adjust number formatting to improve their
parseability (such as adding trailing decimal marks when needed).
Colour
In terminal output, some commands can produce colour when the terminal
supports it:
o if the --color/--colour option is given a value of yes or always (or
no or never), colour will (or will not) be used;
o otherwise, if the NO_COLOR environment variable is set, colour will
not be used;
o otherwise, colour will be used if the output (terminal or file) sup-
ports it.
Box-drawing
In terminal output, you can enable unicode box-drawing characters to
render prettier tables:
o if the --pretty option is given a value of yes or always (or no or
never), unicode characters will (or will not) be used;
o otherwise, unicode characters will not be used.
Paging
When showing long output in the terminal, hledger will try to use the
pager specified by the PAGER environment variable, or less, or more.
(A pager is a helper program that shows one page at a time rather than
scrolling everything off screen). Currently it does this only for help
output, not for reports; specifically,
o when listing commands, with hledger
o when showing help with hledger [CMD] --help,
o when viewing manuals with hledger help or hledger --man.
Note the pager is expected to handle ANSI codes, which hledger uses eg
for bold emphasis. For the common pager less (and its more compatibil-
ity mode), we add R to the LESS and MORE environment variables to make
this work. If you use a different pager, you might need to configure
it similarly, to avoid seeing junk on screen (let us know). Otherwise,
you can set the NO_COLOR environment variable to 1 to disable all ANSI
output (see Colour).
Debug output
We intend hledger to be relatively easy to troubleshoot, introspect and
develop. You can add --debug[=N] to any hledger command line to see
additional debug output. N ranges from 1 (least output, the default)
to 9 (maximum output). Typically you would start with 1 and increase
until you are seeing enough. Debug output goes to stderr, and is not
affected by -o/--output-file (unless you redirect stderr to stdout, eg:
2>&1). It will be interleaved with normal output, which can help re-
veal when parts of the code are evaluated. To capture debug output in
a log file instead, you can usually redirect stderr, eg:
hledger bal --debug=3 2>hledger.log
Environment
These environment variables affect hledger:
COLUMNS This is normally set by your terminal; some hledger commands
(register) will format their output to this width. If not set, they
will try to use the available terminal width.
LEDGER_FILE The main journal file to use when not specified with
-f/--file. Default: $HOME/.hledger.journal.
NO_COLOR If this environment variable is set (with any value), hledger
will not use ANSI color codes in terminal output, unless overridden by
an explicit --color/--colour option.
PART 2: DATA FORMATS
Journal
hledger's usual data source is a plain text file containing journal en-
tries in hledger journal format. If you're looking for a quick refer-
ence, jump ahead to the journal cheatsheet (or use the table of con-
tents at https://hledger.org/hledger.html).
This file represents an accounting General Journal. The .journal file
extension is most often used, though not strictly required. The jour-
nal file contains a number of transaction entries, each describing a
transfer of money (or any commodity) between two or more named ac-
counts, in a simple format readable by both hledger and humans.
hledger's journal format is compatible with most of Ledger's journal
format, but not all of it. The differences and interoperation tips are
described at hledger and Ledger. With some care, and by avoiding in-
compatible features, you can keep your hledger journal readable by
Ledger and vice versa. This can useful eg for comparing the behaviour
of one app against the other.
You can use hledger without learning any more about this file; just use
the add or web or import commands to create and update it.
Many users, though, edit the journal file with a text editor, and track
changes with a version control system such as git. Editor addons such
as ledger-mode or hledger-mode for Emacs, vim-ledger for Vim, and
hledger-vscode for Visual Studio Code, make this easier, adding colour,
formatting, tab completion, and useful commands. See Editor configura-
tion at hledger.org for the full list.
A hledger journal file can contain three kinds of thing: comment lines,
transactions, and/or directives (including periodic transaction rules
and auto posting rules). Understanding the journal file format will
also give you a good understanding of hledger's data model. Here's a
quick cheatsheet/overview, followed by detailed descriptions of each
part.
Journal cheatsheet
# Here is the main syntax of hledger's journal format
# (omitting extra Ledger compatibility syntax).
###############################################################################
# 1. These are comment lines, for notes or temporarily disabling things.
; They begin with # or ;
comment
Or, lines can be enclosed within "comment" / "end comment".
This is a block of
commented lines.
end comment
# Some journal entries can have semicolon comments at end of line ; like this
# Some of them require 2 or more spaces before the semicolon.
###############################################################################
# 2. Directives customise processing or output in some way.
# You don't need any directives to get started.
# But they can add more error checking, or change how things are displayed.
# They begin with a word, letter, or symbol.
# They are most often placed at the top, before transactions.
account assets ; Declare valid account names and display order.
account assets:savings ; A subaccount. This one represents a bank account.
account assets:checking ; Another. Note, 2+ spaces after the account name.
account assets:receivable ; Accounting type is inferred from english names,
account passifs ; or declared with a "type" tag, type:L
account expenses ; type:X
; A follow-on comment line, indented.
account expenses:rent ; Expense and revenue categories are also accounts.
; Subaccounts inherit their parent's type.
commodity $0.00 ; Declare valid commodities and their display styles.
commodity 1.000,00 EUR
decimal-mark . ; The decimal mark used in this file (if ambiguous).
payee Whole Foods ; Declare a valid payee name.
tag trip ; Declare a valid tag name.
P 2024-03-01 AAPL $179 ; Declare a market price for AAPL in $ on this date.
include other.journal ; Include another journal file here.
# Declare a recurring "periodic transaction", for budget/forecast reports
~ monthly set budget goals ; <- Note, 2+ spaces before the description.
(expenses:rent) $1000
(expenses:food) $500
# Declare an auto posting rule, to modify existing transactions in reports
= revenues:consulting
liabilities:tax:2024:us *0.25 ; Add a tax liability & expense
expenses:tax:2024:us *-0.25 ; for 25% of the revenue.
###############################################################################
# 3. Transactions are what it's all about.
# They are dated events, usually movements of money between 2 or more accounts.
# They begin with a numeric date.
# Here is their basic shape:
#
# DATE DESCRIPTION ; The transaction's date and optional description.
# ACCOUNT1 AMOUNT ; A posting of an amount to/from this account, indented.
# ACCOUNT2 AMOUNT ; A second posting, balancing the first.
# ... ; More if needed. Amounts must sum to zero.
# ; Note, 2+ spaces between account names and amounts.
2024-01-01 opening balances ; At the start, declare pre-existing balances this way.
assets:savings $10000 ; Account names can be anything. lower case is easy to type.
assets:checking $1000 ; assets, liabilities, equity, revenues, expenses are common.
liabilities:credit card $-500 ; liabilities, equity, revenues balances are usually negative.
equity:start ; One amount can be left blank. $-10500 is inferred here.
; Some of these accounts we didn't declare above,
; so -s/--strict would complain.
2024-01-03 ! (12345) pay rent
; Additional transaction comment lines, indented.
; There can be a ! or * after the date meaning "pending" or "cleared".
; There can be a parenthesised (code) after the date/status.
; Amounts' sign shows direction of flow.
assets:checking $-500 ; Minus means removed from this account (credit).
expenses:rent $500 ; Plus means added to this account (debit).
; Keeping transactions in date order is optional (but helps error checking).
2024-01-02 Gringott's Bank | withdrawal ; Description can be PAYEE | NOTE
assets:bank:gold -10 gold
assets:pouch 10 gold
2024-01-02 shopping
expenses:clothing 1 gold
expenses:wands 5 gold
assets:pouch -6 gold
2024-01-02 receive gift
revenues:gifts -3 "Chocolate Frogs" ; Complex commodity symbols
assets:pouch 3 "Chocolate Frogs" ; must be in double quotes.
2024-01-15 buy some shares, in two lots ; Cost can be noted.
assets:investments:2024-01-15 2.0 AAAA @ $1.50 ; @ means per-unit cost
assets:investments:2024-01-15-02 3.0 AAAA @@ $4 ; @@ means total cost
; ^ Per-lot subaccounts are sometimes useful.
assets:checking $-7
2024-01-15 assert some account balances on this date
; Balances can be asserted in any transaction, with =, for extra error checking.
; Assertion txns like this one can be made with hledger close --assert --show-costs
;
assets:savings $0 = $10000
assets:checking $0 = $493
assets:bank:gold 0 gold = -10 gold
assets:pouch 0 gold = 4 gold
assets:pouch 0 "Chocolate Frogs" = 3 "Chocolate Frogs"
assets:investments:2024-01-15 0.0 AAAA = 2.0 AAAA @ $1.50
assets:investments:2024-01-15-02 0.0 AAAA = 3.0 AAAA @@ $4
liabilities:credit card $0 = $-500
2024-02-01 note some event, or a transaction not yet fully entered, on this date
; Postings are not required.
; Some other date formats are allowed (but, consistent YYYY-MM-DD is useful).
2024.01.01
2024/1/1
Comments
Lines in the journal will be ignored if they begin with a hash (#) or a
semicolon (;). (See also Other syntax.) hledger will also ignore re-
gions beginning with a comment line and ending with an end comment line
(or file end). Here's a suggestion for choosing between them:
o # for top-level notes
o ; for commenting out things temporarily
o comment for quickly commenting large regions (remember it's there, or
you might get confused)
Eg:
# a comment line
; another commentline
comment
A multi-line comment block,
continuing until "end comment" directive
or the end of the current file.
end comment
Some hledger entries can have same-line comments attached to them, from
; (semicolon) to end of line. See Transaction comments, Posting com-
ments, and Account comments below.
Transactions
Transactions are the main unit of information in a journal file. They
represent events, typically a movement of some quantity of commodities