simonmichael/hledger
1
1
Fork 0
mirror of https://github.com/simonmichael/hledger.git synced 2024-11-10 14:16:41 +03:00
Code Issues Projects Releases Wiki Activity
090f65ec83
hledger/hledger-web/hledger-web.txt
Simon Michael 090f65ec83 ;doc: regen manuals 
[ci skip]
2020-01-20 18:02:42 -08:00

380 lines
15 KiB
Plaintext
Raw Blame History

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)
Reference in New Issue View Git Blame Copy Permalink