380 lines
15 KiB
Plaintext
380 lines
15 KiB
Plaintext
|
|
hledger-web(1) hledger User Manuals hledger-web(1)
|
|
|
|
|
|
|
|
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).
|
|
|
|
hledger-web is hledger's web interface. It starts a simple web appli-
|
|
cation 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 (ac-
|
|
counts, the current account register, balance charts) and allowing his-
|
|
tory-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.
|
|
|
|
OPTIONS
|
|
Command-line options and arguments may be used to set an initial filter
|
|
on the data. These filter options are not shown in the web UI, but it
|
|
will be applied in addition to any search query entered there.
|
|
|
|
Note: if invoking hledger-web as a hledger subcommand, write -- before
|
|
options, as shown in the synopsis above.
|
|
|
|
--serve
|
|
serve and log requests, don't browse or auto-exit
|
|
|
|
--serve-api
|
|
like --serve, but serve only the JSON web API, without the
|
|
server-side web UI
|
|
|
|
--host=IPADDR
|
|
listen on this IP address (default: 127.0.0.1)
|
|
|
|
--port=PORT
|
|
listen on this TCP port (default: 5000)
|
|
|
|
--socket=SOCKETFILE
|
|
use a unix domain socket file to listen for requests instead of
|
|
a TCP socket. Implies --serve. It can only be used if the op-
|
|
erating system can provide this type of socket.
|
|
|
|
--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.
|
|
|
|
--capabilities=CAP[,CAP..]
|
|
enable the view, add, and/or manage capabilities (default:
|
|
view,add)
|
|
|
|
--capabilities-header=HTTPHEADER
|
|
read capabilities to enable from a HTTP header, like X-Sand-
|
|
storm-Permissions (default: disabled)
|
|
|
|
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
|
|
disable balance assertion checks (note: does not disable balance
|
|
assignments)
|
|
|
|
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 syntax
|
|
|
|
--date2
|
|
match the secondary date instead (see command help for other ef-
|
|
fects)
|
|
|
|
-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, if any)
|
|
|
|
-V --value
|
|
convert amounts to their market value on the report end date
|
|
(using the most recent applicable market price, if any)
|
|
|
|
--auto apply automated posting rules to modify transactions.
|
|
|
|
--forecast
|
|
apply periodic transaction rules to generate future transac-
|
|
tions, 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.
|
|
|
|
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.)
|
|
|
|
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 win-
|
|
dow, 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. With --serve-api,
|
|
only the JSON web api (see below) is served, with the usual HTML
|
|
server-side web UI disabled.
|
|
|
|
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.
|
|
|
|
Both of these options are ignored when --socket is used. In this case,
|
|
it creates an AF_UNIX socket file at the supplied path and uses that
|
|
for communication. This is an alternative way of running multiple
|
|
hledger-web instances behind a reverse proxy that handles authentica-
|
|
tion for different users. The path can be derived in a predictable
|
|
way, eg by using the username within the path. As an example, nginx as
|
|
reverse proxy can use the variabel $remote_user to derive a path from
|
|
the username used in a HTTP basic authentication. The following
|
|
proxy_pass directive allows access to all hledger-web instances that
|
|
created a socket in /tmp/hledger/:
|
|
|
|
proxy_pass http://unix:/tmp/hledger/${remote_user}.socket;
|
|
|
|
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.
|
|
|
|
PERMISSIONS
|
|
By default, hledger-web allows anyone who can reach it to view the
|
|
journal and to add new transactions, but not to change existing data.
|
|
|
|
You can restrict who can reach it by
|
|
|
|
o setting the IP address it listens on (see --host above). By default
|
|
it listens on 127.0.0.1, accessible to all users on the local ma-
|
|
chine.
|
|
|
|
o putting it behind an authenticating proxy, using eg apache or nginx
|
|
|
|
o custom firewall rules
|
|
|
|
You can restrict what the users who reach it can do, by
|
|
|
|
o using the --capabilities=CAP[,CAP..] flag when you start it, enabling
|
|
one or more of the following capabilities. The default value is
|
|
view,add:
|
|
|
|
o view - allows viewing the journal file and all included files
|
|
|
|
o add - allows adding new transactions to the main journal file
|
|
|
|
o manage - allows editing, uploading or downloading the main or in-
|
|
cluded files
|
|
|
|
o using the --capabilities-header=HTTPHEADER flag to specify a HTTP
|
|
header from which it will read capabilities to enable. hledger-web
|
|
on Sandstorm uses the X-Sandstorm-Permissions header to integrate
|
|
with Sandstorm's permissions. This is disabled by default.
|
|
|
|
EDITING, UPLOADING, DOWNLOADING
|
|
If you enable the manage capability mentioned above, you'll see a new
|
|
"spanner" button to the right of the search form. Clicking this will
|
|
let you edit, upload, or download the journal file or any files it in-
|
|
cludes.
|
|
|
|
Note, unlike any other hledger command, in this mode you (or any visi-
|
|
tor) can alter or wipe the data files.
|
|
|
|
Normally whenever a file is changed in this way, hledger-web saves a
|
|
numbered backup (assuming file permissions allow it, the disk is not
|
|
full, etc.) hledger-web is not aware of version control systems, cur-
|
|
rently; if you use one, you'll have to arrange to commit the changes
|
|
yourself (eg with a cron job or a file watcher like entr).
|
|
|
|
Changes which would leave the journal file(s) unparseable or non-valid
|
|
(eg with failing balance assertions) are prevented. (Probably. This
|
|
needs re-testing.)
|
|
|
|
RELOADING
|
|
hledger-web detects changes made to the files by other means (eg if you
|
|
edit it directly, outside of hledger-web), and it will show the new
|
|
data when you reload the page or navigate to a new page. If a change
|
|
makes a file unparseable, hledger-web will display an error message un-
|
|
til the file has been fixed.
|
|
|
|
(Note: if you are viewing files mounted from another machine, make sure
|
|
that both machine clocks are roughly in step.)
|
|
|
|
JSON API
|
|
In addition to the web UI, hledger-web provides some API routes that
|
|
serve JSON in response to GET requests. (And when started with
|
|
--serve-api, it provides only these routes.):
|
|
|
|
/accountnames
|
|
/transactions
|
|
/prices
|
|
/commodities
|
|
/accounts
|
|
/accounttransactions/#AccountName
|
|
|
|
Also, you can append a new transaction to the journal by sending a PUT
|
|
request to /add (hledger-web only). As with the web UI's add form,
|
|
hledger-web must be started with the add capability for this (enabled
|
|
by default).
|
|
|
|
The payload should be a valid hledger transaction as JSON, similar to
|
|
what you get from /transactions or /accounttransactions.
|
|
|
|
Another way to generate test data is with the readJsonFile/writeJson-
|
|
File helpers in Hledger.Web.Json, which read or write any of hledger's
|
|
JSON-capable types from or to a file. Eg here we write the first
|
|
transaction of a sample journal:
|
|
|
|
$ make ghci-web
|
|
>>> :m +*Hledger.Web.Json
|
|
>>> writeJsonFile "txn.json" (head $ jtxns samplejournal)
|
|
>>> :q
|
|
$ python -m json.tool <txn.json >txn.pretty.json # optional: make human-readable
|
|
|
|
(sample output & discussion)
|
|
|
|
And here's how to test adding that with curl:
|
|
|
|
$ curl -s http://127.0.0.1:5000/add -X PUT -H 'Content-Type: application/json' --data-binary @txn.pretty.json; echo
|
|
|
|
By default, both the server-side HTML UI and the JSON API are served.
|
|
Running with --serve-api disables the former, useful if you only want
|
|
to serve the API.
|
|
|
|
ENVIRONMENT
|
|
LEDGER_FILE The journal file path when not specified with -f. Default:
|
|
~/.hledger.journal (on windows, perhaps C:/Users/USER/.hledger.jour-
|
|
nal).
|
|
|
|
FILES
|
|
Reads data from one or more files in hledger journal, timeclock, time-
|
|
dot, 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 awk-
|
|
ward.
|
|
|
|
-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.
|
|
|
|
|
|
|
|
REPORTING BUGS
|
|
Report bugs at http://bugs.hledger.org (or on the #hledger IRC channel
|
|
or hledger mail list)
|
|
|
|
|
|
AUTHORS
|
|
Simon Michael <simon@joyful.com> and contributors
|
|
|
|
|
|
COPYRIGHT
|
|
Copyright (C) 2007-2019 Simon Michael.
|
|
Released under GNU GPL v3 or later.
|
|
|
|
|
|
SEE ALSO
|
|
hledger(1), hledger-ui(1), hledger-web(1), hledger-api(1),
|
|
hledger_csv(5), hledger_journal(5), hledger_timeclock(5), hledger_time-
|
|
dot(5), ledger(1)
|
|
|
|
http://hledger.org
|
|
|
|
|
|
|
|
hledger-web 1.16.99 January 2020 hledger-web(1)
|