hledger(1)

This is the command-line interface (CLI) for the hledger accounting tool. Here we also describe hledger\[aq]s concepts and file formats. This manual is for hledger 1.25.

\f[C]hledger\f[R]

\f[C]hledger [-f FILE] COMMAND [OPTIONS] [ARGS]\f[R]

\f[C]hledger [-f FILE] ADDONCMD -- [OPTIONS] [ARGS]\f[R]

hledger is a reliable, cross-platform set of programs for tracking money, time, or any other commodity, using double-entry accounting and a simple, editable file format. hledger is inspired by and largely compatible with ledger(1).

The basic function of the hledger CLI is to read a plain text file describing financial transactions (in accounting terms, a general journal) and print useful reports on standard output, or export them as CSV. hledger can also read some other file formats such as CSV files, translating them to journal format. Additionally, hledger lists other hledger-* executables found in the user\[cq]s $PATH and can invoke them as subcommands.

hledger reads data from one or more files in hledger journal, timeclock, timedot, or CSV format specified with \f[C]-f\f[R], or \f[C]$LEDGER_FILE\f[R], or \f[C]$HOME/.hledger.journal\f[R] (on windows, perhaps \f[C]C:/Users/USER/.hledger.journal\f[R]). If using \f[C]$LEDGER_FILE\f[R], note this must be a real environment variable, not a shell variable. You can specify standard input with \f[C]-f-\f[R].

Transactions are dated movements of money between two (or more) named accounts, and are recorded with journal entries like this:

\f[C] 2015/10/16 bought food expenses:food $10 assets:cash \f[R]

Most users use a text editor to edit the journal, usually with an editor mode such as ledger-mode for added convenience. hledger\[cq]s interactive add command is another way to record new transactions. hledger never changes existing transactions.

To get started, you can either save some entries like the above in \f[C]\[ti]/.hledger.journal\f[R], or run \f[C]hledger add\f[R] and follow the prompts. Then try some commands like \f[C]hledger print\f[R] or \f[C]hledger balance\f[R]. Run \f[C]hledger\f[R] with no arguments for a list of commands.

To see general usage help, including general options which are supported by most hledger commands, run \f[C]hledger -h\f[R].

General help options:

\f[B]\f[CB]-h --help\f[B]\f[R] show general or COMMAND help

\f[B]\f[CB]--man\f[B]\f[R] show general or COMMAND user manual with man

\f[B]\f[CB]--info\f[B]\f[R] show general or COMMAND user manual with info

\f[B]\f[CB]--version\f[B]\f[R] show general or ADDONCMD version

\f[B]\f[CB]--debug[=N]\f[B]\f[R] show debug output (levels 1-9, default: 1)

General input options:

\f[B]\f[CB]-f FILE --file=FILE\f[B]\f[R] use a different input file. For stdin, use - (default: \f[C]$LEDGER_FILE\f[R] or \f[C]$HOME/.hledger.journal\f[R])

\f[B]\f[CB]--rules-file=RULESFILE\f[B]\f[R] Conversion rules file to use when reading CSV (default: FILE.rules)

\f[B]\f[CB]--separator=CHAR\f[B]\f[R] Field separator to expect when reading CSV (default: \[aq],\[aq])

\f[B]\f[CB]--alias=OLD=NEW\f[B]\f[R] rename accounts named OLD to NEW

\f[B]\f[CB]--anon\f[B]\f[R] anonymize accounts and payees

\f[B]\f[CB]--pivot FIELDNAME\f[B]\f[R] use some other field or tag for the account name

\f[B]\f[CB]-I --ignore-assertions\f[B]\f[R] disable balance assertion checks (note: does not disable balance assignments)

\f[B]\f[CB]-s --strict\f[B]\f[R] do extra error checking (check that all posted accounts are declared)

General reporting options:

\f[B]\f[CB]-b --begin=DATE\f[B]\f[R] include postings/txns on or after this date (will be adjusted to preceding subperiod start when using a report interval)

\f[B]\f[CB]-e --end=DATE\f[B]\f[R] include postings/txns before this date (will be adjusted to following subperiod end when using a report interval)

\f[B]\f[CB]-D --daily\f[B]\f[R] multiperiod/multicolumn report by day

\f[B]\f[CB]-W --weekly\f[B]\f[R] multiperiod/multicolumn report by week

\f[B]\f[CB]-M --monthly\f[B]\f[R] multiperiod/multicolumn report by month

\f[B]\f[CB]-Q --quarterly\f[B]\f[R] multiperiod/multicolumn report by quarter

\f[B]\f[CB]-Y --yearly\f[B]\f[R] multiperiod/multicolumn report by year

\f[B]\f[CB]-p --period=PERIODEXP\f[B]\f[R] set start date, end date, and/or reporting interval all at once using period expressions syntax

\f[B]\f[CB]--date2\f[B]\f[R] match the secondary date instead (see command help for other effects)

\f[B]\f[CB]--today=DATE\f[B]\f[R] override today\[aq]s date (affects relative smart dates, for tests/examples)

\f[B]\f[CB]-U --unmarked\f[B]\f[R] include only unmarked postings/txns (can combine with -P or -C)

\f[B]\f[CB]-P --pending\f[B]\f[R] include only pending postings/txns

\f[B]\f[CB]-C --cleared\f[B]\f[R] include only cleared postings/txns

\f[B]\f[CB]-R --real\f[B]\f[R] include only non-virtual postings

\f[B]\f[CB]-NUM --depth=NUM\f[B]\f[R] hide/aggregate accounts or postings more than NUM levels deep

\f[B]\f[CB]-E --empty\f[B]\f[R] show items with zero amount, normally hidden (and vice-versa in hledger-ui/hledger-web)

\f[B]\f[CB]-B --cost\f[B]\f[R] convert amounts to their cost/selling amount at transaction time

\f[B]\f[CB]-V --market\f[B]\f[R] convert amounts to their market value in default valuation commodities

\f[B]\f[CB]-X --exchange=COMM\f[B]\f[R] convert amounts to their market value in commodity COMM

\f[B]\f[CB]--value\f[B]\f[R] convert amounts to cost or market value, more flexibly than -B/-V/-X

\f[B]\f[CB]--infer-market-prices\f[B]\f[R] use transaction prices (recorded with \[at] or \[at]\[at]) as additional market prices, as if they were P directives

\f[B]\f[CB]--auto\f[B]\f[R] apply automated posting rules to modify transactions.

\f[B]\f[CB]--forecast\f[B]\f[R] generate future transactions from periodic transaction rules, for the next 6 months or till report end date. In hledger-ui, also make ordinary future transactions visible.

\f[B]\f[CB]--commodity-style\f[B]\f[R] Override the commodity style in the output for the specified commodity. For example \[aq]EUR1.000,00\[aq].

\f[B]\f[CB]--color=WHEN (or --colour=WHEN)\f[B]\f[R] Should color-supporting commands use ANSI color codes in text output. \[aq]auto\[aq] (default): whenever stdout seems to be a color-supporting terminal. \[aq]always\[aq] or \[aq]yes\[aq]: always, useful eg when piping output into \[aq]less -R\[aq]. \[aq]never\[aq] or \[aq]no\[aq]: never. A NO_COLOR environment variable overrides this.

\f[B]\f[CB]--pretty[=WHEN]\f[B]\f[R] Show prettier output, e.g. using unicode box-drawing characters. Accepts \[aq]yes\[aq] (the default) or \[aq]no\[aq] (\[aq]y\[aq], \[aq]n\[aq], \[aq]always\[aq], \[aq]never\[aq] also work). If you provide an argument you must use \[aq]=\[aq], e.g. \[aq]--pretty=yes\[aq].

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.

To see options for a particular command, including command-specific options, run: \f[C]hledger COMMAND -h\f[R].

Command-specific options must be written after the command name, eg: \f[C]hledger print -x\f[R].

Additionally, if the command is an add-on, you may need to put its options after a double-hyphen, eg: \f[C]hledger ui -- --watch\f[R]. Or, you can run the add-on executable directly: \f[C]hledger-ui --watch\f[R].

Most hledger commands accept arguments after the command name, which are often a query, filtering the data in some way.

You can save a set of command line options/arguments in a file, and then reuse them by writing \f[C]\[at]FILENAME\f[R] as a command line argument. Eg: \f[C]hledger bal \[at]foo.args\f[R]. (To prevent this, eg if you have an argument that begins with a literal \f[C]\[at]\f[R], precede it with \f[C]--\f[R], eg: \f[C]hledger bal -- \[at]ARG\f[R]).

Inside the argument file, each line should contain just one option or argument. Avoid the use of spaces, except inside quotes (or you\[aq]ll see a confusing error). Between a flag and its argument, use = (or nothing). Bad:

\f[C] assets depth:2 -X USD \f[R]

Good:

\f[C] assets depth:2 -X=USD \f[R]

For special characters (see below), use one less level of quoting than you would at the command prompt. Bad:

\f[C] -X\[dq]$\[dq] \f[R]

Good:

\f[C] -X$ \f[R]

See also: Save frequently used options.

In shell command lines, characters significant to your shell - such as spaces, \f[C]<\f[R], \f[C]>\f[R], \f[C](\f[R], \f[C])\f[R], \f[C]|\f[R], \f[C]$\f[R] and \f[C]\[rs]\f[R] - should be \[dq]shell-escaped\[dq] if you want hledger to see them. This is done by enclosing them in single or double quotes, or by writing a backslash before them. Eg to match an account name containing a space:

\f[C] $ hledger register \[aq]credit card\[aq] \f[R]

or:

\f[C] $ hledger register credit\[rs] card \f[R]

Windows users should keep in mind that \f[C]cmd\f[R] treats single quote as a regular character, so you should be using double quotes exclusively. PowerShell treats both single and double quotes as quotes.

Characters significant in regular expressions (described below) - such as \f[C].\f[R], \f[C]\[ha]\f[R], \f[C]$\f[R], \f[C][\f[R], \f[C]]\f[R], \f[C](\f[R], \f[C])\f[R], \f[C]|\f[R], and \f[C]\[rs]\f[R] - may need to be \[dq]regex-escaped\[dq] if you don\[aq]t want them to be interpreted by hledger\[aq]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 \f[C]$\f[R] sign while using the bash shell:

\f[C] $ hledger balance cur:\[aq]\[rs]$\[aq] \f[R]

or:

\f[C] $ hledger balance cur:\[rs]\[rs]$ \f[R]

When you use hledger to run an external add-on command (described below), 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 \f[C]$\f[R] sign while using the bash shell and running an add-on command (\f[C]ui\f[R]):

\f[C] $ hledger ui cur:\[aq]\[rs]\[rs]$\[aq] \f[R]

or:

\f[C] $ hledger ui cur:\[rs]\[rs]\[rs]\[rs]$ \f[R]

If you wondered why \f[I]four\f[R] backslashes, perhaps this helps:

tab(@); l l. T{ unescaped: T}@T{ \f[C]$\f[R] T} T{ escaped: T}@T{ \f[C]\[rs]$\f[R] T} T{ double-escaped: T}@T{ \f[C]\[rs]\[rs]$\f[R] T} T{ triple-escaped: T}@T{ \f[C]\[rs]\[rs]\[rs]\[rs]$\f[R] T}

Or, you can avoid the extra escaping by running the add-on executable directly:

\f[C] $ hledger-ui cur:\[rs]\[rs]$ \f[R]

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:

an \[at]argumentfile

hledger-ui\[aq]s filter field

hledger-web\[aq]s search form

GHCI\[aq]s prompt (used by developers).

hledger is expected to handle non-ascii characters correctly:

they should be parsed correctly in input files and on the command line, by all hledger tools (add, iadd, hledger-web\[aq]s search/add/edit forms, etc.)

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:

A system locale must be configured, and it must be one that can decode the characters being used. In bash, you can set a locale like this: \f[C]export LANG=en_US.UTF-8\f[R]. There are some more details in Troubleshooting. This step is essential - without it, hledger will quit on encountering a non-ascii character (as with all GHC-compiled programs).

your terminal software (eg Terminal.app, iTerm, CMD.exe, xterm..) must support unicode

the terminal must be using a font which includes the required unicode glyphs

the terminal should be configured to display wide characters as double width (for report alignment)