diff --git a/hledger-ui/hledger-ui.m4.md b/hledger-ui/hledger-ui.m4.md index dbdf170d5..b424bd81a 100644 --- a/hledger-ui/hledger-ui.m4.md +++ b/hledger-ui/hledger-ui.m4.md @@ -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** diff --git a/hledger-web/hledger-web.m4.md b/hledger-web/hledger-web.m4.md index 767730083..473f0f1ab 100644 --- a/hledger-web/hledger-web.m4.md +++ b/hledger-web/hledger-web.m4.md @@ -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,48 +65,43 @@ 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 +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 (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. --> -`--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 diff --git a/hledger/hledger.m4.md b/hledger/hledger.m4.md index 98062c015..000b94a2d 100644 --- a/hledger/hledger.m4.md +++ b/hledger/hledger.m4.md @@ -15,8 +15,10 @@ _notinfo_({{ }}) `hledger`\ -`hledger COMMAND [OPTS] [ARGS]`\ -`hledger ADDONCMD -- [OPTS] [ARGS]` +or\ +`hledger COMMAND [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