slaesvuo/hledger
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

;doc: cli, ui, web: synopsis, options cleanup/consistency

Browse Source
This commit is contained in:
Simon Michael 2024-05-31 18:17:04 -10:00
parent 7f583a8414
commit 88f70eba6b
3 changed files with 78 additions and 108 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

69
hledger-ui/hledger-ui.m4.md
View File

@ -13,6 +13,7 @@ _notinfo_({{
}}) }})
`hledger-ui [OPTS] [QUERYARGS]`\ `hledger-ui [OPTS] [QUERYARGS]`\
or\
`hledger ui -- [OPTS] [QUERYARGS]` `hledger ui -- [OPTS] [QUERYARGS]`
_notinfo_({{ _notinfo_({{
@ -50,50 +51,32 @@ by pressing the F key (or starting with --forecast) to enable "forecast mode".
# OPTIONS # 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: 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` and also supports many of hledger's [general options](hledger.md#options):
: 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
_generaloptions_ _generaloptions_
With hledger-ui, the `--debug` option sends debug output to a `hledger-ui.log` file in the current directory.
# MOUSE # MOUSE
In most modern terminals, you can navigate through the screens with a 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.) (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. 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 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 If you are viewing files mounted from another machine, the system
clocks on both machines should be roughly in agreement. 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 # ENVIRONMENT
**COLUMNS** **COLUMNS**

89
hledger-web/hledger-web.m4.md
View File

@ -12,8 +12,9 @@ _notinfo_({{
# SYNOPSIS # SYNOPSIS
}}) }})
`hledger-web [--serve|--serve-api] [OPTS] [ARGS]`\ `hledger-web [OPTS] [QUERY]`\
`hledger web -- [--serve|--serve-api] [OPTS] [ARGS]` or\
`hledger web -- [OPTS] [QUERY]`
_notinfo_({{ _notinfo_({{
# DESCRIPTION # DESCRIPTION
@ -64,48 +65,43 @@ In all cases hledger-web runs as a foreground process, logging requests to stdou
hledger-web provides the following options: 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` By default hledger-web listens only on IP address `127.0.0.1`,
: like --serve, but serve only the JSON web API, not the web UI which be accessed only from the local machine.
`--allow=view|add|edit` To allow access from elsewhere, use `--host` to specify an externally accessible address configured on this machine,
: set the user's access level for changing data (default: `add`). The special address `0.0.0.0` causes it to listen on all of this machine's addresses.
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)
Similarly, you can use `--port` to listen on a TCP port other than 5000. 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. 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. 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, 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: such as running per-user instances behind an nginx reverse proxy. (Eg:
`proxy_pass http://unix:/tmp/hledger/${remote_user}.socket;`.) `proxy_pass http://unix:/tmp/hledger/${remote_user}.socket;`.)
`--base-url=URL` You can use `--base-url` to change the protocol, hostname, port and path that appear in
: 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. 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 The default is `http://HOST:PORT/` using the server's configured host address and TCP port
(or `http://HOST` if PORT is 80). (or `http://HOST` if PORT is 80).
@ -121,25 +117,20 @@ eg for better caching or cookie-less serving on high performance websites,
you can customise their urls with this. you can customise their urls with this.
--> -->
`--test` hledger-web also supports many of hledger's [general options](hledger.md#options):
: 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
_generaloptions_ _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 # PERMISSIONS
By default, hledger-web allows anyone who can reach it to view the journal By default, hledger-web allows anyone who can reach it to view the journal

28
hledger/hledger.m4.md
View File

@ -15,8 +15,10 @@ _notinfo_({{
}}) }})
`hledger`\ `hledger`\
`hledger COMMAND [OPTS] [ARGS]`\ or\
`hledger ADDONCMD -- [OPTS] [ARGS]` `hledger COMMAND [OPTS] [ARGS]`\
or\
`hledger ADDONCMD [OPTS] -- [ADDONOPTS] [ADDONARGS]`
_notinfo_({{ _notinfo_({{
# DESCRIPTION # DESCRIPTION
@ -149,7 +151,8 @@ The file name `-` means standard input:
$ cat FILE | hledger -f- print $ 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 ```cli
$ echo 'i 2009/13/1 08:00:00' | hledger print -f timeclock:- $ 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 # Options
Run `hledger -h` to see general command line help, and general options which are common Run `hledger -h` to see general command line help.
to most hledger commands. These options can be written anywhere on the command line: The following general options are common to most hledger commands.
General options can be written either before or after the command name.
_generaloptions_ _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). With most commands, arguments are interpreted as a hledger [query](hledger.md#queries) which filter the data.
Feel free to skip this section until you need it. Some queries can be expressed either with options or with arguments.
## Option repetition Below are more tips for using the command line interface -
feel free to skip these until you need them.
If options are repeated in a command line, hledger will generally use the last (right-most) occurence.
## Special characters ## Special characters