333 lines
8.7 KiB
Groff
333 lines
8.7 KiB
Groff
|
|
.TH "hledger\-web" "1" "January 2019" "hledger\-web 1.12.99" "hledger User Manuals"
|
|
|
|
|
|
|
|
.SH NAME
|
|
.PP
|
|
hledger\-web \- web interface for the hledger accounting tool
|
|
.SH SYNOPSIS
|
|
.PP
|
|
\f[C]hledger\-web\ [OPTIONS]\f[]
|
|
.PD 0
|
|
.P
|
|
.PD
|
|
\f[C]hledger\ web\ \-\-\ [OPTIONS]\f[]
|
|
.SH DESCRIPTION
|
|
.PP
|
|
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).
|
|
.PP
|
|
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.
|
|
.PP
|
|
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.
|
|
.PP
|
|
Like hledger, it reads data from one or more files in hledger journal,
|
|
timeclock, timedot, or CSV format specified with \f[C]\-f\f[], or
|
|
\f[C]$LEDGER_FILE\f[], or \f[C]$HOME/.hledger.journal\f[] (on windows,
|
|
perhaps \f[C]C:/Users/USER/.hledger.journal\f[]).
|
|
For more about this see hledger(1), hledger_journal(5) etc.
|
|
.PP
|
|
By default, hledger\-web starts the web app in \[lq]transient mode\[rq]
|
|
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 \f[C]\-\-serve\f[], it just runs the web app without exiting, and
|
|
logs requests to the console.
|
|
.PP
|
|
By default the server listens on IP address 127.0.0.1, accessible only
|
|
to local requests.
|
|
You can use \f[C]\-\-host\f[] to change this, eg
|
|
\f[C]\-\-host\ 0.0.0.0\f[] to listen on all configured addresses.
|
|
.PP
|
|
Similarly, use \f[C]\-\-port\f[] to set a TCP port other than 5000, eg
|
|
if you are running multiple hledger\-web instances.
|
|
.PP
|
|
You can use \f[C]\-\-base\-url\f[] 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 \f[C]http://HOST:PORT/\f[] using the server's configured
|
|
host address and TCP port (or \f[C]http://HOST\f[] if PORT is 80).
|
|
.PP
|
|
With \f[C]\-\-file\-url\f[] you can set a different base url for static
|
|
files, eg for better caching or cookie\-less serving on high performance
|
|
websites.
|
|
.PP
|
|
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.
|
|
.PP
|
|
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.
|
|
.PP
|
|
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.
|
|
.SH OPTIONS
|
|
.PP
|
|
Note: if invoking hledger\-web as a hledger subcommand, write
|
|
\f[C]\-\-\f[] before options as shown above.
|
|
.TP
|
|
.B \f[C]\-\-serve\f[]
|
|
serve and log requests, don't browse or auto\-exit
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]\-\-host=IPADDR\f[]
|
|
listen on this IP address (default: 127.0.0.1)
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]\-\-port=PORT\f[]
|
|
listen on this TCP port (default: 5000)
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]\-\-base\-url=URL\f[]
|
|
set the base url (default: http://IPADDR:PORT).
|
|
You would change this when sharing over the network, or integrating
|
|
within a larger website.
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]\-\-file\-url=URL\f[]
|
|
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.
|
|
.RS
|
|
.RE
|
|
.PP
|
|
hledger input options:
|
|
.TP
|
|
.B \f[C]\-f\ FILE\ \-\-file=FILE\f[]
|
|
use a different input file.
|
|
For stdin, use \- (default: \f[C]$LEDGER_FILE\f[] or
|
|
\f[C]$HOME/.hledger.journal\f[])
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]\-\-rules\-file=RULESFILE\f[]
|
|
Conversion rules file to use when reading CSV (default: FILE.rules)
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]\-\-separator=CHAR\f[]
|
|
Field separator to expect when reading CSV (default: `,')
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]\-\-alias=OLD=NEW\f[]
|
|
rename accounts named OLD to NEW
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]\-\-anon\f[]
|
|
anonymize accounts and payees
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]\-\-pivot\ FIELDNAME\f[]
|
|
use some other field or tag for the account name
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]\-I\ \-\-ignore\-assertions\f[]
|
|
ignore any failing balance assertions
|
|
.RS
|
|
.RE
|
|
.PP
|
|
hledger reporting options:
|
|
.TP
|
|
.B \f[C]\-b\ \-\-begin=DATE\f[]
|
|
include postings/txns on or after this date
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]\-e\ \-\-end=DATE\f[]
|
|
include postings/txns before this date
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]\-D\ \-\-daily\f[]
|
|
multiperiod/multicolumn report by day
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]\-W\ \-\-weekly\f[]
|
|
multiperiod/multicolumn report by week
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]\-M\ \-\-monthly\f[]
|
|
multiperiod/multicolumn report by month
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]\-Q\ \-\-quarterly\f[]
|
|
multiperiod/multicolumn report by quarter
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]\-Y\ \-\-yearly\f[]
|
|
multiperiod/multicolumn report by year
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]\-p\ \-\-period=PERIODEXP\f[]
|
|
set start date, end date, and/or reporting interval all at once using
|
|
period expressions syntax (overrides the flags above)
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]\-\-date2\f[]
|
|
match the secondary date instead (see command help for other effects)
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]\-U\ \-\-unmarked\f[]
|
|
include only unmarked postings/txns (can combine with \-P or \-C)
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]\-P\ \-\-pending\f[]
|
|
include only pending postings/txns
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]\-C\ \-\-cleared\f[]
|
|
include only cleared postings/txns
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]\-R\ \-\-real\f[]
|
|
include only non\-virtual postings
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]\-NUM\ \-\-depth=NUM\f[]
|
|
hide/aggregate accounts or postings more than NUM levels deep
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]\-E\ \-\-empty\f[]
|
|
show items with zero amount, normally hidden (and vice\-versa in
|
|
hledger\-ui/hledger\-web)
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]\-B\ \-\-cost\f[]
|
|
convert amounts to their cost at transaction time (using the transaction
|
|
price, if any)
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]\-V\ \-\-value\f[]
|
|
convert amounts to their market value on the report end date (using the
|
|
most recent applicable market price, if any)
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]\-\-auto\f[]
|
|
apply automated posting rules to modify transactions.
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]\-\-forecast\f[]
|
|
apply periodic transaction rules to generate future transactions, to 6
|
|
months from now or report end date.
|
|
.RS
|
|
.RE
|
|
.PP
|
|
When a reporting option appears more than once in the command line, the
|
|
last one takes precedence.
|
|
.PP
|
|
Some reporting options can also be written as query arguments.
|
|
.PP
|
|
hledger help options:
|
|
.TP
|
|
.B \f[C]\-h\ \-\-help\f[]
|
|
show general usage (or after COMMAND, command usage)
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]\-\-version\f[]
|
|
show version
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]\-\-debug[=N]\f[]
|
|
show debug output (levels 1\-9, default: 1)
|
|
.RS
|
|
.RE
|
|
.PP
|
|
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 \f[C]\-\-\f[] argument before.)
|
|
.SH ENVIRONMENT
|
|
.PP
|
|
\f[B]LEDGER_FILE\f[] The journal file path when not specified with
|
|
\f[C]\-f\f[].
|
|
Default: \f[C]~/.hledger.journal\f[] (on windows, perhaps
|
|
\f[C]C:/Users/USER/.hledger.journal\f[]).
|
|
.SH FILES
|
|
.PP
|
|
Reads data from one or more files in hledger journal, timeclock,
|
|
timedot, or CSV format specified with \f[C]\-f\f[], or
|
|
\f[C]$LEDGER_FILE\f[], or \f[C]$HOME/.hledger.journal\f[] (on windows,
|
|
perhaps \f[C]C:/Users/USER/.hledger.journal\f[]).
|
|
.SH BUGS
|
|
.PP
|
|
The need to precede options with \f[C]\-\-\f[] when invoked from hledger
|
|
is awkward.
|
|
.PP
|
|
\f[C]\-f\-\f[] doesn't work (hledger\-web can't read from stdin).
|
|
.PP
|
|
Query arguments and some hledger options are ignored.
|
|
.PP
|
|
Does not work in text\-mode browsers.
|
|
.PP
|
|
Does not work well on small screens.
|
|
|
|
|
|
.SH "REPORTING BUGS"
|
|
Report bugs at http://bugs.hledger.org
|
|
(or on the #hledger IRC channel or hledger mail list)
|
|
|
|
.SH AUTHORS
|
|
Simon Michael <simon@joyful.com> and contributors
|
|
|
|
.SH COPYRIGHT
|
|
|
|
Copyright (C) 2007-2016 Simon Michael.
|
|
.br
|
|
Released under GNU GPL v3 or later.
|
|
|
|
.SH SEE ALSO
|
|
hledger(1), hledger\-ui(1), hledger\-web(1), hledger\-api(1),
|
|
hledger_csv(5), hledger_journal(5), hledger_timeclock(5), hledger_timedot(5),
|
|
ledger(1)
|
|
|
|
http://hledger.org
|