
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  --serve,  it  starts  the  web app in non-transient mode and logs
       requests to the console.

       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.

       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.

       Note there is no built-in  access  control  (aside  from  listening  on
       127.0.0.1  by default).  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.

       --serve
              serve and log requests, don't browse or auto-exit

       --host=IPADDR
              listen on this IP address (default: 127.0.0.1)

       --port=PORT
              listen on this TCP port (default: 5000)

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

       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
              convert  amounts  to  their  cost at transaction time (using the
              transaction price, if any)

       --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
              transaction.  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 dev                  January 2017                   hledger-web(1)
