1This is hledger-web.info, produced by makeinfo version 6.7 from stdin.
2
3
4File: hledger-web.info,  Node: Top,  Next: OPTIONS,  Up: (dir)
5
6hledger-web(1) hledger-web 1.18.99
7**********************************
8
9hledger-web - web interface for the hledger accounting tool
10
11   'hledger-web [OPTIONS]'
12'hledger web -- [OPTIONS]'
13
14   hledger is a reliable, cross-platform set of programs for tracking
15money, time, or any other commodity, using double-entry accounting and a
16simple, editable file format.  hledger is inspired by and largely
17compatible with ledger(1).
18
19   hledger-web is hledger's web interface.  It starts a simple web
20application for browsing and adding transactions, and optionally opens
21it in a web browser window if possible.  It provides a more
22user-friendly UI than the hledger CLI or hledger-ui interface, showing
23more at once (accounts, the current account register, balance charts)
24and allowing history-aware data entry, interactive searching, and
25bookmarking.
26
27   hledger-web also lets you share a ledger with multiple users, or even
28the public web.  There is no access control, so if you need that you
29should put it behind a suitable web proxy.  As a small protection
30against data loss when running an unprotected instance, it writes a
31numbered backup of the main journal file (only ?)  on every edit.
32
33   Like hledger, it reads data from one or more files in hledger
34journal, timeclock, timedot, or CSV format specified with '-f', or
35'$LEDGER_FILE', or '$HOME/.hledger.journal' (on windows, perhaps
36'C:/Users/USER/.hledger.journal').  For more about this see hledger(1),
37hledger_journal(5) etc.
38
39* Menu:
40
41* OPTIONS::
42* PERMISSIONS::
43* EDITING UPLOADING DOWNLOADING::
44* RELOADING::
45* JSON API::
46* ENVIRONMENT::
47* FILES::
48* BUGS::
49
50
51File: hledger-web.info,  Node: OPTIONS,  Next: PERMISSIONS,  Prev: Top,  Up: Top
52
531 OPTIONS
54*********
55
56Command-line options and arguments may be used to set an initial filter
57on the data.  These filter options are not shown in the web UI, but it
58will be applied in addition to any search query entered there.
59
60   Note: if invoking hledger-web as a hledger subcommand, write '--'
61before options, as shown in the synopsis above.
62
63'--serve'
64
65     serve and log requests, don't browse or auto-exit
66'--serve-api'
67
68     like -serve, but serve only the JSON web API, without the
69     server-side web UI
70'--host=IPADDR'
71
72     listen on this IP address (default: 127.0.0.1)
73'--port=PORT'
74
75     listen on this TCP port (default: 5000)
76'--socket=SOCKETFILE'
77
78     use a unix domain socket file to listen for requests instead of a
79     TCP socket.  Implies '--serve'.  It can only be used if the
80     operating system can provide this type of socket.
81'--base-url=URL'
82
83     set the base url (default: http://IPADDR:PORT). You would change
84     this when sharing over the network, or integrating within a larger
85     website.
86'--file-url=URL'
87
88     set the static files url (default: BASEURL/static).  hledger-web
89     normally serves static files itself, but if you wanted to serve
90     them from another server for efficiency, you would set the url with
91     this.
92'--capabilities=CAP[,CAP..]'
93
94     enable the view, add, and/or manage capabilities (default:
95     view,add)
96'--capabilities-header=HTTPHEADER'
97
98     read capabilities to enable from a HTTP header, like
99     X-Sandstorm-Permissions (default: disabled)
100
101   hledger input options:
102
103'-f FILE --file=FILE'
104
105     use a different input file.  For stdin, use - (default:
106     '$LEDGER_FILE' or '$HOME/.hledger.journal')
107'--rules-file=RULESFILE'
108
109     Conversion rules file to use when reading CSV (default: FILE.rules)
110'--separator=CHAR'
111
112     Field separator to expect when reading CSV (default: ',')
113'--alias=OLD=NEW'
114
115     rename accounts named OLD to NEW
116'--anon'
117
118     anonymize accounts and payees
119'--pivot FIELDNAME'
120
121     use some other field or tag for the account name
122'-I --ignore-assertions'
123
124     disable balance assertion checks (note: does not disable balance
125     assignments)
126
127   hledger reporting options:
128
129'-b --begin=DATE'
130
131     include postings/txns on or after this date
132'-e --end=DATE'
133
134     include postings/txns before this date
135'-D --daily'
136
137     multiperiod/multicolumn report by day
138'-W --weekly'
139
140     multiperiod/multicolumn report by week
141'-M --monthly'
142
143     multiperiod/multicolumn report by month
144'-Q --quarterly'
145
146     multiperiod/multicolumn report by quarter
147'-Y --yearly'
148
149     multiperiod/multicolumn report by year
150'-p --period=PERIODEXP'
151
152     set start date, end date, and/or reporting interval all at once
153     using period expressions syntax
154'--date2'
155
156     match the secondary date instead (see command help for other
157     effects)
158'-U --unmarked'
159
160     include only unmarked postings/txns (can combine with -P or -C)
161'-P --pending'
162
163     include only pending postings/txns
164'-C --cleared'
165
166     include only cleared postings/txns
167'-R --real'
168
169     include only non-virtual postings
170'-NUM --depth=NUM'
171
172     hide/aggregate accounts or postings more than NUM levels deep
173'-E --empty'
174
175     show items with zero amount, normally hidden (and vice-versa in
176     hledger-ui/hledger-web)
177'-B --cost'
178
179     convert amounts to their cost/selling amount at transaction time
180'-V --market'
181
182     convert amounts to their market value in default valuation
183     commodities
184'-X --exchange=COMM'
185
186     convert amounts to their market value in commodity COMM
187'--value'
188
189     convert amounts to cost or market value, more flexibly than
190     -B/-V/-X
191'--infer-value'
192
193     with -V/-X/-value, also infer market prices from transactions
194'--auto'
195
196     apply automated posting rules to modify transactions.
197'--forecast'
198
199     generate future transactions from periodic transaction rules, for
200     the next 6 months or till report end date.  In hledger-ui, also
201     make ordinary future transactions visible.
202'--color=WHEN (or --colour=WHEN)'
203
204     Should color-supporting commands use ANSI color codes in text
205     output.  'auto' (default): whenever stdout seems to be a
206     color-supporting terminal.  'always' or 'yes': always, useful eg
207     when piping output into 'less -R'. 'never' or 'no': never.  A
208     NO_COLOR environment variable overrides this.
209
210   When a reporting option appears more than once in the command line,
211the last one takes precedence.
212
213   Some reporting options can also be written as query arguments.
214
215   hledger help options:
216
217'-h --help'
218
219     show general usage (or after COMMAND, command usage)
220'--version'
221
222     show version
223'--debug[=N]'
224
225     show debug output (levels 1-9, default: 1)
226
227   A @FILE argument will be expanded to the contents of FILE, which
228should contain one command line option/argument per line.  (To prevent
229this, insert a '--' argument before.)
230
231   By default, hledger-web starts the web app in "transient mode" and
232also opens it in your default web browser if possible.  In this mode the
233web app will keep running for as long as you have it open in a browser
234window, and will exit after two minutes of inactivity (no requests and
235no browser windows viewing it).  With '--serve', it just runs the web
236app without exiting, and logs requests to the console.  With
237'--serve-api', only the JSON web api (see below) is served, with the
238usual HTML server-side web UI disabled.
239
240   By default the server listens on IP address 127.0.0.1, accessible
241only to local requests.  You can use '--host' to change this, eg '--host
2420.0.0.0' to listen on all configured addresses.
243
244   Similarly, use '--port' to set a TCP port other than 5000, eg if you
245are running multiple hledger-web instances.
246
247   Both of these options are ignored when '--socket' is used.  In this
248case, it creates an 'AF_UNIX' socket file at the supplied path and uses
249that for communication.  This is an alternative way of running multiple
250hledger-web instances behind a reverse proxy that handles authentication
251for different users.  The path can be derived in a predictable way, eg
252by using the username within the path.  As an example, 'nginx' as
253reverse proxy can use the variable '$remote_user' to derive a path from
254the username used in a HTTP basic authentication.  The following
255'proxy_pass' directive allows access to all 'hledger-web' instances that
256created a socket in '/tmp/hledger/':
257
258  proxy_pass http://unix:/tmp/hledger/${remote_user}.socket;
259
260   You can use '--base-url' to change the protocol, hostname, port and
261path that appear in hyperlinks, useful eg for integrating hledger-web
262within a larger website.  The default is 'http://HOST:PORT/' using the
263server's configured host address and TCP port (or 'http://HOST' if PORT
264is 80).
265
266   With '--file-url' you can set a different base url for static files,
267eg for better caching or cookie-less serving on high performance
268websites.
269
270
271File: hledger-web.info,  Node: PERMISSIONS,  Next: EDITING UPLOADING DOWNLOADING,  Prev: OPTIONS,  Up: Top
272
2732 PERMISSIONS
274*************
275
276By default, hledger-web allows anyone who can reach it to view the
277journal and to add new transactions, but not to change existing data.
278
279   You can restrict who can reach it by
280
281   * setting the IP address it listens on (see '--host' above).  By
282     default it listens on 127.0.0.1, accessible to all users on the
283     local machine.
284   * putting it behind an authenticating proxy, using eg apache or nginx
285   * custom firewall rules
286
287   You can restrict what the users who reach it can do, by
288
289   * using the '--capabilities=CAP[,CAP..]' flag when you start it,
290     enabling one or more of the following capabilities.  The default
291     value is 'view,add':
292        * 'view' - allows viewing the journal file and all included
293          files
294        * 'add' - allows adding new transactions to the main journal
295          file
296        * 'manage' - allows editing, uploading or downloading the main
297          or included files
298
299   * using the '--capabilities-header=HTTPHEADER' flag to specify a HTTP
300     header from which it will read capabilities to enable.  hledger-web
301     on Sandstorm uses the X-Sandstorm-Permissions header to integrate
302     with Sandstorm's permissions.  This is disabled by default.
303
304
305File: hledger-web.info,  Node: EDITING UPLOADING DOWNLOADING,  Next: RELOADING,  Prev: PERMISSIONS,  Up: Top
306
3073 EDITING, UPLOADING, DOWNLOADING
308*********************************
309
310If you enable the 'manage' capability mentioned above, you'll see a new
311"spanner" button to the right of the search form.  Clicking this will
312let you edit, upload, or download the journal file or any files it
313includes.
314
315   Note, unlike any other hledger command, in this mode you (or any
316visitor) can alter or wipe the data files.
317
318   Normally whenever a file is changed in this way, hledger-web saves a
319numbered backup (assuming file permissions allow it, the disk is not
320full, etc.)  hledger-web is not aware of version control systems,
321currently; if you use one, you'll have to arrange to commit the changes
322yourself (eg with a cron job or a file watcher like entr).
323
324   Changes which would leave the journal file(s) unparseable or
325non-valid (eg with failing balance assertions) are prevented.
326(Probably.  This needs re-testing.)
327
328
329File: hledger-web.info,  Node: RELOADING,  Next: JSON API,  Prev: EDITING UPLOADING DOWNLOADING,  Up: Top
330
3314 RELOADING
332***********
333
334hledger-web detects changes made to the files by other means (eg if you
335edit it directly, outside of hledger-web), and it will show the new data
336when you reload the page or navigate to a new page.  If a change makes a
337file unparseable, hledger-web will display an error message until the
338file has been fixed.
339
340   (Note: if you are viewing files mounted from another machine, make
341sure that both machine clocks are roughly in step.)
342
343
344File: hledger-web.info,  Node: JSON API,  Next: ENVIRONMENT,  Prev: RELOADING,  Up: Top
345
3465 JSON API
347**********
348
349In addition to the web UI, hledger-web also serves a JSON API that can
350be used to get data or add new transactions.  If you want the JSON API
351only, you can use the '--serve-api' flag.  Eg:
352
353$ hledger-web -f examples/sample.journal --serve-api
354...
355
356   You can get JSON data from these routes:
357
358/accountnames
359/transactions
360/prices
361/commodities
362/accounts
363/accounttransactions/ACCOUNTNAME
364
365   Eg, all account names in the journal (similar to the accounts
366command).  (hledger-web's JSON does not include newlines, here we use
367python to prettify it):
368
369$ curl -s http://127.0.0.1:5000/accountnames | python -m json.tool
370[
371    "assets",
372    "assets:bank",
373    "assets:bank:checking",
374    "assets:bank:saving",
375    "assets:cash",
376    "expenses",
377    "expenses:food",
378    "expenses:supplies",
379    "income",
380    "income:gifts",
381    "income:salary",
382    "liabilities",
383    "liabilities:debts"
384]
385
386   Or all transactions:
387
388$ curl -s http://127.0.0.1:5000/transactions | python -m json.tool
389[
390    {
391        "tcode": "",
392        "tcomment": "",
393        "tdate": "2008-01-01",
394        "tdate2": null,
395        "tdescription": "income",
396        "tindex": 1,
397        "tpostings": [
398            {
399                "paccount": "assets:bank:checking",
400                "pamount": [
401                    {
402                        "acommodity": "$",
403                        "aismultiplier": false,
404                        "aprice": null,
405...
406
407   Most of the JSON corresponds to hledger's data types; for details of
408what the fields mean, see the Hledger.Data.Json haddock docs and click
409on the various data types, eg Transaction.  And for a higher level
410understanding, see the journal manual.
411
412   In some cases there is outer JSON corresponding to a "Report" type.
413To understand that, go to the Hledger.Web.Handler.MiscR haddock and look
414at the source for the appropriate handler to see what it returns.  Eg
415for '/accounttransactions' it's getAccounttransactionsR, returning a
416"'accountTransactionsReport ...'".  Looking up the haddock for that we
417can see that /accounttransactions returns an AccountTransactionsReport,
418which consists of a report title and a list of
419AccountTransactionsReportItem (etc).
420
421   You can add a new transaction to the journal with a PUT request to
422'/add', if hledger-web was started with the 'add' capability (enabled by
423default).  The payload must be the full, exact JSON representation of a
424hledger transaction (partial data won't do).  You can get sample JSON
425from hledger-web's '/transactions' or '/accounttransactions', or you can
426export it with hledger-lib, eg like so:
427
428.../hledger$ stack ghci hledger-lib
429>>> writeJsonFile "txn.json" (head $ jtxns samplejournal)
430>>> :q
431
432   Here's how it looks as of hledger-1.17 (remember, this JSON
433corresponds to hledger's Transaction and related data types):
434
435{
436    "tcomment": "",
437    "tpostings": [
438        {
439            "pbalanceassertion": null,
440            "pstatus": "Unmarked",
441            "pamount": [
442                {
443                    "aprice": null,
444                    "acommodity": "$",
445                    "aquantity": {
446                        "floatingPoint": 1,
447                        "decimalPlaces": 10,
448                        "decimalMantissa": 10000000000
449                    },
450                    "aismultiplier": false,
451                    "astyle": {
452                        "ascommodityside": "L",
453                        "asdigitgroups": null,
454                        "ascommodityspaced": false,
455                        "asprecision": 2,
456                        "asdecimalpoint": "."
457                    }
458                }
459            ],
460            "ptransaction_": "1",
461            "paccount": "assets:bank:checking",
462            "pdate": null,
463            "ptype": "RegularPosting",
464            "pcomment": "",
465            "pdate2": null,
466            "ptags": [],
467            "poriginal": null
468        },
469        {
470            "pbalanceassertion": null,
471            "pstatus": "Unmarked",
472            "pamount": [
473                {
474                    "aprice": null,
475                    "acommodity": "$",
476                    "aquantity": {
477                        "floatingPoint": -1,
478                        "decimalPlaces": 10,
479                        "decimalMantissa": -10000000000
480                    },
481                    "aismultiplier": false,
482                    "astyle": {
483                        "ascommodityside": "L",
484                        "asdigitgroups": null,
485                        "ascommodityspaced": false,
486                        "asprecision": 2,
487                        "asdecimalpoint": "."
488                    }
489                }
490            ],
491            "ptransaction_": "1",
492            "paccount": "income:salary",
493            "pdate": null,
494            "ptype": "RegularPosting",
495            "pcomment": "",
496            "pdate2": null,
497            "ptags": [],
498            "poriginal": null
499        }
500    ],
501    "ttags": [],
502    "tsourcepos": {
503        "tag": "JournalSourcePos",
504        "contents": [
505            "",
506            [
507                1,
508                1
509            ]
510        ]
511    },
512    "tdate": "2008-01-01",
513    "tcode": "",
514    "tindex": 1,
515    "tprecedingcomment": "",
516    "tdate2": null,
517    "tdescription": "income",
518    "tstatus": "Unmarked"
519}
520
521   And here's how to test adding it with curl.  This should add a new
522entry to your journal:
523
524$ curl http://127.0.0.1:5000/add -X PUT -H 'Content-Type: application/json' --data-binary @txn.json
525
526
527File: hledger-web.info,  Node: ENVIRONMENT,  Next: FILES,  Prev: JSON API,  Up: Top
528
5296 ENVIRONMENT
530*************
531
532*LEDGER_FILE* The journal file path when not specified with '-f'.
533Default: '~/.hledger.journal' (on windows, perhaps
534'C:/Users/USER/.hledger.journal').
535
536   A typical value is '~/DIR/YYYY.journal', where DIR is a
537version-controlled finance directory and YYYY is the current year.  Or
538'~/DIR/current.journal', where current.journal is a symbolic link to
539YYYY.journal.
540
541   On Mac computers, you can set this and other environment variables in
542a more thorough way that also affects applications started from the GUI
543(say, an Emacs dock icon).  Eg on MacOS Catalina I have a
544'~/.MacOSX/environment.plist' file containing
545
546{
547  "LEDGER_FILE" : "~/finance/current.journal"
548}
549
550   To see the effect you may need to 'killall Dock', or reboot.
551
552
553File: hledger-web.info,  Node: FILES,  Next: BUGS,  Prev: ENVIRONMENT,  Up: Top
554
5557 FILES
556*******
557
558Reads data from one or more files in hledger journal, timeclock,
559timedot, or CSV format specified with '-f', or '$LEDGER_FILE', or
560'$HOME/.hledger.journal' (on windows, perhaps
561'C:/Users/USER/.hledger.journal').
562
563
564File: hledger-web.info,  Node: BUGS,  Prev: FILES,  Up: Top
565
5668 BUGS
567******
568
569The need to precede options with '--' when invoked from hledger is
570awkward.
571
572   '-f-' doesn't work (hledger-web can't read from stdin).
573
574   Query arguments and some hledger options are ignored.
575
576   Does not work in text-mode browsers.
577
578   Does not work well on small screens.
579
580
581Tag Table:
582Node: Top72
583Node: OPTIONS1752
584Ref: #options1857
585Node: PERMISSIONS8737
586Ref: #permissions8876
587Node: EDITING UPLOADING DOWNLOADING10088
588Ref: #editing-uploading-downloading10269
589Node: RELOADING11103
590Ref: #reloading11237
591Node: JSON API11670
592Ref: #json-api11784
593Node: ENVIRONMENT17265
594Ref: #environment17381
595Node: FILES18114
596Ref: #files18214
597Node: BUGS18427
598Ref: #bugs18505
599
600End Tag Table
601
602
603Local Variables:
604coding: utf-8
605End:
606