hledger/hledger/doc/options.m4.md

OPTIONS

To see general usage and the command list: hledger -h or just hledger

To see usage for a specific command: hledger COMMAND -h

Except for the General options below, options must be written after COMMAND, not before it.

Also, when invoking external add-on commands, their options must be written after a double hyphen. (Or, you can invoke the external command directly.) Eg:

shell({{ $ hledger ui – –register cash $ hledger-ui –register cash }})

Options and command arguments can be intermixed. Arguments are usually interpreted as a search query which filters the data, see QUERIES.

There are three kinds of options. General options are always available and can appear anywhere in the command line:

-h

show general usage (or if after COMMAND, the command’s usage)

--help

show the current program’s manual as plain text (or after an add-on COMMAND, the add-on’s manual)

--man

show the current program’s manual with man

--info

show the current program’s manual with info

--version

show version

-f FILE --file=FILE

use a different input file. For stdin, use -

--rules-file=RULESFILE

Conversion rules file to use when reading CSV (default: FILE.rules)

--alias=OLD=NEW

display accounts named OLD as NEW

--ignore-assertions

ignore any failing balance assertions in the journal

--debug=N

: show debug output if N is 1-9 (default: 0)

Common reporting options are supported by most commands where applicable, and individual commands may provide additional command-specific options. Both of these must be written after the command name.

-b --begin=DATE

include postings/txns on or after this date

-e --end=DATE

include postings/txns before this date

-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 (overrides the flags above)

--date2

show, and match with -b/-e/-p/date:, secondary dates instead

-C --cleared

include only cleared postings/txns

--pending

include only pending postings/txns

-U --uncleared

include only uncleared (and pending) postings/txns

-R --real

include only non-virtual postings

--depth=N

hide accounts/postings deeper than N

-E --empty

show empty/zero things which are normally omitted

-B --cost

show amounts in their cost price’s commodity

`–pivot TAG

will transform the journal before any other processing by replacing the account name of every posting having the tag TAG with content VALUE by the account name “TAG:VALUE”.

The TAG will only match if it is a full-length match. The pivot will only happen if the TAG is on a posting, not if it is on the transaction. If the tag value is a multi:level:account:name the new account name will be “TAG:multi:level:account:name”.

Multiple files

You can specify multiple -f/--file FILE options. This is like combining all the files into one, except they can have different formats. Also directives and aliases in one file do not affect subsequent files (if you need that, use the include directive instead).

Repeated options

Otherwise, if a reporting option is repeated, the last one takes precedence. Eg -p jan -p feb is equivalent to -p feb.

Depth limiting

With the --depth N option, commands like account, balance and register will show only the uppermost accounts in the account tree, down to level N. Use this when you want a summary with less detail.

Smart dates

hledger’s user interfaces accept a flexible “smart date” syntax (unlike dates in the journal file). Smart dates allow some english words, can be relative to today’s date, and can have less-significant date parts omitted (defaulting to 1).

Examples:

2009/1/1, 2009/01/01, 2009-1-1, 2009.1.1	simple dates, several separators allowed
2009/1, 2009	same as above - a missing day or month defaults to 1
1/1, january, jan, this year	relative dates, meaning january 1 of the current year
next year	january 1 of next year
this month	the 1st of the current month
this week	the most recent monday
last week	the monday of the week before this one
lastweek	spaces are optional
today, yesterday, tomorrow

Reporting interval

A reporting interval can be specified so that commands like register, balance and activity will divide their reports into multiple report periods. The basic intervals can be selected with one of -D/--daily, -W/--weekly, -M/--monthly, -Q/--quarterly, or -Y/--yearly. More complex intervals may be specified with a period expression.

Period expressions

The -p/--period option accepts period expressions, a shorthand way of expressing a start date, end date, and or reporting interval all at once. Note a period expression on the command line will cause any other date flags (-b/-e/-D/-W/-M/-Q/-Y) to be ignored.

hledger’s period expressions are similar to Ledger’s, though not identical. Here’s a basic period expression specifying the first quarter of 2009. Note, hledger always treats start dates as inclusive and end dates as exclusive:

-p "from 2009/1/1 to 2009/4/1"

Keywords like “from” and “to” are optional, and so are the spaces, as long as you don’t run two dates together. “to” can also be written as “-”. These are equivalent to the above:

-p "2009/1/1 2009/4/1"

-p2009/1/1to2009/4/1

-p2009/1/1-2009/4/1

Dates are smart dates, so if the current year is 2009, the above can also be written as:

-p "1/1 4/1"

-p "january-apr"

-p "this year to 4/1"

If you specify only one date, the missing start or end date will be the earliest or latest transaction in your journal:

-p "from 2009/1/1"	everything after january 1, 2009
-p "from 2009/1"	the same
-p "from 2009"	the same
-p "to 2009"	everything before january 1, 2009

A single date with no “from” or “to” defines both the start and end date like so:

-p "2009"	the year 2009; equivalent to “2009/1/1 to 2010/1/1”
-p "2009/1"	the month of jan; equivalent to “2009/1/1 to 2009/2/1”
-p "2009/1/1"	just that day; equivalent to “2009/1/1 to 2009/1/2”

Period expressions can also start with (or be) a reporting interval: daily, weekly, monthly, quarterly, yearly, or one of the every ... expressions below. Optionally the word in may appear between the reporting interval and the start/end dates. Examples:

-p "weekly from 2009/1/1 to 2009/4/1"

-p "monthly in 2008"

-p "bimonthly from 2008"

-p "quarterly"

-p "every 2 weeks"

-p "every 5 days from 1/3"

-p "every 15th day of month"

-p "every 4th day of week"

Regular Expressions

hledger uses regular expressions in a number of places:

• query terms, on the command line and in the hledger-web search form: REGEX, desc:REGEX, cur:REGEX, tag:...=REGEX
• CSV rules conditional blocks: if REGEX ...
• account alias directives and options: alias /REGEX/ = REPLACEMENT, --alias /REGEX/=REPLACEMENT

hledger’s regular expressions come from the regex-tdfa library. In general they:

• are case insensitive
• are infix matching (do not need to match the entire thing being matched)
• are POSIX extended regular expressions
• also support GNU word boundaries (\<, \>, \b, \B)
• and parenthesised capturing groups and numeric backreferences in replacement strings
• do not support mode modifiers like (?s)

Some things to note:

• In the alias directive and --alias option, regular expressions must be enclosed in forward slashes (/REGEX/). Elsewhere in hledger, these are not required.

• 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:\$.

• On the command line, some metacharacters like $ have a special meaning to the shell and so must be escaped a second time, with single or double quotes or another backslash. Eg, to match amounts with the dollar sign from the command line, write cur:'\$' or cur:\\$.