254 lines
8.3 KiB
Markdown
254 lines
8.3 KiB
Markdown
# hledger-web
|
|
|
|
This doc is for version **1.13**. []{.docversions}
|
|
|
|
\$toc\$
|
|
|
|
## NAME
|
|
|
|
hledger-web - web interface for the hledger accounting tool
|
|
|
|
## SYNOPSIS
|
|
|
|
`hledger-web [OPTIONS]`\
|
|
`hledger web -- [OPTIONS]`
|
|
|
|
## 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:thin grey solid; margin:0 0 1em 1em; }
|
|
.highslide-caption {color:white; background-color:black;}
|
|
</style>
|
|
<div style="float:right; max-width:200px; text-align:right;">
|
|
|
|
<a href="images/hledger-web/normal/register.png" class="highslide" onclick="return hs.expand(this)"><img src="images/hledger-web/normal/register.png" title="Account register view with accounts sidebar" /></a>
|
|
<a href="images/hledger-web/normal/journal.png" class="highslide" onclick="return hs.expand(this)"><img src="images/hledger-web/normal/journal.png" title="Journal view" /></a>
|
|
<a href="images/hledger-web/normal/help.png" class="highslide" onclick="return hs.expand(this)"><img src="images/hledger-web/normal/help.png" title="Help dialog" /></a>
|
|
<a href="images/hledger-web/normal/add.png" class="highslide" onclick="return hs.expand(this)"><img src="images/hledger-web/normal/add.png" title="Add form" /></a>
|
|
|
|
</div>
|
|
|
|
hledger-web is hledger's web interface. It starts a simple web
|
|
application for browsing and adding transactions, and optionally opens
|
|
it in a web browser window if possible. It provides a more user-friendly
|
|
UI than the hledger CLI or hledger-ui interface, showing more at once
|
|
(accounts, the current account register, balance charts) and allowing
|
|
history-aware data entry, interactive searching, and bookmarking.
|
|
|
|
hledger-web also lets you share a ledger with multiple users, or even
|
|
the public web. There is no access control, so if you need that you
|
|
should put it behind a suitable web proxy. As a small protection against
|
|
data loss when running an unprotected instance, it writes a numbered
|
|
backup of the main journal file (only ?) on every edit.
|
|
|
|
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.
|
|
|
|
By default, hledger-web starts the web app in "transient mode" and also
|
|
opens it in your default web browser if possible. In this mode the web
|
|
app will keep running for as long as you have it open in a browser
|
|
window, and will exit after two minutes of inactivity (no requests and
|
|
no browser windows viewing it). With `--serve`, it just runs the web app
|
|
without exiting, and logs requests to the console.
|
|
|
|
By default the server listens on IP address 127.0.0.1, accessible only
|
|
to local requests. You can use `--host` to change this, eg
|
|
`--host 0.0.0.0` to listen on all configured addresses.
|
|
|
|
Similarly, use `--port` to set a TCP port other than 5000, eg if you are
|
|
running multiple hledger-web instances.
|
|
|
|
You can use `--base-url` to change the protocol, hostname, port and path
|
|
that appear in hyperlinks, useful eg for integrating hledger-web within
|
|
a larger website. The default is `http://HOST:PORT/` using the server's
|
|
configured host address and TCP port (or `http://HOST` if PORT is 80).
|
|
|
|
With `--file-url` you can set a different base url for static files, eg
|
|
for better caching or cookie-less serving on high performance websites.
|
|
|
|
Note there is no built-in access control (aside from listening on
|
|
127.0.0.1 by default). So you will need to hide hledger-web behind an
|
|
authenticating proxy (such as apache or nginx) if you want to restrict
|
|
who can see and add entries to your journal.
|
|
|
|
Command-line options and arguments may be used to set an initial filter
|
|
on the data. This is not shown in the web UI, but it will be applied in
|
|
addition to any search query entered there.
|
|
|
|
With journal and timeclock files (but not CSV files, currently) the web
|
|
app detects changes made by other means and will show the new data on
|
|
the next request. If a change makes the file unparseable, hledger-web
|
|
will show an error until the file has been fixed.
|
|
|
|
## OPTIONS
|
|
|
|
Note: if invoking hledger-web as a hledger subcommand, write `--` before
|
|
options as shown above.
|
|
|
|
`--serve`
|
|
: serve and log requests, don't browse or auto-exit
|
|
|
|
`--host=IPADDR`
|
|
: listen on this IP address (default: 127.0.0.1)
|
|
|
|
`--port=PORT`
|
|
: listen on this TCP port (default: 5000)
|
|
|
|
`--base-url=URL`
|
|
: set the base url (default: http://IPADDR:PORT). You would change
|
|
this when sharing over the network, or integrating within a larger
|
|
website.
|
|
|
|
`--file-url=URL`
|
|
: set the static files url (default: BASEURL/static). hledger-web
|
|
normally serves static files itself, but if you wanted to serve them
|
|
from another server for efficiency, you would set the url with this.
|
|
|
|
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.)
|
|
|
|
## ENVIRONMENT
|
|
|
|
**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-web can't read from stdin).
|
|
|
|
Query arguments and some hledger options are ignored.
|
|
|
|
Does not work in text-mode browsers.
|
|
|
|
Does not work well on small screens.
|