hledger/hledger-web/doc/hledger-web.1.txt

hledger-web(1)               hledger User Manuals               hledger-web(1)



NNAAMMEE
       hledger-web - web interface for the hledger accounting tool

SSYYNNOOPPSSIISS
       hledger-web [OPTIONS]
       hledger web -- [OPTIONS]



DDEESSCCRRIIPPTTIIOONN
       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
       (accounts, the current account register, balance charts)  and  allowing
       history-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.

       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).

              $ hledger web
              Starting web app on port 5000 with base url http://localhost:5000
              Starting web browser if possible
              Web app will auto-exit after a few minutes with no browsers (or press ctrl-c)

       With  --server,  it  starts  the web app in non-transient mode and logs
       requests to the console.  Typically when running hledger web as part of
       a  website  you'll  want  to  use  --base-url to set the protocol/host-
       name/port/path to be used in hyperlinks.  The --file-url option  allows
       static  files  to be served from a different url, eg for better caching
       or cookie-less serving.

       You can use --port to listen on a different TCP port,  eg  if  you  are
       running  multiple  hledger-web instances.  This need not be the same as
       the PORT in the base url.

       Note there is no built-in access control, 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.

       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.

       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.

OOPPTTIIOONNSS
       Note:  if invoking hledger-web as a hledger subcommand, write -- before
       options as shown above.

       ----sseerrvveerr
              disable  browser-opening  and  auto-exit-on-idle,  and  log  all
              requests to stdout

       ----ppoorrtt==PPOORRTT
              set the TCP port to listen on (default: 5000)

       ----bbaassee--uurrll==UURRLL
              set  the  base  url (default: http://localhost:PORT).  You would
              change this when sharing over the network, or integrating within
              a larger website.

       ----ffiillee--uurrll==UURRLL
              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.

       hledger general options:

       --hh     show general usage (or after COMMAND, the command's usage)

       ----hheellpp show the current program's manual as plain  text  (or  after  an
              add-on COMMAND, the add-on's manual)

       ----mmaann  show the current program's manual with man

       ----iinnffoo show the current program's manual with info

       ----vveerrssiioonn
              show version

       ----ddeebbuugg==NN
              show debug output if N is 1-9 (default: 0)

       --ff FFIILLEE ----ffiillee==FFIILLEE
              use a different input file.  For stdin, use -

       ----rruulleess--ffiillee==RRUULLEESSFFIILLEE
              Conversion   rules  file  to  use  when  reading  CSV  (default:
              FILE.rules)

       ----aalliiaass==OOLLDD==NNEEWW
              display accounts named OLD as NEW

       ----iiggnnoorree--aasssseerrttiioonnss
              ignore any failing balance assertions in the journal

       hledger reporting options:

       --bb ----bbeeggiinn==DDAATTEE
              include postings/txns on or after this date

       --ee ----eenndd==DDAATTEE
              include postings/txns before this date

       --DD ----ddaaiillyy
              multiperiod/multicolumn report by day

       --WW ----wweeeekkllyy
              multiperiod/multicolumn report by week

       --MM ----mmoonntthhllyy
              multiperiod/multicolumn report by month

       --QQ ----qquuaarrtteerrllyy
              multiperiod/multicolumn report by quarter

       --YY ----yyeeaarrllyy
              multiperiod/multicolumn report by year

       --pp ----ppeerriioodd==PPEERRIIOODDEEXXPP
              set start date, end date, and/or reporting interval all at  once
              (overrides the flags above)

       ----ddaattee22
              show, and match with -b/-e/-p/date:, secondary dates instead

       --CC ----cclleeaarreedd
              include only cleared postings/txns

       ----ppeennddiinngg
              include only pending postings/txns

       --UU ----uunncclleeaarreedd
              include only uncleared (and pending) postings/txns

       --RR ----rreeaall
              include only non-virtual postings

       ----ddeepptthh==NN
              hide accounts/postings deeper than N

       --EE ----eemmppttyy
              show items with zero amount, normally hidden

       --BB ----ccoosstt
              show amounts in their cost price's commodity

       ----ppiivvoott TTAAGG
              will  transform  the  journal  before  any  other  processing by
              replacing the account name of every posting having the  tag  TAG
              with content VALUE by the account name "TAG:VALUE".
       The  TAG  will only match if it is a full-length match.  The pivot will
       only happen if the TAG is on a posting, not if it is  on  the  transac-
       tion.   If  the tag value is a multi:level:account:name the new account
       name will be "TAG:multi:level:account:name".

EENNVVIIRROONNMMEENNTT
       LLEEDDGGEERR__FFIILLEE The journal file path when not specified with -f.  Default:
       ~/.hledger.journal  (on  windows,  perhaps C:/Users/USER/.hledger.jour-
       nal).

FFIILLEESS
       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).

BBUUGGSS
       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.



RREEPPOORRTTIINNGG BBUUGGSS
       Report bugs at http://bugs.hledger.org (or on the #hledger IRC  channel
       or hledger mail list)


AAUUTTHHOORRSS
       Simon Michael <simon@joyful.com> and contributors


CCOOPPYYRRIIGGHHTT
       Copyright (C) 2007-2016 Simon Michael.
       Released under GNU GPL v3 or later.


SSEEEE AALLSSOO
       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 0.28                   May 2016                     hledger-web(1)