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