Redesign CLI flags, help, and argument validation

README.md

@@ -16,6 +16,10 @@ Current version: 3.3.6 | [Changelog](debian/changelog)
 [CLI reference and configuration guide](https://shadowsocks.github.io/shadowsocks-c/)
 are generated from the source with Doxygen and published after updates to `master`.
 
+Use `--help` for grouped CLI options and `--version` for version information.
+See [CLI conventions](https://shadowsocks.github.io/shadowsocks-c/index.html#cli_conventions)
+for the long flags, short aliases, and configuration precedence.
+
 ## Community
 
 See the [contribution guide](CONTRIBUTION.md) for development setup, testing,

doc/index.md

@@ -14,3 +14,34 @@ source documentation.
 [Download the generated man pages](https://shadowsocks.github.io/shadowsocks-c/man-pages.tar.gz)
 from the published site. The archive includes the six CLI manuals and both
 overview lookup names.
+
+\section cli_conventions CLI conventions
+
+Use descriptive long flags or their existing short aliases. Connections use
+different names for the remote server and the local listener:
+
+- Clients: `--server HOST --server-port PORT` selects the remote Shadowsocks server.
+- Listeners: `--listen-address ADDRESS --listen-port PORT` controls where a client
+  or server accepts connections. The manager uses `--manager-address` for its
+  control socket and configuration or its API for individual server ports.
+- Tunnels: `--destination HOST:PORT` selects the forwarding destination.
+- Configuration: `--config FILE`, `--cipher NAME`, and `--password SECRET` map to
+  `-c`, `-m`, and `-k`. AEAD-2022 keys can also be supplied with `--key BASE64`.
+
+Explicit transport and address-family flags override the JSON configuration.
+The last transport flag
+(`--tcp-only`, `--udp`, or `--udp-only`) wins, as does the last address preference
+(`--ipv4-first` or `--ipv6-first`). Address preferences do not disable either IP
+family. Other options retain their existing semantics, including repeatable
+server addresses and `ss-local --server-url` imports. Zero-valued resource
+settings such as MTU and TCP buffer sizes retain their existing behavior: they
+fall back to the configured value, or the system default when none is configured.
+
+`--help` and `--version` write to standard output and exit successfully. Unknown
+options, missing values, invalid numeric CLI values, and unexpected positional
+arguments write usage errors to standard error and exit with status 2.
+
+The formerly ignored `-l` flag in `ss-server` and `ss-manager` is now an error.
+Use `ss-server --listen-port` instead; manager-controlled ports come from its
+configuration or API. The removed one-time-authentication flag `-A` remains an
+error. Use an AEAD cipher.

doc/ss-local.md

@@ -29,7 +29,7 @@ ss-local(1) can be started from command line and run in foreground.
 Here is an example:
 ```
 # Start ss-local with given parameters
-ss-local -s example.com -p 12345 -l 1080 -k foobar -m aes-256-cfb
+ss-local --server example.com --server-port 12345 --listen-port 1080 --password foobar --cipher aes-256-gcm
 ```
 
 \section ss_local_see_also SEE ALSO

doc/ss-server.md

@@ -32,7 +32,7 @@ Check out the `SEE ALSO` section for the default path of config file.
 
 ```
 # Start the ss-server
-ss-server -c /etc/shadowsocks-libev/config.json
+ss-server --config /etc/shadowsocks-libev/config.json
 ```
 
 \section ss_server_incompatibility INCOMPATIBILITY

doc/ss-tunnel.md

@@ -31,7 +31,7 @@ through the shadowsocks tunnel. Here is an example:
 
 ```
 # Forward local UDP port 5353 to 8.8.8.8:53 through the ss-server
-ss-tunnel -s example.com -p 12345 -l 5353 -k foobar -m aes-256-cfb -L 8.8.8.8:53 -u
+ss-tunnel --server example.com --server-port 12345 --listen-port 5353 --password foobar --cipher aes-256-gcm --destination 8.8.8.8:53 --udp
 
 # Then configure your system to use 127.0.0.1:5353 as the DNS server
 dig @127.0.0.1 -p 5353 www.google.com

scripts/check_cli_docs.py

@@ -51,7 +51,7 @@ def options(source, shell=False):
     if len(tables) != 1:
         raise ValueError("Expected one long_options table")
     table = re.sub(r'^\s*#.*$', '', tables[0], flags=re.M)
-    entry = re.compile(r'\{\s*"([a-z0-9-]+)"\s*,\s*(no_argument|required_argument)\s*,\s*NULL\s*,\s*GETOPT_VAL_[A-Z0-9_]+\s*\}\s*,', re.S)
+    entry = re.compile(r'\{\s*"([a-z0-9-]+)"\s*,\s*(no_argument|required_argument)\s*,\s*NULL\s*,\s*(?:GETOPT_VAL_[A-Z0-9_]+|\x27[A-Za-z0-9]\x27)\s*\}\s*,', re.S)
     for match in entry.finditer(table):
         flag, argument = match.groups()
         if '--' + flag in result:

src/common.h

@@ -76,7 +76,10 @@ enum {
     GETOPT_VAL_TCP_OUTGOING_SNDBUF,
     GETOPT_VAL_TCP_OUTGOING_RCVBUF,
     GETOPT_VAL_NFTABLES_SETS,
-    GETOPT_VAL_SERVER_URL
+    GETOPT_VAL_SERVER_URL,
+    GETOPT_VAL_VERSION,
+    GETOPT_VAL_TCP_ONLY,
+    GETOPT_VAL_IPV4_FIRST
 };
 
 #endif // _COMMON_H