130 lines
3.6 KiB
Groff
130 lines
3.6 KiB
Groff
|
|
.TH "hledger-api" "1" "March 2019" "hledger-api 1.14.99" "hledger User Manuals"
|
|
|
|
|
|
|
|
.SH NAME
|
|
.PP
|
|
hledger-api - web API server for the hledger accounting tool
|
|
.SH SYNOPSIS
|
|
.PP
|
|
\f[C]hledger-api [OPTIONS]\f[R]
|
|
.PD 0
|
|
.P
|
|
.PD
|
|
\f[C]hledger api -- [OPTIONS]\f[R]
|
|
.SH DESCRIPTION
|
|
.PP
|
|
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).
|
|
.PP
|
|
hledger-api is a simple web API server, intended to support client-side
|
|
web apps operating on hledger data.
|
|
It comes with a series of simple client-side app examples, which drive
|
|
its evolution.
|
|
.PP
|
|
Like hledger, it reads data from one or more files in hledger journal,
|
|
timeclock, timedot, or CSV format specified with \f[C]-f\f[R], or
|
|
\f[C]$LEDGER_FILE\f[R], or \f[C]$HOME/.hledger.journal\f[R] (on windows,
|
|
perhaps \f[C]C:/Users/USER/.hledger.journal\f[R]).
|
|
For more about this see hledger(1), hledger_journal(5) etc.
|
|
.PP
|
|
The server listens on IP address 127.0.0.1, accessible only to local
|
|
requests, by default.
|
|
You can change this with \f[C]--host\f[R], eg \f[C]--host 0.0.0.0\f[R]
|
|
to listen on all addresses.
|
|
Note there is no other access control, and hledger-api allows file
|
|
browsing, so on shared machines you will certainly need to put it behind
|
|
an authenticating proxy to restrict access.
|
|
.PP
|
|
You can change the TCP port it listens on (default: 8001) with
|
|
\f[C]-p PORT\f[R].
|
|
.PP
|
|
API methods look like:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
/api/v1/accountnames
|
|
/api/v1/transactions
|
|
/api/v1/prices
|
|
/api/v1/commodities
|
|
/api/v1/accounts
|
|
/api/v1/accounts/ACCTNAME
|
|
\f[R]
|
|
.fi
|
|
.PP
|
|
See \f[C]/api/swagger.json\f[R] for a full list in Swagger 2.0 format.
|
|
(Or you can run \f[C]hledger-api --swagger\f[R] to print this in the
|
|
console.)
|
|
.PP
|
|
hledger-api also serves files, from the current directory by default,
|
|
and the \f[C]/\f[R] path will also show a directory listing.
|
|
This is convenient for serving client-side web code, in addition to the
|
|
server-side api.
|
|
.SH OPTIONS
|
|
.PP
|
|
Note: if invoking hledger-api as a hledger subcommand, write
|
|
\f[C]--\f[R] before options as shown above.
|
|
.TP
|
|
.B \f[C]-f --file=FILE\f[R]
|
|
use a different input file.
|
|
For stdin, use - (default: \f[C]$LEDGER_FILE\f[R] or
|
|
\f[C]$HOME/.hledger.journal\f[R])
|
|
.TP
|
|
.B \f[C]-d --static-dir=DIR\f[R]
|
|
serve files from a different directory (default: \f[C].\f[R])
|
|
.TP
|
|
.B \f[C]--host=IPADDR\f[R]
|
|
listen on this IP address (default: 127.0.0.1)
|
|
.TP
|
|
.B \f[C]-p --port=PORT\f[R]
|
|
listen on this TCP port (default: 8001)
|
|
.TP
|
|
.B \f[C]--swagger\f[R]
|
|
print API docs in Swagger 2.0 format, and exit
|
|
.TP
|
|
.B \f[C]--version\f[R]
|
|
show version
|
|
.TP
|
|
.B \f[C]-h --help\f[R]
|
|
show usage
|
|
.SH ENVIRONMENT
|
|
.PP
|
|
\f[B]LEDGER_FILE\f[R] The journal file path when not specified with
|
|
\f[C]-f\f[R].
|
|
Default: \f[C]\[ti]/.hledger.journal\f[R] (on windows, perhaps
|
|
\f[C]C:/Users/USER/.hledger.journal\f[R]).
|
|
.SH FILES
|
|
.PP
|
|
Reads data from one or more files in hledger journal, timeclock,
|
|
timedot, or CSV format specified with \f[C]-f\f[R], or
|
|
\f[C]$LEDGER_FILE\f[R], or \f[C]$HOME/.hledger.journal\f[R] (on windows,
|
|
perhaps \f[C]C:/Users/USER/.hledger.journal\f[R]).
|
|
.SH BUGS
|
|
.PP
|
|
The need to precede options with \f[C]--\f[R] when invoked from hledger
|
|
is awkward.
|
|
|
|
|
|
.SH "REPORTING BUGS"
|
|
Report bugs at http://bugs.hledger.org
|
|
(or on the #hledger IRC channel or hledger mail list)
|
|
|
|
.SH AUTHORS
|
|
Simon Michael <simon@joyful.com> and contributors
|
|
|
|
.SH COPYRIGHT
|
|
|
|
Copyright (C) 2007-2016 Simon Michael.
|
|
.br
|
|
Released under GNU GPL v3 or later.
|
|
|
|
.SH SEE ALSO
|
|
hledger(1), hledger\-ui(1), hledger\-web(1), hledger\-api(1),
|
|
hledger_csv(5), hledger_journal(5), hledger_timeclock(5), hledger_timedot(5),
|
|
ledger(1)
|
|
|
|
http://hledger.org
|