243 lines
8.0 KiB
Markdown
243 lines
8.0 KiB
Markdown
# hledger-web
|
|
|
|
This doc is for version **1.1**. <span class="docversions"></span>
|
|
|
|
- toc
|
|
|
|
## NAME
|
|
|
|
hledger-web - web interface for the hledger accounting tool
|
|
|
|
## SYNOPSIS
|
|
|
|
`hledger-web [OPTIONS]`\
|
|
`hledger web -- [OPTIONS]`
|
|
|
|
<style>
|
|
.highslide img {max-width:250px; float:right; margin:0 0 1em 1em;}
|
|
.highslide-caption {color:white; background-color:black;}
|
|
</style>
|
|
<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>
|
|
|
|
## 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).
|
|
|
|
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).
|
|
|
|
``` {.shell}
|
|
$ hledger web
|
|
Starting web app on port 5000 with base url http://localhost:5000
|
|
Starting web browser if possible
|
|
Web app will auto-exit after a few minutes with no browsers (or press ctrl-c)
|
|
```
|
|
|
|
With `--serve`, it starts the web app in non-transient mode 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 general options:
|
|
|
|
`-h`
|
|
: show general usage (or 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
|
|
|
|
`--debug[=N]`
|
|
: show debug output (levels 1-9, default: 1)
|
|
|
|
`-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
|
|
|
|
`-I --ignore-assertions`
|
|
: ignore any failing balance assertions in the journal
|
|
|
|
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
|
|
(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 items with zero amount, normally hidden
|
|
|
|
`-B --cost`
|
|
: convert amounts to their cost at transaction time (using the
|
|
[transaction price](journal.html#transaction-prices), if any)
|
|
|
|
`--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".
|
|
|
|
`--anon`
|
|
: show anonymized accounts and payees
|
|
|
|
## 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.
|