feat!(cli): switch to subcmd CLI; add new options

The options `-c` and `-u` select different modes of operation.
They will be better as subcommands.

Add the option `-d`/`--debug`.
Add a short version for `--no-date` and `--no-initial-values`.

v0.7.0

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "jsonwatch"
-version = "0.6.1"
+version = "0.7.0"
 authors = ["D. Bohdan <[email protected]>"]
 edition = "2018"
 license = "MIT"

README.md

@@ -1,9 +1,9 @@
-# jsonwatch — like `watch -d` but for JSON
+# jsonwatch — like `watch -d`, but for JSON
 
-jsonwatch is a command-line utility that lets you track changes in JSON data delivered by a shell command or a web (HTTP/HTTPS) API.
+jsonwatch is a command-line utility that lets you track changes in JSON data delivered by a command or a web (HTTP/HTTPS) API.
 jsonwatch requests data from the source repeatedly at a set interval.
 It displays the differences when the data changes.
-It is similar but not identical to how [watch(1)](https://manpages.debian.org/stable/procps/watch.1.en.html) with the `-d` switch works for plain-text data.
+It is similar but not identical to how [watch(1)](https://manpages.debian.org/stable/procps/watch.1.en.html) with the `-d` switch works for plain text.
 
 jsonwatch has been tested on Debian 12, Ubuntu 24.04, macOS 14, and Windows 10 and Server 2022.
 
@@ -15,7 +15,7 @@ and
 
 ## Installation
 
-Prebuilt binaries are available for Linux and Windows.
+Prebuilt binaries are available for Linux (x86_64) and Windows (x86).
 Binaries are attached to releases on the
 ["Releases"](https://github.com/dbohdan/jsonwatch/releases)
 page.
@@ -91,31 +91,69 @@ just release-windows
 
 ## Usage
 
+### Generic options
+
+`command` can be shortened to `c` or `cmd`;
+`url` can be shortened to `u`.
+
 ```none
 Track changes in JSON data
 
-Usage: jsonwatch [OPTIONS]
+Usage: jsonwatch [OPTIONS] <COMMAND>
+
+Commands:
+  command  Execute a command and track its JSON output
+  url      Fetch a URL and track its JSON output
+  help     Print this message or the help of the given subcommand(s)
 
 Options:
-  -c, --command <command>   Command to execute
-  -u, --url <url>           URL to fetch
-  -n, --interval <seconds>  Polling interval in seconds [default: 5]
-      --no-date             Don't print date and time for each diff
-      --no-initial-values   Don't print initial JSON values
+  -D, --no-date             Don't print date and time for each diff
+  -I, --no-initial-values   Don't print initial JSON values
+  -d, --debug               Print raw output to stderr with a timestamp
+  -n, --interval <seconds>  Polling interval in seconds [default: 1]
   -h, --help                Print help
   -V, --version             Print version
 ```
 
+### `command`
+
+```none
+Execute a command and track its JSON output
+
+Usage: jsonwatch command [command]...
+
+Arguments:
+  [command]...  Command to execute with arguments
+
+Options:
+  -h, --help  Print help
+```
+
+### `url`
+
+```none
+Fetch a URL and track its JSON output
+
+Usage: jsonwatch url [OPTIONS] <url>
+
+Arguments:
+  <url>  URL to fetch
+
+Options:
+  -A, --user-agent <user-agent>  Custom User-Agent string [default: curl/7.58.0]
+  -h, --help                     Print help
+```
+
 ## Use examples
 
 ### Commands
 
 #### *nix
 
-Testing jsonwatch.
+##### Testing jsonwatch
 
 ```none
-$ jsonwatch -n 1 -c "echo '{ \"filename\": \"'\$(mktemp -u)'\"}'"
+$ jsonwatch -n 1 cmd sh -c "echo '{ \"filename\": \"'\$(mktemp -u)'\"}'"
 
 {
   "filename": "/tmp/tmp.dh3Y7LJTaK"
@@ -127,10 +165,12 @@ $ jsonwatch -n 1 -c "echo '{ \"filename\": \"'\$(mktemp -u)'\"}'"
 2020-01-19T18:52:23+0000 .filename: "/tmp/tmp.1LGk4ok8O2" -> "/tmp/tmp.wWulyho8Qj"
 ```
 
-Docker process information.
+##### Docker
+
+Docker process information for a single running container.
 
 ```none
-$ jsonwatch -c 'docker ps -a "--format={{json .}}"' -n 1
+$ jsonwatch command docker ps -a "--format={{json .}}"
 
 2020-01-19T18:57:20+0000
     + .Command: "\"bash\""
@@ -158,12 +198,16 @@ $ jsonwatch -c 'docker ps -a "--format={{json .}}"' -n 1
     .Status: "Up 2 seconds" -> "Up 3 seconds"
 ```
 
-#### Windows
+For multiple containers, you will to use a more complex command like the following with [jq](https://en.wikipedia.org/wiki/Jq_(programming_language)):
+
+```shell
+jsonwatch -I cmd sh -c 'docker ps -a "--format={{json .}}" | jq -s .'
+```
 
-On Windows, `-c` executes `cmd.exe` commands.
+#### Windows
 
 ```none
-> jsonwatch -c "type tests\weather1.json"
+> jsonwatch command cmd.exe /c "type tests\weather1.json"
 
 {
   "clouds": {
@@ -222,11 +266,12 @@ On Windows, `-c` executes `cmd.exe` commands.
 
 Watching a URL works identically on *nix and on Windows.
 
-Weather tracking.
-(This API no longer works without a key.)
+#### Weather tracking
+
+This API no longer works without a key.
 
 ```none
-$ jsonwatch -u http://api.openweathermap.org/data/2.5/weather\?q\=Kiev,ua --no-initial-values -n 300
+$ jsonwatch url --no-initial-values -n 300 'http://api.openweathermap.org/data/2.5/weather?q=Kiev,ua'
 
 2014-03-17T23:06:19.073790
     + .rain.1h: 0.76
@@ -238,11 +283,12 @@ $ jsonwatch -u http://api.openweathermap.org/data/2.5/weather\?q\=Kiev,ua --no-i
     .sys.message: 0.0353 -> 0.0083
 ```
 
-Geolocation.
-(Try this on a mobile device.)
+#### Geolocation
+
+Try this on a mobile device.
 
 ```none
-$ jsonwatch -u https://ipinfo.io/ --no-initial-values -n 300
+$ jsonwatch u --no-initial-values -n 300 https://ipinfo.io/
 ```
 
 ## License