improve readme

Signed-off-by: Marc Schöchlin <[email protected]>

Author: scoopex

README.md

@@ -44,117 +44,115 @@ Invoke hostctl to execute commands or scripts on the specified hosts.
 
 See also "EXAMPLES" section.
 
-# Manpage:
-(output of "hostctl -h")
+# Help
+(output of "hostctl --help")
 ```
-License - see: LICENSE.txt
+$ hostctl --help
+
+Run a binary or example of the local package
+
+Usage: cargo run [OPTIONS] [ARGS]...
+
+Arguments:
+  [ARGS]...  Arguments for the binary or example to run
+
+Options:
+      --message-format <FMT>  Error format
+  -v, --verbose...            Use verbose output (-vv very verbose/build.rs output)
+  -q, --quiet                 Do not print cargo log messages
+      --color <WHEN>          Coloring: auto, always, never
+      --config <KEY=VALUE>    Override a configuration value
+  -Z <FLAG>                   Unstable (nightly-only) flags to Cargo, see 'cargo -Z help' for details
+  -h, --help                  Print help
+
+Package Selection:
+  -p, --package [<SPEC>]  Package with the target to run
+
+Target Selection:
+      --bin [<NAME>]      Name of the bin target to run
+      --example [<NAME>]  Name of the example target to run
+
+Feature Selection:
+  -F, --features <FEATURES>  Space or comma separated list of features to activate
+      --all-features         Activate all available features
+      --no-default-features  Do not activate the `default` feature
+
+Compilation Options:
+  -j, --jobs <N>                Number of parallel jobs, defaults to # of CPUs.
+      --keep-going              Do not abort the build as soon as there is an error
+  -r, --release                 Build artifacts in release mode, with optimizations
+      --profile <PROFILE-NAME>  Build artifacts with the specified profile
+      --target [<TRIPLE>]       Build for the target triple
+      --target-dir <DIRECTORY>  Directory for all generated artifacts
+      --unit-graph              Output build graph in JSON (unstable)
+      --timings[=<FMTS>]        Timing output formats (unstable) (comma separated): html, json
+
+Manifest Options:
+      --manifest-path <PATH>  Path to Cargo.toml
+      --lockfile-path <PATH>  Path to Cargo.lock (unstable)
+      --ignore-rust-version   Ignore `rust-version` specification in packages
+      --locked                Assert that `Cargo.lock` will remain unchanged
+      --offline               Run without accessing the network
+      --frozen                Equivalent to specifying both --locked and --offline
+
+Run `cargo help run` for more detailed information.
+marc@frink(2024-11-17 22:39:07)  ~/src/github/hostctl-rust [master]   
+$ cargo run -- --help
+   Compiling hostctl v0.1.0 (/home/marc/src/github/hostctl-rust)
+    Finished `dev` profile [unoptimized + debuginfo] target(s) in 1.49s
+     Running `target/debug/hostctl --help`
+convenient management and execution of command on groups of hosts
+
+Usage: hostctl [OPTIONS] [ITEMS]...
+
+Arguments:
+  [ITEMS]...  Groups or nodes for the iteration
+
+Options:
+  -c, --command <COMMAND>      Command to execute. A ssh login is performed on the specified hosts and the specified command is executed on the remotehost [default: ]
+  -e, --execute-local          Execute as local command and add hostname to the command (Hostname will be appended to the command, or inserted where 'HOST' string is located in the string
+  -r, --recipe <RECIPE>        Recipe to execute. A recipe is a shellscript which defines recurring administration tasks. Recipes can be stored in $HOME/.hostctl/recipe/ or <hostctl-installation-path>/recipe/ and can be called by their basename. Alternatively, recipes can be called be their fully qualified path [default: ]
+  -n, --nodes                  Specify hosts instead of groups
+  -s, --show                   show group(s)
+  -a, --array                  Output an array list od nodes
+  -j, --json                   output hosts in json format
+  -d, --debug                  debug mode
+  -f, --forcecolor             disable automatic detection of interactive usage and output colors always
+  -q, --quiet                  reduce output, useful for aggregating output of multiple hosts
+  -b, --batchmode              
+  -i, --inscreen <INSCREEN>    start command/script screen session [default: ]
+  -o, --optssh <OPTSSH>        Add the arguments to the ssh command [default: ]
+  -l, --login                  
+      --sudo                   
+  -t, --term                   
+  -w, --wait <WAIT>            wait a specified number of seconds before continuing at next host [default: 0]
+  -p, --prompt                 ask after every execution, if hostctl should continue, retry, execute a shell or quit
+  -m, --makeselection          raise a prompt before each host which provides the possibility to confirm or skip the host or quit execution
+      --log-level <LOG_LEVEL>  The log level [default: info]
+  -h, --help                   Print help
+  -V, --version                Print version
+
+
+    EXAMPLES
 
-
-NAME
-    hostctl - convenient management and execution of comand on groups of hosts
-
-SYNOPSIS
-    hostctl [OPTIONS] [GROUPNAMES]
-
-    To specify more than one <groupname>, specify groups separated by spaces
-    or comma. Options and groupnames can be mixed. Options can be
-    abbreviated if there are no ambiguities.
-
-OPTIONS
-    --command <command>
-        Command to execute. A ssh login is performed on the specified hosts
-        and the specified command is executed on the remotehost.
-
-    --executelocal <command>
-        Execute a local command and add hostname to the command (Hostname
-        will be appended to the command, or inserted where 'HOST' string is
-        located in the string.
-
-    --recipe <name>|<path>
-        Recipe to execute. A recipe is a shellscript which defines recurring
-        administration tasks. Recipes can be stored in
-        $HOME/.hostctl/recipe/ or <hostctl-installation-path>/recipe/ and
-        can be called by their basename. Alternatively, recipes can be
-        called be their fully qualified path.
-
-    --nodes
-        Specify hosts instead of groups.
-
-    --debug
-        debug mode
-
-    --quiet
-        reduce output, useful for aggregating output of multiple hosts
-
-    --help
-        show this manpage
-
-    --show
-        show group(s)
-
-    --show --array
-        list hosts suitable for array iteration
-
-    --login
-        login to each host (sleep 1 second after every login, use STRG+c to
-        terminate iteration)
-
-    --optssh <arguments>
-        Add the arguments to the ssh command.
-
-    --batchmode
-        batchmode, no password prompting (skip host if not ssh-key auth is
-        possible)
-
-    --prompt
-        ask after every execution, if hostctl should (c)ontinue, (r)etry,
-        (s)hell, (q)uit
-
-    --makeselection
-        raise a prompt before each host which provides the possibility to
-        confirm, skip or quit execution
-
-    --inscreen <session>
-        start command/script screen session (screen -x <session>, see 'man
-        screen' or 'STRG+a :help')
-
-    --term
-        Force pseudo-tty allocation (typically needed for tools which use
-        (ncurses-)text-menus)
-
-    --wait <seconds>
-        wait a specified number of seconds before continuing at next host
-
-    --prompt
-        raise a prompt after each host which provides the possibility to to
-        open a shell, re-execute, quit
-
-DESCRIPTION
-    hostctl is a generic tool which supports batched execution of tasks on
-    groups of hosts.
-
-EXAMPLES
     Show disk usage on all systems which belong to group 'foobar'
         "hostctl -c 'df -h' foobar"
 
-    Show a aggregated view of all cronjobs running on a cluster
-        "hostctl -c "crontab -l -u www-user" webcluster01 -q | less"
-
     Show disk usage on all systems which belong to group 'foobar', ask after
     every node what to do next
         "hostctl -p -c 'df -h' foobar"
 
     Execute ncurses application 'top' on all systems which belong to group
-    'foobar'
+    'foobar' using a pseudo tty
         "hostctl -t -c 'top' foobar"
 
-    Copy files using rsync to a remotehost
-        "hostctl -e 'rsync -avP /tmp/foo HOST:/tmp/bar' foobar"
+    Copy files using rsync to a remotehost by replacing the string HOST with the
+    current hostname of the systems
+        "hostctl -e -c 'rsync -avP /tmp/foo HOST:/tmp/bar' foobar"
 
     Execute script/recipe 'apache_status' on all systems which belong to
-    group 'foobar'
+    group 'foobar' (shortcut or explictit path)
         "hostctl -r apache_status foobar"
-
         "hostctl -r /foo/bar/baz/apache_status foobar"
 
     Login sequentially on all hosts which belong to group 'foobar'
@@ -163,27 +161,14 @@ EXAMPLES
     Start a screen session with 'top' on all systems which belong to group
     'foobar'
         "hostctl -c 'top' --inscreen my-magic-screen foobar"
-
         "screen -x my-magic-screen"
 
-ENVIRONMENT VARIABLES
-    HOSTCTL_CONFIG
-        Define a alternate configuration location
-
-        Default search order: ~/.hostctl/hostctl.conf, <HOSTCTL BINARY
-        DIRECTORY>/hostctl.conf
-
-    HOSTCTL_CONFIG_DYNAMIC_SCRIPT
-        Get additional group definitions by reading stdout of the given
-        script
+    ENVIRONMENT VARIABLES
 
-BUGS
-    features :-)
-
-AUTHOR
-    Marc Schoechlin <[email protected]>
+    HOSTCTL_CONFIG
+        Define a alternate configuration location directory
 
-    Marc Schoechlin <[email protected]>
+        Default search order: ~/.hostctl/hostctl.conf, <HOSTCTL BINARY DIRECTORY>/hostctl.conf
 
 ```