mirror of
https://github.com/simonmichael/hledger.git
synced 2024-11-07 21:15:19 +03:00
;doc: cli, ui, web: synopsis, options cleanup/consistency
This commit is contained in:
Simon Michael
parent
7f583a8414
commit
88f70eba6b
@ -13,6 +13,7 @@ _notinfo_({{
|
||||
}})
|
||||
|
||||
`hledger-ui [OPTS] [QUERYARGS]`\
|
||||
or\
|
||||
`hledger ui -- [OPTS] [QUERYARGS]`
|
||||
|
||||
_notinfo_({{
|
||||
@ -50,50 +51,32 @@ by pressing the F key (or starting with --forecast) to enable "forecast mode".
|
||||
|
||||
# OPTIONS
|
||||
|
||||
Any QUERYARGS are interpreted as a hledger search query which filters the data.
|
||||
|
||||
Any arguments are interpreted as a hledger [query](hledger.md#queries) which filters the data.
|
||||
hledger-ui provides the following options:
|
||||
|
||||
`-w --watch`
|
||||
: watch for data and date changes and reload automatically
|
||||
```
|
||||
Flags:
|
||||
-w --watch watch for data and date changes and reload
|
||||
automatically
|
||||
--theme=THEME use this custom display theme (default,
|
||||
greenterm, terminal, dark)
|
||||
--cash start in the cash accounts screen
|
||||
--bs start in the balance sheet accounts screen
|
||||
--is start in the income statement accounts screen
|
||||
--all start in the all accounts screen
|
||||
--register=ACCTREGEX start in the (first matched) account's register
|
||||
--change show period balances (changes) at startup instead
|
||||
of historical balances
|
||||
-l --flat show accounts as a flat list (default)
|
||||
-t --tree show accounts as a tree
|
||||
```
|
||||
|
||||
`--theme=default|terminal|greenterm|dark`
|
||||
: use this custom display theme
|
||||
|
||||
`--menu`
|
||||
: start in the menu screen
|
||||
|
||||
`--cash`
|
||||
: start in the cash accounts screen
|
||||
|
||||
`--bs`
|
||||
: start in the balance sheet accounts screen
|
||||
|
||||
`--is`
|
||||
: start in the income statement accounts screen
|
||||
|
||||
`--all`
|
||||
: start in the all accounts screen
|
||||
|
||||
`--register=ACCTREGEX`
|
||||
: start in the (first) matched account's register screen
|
||||
|
||||
`--change`
|
||||
: show period balances (changes) at startup instead of historical balances
|
||||
|
||||
`-l --flat`
|
||||
: show accounts as a flat list (default)
|
||||
|
||||
`-t --tree`
|
||||
: show accounts as a tree
|
||||
|
||||
hledger-ui also supports many of hledger's general options
|
||||
(and the hledger manual's command line tips also apply here):
|
||||
|
||||
## General options
|
||||
and also supports many of hledger's [general options](hledger.md#options):
|
||||
|
||||
_generaloptions_
|
||||
|
||||
With hledger-ui, the `--debug` option sends debug output to a `hledger-ui.log` file in the current directory.
|
||||
|
||||
# MOUSE
|
||||
|
||||
In most modern terminals, you can navigate through the screens with a
|
||||
@ -321,9 +304,7 @@ press g again to reload and resume normal operation.
|
||||
(Or, you can press escape to cancel the reload attempt.)
|
||||
|
||||
|
||||
# TIPS
|
||||
|
||||
## Watch mode
|
||||
# WATCH MODE
|
||||
|
||||
One of hledger-ui's best features is the auto-reloading `-w/--watch` mode.
|
||||
With this flag, it will update the display automatically whenever changes
|
||||
@ -362,12 +343,6 @@ or try [#1617](https://github.com/simonmichael/hledger/issues/1617)'s `fs.inotif
|
||||
If you are viewing files mounted from another machine, the system
|
||||
clocks on both machines should be roughly in agreement.
|
||||
|
||||
## Debug output
|
||||
|
||||
You can add `--debug[=N]` to the command line to log debug output.
|
||||
This will be logged to the file `hledger-ui.log` in the current directory.
|
||||
N ranges from 1 (least output, the default) to 9 (maximum output).
|
||||
|
||||
# ENVIRONMENT
|
||||
|
||||
**COLUMNS**
|
||||
|
||||
@ -12,8 +12,9 @@ _notinfo_({{
|
||||
# SYNOPSIS
|
||||
}})
|
||||
|
||||
`hledger-web [--serve|--serve-api] [OPTS] [ARGS]`\
|
||||
`hledger web -- [--serve|--serve-api] [OPTS] [ARGS]`
|
||||
`hledger-web [OPTS] [QUERY]`\
|
||||
or\
|
||||
`hledger web -- [OPTS] [QUERY]`
|
||||
|
||||
_notinfo_({{
|
||||
# DESCRIPTION
|
||||
@ -64,47 +65,42 @@ In all cases hledger-web runs as a foreground process, logging requests to stdou
|
||||
|
||||
hledger-web provides the following options:
|
||||
|
||||
`--serve`
|
||||
: serve and log requests, don't browse or auto-exit after timeout
|
||||
```
|
||||
Flags:
|
||||
--serve --server serve and log requests, don't browse or auto-exit
|
||||
--serve-api like --serve, but serve only the JSON web API,
|
||||
not the web UI
|
||||
--allow=view|add|edit set the user's access level for changing data
|
||||
(default: `add`). It also accepts `sandstorm` for
|
||||
use on that platform (reads permissions from the
|
||||
`X-Sandstorm-Permissions` request header).
|
||||
--cors=ORIGIN allow cross-origin requests from the specified
|
||||
origin; setting ORIGIN to "*" allows requests from
|
||||
any origin
|
||||
--host=IPADDR listen on this IP address (default: 127.0.0.1)
|
||||
--port=PORT listen on this TCP port (default: 5000)
|
||||
--socket=SOCKET listen on the given unix socket instead of an IP
|
||||
address and port (unix only; implies --serve)
|
||||
--base-url=BASEURL set the base url (default: http://IPADDR:PORT)
|
||||
--test run hledger-web's tests and exit. hspec test
|
||||
runner args may follow a --, eg: hledger-web --test
|
||||
-- --help
|
||||
```
|
||||
|
||||
`--serve-api`
|
||||
: like --serve, but serve only the JSON web API, not the web UI
|
||||
By default hledger-web listens only on IP address `127.0.0.1`,
|
||||
which be accessed only from the local machine.
|
||||
|
||||
`--allow=view|add|edit`
|
||||
: set the user's access level for changing data (default: `add`).
|
||||
It also accepts `sandstorm` for use on that platform
|
||||
(reads permissions from the `X-Sandstorm-Permissions` request header).
|
||||
|
||||
`--cors=ORIGIN`
|
||||
: allow cross-origin requests from the specified origin;
|
||||
setting ORIGIN to "*" allows requests from any origin
|
||||
|
||||
`--host=IPADDR`
|
||||
: listen on this IP address (default: 127.0.0.1)
|
||||
|
||||
By default the server listens on IP address `127.0.0.1`,
|
||||
which is accessible only to requests from the local machine..
|
||||
You can use `--host` to listen on a different address configured on the machine,
|
||||
eg to allow access from other machines.
|
||||
The special address `0.0.0.0` causes it to listen on all addresses configured on the machine.
|
||||
|
||||
`--port=PORT`
|
||||
: listen on this TCP port (default: 5000)
|
||||
To allow access from elsewhere, use `--host` to specify an externally accessible address configured on this machine,
|
||||
The special address `0.0.0.0` causes it to listen on all of this machine's addresses.
|
||||
|
||||
Similarly, you can use `--port` to listen on a TCP port other than 5000.
|
||||
This is useful if you want to run multiple hledger-web instances on a machine.
|
||||
|
||||
`--socket=SOCKETFILE`
|
||||
: listen on the given unix socket instead of an IP address and port (unix only; implies --serve)
|
||||
|
||||
When `--socket` is used, hledger-web creates and communicates via a socket file instead of a TCP port.
|
||||
This can be more secure, respects unix file permissions, and makes certain use cases easier,
|
||||
such as running per-user instances behind an nginx reverse proxy. (Eg:
|
||||
`proxy_pass http://unix:/tmp/hledger/${remote_user}.socket;`.)
|
||||
|
||||
`--base-url=URL`
|
||||
: set the base url (default: http://IPADDR:PORT).
|
||||
|
||||
You can use `--base-url` to change the protocol, hostname, port and path that appear in
|
||||
hledger-web's hyperlinks. This is useful eg when integrating hledger-web within a larger website.
|
||||
The default is `http://HOST:PORT/` using the server's configured host address and TCP port
|
||||
@ -121,25 +117,20 @@ eg for better caching or cookie-less serving on high performance websites,
|
||||
you can customise their urls with this.
|
||||
-->
|
||||
|
||||
`--test`
|
||||
: run hledger-web's tests and exit. hspec test runner args may follow a --, eg: hledger-web --test -- --help
|
||||
|
||||
hledger-web also supports many of hledger's general options.
|
||||
Query options and arguments may be used to set an initial filter,
|
||||
which although not shown in the UI, will restrict the data shown,
|
||||
in addition to any search query entered in the UI.
|
||||
|
||||
Note that hledger-web shows accounts with zero balances by default, like `hledger-ui` (and unlike `hledger`).
|
||||
Using the `-E/--empty` flag at startup will hide them.
|
||||
|
||||
If you see accounts which appear to have a zero balance, but cannot be hidden with `-E`:
|
||||
these have a mixed-cost balance which looks like zero when costs are hidden.
|
||||
Currently hledger-web does not show costs at all.
|
||||
|
||||
## General options
|
||||
hledger-web also supports many of hledger's [general options](hledger.md#options):
|
||||
|
||||
_generaloptions_
|
||||
|
||||
hledger-web shows accounts with zero balances by default (like `hledger-ui`, and unlike `hledger`).
|
||||
Using the `-E/--empty` flag will reverse this behaviour.
|
||||
If you see accounts which appear to have a zero balance, but cannot be hidden with `-E`,
|
||||
it's because they have a mixed-cost balance, which looks like zero when costs are hidden.
|
||||
(hledger-web does not show costs.)
|
||||
|
||||
Reporting options and/or query arguments can be used to set an initial query,
|
||||
which although not shown in the UI, will restrict the data shown
|
||||
(in addition to any search query entered in the UI).
|
||||
|
||||
# PERMISSIONS
|
||||
|
||||
By default, hledger-web allows anyone who can reach it to view the journal
|
||||
|
||||
@ -15,8 +15,10 @@ _notinfo_({{
|
||||
}})
|
||||
|
||||
`hledger`\
|
||||
or\
|
||||
`hledger COMMAND [OPTS] [ARGS]`\
|
||||
`hledger ADDONCMD -- [OPTS] [ARGS]`
|
||||
or\
|
||||
`hledger ADDONCMD [OPTS] -- [ADDONOPTS] [ADDONARGS]`
|
||||
|
||||
_notinfo_({{
|
||||
# DESCRIPTION
|
||||
@ -149,7 +151,8 @@ The file name `-` means standard input:
|
||||
$ cat FILE | hledger -f- print
|
||||
```
|
||||
|
||||
If reading non-journal data in this way, you'll need to add a file format prefix, like:
|
||||
If reading non-journal data in this way, you'll need to write the format as a prefix,
|
||||
like `timeclock:` here:
|
||||
|
||||
```cli
|
||||
$ echo 'i 2009/13/1 08:00:00' | hledger print -f timeclock:-
|
||||
@ -239,21 +242,22 @@ If this causes difficulty, you can always run the add-on directly, without using
|
||||
|
||||
# Options
|
||||
|
||||
Run `hledger -h` to see general command line help, and general options which are common
|
||||
to most hledger commands. These options can be written anywhere on the command line:
|
||||
Run `hledger -h` to see general command line help.
|
||||
The following general options are common to most hledger commands.
|
||||
General options can be written either before or after the command name.
|
||||
|
||||
_generaloptions_
|
||||
|
||||
Some reporting options can also be written as [query arguments](#queries).
|
||||
Usually hledger accepts any unambiguous flag prefix,
|
||||
eg you can write `--tl` instead of `--tldr` or `--dry` instead of `--dry-run`.
|
||||
|
||||
# Command line tips
|
||||
If the same option appears more than once in a command, usually the last (right-most) wins.
|
||||
|
||||
Here are some details useful to know about for hledger command lines (and elsewhere).
|
||||
Feel free to skip this section until you need it.
|
||||
With most commands, arguments are interpreted as a hledger [query](hledger.md#queries) which filter the data.
|
||||
Some queries can be expressed either with options or with arguments.
|
||||
|
||||
## Option repetition
|
||||
|
||||
If options are repeated in a command line, hledger will generally use the last (right-most) occurence.
|
||||
Below are more tips for using the command line interface -
|
||||
feel free to skip these until you need them.
|
||||
|
||||
## Special characters
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user