430 lines
17 KiB
Markdown
430 lines
17 KiB
Markdown
# hledger-ui
|
|
|
|
This doc is for version **1.13**. []{.docversions}
|
|
|
|
\$toc\$
|
|
|
|
## NAME
|
|
|
|
hledger-ui - curses-style interface for the hledger accounting tool
|
|
|
|
## SYNOPSIS
|
|
|
|
`hledger-ui [OPTIONS] [QUERYARGS]`\
|
|
`hledger ui -- [OPTIONS] [QUERYARGS]`
|
|
|
|
## DESCRIPTION
|
|
|
|
hledger is a cross-platform program 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).
|
|
|
|
<style>
|
|
.highslide img {max-width:200px; border:0;}
|
|
.highslide-caption {color:white; background-color:black;}
|
|
</style>
|
|
<div style="float:right; max-width:200px; text-align:right;">
|
|
|
|
<a href="images/hledger-ui/hledger-ui-sample-acc2.png" class="highslide" onclick="return hs.expand(this)"><img src="images/hledger-ui/hledger-ui-sample-acc2.png" title="Accounts screen with query and depth limit" /></a>
|
|
<a href="images/hledger-ui/hledger-ui-sample-acc.png" class="highslide" onclick="return hs.expand(this)"><img src="images/hledger-ui/hledger-ui-sample-acc.png" title="Accounts screen" /></a>
|
|
<a href="images/hledger-ui/hledger-ui-sample-acc-greenterm.png" class="highslide" onclick="return hs.expand(this)"><img src="images/hledger-ui/hledger-ui-sample-acc-greenterm.png" title="Accounts screen with greenterm theme" /></a>
|
|
<a href="images/hledger-ui/hledger-ui-sample-txn.png" class="highslide" onclick="return hs.expand(this)"><img src="images/hledger-ui/hledger-ui-sample-txn.png" title="Transaction screen" /></a>
|
|
<a href="images/hledger-ui/hledger-ui-sample-reg.png" class="highslide" onclick="return hs.expand(this)"><img src="images/hledger-ui/hledger-ui-sample-reg.png" title="Register screen" /></a>
|
|
<!-- <br clear=all> -->
|
|
<a href="images/hledger-ui/hledger-ui-bcexample-acc.png" class="highslide" onclick="return hs.expand(this)"><img src="images/hledger-ui/hledger-ui-bcexample-acc.png" title="beancount example accounts" /></a>
|
|
<a href="images/hledger-ui/hledger-ui-bcexample-acc-etrade-cash.png" class="highslide" onclick="return hs.expand(this)"><img src="images/hledger-ui/hledger-ui-bcexample-acc-etrade-cash.png" title="beancount example's etrade cash subaccount" /></a>
|
|
<a href="images/hledger-ui/hledger-ui-bcexample-acc-etrade.png" class="highslide" onclick="return hs.expand(this)"><img src="images/hledger-ui/hledger-ui-bcexample-acc-etrade.png" title="beancount example's etrade investments, all commoditiess" /></a>
|
|
|
|
</div>
|
|
|
|
hledger-ui is hledger's curses-style interface, providing an efficient
|
|
full-window text UI for viewing accounts and transactions, and some
|
|
limited data entry capability. It is easier than hledger's command-line
|
|
interface, and sometimes quicker and more convenient than the web
|
|
interface.
|
|
|
|
Note hledger-ui has some different defaults (experimental):
|
|
|
|
- it generates rule-based transactions and postings by default
|
|
(--forecast and --auto are always on).
|
|
- it hides transactions dated in the future by default (change this
|
|
with --future or the F key).
|
|
|
|
Like hledger, it reads data from one or more files in hledger journal,
|
|
timeclock, timedot, or CSV format specified with `-f`, or
|
|
`$LEDGER_FILE`, or `$HOME/.hledger.journal` (on windows, perhaps
|
|
`C:/Users/USER/.hledger.journal`). For more about this see hledger(1),
|
|
hledger\_journal(5) etc.
|
|
|
|
## OPTIONS
|
|
|
|
Note: if invoking hledger-ui as a hledger subcommand, write `--` before
|
|
options as shown above.
|
|
|
|
Any QUERYARGS are interpreted as a hledger search query which filters
|
|
the data.
|
|
|
|
`--watch`
|
|
: watch for data and date changes and reload automatically
|
|
|
|
`--theme=default|terminal|greenterm`
|
|
: use this custom display theme
|
|
|
|
`--register=ACCTREGEX`
|
|
: start in the (first) matched account's register screen
|
|
|
|
`--change`
|
|
: show period balances (changes) at startup instead of historical
|
|
balances
|
|
|
|
`-F --flat`
|
|
: show accounts as a list (default)
|
|
|
|
`-T --tree`
|
|
: show accounts as a tree
|
|
|
|
`--future`
|
|
: show transactions dated later than today (normally hidden)
|
|
|
|
hledger 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
|
|
|
|
`--anon`
|
|
: anonymize accounts and payees
|
|
|
|
`--pivot FIELDNAME`
|
|
: use some other field or tag for the account name
|
|
|
|
`-I --ignore-assertions`
|
|
: ignore any failing balance assertions
|
|
|
|
hledger reporting options:
|
|
|
|
`-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
|
|
using [period expressions](manual.html#period-expressions) syntax
|
|
(overrides the flags above)
|
|
|
|
`--date2`
|
|
: match the secondary date instead (see command help for other
|
|
effects)
|
|
|
|
`-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 at transaction time (using the
|
|
[transaction price](journal.html#transaction-prices), if any)
|
|
|
|
`-V --value`
|
|
: convert amounts to their market value on the report end date (using
|
|
the most recent applicable [market
|
|
price](journal.html#market-prices), if any)
|
|
|
|
`--auto`
|
|
: apply [automated posting
|
|
rules](journal.html#automated-posting-rules) to modify transactions.
|
|
|
|
`--forecast`
|
|
: apply [periodic transaction](journal.html#periodic-transactions)
|
|
rules to generate future transactions, to 6 months from now or
|
|
report end date.
|
|
|
|
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](#queries).
|
|
|
|
hledger help options:
|
|
|
|
`-h --help`
|
|
: show general usage (or after COMMAND, command usage)
|
|
|
|
`--version`
|
|
: show version
|
|
|
|
`--debug[=N]`
|
|
: show debug output (levels 1-9, default: 1)
|
|
|
|
A @FILE argument will be expanded to the contents of FILE, which should
|
|
contain one command line option/argument per line. (To prevent this,
|
|
insert a `--` argument before.)
|
|
|
|
## KEYS
|
|
|
|
`?` shows a help dialog listing all keys. (Some of these also appear in
|
|
the quick help at the bottom of each screen.) Press `?` again (or
|
|
`ESCAPE`, or `LEFT`) to close it. The following keys work on most
|
|
screens:
|
|
|
|
The cursor keys navigate: `right` (or `enter`) goes deeper, `left`
|
|
returns to the previous screen,
|
|
`up`/`down`/`page up`/`page down`/`home`/`end` move up and down through
|
|
lists. Vi-style (`h`/`j`/`k`/`l`) and Emacs-style
|
|
(`CTRL-p`/`CTRL-n`/`CTRL-f`/`CTRL-b`) movement keys are also supported.
|
|
A tip: movement speed is limited by your keyboard repeat rate, to move
|
|
faster you may want to adjust it. (If you're on a mac, the Karabiner app
|
|
is one way to do that.)
|
|
|
|
With shift pressed, the cursor keys adjust the report period, limiting
|
|
the transactions to be shown (by default, all are shown).
|
|
`shift-down/up` steps downward and upward through these standard report
|
|
period durations: year, quarter, month, week, day. Then,
|
|
`shift-left/right` moves to the previous/next period. `t` sets the
|
|
report period to today. With the `--watch` option, when viewing a
|
|
"current" period (the current day, week, month, quarter, or year), the
|
|
period will move automatically to track the current date. To set a
|
|
non-standard period, you can use `/` and a `date:` query.
|
|
|
|
`/` lets you set a general filter query limiting the data shown, using
|
|
the same [query terms](/hledger.html#queries) as in hledger and
|
|
hledger-web. While editing the query, you can use [CTRL-a/e/d/k, BS,
|
|
cursor
|
|
keys](http://hackage.haskell.org/package/brick-0.7/docs/Brick-Widgets-Edit.html#t:Editor);
|
|
press `ENTER` to set it, or `ESCAPE`to cancel. There are also keys for
|
|
quickly adjusting some common filters like account depth and transaction
|
|
status (see below). `BACKSPACE` or `DELETE` removes all filters, showing
|
|
all transactions.
|
|
|
|
As mentioned above, hledger-ui shows auto-generated periodic
|
|
transactions, and hides future transactions (auto-generated or not) by
|
|
default. `F` toggles showing and hiding these future transactions. This
|
|
is similar to using a query like `date:-tomorrow`, but more convenient.
|
|
(experimental)
|
|
|
|
`ESCAPE` removes all filters and jumps back to the top screen. Or, it
|
|
cancels a minibuffer edit or help dialog in progress.
|
|
|
|
`CTRL-l` redraws the screen and centers the selection if possible
|
|
(selections near the top won't be centered, since we don't scroll above
|
|
the top).
|
|
|
|
`g` reloads from the data file(s) and updates the current screen and any
|
|
previous screens. (With large files, this could cause a noticeable
|
|
pause.)
|
|
|
|
`I` toggles balance assertion checking. Disabling balance assertions
|
|
temporarily can be useful for troubleshooting.
|
|
|
|
`a` runs command-line hledger's add command, and reloads the updated
|
|
file. This allows some basic data entry.
|
|
|
|
`A` is like `a`, but runs the
|
|
[hledger-iadd](http://hackage.haskell.org/package/hledger-iadd) tool,
|
|
which provides a curses-style interface. This key will be available if
|
|
`hledger-iadd` is installed in \$PATH.
|
|
|
|
`E` runs \$HLEDGER\_UI\_EDITOR, or \$EDITOR, or a default
|
|
(`emacsclient -a "" -nw`) on the journal file. With some editors (emacs,
|
|
vi), the cursor will be positioned at the current transaction when
|
|
invoked from the register and transaction screens, and at the error
|
|
location (if possible) when invoked from the error screen.
|
|
|
|
`q` quits the application.
|
|
|
|
Additional screen-specific keys are described below.
|
|
|
|
## SCREENS
|
|
|
|
### Accounts screen
|
|
|
|
This is normally the first screen displayed. It lists accounts and their
|
|
balances, like hledger's balance command. By default, it shows all
|
|
accounts and their latest ending balances (including the balances of
|
|
subaccounts). if you specify a query on the command line, it shows just
|
|
the matched accounts and the balances from matched transactions.
|
|
|
|
Account names are shown as a flat list by default. Press `T` to toggle
|
|
tree mode. In flat mode, account balances are exclusive of subaccounts,
|
|
except where subaccounts are hidden by a depth limit (see below). In
|
|
tree mode, all account balances are inclusive of subaccounts.
|
|
|
|
To see less detail, press a number key, `1` to `9`, to set a depth
|
|
limit. Or use `-` to decrease and `+`/`=` to increase the depth limit.
|
|
`0` shows even less detail, collapsing all accounts to a single total.
|
|
To remove the depth limit, set it higher than the maximum account depth,
|
|
or press `ESCAPE`.
|
|
|
|
`H` toggles between showing historical balances or period balances.
|
|
Historical balances (the default) are ending balances at the end of the
|
|
report period, taking into account all transactions before that date
|
|
(filtered by the filter query if any), including transactions before the
|
|
start of the report period. In other words, historical balances are what
|
|
you would see on a bank statement for that account (unless disturbed by
|
|
a filter query). Period balances ignore transactions before the report
|
|
start date, so they show the change in balance during the report period.
|
|
They are more useful eg when viewing a time log.
|
|
|
|
`U` toggles filtering by [unmarked status](/journal.html#status),
|
|
including or excluding unmarked postings in the balances. Similarly, `P`
|
|
toggles pending postings, and `C` toggles cleared postings. (By default,
|
|
balances include all postings; if you activate one or two status
|
|
filters, only those postings are included; and if you activate all
|
|
three, the filter is removed.)
|
|
|
|
`R` toggles real mode, in which [virtual
|
|
postings](/journal.html#virtual-postings) are ignored.
|
|
|
|
`Z` toggles nonzero mode, in which only accounts with nonzero balances
|
|
are shown (hledger-ui shows zero items by default, unlike command-line
|
|
hledger).
|
|
|
|
Press `right` or `enter` to view an account's transactions register.
|
|
|
|
### Register screen
|
|
|
|
This screen shows the transactions affecting a particular account, like
|
|
a check register. Each line represents one transaction and shows:
|
|
|
|
- the other account(s) involved, in abbreviated form. (If there are
|
|
both real and virtual postings, it shows only the accounts affected
|
|
by real postings.)
|
|
|
|
- the overall change to the current account's balance; positive for an
|
|
inflow to this account, negative for an outflow.
|
|
|
|
- the running historical total or period total for the current
|
|
account, after the transaction. This can be toggled with `H`.
|
|
Similar to the accounts screen, the historical total is affected by
|
|
transactions (filtered by the filter query) before the report start
|
|
date, while the period total is not. If the historical total is not
|
|
disturbed by a filter query, it will be the running historical
|
|
balance you would see on a bank register for the current account.
|
|
|
|
Transactions affecting this account's subaccounts will be included in
|
|
the register if the accounts screen is in tree mode, or if it's in flat
|
|
mode but this account has subaccounts which are not shown due to a depth
|
|
limit. In other words, the register always shows the transactions
|
|
contributing to the balance shown on the accounts screen.\
|
|
Tree mode/flat mode can be toggled with `T` here also.
|
|
|
|
`U` toggles filtering by [unmarked status](/journal.html#status),
|
|
showing or hiding unmarked transactions. Similarly, `P` toggles pending
|
|
transactions, and `C` toggles cleared transactions. (By default,
|
|
transactions with all statuses are shown; if you activate one or two
|
|
status filters, only those transactions are shown; and if you activate
|
|
all three, the filter is removed.)
|
|
|
|
`R` toggles real mode, in which [virtual
|
|
postings](/journal.html#virtual-postings) are ignored.
|
|
|
|
`Z` toggles nonzero mode, in which only transactions posting a nonzero
|
|
change are shown (hledger-ui shows zero items by default, unlike
|
|
command-line hledger).
|
|
|
|
Press `right` (or `enter`) to view the selected transaction in detail.
|
|
|
|
### Transaction screen
|
|
|
|
This screen shows a single transaction, as a general journal entry,
|
|
similar to hledger's print command and journal format
|
|
(hledger\_journal(5)).
|
|
|
|
The transaction's date(s) and any cleared flag, transaction code,
|
|
description, comments, along with all of its account postings are shown.
|
|
Simple transactions have two postings, but there can be more (or in
|
|
certain cases, fewer).
|
|
|
|
`up` and `down` will step through all transactions listed in the
|
|
previous account register screen. In the title bar, the numbers in
|
|
parentheses show your position within that account register. They will
|
|
vary depending on which account register you came from (remember most
|
|
transactions appear in multiple account registers). The \#N number
|
|
preceding them is the transaction's position within the complete
|
|
unfiltered journal, which is a more stable id (at least until the next
|
|
reload).
|
|
|
|
### Error screen
|
|
|
|
This screen will appear if there is a problem, such as a parse error,
|
|
when you press g to reload. Once you have fixed the problem, press g
|
|
again to reload and resume normal operation. (Or, you can press escape
|
|
to cancel the reload attempt.)
|
|
|
|
## ENVIRONMENT
|
|
|
|
**COLUMNS** The screen width to use. Default: the full terminal width.
|
|
|
|
**LEDGER\_FILE** The journal file path when not specified with `-f`.
|
|
Default: `~/.hledger.journal` (on windows, perhaps
|
|
`C:/Users/USER/.hledger.journal`).
|
|
|
|
## FILES
|
|
|
|
Reads data from one or more files in hledger journal, timeclock,
|
|
timedot, or CSV format specified with `-f`, or `$LEDGER_FILE`, or
|
|
`$HOME/.hledger.journal` (on windows, perhaps
|
|
`C:/Users/USER/.hledger.journal`).
|
|
|
|
## BUGS
|
|
|
|
The need to precede options with `--` when invoked from hledger is
|
|
awkward.
|
|
|
|
`-f-` doesn't work (hledger-ui can't read from stdin).
|
|
|
|
`-V` affects only the accounts screen.
|
|
|
|
When you press `g`, the current and all previous screens are
|
|
regenerated, which may cause a noticeable pause with large files. Also
|
|
there is no visual indication that this is in progress.
|
|
|
|
`--watch` is not yet fully robust. It works well for normal usage, but
|
|
many file changes in a short time (eg saving the file thousands of times
|
|
with an editor macro) can cause problems at least on OSX. Symptoms
|
|
include: unresponsive UI, periodic resetting of the cursor position,
|
|
momentary display of parse errors, high CPU usage eventually subsiding,
|
|
and possibly a small but persistent build-up of CPU usage until the
|
|
program is restarted.
|