v0.26.4 cli enhancements

doc/cli.md

@@ -33,8 +33,12 @@ manages SCRAM credentials and logs in to `scram` listeners
 - A value follows as the next argument or after `=` (`-c FILE`, `-c=FILE`,
   `--config FILE`, `--config=FILE`); a value that starts with `-` follows `=`,
   and `--` ends the options.
+- A switch (`--check`, `--quiet`, any boolean key) takes no separate value:
+  `--quiet=false`, not `--quiet false`.
 - Short options do not combine (`-q -t`, not `-qt`) or take an attached value
-  (`-cFILE`); an unknown single-dash option is an error.
+  (`-cFILE`).
+- lw takes options only. An unknown option and a word no option takes (`lw
+  tail`, `lw -t FILE`) are usage errors, named on stderr.
 - lw's multiword options join words with `-` (`--rate-limit`,
   `--password-file`); configuration keys, spec keys and preset keys keep
   TOML's `_` and `.` (`--status_reporter`, `--sink http,tls.cert_file=F`,
@@ -48,7 +52,7 @@ pipelines have [their own flags](#pipelines):
 ```
 --<path>=<value>        e.g. --logging.level=debug
 --<path> <value>        e.g. --logging.level debug
---<path>                bare flag: true, for a boolean path only
+--<path>                a switch: true, for a boolean path only
 ```
 
 ### Common
@@ -309,14 +313,16 @@ service untouched; see [Configuration](configuration.md#hot-reload).
 
 - `0`: the end of input, a clean shutdown (`SIGINT`, `SIGTERM`), `--version` /
   `--help`, `--dump`, or a valid `--check`
-- `1`: general error: a command-line error (an unknown option, a missing
-  `-c` path), a configuration load or validation failure (`--check`
-  included), a logger init failure, a service bootstrap failure
-- `2`: an explicitly requested configuration file is not found
+- `1`: general error: a configuration load or validation failure (`--check`
+  included, and a bad value on the command line), a logger init failure, a
+  service bootstrap failure
+- `2`: a usage error (an unknown option, a word no option takes, a missing
+  value or `-c` path), or an explicitly requested configuration file that is
+  not found
 - killed by `SIGPIPE` (shell status `141`): the reader of stdout went away, as
   in `lw | head`; `cat` ends the same way
 
-Exit code 2 applies only when the file was named explicitly (`-c`,
+A missing file is exit code 2 only when it was named explicitly (`-c`,
 `--config=`, or the `LOGWISP_CONFIG_*` variables). A missing discovered default
 is not an error, and LogWisp starts on built-in defaults.
 
@@ -511,7 +517,7 @@ Makes ECDSA P-256 certificates for `tls` blocks. It never replaces a file
 
 ```
 lw tls ca   --dir DIR [--name NAME] [--days 3650]
-lw tls cert --ca-dir DIR --name NAME [--host NAME,...] [--server] [--client]
+lw tls cert --ca-dir DIR --name NAME [--hosts NAME,...] [--server] [--client]
             [--days 397] [--out DIR]
 ```
 
@@ -520,9 +526,9 @@ lw tls cert --ca-dir DIR --name NAME [--host NAME,...] [--server] [--client]
   `tls.client_ca_file`; with `ca.key` it is a listener's
   `tls.issuer_cert_file` and `tls.issuer_key_file`.
 - `cert`: `NAME.crt` and `NAME.key`, in `--out` (default: `--ca-dir`).
-  - `--server` for a listener: `--host` lists the DNS names and IP addresses it
-    carries, default `NAME`; `--client` for a dialer presenting a certificate;
-    both may be given.
+  - `--server` for a listener: `--hosts` lists the DNS names and IP addresses
+    it carries, default `NAME` (`--host`, its earlier name, still works);
+    `--client` for a dialer presenting a certificate; both may be given.
   - `NAME` is the subject CN, the identity `auth.type = "mtls"` matches.
   - Valid 397 days (the longest browsers accept), never past the CA. It prints
     the certificate's `pin_sha256`.

doc/configuration.md

@@ -234,17 +234,12 @@ lw --logging.level debug          # space form also works
 lw --quiet                        # bare flag means true
 ```
 
-A bare flag is accepted only for a boolean key: `--logging.file.directory
---quiet` fails with `--logging.file.directory needs a value`. Unrecognized `--`
-flags and positional words are reported on stderr before the logger exists and
-are then ignored:
-
-```
-Warning: unrecognized flags ignored: [nosuch.key]
-```
-
-Single-dash options are lw's own ([CLI](cli.md#options)); an unknown one is
-an error.
+A bare flag is accepted only for a boolean key, which takes its value only
+after `=`: `--logging.file.directory --quiet` fails with
+`--logging.file.directory needs a value`, and `--quiet false` with `unexpected
+argument "false"`. An unknown key is an error too (`unknown option
+--nosuch.key`); each is a usage error, exit code 2. Single-dash options are
+lw's own ([CLI](cli.md#options)).
 
 An empty `LOGWISP_<PATH>` variable counts as unset, as the pipeline variables
 do.

doc/lw.1

@@ -112,10 +112,13 @@ that stands for it in every command that has it.
 A value follows as the next argument or after
 .Ql = ;
 a value that starts with
-.Ql -
-follows
+.Ql - ,
+and a switch's, follows
 .Ql = .
-Short options do not combine, and an unknown one is an error.
+Short options do not combine.
+.Nm
+takes options only: an unknown option, or a word no option takes, is a usage
+error.
 The options of
 .Nm
 join words with
@@ -375,13 +378,14 @@ Create a certificate authority,
 and
 .Pa dir/ca.key ,
 valid 3650 days.
-.It Cm cert Fl \-ca\-dir Ar dir Fl \-name Ar name Oo Fl \-host Ar names Oc Oo Fl \-server Oc Oo Fl \-client Oc Oo Fl \-days Ar n Oc Op Fl \-out Ar dir
+.It Cm cert Fl \-ca\-dir Ar dir Fl \-name Ar name Oo Fl \-hosts Ar names Oc Oo Fl \-server Oc Oo Fl \-client Oc Oo Fl \-days Ar n Oc Op Fl \-out Ar dir
 Issue
 .Pa name.crt
 and
 .Pa name.key
 from that authority, valid 397 days and never past it.
-.Fl \-host
+.Fl \-hosts
+.Pq or Fl \-host
 lists the DNS names and addresses a server certificate carries
 .Pq default: Ar name ;
 .Ar name
@@ -547,8 +551,8 @@ The service's working directory on Linux and on
 .Nm
 exits 0 at the end of input, after a clean shutdown,
 .Fl \-version
-or help; 1 on a command-line, configuration, logger or startup error; and 2
-when a configuration file named by
+or help; 1 on a configuration, logger or startup error; and 2 on a usage
+error or when a configuration file named by
 .Fl c
 or
 .Ev LOGWISP_CONFIG_*
@@ -568,7 +572,7 @@ the shell reports status 141.
 .Cm tls
 and
 .Cm preset
-exit 0 on success or help, 1 on failure, and 2 on a usage error.
+do the same: 0 on success or help, 1 on failure, and 2 on a usage error.
 .Sh SIGNALS
 .Bl -tag -width "SIGINT, SIGTERM"
 .It Dv SIGINT , SIGTERM

doc/todo.md

@@ -65,19 +65,9 @@ identity, and both skeletons download the tagged source.
 
 Smaller items found along the way, each independent of the others.
 
-1. Command line:
-   - a positional word at the top level (`lw tail`, `lw -t FILE`) still reaches
-     config with an unclear message; name it ("unexpected argument X; the file
-     is -c FILE");
-   - Go's flag errors keep single dashes ("flag needs an argument: -u");
-   - an unknown `--key` only warns and then runs the stdin pipe; consider an
-     error when stdin is a terminal;
-   - `lw tls cert --host` could become `--hosts` (keeping `--host`), to match
-     `tls.hosts` and the preset key;
-   - top-level usage errors exit 1, subcommand ones 2.
-2. TLS: the generated-certificate key is one per process, so a pin taken from a
+1. TLS: the generated-certificate key is one per process, so a pin taken from a
    `self_signed` listener also matches an `issuer` listener of the same
    process; document it or key per listener. Pins are checked in
    `VerifyPeerCertificate`, which Go skips on resumption: guard it if a dialer
    ever keeps a `ClientSessionCache`.
-3. `core.ShutdownTimeout` is unused.
+2. `core.ShutdownTimeout` is unused.