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

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

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

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

       --base-url=URL
              set  the  base  url (default: http://localhost: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.

       hledger general options:

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

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

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

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

       --version
              show version

       --debug[=N]
              show debug output (levels 1-9, default: 1)

       -f FILE --file=FILE
              use a different input file.  For stdin, use -

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

       --alias=OLD=NEW
              display accounts named OLD as NEW

       -I --ignore-assertions
              ignore any failing balance assertions in the journal

       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
              (overrides the flags above)

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

       -C --cleared
              include only cleared postings/txns

       --pending
              include only pending postings/txns

       -U --uncleared
              include only uncleared (and pending) postings/txns

       -R --real
              include only non-virtual postings

       --depth=N
              hide accounts/postings deeper than N

       -E --empty
              show items with zero amount, normally hidden

       -B --cost
              show amounts in their cost price's commodity

       --pivot TAG
              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".

       --anon show anonymized accounts and payees

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-2016 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.0                  October 2016                   hledger-web(1)
