aspera-cli 4.17.0 → 4.18.1

data/README.md

@@ -10,7 +10,7 @@
 
 ## Introduction
 
-Version : 4.17.0
+Version : 4.18.1
 
 Laurent/2016-2024
 
@@ -70,7 +70,7 @@ For scripting and ad'hoc command line operations, `ascli` is perfect.
 
 Command line operations examples are shown using a shell such as: `bash` or `zsh`.
 
-Command line parameters in examples beginning with `my_`, e.g. `my_param_value`, are user-provided value and not fixed value commands.
+Command line arguments beginning with `my_` in examples, e.g. `my_param_value`, are user-provided value and not fixed value commands.
 
 `ascli` is an API **Client** toward the remote Aspera application **Server** (Faspex, HSTS, etc...)
 
@@ -92,7 +92,7 @@ Once the gem is installed, `ascli` shall be accessible:
 
 ```console
 $ ascli --version
-4.17.0
+4.18.1
 ```
 
 ### First use
@@ -122,10 +122,10 @@ ascli server browse /
 +------------+--------+-----------+-------+---------------------------+-----------------------+
 ```
 
-If you want to use `ascli` with another server, and in order to make further calls more convenient, it is advised to define a [Option Preset](#option-preset)' for the server's authentication options.
+If you want to use `ascli` with another server, and in order to make further calls more convenient, it is advised to define a [Option Preset](#option-preset) for the server's authentication options.
 The following example will:
 
-- Create a [Option Preset](#option-preset)'
+- Create a [Option Preset](#option-preset)
 - Define it as default for the `server` plugin
 - List files in a folder
 - Download a file
@@ -188,8 +188,8 @@ It is possible to install **either** directly on the host operating system (Linu
 The direct installation is recommended and consists in installing:
 
 - [Ruby](#ruby)
-- [aspera-cli](#ruby-gem)
-- [Aspera SDK (`ascp`)](#fasp-protocol)
+- [aspera-cli](#ruby-gem-aspera-cli) <!-- markdownlint-disable-line -->
+- [Aspera SDK (`ascp`)](#fasp-protocol-ascp)
 
 Ruby version: >= 2.6.
 
@@ -253,7 +253,7 @@ Install the chosen pre-compiled Ruby version:
 rvm install 3.2.2
 ```
 
-Ruby is now installed for the user, go to [Gem installation](#ruby-gem).
+Ruby is now installed for the user, go to [Gem installation](#ruby-gem-aspera-cli). <!-- markdownlint-disable-line -->
 
 Alternatively RVM can be installed system-wide, for this execute as `root`.
 It then installs by default in `/usr/local/rvm` for all users and creates `/etc/profile.d/rvm.sh`.
@@ -300,52 +300,6 @@ Download the Ruby installer executable from <https://rubyinstaller.org/downloads
 rubyinstaller-devkit-3.2.2-1-x64.exe /silent /currentuser /noicons /dir=C:\aspera-cli
 ```
 
-Installation without network:
-
-It is essentially the same procedure, but instead of retrieving files from internet, copy the files from a machine with internet access, and then install from those archives:
-
-- Download the `exe` Ruby installer from <https://rubyinstaller.org/downloads/>
-
-  ```bash
-  v=$(curl -s https://rubyinstaller.org/downloads/|sed -nEe 's|.*(https://.*/releases/download/.*exe).*|\1|p'|head -n 1)
-  curl -o ${v##*/} $v
-  ```
-
-- Create an archive with necessary gems: <https://help.rubygems.org/kb/rubygems/installing-gems-with-no-network>
-
-  ```bat
-  gem install aspera-cli -N -i my_gems
-  ```
-
-  Zip the files `*.gem` from folder `repo/my_gems`
-
-- Download the SDK from: <https://ibm.biz/aspera_sdk>
-
-Create a Zip with all those files, and transfer to the target system.
-
-Then, on the target system:
-
-- Unzip the archive
-- Execute the installer:
-
-```bat
-rubyinstaller-devkit-3.2.2-1-x64.exe /silent /currentuser /noicons /dir=C:\aspera-cli
-```
-
-- Install the gems:
-
-```bat
-gem install --force --local *.gem
-```
-
-- Install the SDK
-
-```bash
-ascli config ascp install --sdk-url=file:///sdk.zip
-```
-
-> **Note:** An example of installation script is provided: [docs/install.bat](docs/install.bat)
-
 #### macOS: `brew`
 
 **macOS** come with Ruby.
@@ -388,6 +342,12 @@ If your Linux distribution provides a standard Ruby package, you can use it prov
   dnf install -y ruby-devel
   ```
 
+**Example:** Ubuntu
+
+```bash
+apt-get install -y ruby-full
+```
+
 **Other examples:**
 
 ```bash
@@ -404,6 +364,26 @@ One can remove all installed gems, for example to start fresh:
 gem uninstall -axI $(ls $(gem env gemdir)/gems/|sed -e 's/-[^-]*$//'|sort -u)
 ```
 
+#### Linux as simple user
+
+If you don't have root access, you can install Ruby in your home directory using `rbenv` see [rbenv-installer](https://github.com/rbenv/rbenv-installer#rbenv-installer):
+
+```bash
+curl -fsSL https://github.com/rbenv/rbenv-installer/raw/HEAD/bin/rbenv-installer | bash
+```
+
+Then open a new terminal, or "source" the shell initialization script:
+
+```bash
+source ~/.bashrc
+```
+
+Then install Ruby:
+
+```bash
+rbenv install 3.2.2
+```
+
 #### Other Unixes (AIX)
 
 Ruby is sometimes made available as an installable package through third party providers.
@@ -479,7 +459,7 @@ gem install rmagick grpc mimemagic
 
 > **Note:** Those are not installed as part of dependencies because they involve compilation of native code.
 
-### Ruby Gem
+### Ruby Gem: `aspera-cli`
 
 Once you have Ruby and rights to install gems, install the `aspera-cli` gem and its dependencies:
 
@@ -502,7 +482,26 @@ To check if a new version is available (independently of `version_check_days`):
 ascli config check_update
 ```
 
-### FASP Protocol
+#### Gem installation with signature verification
+
+The gem is signed with a private key, and the public certificate is available in the github repository (`certs/aspera-cli-public-cert.pem`).
+When installing the gem, the signature can be optionally verified.
+
+For [secure installation](https://guides.rubygems.org/security/#using-gems), one can install the gem with the public key:
+
+- import the verification certificate:
+
+```bash
+gem cert --add <(curl -Ls https://raw.githubusercontent.com/IBM/aspera-cli/main/certs/aspera-cli-public-cert.pem)
+```
+
+- Then, install the gem:
+
+```bash
+gem install -P MediumSecurity aspera-cli
+```
+
+### FASP Protocol: `ascp`
 
 Most file transfers will be executed using the **FASP** protocol, using `ascp`.
 Only two additional files are required to perform an Aspera Transfer, which are part of Aspera SDK:
@@ -519,7 +518,7 @@ ascli config ascp install
 If a local SDK installation is preferred instead of fetching from internet: one can specify the location of the SDK file:
 
 ```bash
-curl -Lso sdk.zip https://ibm.biz/aspera_sdk
+curl -Lso sdk.zip https://ibm.biz/aspera_transfer_sdk
 ```
 
 ```bash
@@ -549,6 +548,18 @@ Refer to section: [Transfer Agents](#transfer-clients-agents)
 
 > **Note:** No pre-packaged version is provided yet.
 
+#### Gem files and dependencies
+
+The sample script: [examples/build_package.sh](examples/build_package.sh) can be used to download all necessary gems and dependencies in a tar gz.
+
+```console
+$ ./build_package.sh aspera-cli 4.18.0
+
+Archive: aspera-cli-4.18.0-gems.tgz
+```
+
+#### Unix-like
+
 A method to build one is provided here:
 
 The procedure:
@@ -570,7 +581,7 @@ ascli --show-config --fields=sdk_url
 - Download the SDK archive from that URL
 
 ```bash
-curl -Lso sdk.zip https://ibm.biz/aspera_sdk
+curl -Lso sdk.zip https://ibm.biz/aspera_transfer_sdk
 ```
 
 - Transfer those 2 files to the target system
@@ -593,15 +604,51 @@ ascli config ascp install --sdk-url=file:///sdk.zip
 source ~/.rvm/scripts/rvm
 ```
 
-> **Note:** Alternatively, to download all necessary gems in folder `my_gems`, execute:
+#### Windows
+
+Installation without network:
+
+It is essentially the same procedure as installation for Windows with internet, but instead of retrieving files from internet, copy the files from a machine with internet access, and then install from those archives:
+
+- Download the `exe` Ruby installer from <https://rubyinstaller.org/downloads/>
+
+  ```bash
+  v=$(curl -s https://rubyinstaller.org/downloads/|sed -nEe 's|.*(https://.*/releases/download/.*exe).*|\1|p'|head -n 1)
+  curl -o ${v##*/} $v
+  ```
+
+- Create an archive with necessary gems like in previous section
+
+- Download the SDK from: <https://ibm.biz/aspera_transfer_sdk>
+
+- Create a Zip with all those files, and transfer to the target system.
+
+Then, on the target system:
+
+- Unzip the archive
+- Execute the installer:
+
+```bat
+rubyinstaller-devkit-3.2.2-1-x64.exe /silent /currentuser /noicons /dir=C:\aspera-cli
+```
+
+- Install the gems: Extract the gem archive, and then:
+
+```bat
+gem install --force --local *.gem
+```
+
+- Install the SDK
 
 ```bash
-gem install aspera-cli -N -i my_gems
+ascli config ascp install --sdk-url=file:///sdk.zip
 ```
 
+> **Note:** An example of installation script is provided: [docs/install.bat](docs/install.bat)
+
 ### Container
 
-The container image is: [`martinlaurent/ascli`](https://hub.docker.com/r/martinlaurent/ascli).
+The container image is: [`docker.io/martinlaurent/ascli`](https://hub.docker.com/r/docker.io/martinlaurent/ascli).
 The container contains: Ruby, `ascli` and the Aspera Transfer SDK.
 To use the container, ensure that you have `podman` (or `docker`) installed.
 
@@ -615,7 +662,7 @@ podman --version
 Execute this:
 
 ```bash
-podman run --rm --tty --interactive --entrypoint bash martinlaurent/ascli:latest
+podman run --rm --tty --interactive --entrypoint bash docker.io/martinlaurent/ascli:latest
 ```
 
 > **Note:** This command changes the entrypoint to an interactive shell instead of direct execution of `ascli`.
@@ -643,13 +690,13 @@ The entry point is `ascli` and the default command is `help`.
 The container can be executed for individual commands like this: (add `ascli` commands and options at the end of the command line, e.g. `-v` to display the version)
 
 ```bash
-podman run --rm --tty --interactive martinlaurent/ascli:latest
+podman run --rm --tty --interactive docker.io/martinlaurent/ascli:latest
 ```
 
 For more convenience, you may define a shell alias:
 
 ```bash
-alias ascli='podman run --rm --tty --interactive martinlaurent/ascli:latest'
+alias ascli='podman run --rm --tty --interactive docker.io/martinlaurent/ascli:latest'
 ```
 
 Then, you can execute the container like a local command:
@@ -659,7 +706,7 @@ ascli -v
 ```
 
 ```text
-4.17.0
+4.18.1
 ```
 
 In order to keep persistency of configuration on the host, you should specify your user's configuration folder as a volume for the container.
@@ -686,12 +733,12 @@ In this case you need also to specify the shared transfer folder as a volume:
 --volume $HOME/xferdir:/xferfiles
 ```
 
-> **Note:** ascli is run inside the container, so transfers are also executed inside the container and do not have access to host storage by default.
+> **Note:** `ascli` is run inside the container, so transfers are also executed inside the container and do not have access to host storage by default.
 
 And if you want all the above, simply use all the options:
 
 ```bash
-alias asclish="podman run --rm --tty --interactive --user root --env ASCLI_HOME=/home/cliuser/.aspera/ascli --volume $HOME/.aspera/ascli:/home/cliuser/.aspera/ascli --volume $HOME/xferdir:/xferfiles --entrypoint bash martinlaurent/ascli:latest"
+alias asclish="podman run --rm --tty --interactive --user root --env ASCLI_HOME=/home/cliuser/.aspera/ascli --volume $HOME/.aspera/ascli:/home/cliuser/.aspera/ascli --volume $HOME/xferdir:/xferfiles --entrypoint bash docker.io/martinlaurent/ascli:latest"
 ```
 
 ```bash
@@ -714,7 +761,7 @@ Some environment variables can be set for this script to adapt its behavior:
 |----------------|------------------------------------|--------------------------|--------------------------|
 | `ASCLI_HOME` | Configuration folder (persistency) | `$HOME/.aspera/ascli` | `$HOME/.ascli_config` |
 | `docker_args`  | Additional options to `podman`     | &lt;empty&gt;            | `--volume /Users:/Users` |
-| `image`        | Container image name               | `martinlaurent/ascli`    |                          |
+| `image`        | Container image name               | `docker.io/martinlaurent/ascli`    |                          |
 | `version`      | Container image version            | Latest                   | `4.8.0.pre`              |
 
 The wrapping script maps the folder `$ASCLI_HOME` on host to `/home/cliuser/.aspera/ascli` in the container.
@@ -748,8 +795,8 @@ echo 'Local file to transfer' > $xferdir/samplefile.txt
 - First create the image archive:
 
 ```bash
-podman pull martinlaurent/ascli
-podman save martinlaurent/ascli|gzip>ascli_image_latest.tar.gz
+podman pull docker.io/martinlaurent/ascli
+podman save docker.io/martinlaurent/ascli|gzip>ascli_image_latest.tar.gz
 ```
 
 - Then, on air-gapped system:
@@ -787,7 +834,7 @@ dnf install singularity-ce
 Build an image like this:
 
 ```bash
-singularity build ascli.sif docker://martinlaurent/ascli
+singularity build ascli.sif docker://docker.io/martinlaurent/ascli
 ```
 
 Then, start `ascli` like this:
@@ -802,6 +849,124 @@ Or get a shell with access to `ascli` like this:
 singularity shell ascli.sif
 ```
 
+### SSL library
+
+`ascli` uses the Ruby `openssl` gem which uses by default the system's `openssl` library and its CA certificate bundle.
+
+To display the version of **openssl** used in `ascli`:
+
+```bash
+ascli config echo @ruby:OpenSSL::OPENSSL_VERSION --format=text
+```
+
+It is possible to specify to use another SSL library or version by executing:
+
+```bash
+gem install openssl -- --with-openssl-dir=[openssl library folder]
+```
+
+Where `[openssl library folder]` is the path to the folder containing the `lib` and `include` folders of the `openssl` library.
+
+For example, on macOS, to use the `openssl@3` library installed with `brew`:
+
+```bash
+$ openssl version -e|sed -n 's|ENGINESDIR: "\(.*\)/lib[^/]*/.*|\1|p'
+/opt/homebrew/Cellar/openssl@3/3.3.0
+$ gem install openssl -- --with-openssl-dir=/opt/homebrew/Cellar/openssl@3/3.3.0
+```
+
+### SSL CA certificate bundle
+
+SSL certificates are validated using a certificate store, by default it is the one of the system's `openssl` library.
+
+To display trusted certificate store locations:
+
+```bash
+ascli --show-config --fields=cert_stores
+```
+
+Certificates are checked against the [Ruby default certificate store](https://ruby-doc.org/stdlib-3.0.3/libdoc/openssl/rdoc/OpenSSL/X509/Store.html) `OpenSSL::X509::DEFAULT_CERT_FILE` and `OpenSSL::X509::DEFAULT_CERT_DIR`, which are typically the ones of `openssl` on Unix-like systems (Linux, macOS, etc..).
+Ruby's default values can be overridden using env vars: `SSL_CERT_FILE` and `SSL_CERT_DIR`.
+
+One can display those default values:
+
+```bash
+ascli config echo @ruby:OpenSSL::X509::DEFAULT_CERT_DIR --format=text
+ascli config echo @ruby:OpenSSL::X509::DEFAULT_CERT_FILE --format=text
+```
+
+In order to get certificate validation, the CA certificate bundle must be up-to-date.
+Check this repository on how to update the system's CA certificate bundle: [https://github.com/millermatt/osca](https://github.com/millermatt/osca).
+
+For example on RHEL/Rocky Linux:
+
+```bash
+dnf install -y ca-certificates
+update-ca-trust extract
+```
+
+The SSL CA certificate bundle can be specified using option `cert_stores`, which is a list of files or folders.
+By default it uses Ruby's default certificate store.
+
+If you use this option, then default locations are not used.
+Default locations can be added using special value `DEF`.
+The value can be either an `Array` or `String` (path).
+Successive options add paths incrementally.
+All files of a folders are added.
+
+JRuby uses its own implementation and CA bundles.
+
+For example, on Linux to force the use the system's certificate store:
+
+```bash
+--cert-stores=$(openssl version -d|cut -f2 -d'"')/cert.pem
+```
+
+`ascp` also needs to validate certificates when using **WSS** for transfer TCP part (instead of **SSH**).
+
+By default,`ascp` uses an hardcoded root location `OPENSSLDIR`.
+Original `ascp`'s hardcoded locations can be found using:
+
+```bash
+ascli config ascp info --fields=openssldir
+```
+
+E.g. on macOS: `/Library/Aspera/ssl`.
+Then trusted certificates are taken from `[OPENSSLDIR]/cert.pem` and files in `[OPENSSLDIR]/certs`.
+`ascli` overrides the default hardcoded location used by `ascp` for WSS and uses the same locations as specified in `cert_stores` (using the `-i` option of `ascp`).
+
+To update trusted root certificates for `ascli`:
+Display the trusted certificate store locations used by `ascli`.
+Typically done by updating the system's root certificate store.
+
+An up-to-date version of the certificate bundle can also be retrieved with:
+
+```bash
+ascli config echo @uri:https://curl.haxx.se/ca/cacert.pem --format=text
+```
+
+To download that certificate store:
+
+```bash
+ascli config echo @uri:https://curl.haxx.se/ca/cacert.pem --format=text --output=/tmp/cacert.pem
+```
+
+Then, use this store by setting the option `cert_stores` (or env var `SSL_CERT_FILE`).
+
+To trust a specific certificate (e.g. self-signed), **provided that the `CN` is correct**, save the certificate chain to a file:
+
+```bash
+ascli config remote_certificate chain https://localhost:9092 --insecure=yes --output=myserver.pem
+```
+
+> **Note:** Use command `name` to display the remote common name of the remote certificate.
+
+Then, use this file as certificate store (e.g. here, Node API):
+
+```bash
+ascli config echo @uri:https://localhost:9092/ping --cert-stores=myserver.pem
+```
+
 ## Command Line Interface
 
 The command line tool is: ``ascli``
@@ -820,9 +985,9 @@ The `aspera-cli` gem provides a command line interface (CLI) which interacts wit
 
 - Supports commands to Aspera server products (on-premise and SaaS)
 - Any command line **options** (products URL, credentials or any option) can be provided on command line, in configuration file, in env var, in files, ...
-- Supports Commands, Option values and Parameters shortcuts
+- Supports Commands, Options, and Option values shortcuts
 - FASP [Transfer Agents](#transfer-clients-agents) can be: local `ascp`, or Connect Client, or any transfer node
-- Transfer parameters can be altered by modification of [*transfer-spec*](#transfer-specification), this includes requiring multi-session
+- Transfer parameters can be altered by modification of [**transfer-spec**](#transfer-specification), this includes requiring multi-session
 - Allows transfers from products to products, essentially at node level (using the node transfer agent)
 - Supports FaspStream creation (using Node API)
 - Supports **Watchfolder** creation (using Node API)
@@ -856,19 +1021,20 @@ Moreover all `ascp` options are supported either through transfer spec parameter
 ### Command line parsing, Special Characters
 
 `ascli` is typically executed in a shell, either interactively or in a script.
-`ascli` receives its arguments from this shell (through the Operating System).
+`ascli` receives its arguments on the command line.
+The way arguments are parsed and provided to `ascli` depend on the Operating System and shell.
 
 #### Shell parsing for Unix-like systems: Linux, macOS, AIX
 
-Linux command line parsing is easy:
+Linux command line parsing is well defined:
 It is fully documented in the shell's documentation.
 
-On Unix-like environments, this is typically a POSIX shell (bash, zsh, ksh, sh).
+On Unix-like environments, this is typically a POSIX-like shell (bash, zsh, ksh, sh).
 A c-shell (`csh`, `tcsh`) or other shell can also be used.
 In this environment the shell parses the command line, possibly replacing variables, etc...
 See [bash shell operation](https://www.gnu.org/software/bash/manual/bash.html#Shell-Operation).
 The shell builds the list of arguments and then `fork`/`exec` Ruby with that list.
-Ruby receives a list parameters from shell and gives it to `ascli`.
+Ruby receives a list command line arguments from shell and gives it to `ascli`.
 Special character handling (quotes, spaces, env vars, ...) is handled by the shell for any command executed.
 
 #### Shell parsing for Windows
@@ -960,16 +1126,16 @@ Major  Minor  Build  Revision
 -----  -----  -----  --------
 5      1      19041  4046
 
-PS C:\> ascli conf echo  --% @json:'{"k":"v","x":"y"}'
+PS C:\> ascli config echo  --% @json:'{"k":"v","x":"y"}'
 
-PS C:\> ascli conf echo @json:'{"""k""":"""v""","""x""":"""y"""}'
+PS C:\> ascli config echo @json:'{"""k""":"""v""","""x""":"""y"""}'
 ```
 
 > **Note:** The special powershell argument `--%` places powershell in legacy parsing mode.
 
 #### Extended Values (JSON, Ruby, ...)
 
-Some of the `ascli` parameters are expected to be [Extended Values](#extended-value-syntax), i.e. not a simple `String`, but a composite structure (`Hash`, `Array`).
+Some of the values provided to `ascli` (options, **Command Parameters**) are expected to be [Extended Values](#extended-value-syntax), i.e. not a simple `String`, but a composite structure (`Hash`, `Array`).
 Typically, the `@json:` modifier is used, it expects a [JSON](https://www.json.org/) string.
 JSON itself has some special syntax: for example `"` is used to enclose a `String`.
 
@@ -1154,16 +1320,15 @@ ascli config echo @ruby:"{'title'=>ENV['MYTITLE']}" --format=json
 {"title":"Test \" ' & \\"}
 ```
 
-### Commands, Options, Positional Arguments
+### Positional Arguments and Options
 
 Command line arguments are the units of command line typically separated by spaces (the `argv` of C).
 The tokenization of the command line is typically done by the shell, refer to the previous section [Command Line Parsing](#command-line-parsing-special-characters).
 
-`ascli` handles three types of command line arguments:
+`ascli` handles two types of command line arguments:
 
-- Commands
-- Positional Arguments
-- Options
+- **Positional Arguments** : position is significant
+- **Options** : only order is significant, but not position
 
 For example:
 
@@ -1171,18 +1336,24 @@ For example:
 ascli command subcommand --option-name=VAL1 VAL2
 ```
 
-- Executes **command**: `command subcommand`
-- With one **option**: `option_name` and its **value**: `VAL1`
-- The command has one additional **positional argument**: `VAL2`
+- Executes **Command** and its **Command Parameters** (**Positional Arguments**): `command subcommand VAL2`
+- With one **Option**: `option_name` and its **value**: `VAL1`
 
 If the value of a command, option or argument is constrained by a fixed list of values, then it is possible to use a few of the first letters of the value, provided that it uniquely identifies the value.
 For example `ascli config pre ov` is the same as `ascli config preset overview`.
 
-The value of options and arguments is evaluated with the [Extended Value Syntax](#extended-value-syntax).
+The value of **Options** and **Positional Arguments** is evaluated with the [Extended Value Syntax](#extended-value-syntax).
+
+#### Positional Arguments
+
+**Positional Arguments** are either:
 
-#### Commands
+- **Commands**, typically at the beginning
+- **Command Parameters** , e.g. creation data or entity identifier
 
-Commands are typically entity types or verbs to act on those entities.
+When options are removed from the command line, the remaining arguments are typically **Positional Arguments** with a pre-defined order.
+
+**Commands** are typically entity types or verbs to act on those entities.
 Its value is a `String` that must belong to a fixed list of values in a given context.
 
 Example:
@@ -1196,27 +1367,24 @@ ascli config ascp info
 - `ascp` is the second level command: name of the component (singleton)
 - `info` is the third level command: action to be performed
 
-Typically, commands are located at the **beginning** of the command line.
+Typically, **Commands** are located at the **beginning** of the command line.
 Order is significant.
 The provided command must match one of the supported commands in the given context.
 If wrong, or no command is provided when expected, an error message is displayed and the list of supported commands is displayed.
 
-Some sub-commands appear after entity selection, e.g. `ascli aoc admin res node do 8669 browse /`: `browse` is a sub-command of `node`.
-
-#### Positional Arguments
-
-Positional Arguments are typically mandatory values for a command, such as entity creation data.
-
-It could also be designed as an option, but since it is mandatory and typically creation parameters need not be set in a configuration file, then it is better to use a positional argument, and not define specific options.
+Some sub-commands appear after entity selection (identifier), e.g. `ascli aoc admin res node do 8669 browse /`: `browse` is a sub-command of `node`.
 
-The advantages of using a positional argument instead of an option for the same are that the command line is shorter(no option name, just the position) and the value is clearly mandatory.
+**Command Parameters** are typically mandatory values for a command, such as entity creation data or entity identifier.
 
+> **Note:** It could also have been designed as an option.
+But since it is mandatory and typically these data need **not** be set in a configuration file, then it is better designed as a **Command Parameter**, and not designed an additional specific option.
+The advantages of using a **Command Parameter** instead of an option for the same are that the command line is shorter (no option name, just the position) and the value is clearly mandatory.
 The disadvantage is that it is not possible to define a default value in a configuration file or environment variable like for options.
-Nevertheless, [Extended Values](#extended-value-syntax) syntax is supported, so it is possible to retrieve a value from the configuration file or environment variable (using `@preset:`).
+Nevertheless, [Extended Values](#extended-value-syntax) syntax is supported, so it is possible to retrieve a value from the configuration file (using `@preset:`) or environment variable (using `@env:`).
 
-If a Positional Arguments begins with `-`, then either use the `@val:` syntax (see [Extended Values](#extended-value-syntax)), or use the `--` separator (see below).
+If a **Command Parameters** begins with `-`, then either use the `@val:` syntax (see [Extended Values](#extended-value-syntax)), or use the `--` separator (see below).
 
-A few positional arguments are optional, they are located at the end of the command line.
+A few **Command Parameters** are optional, they are located at the end of the command line.
 
 #### Options
 
@@ -1225,13 +1393,15 @@ All options, e.g. `--log-level=debug`, are command line arguments that:
 - Start with `--`
 - Have a name, in lowercase, using `-` as word separator in name  (e.g. `--log-level=debug`)
 - Have a value, separated from name with a `=`
-- Can be used by prefix (avoid), provided that it is unique. E.g. `--log-l=debug` is the same as `--log-level=debug`
+- Can be used by prefix (not recommended), provided that it is unique. E.g. `--log-l=debug` is the same as `--log-level=debug`
+- Is optional on command line (it has a default value or no value)
+- whose position is not significant, but order is significant
 
 Exceptions:
 
 - Some options accept a short form, e.g. `-Ptoto` is equivalent to `--preset=toto`, refer to the manual or `-h`.
 - Some options (flags) don't take a value, e.g. `-N`
-- The special option `--` stops option processing and is ignored, following command line arguments are taken as arguments, including the ones starting with a `-`.
+- The special option `--` stops option processing and is ignored, following command line arguments are taken as **Positional Arguments**, including the ones starting with a `-`.
 
 Example:
 
@@ -1248,6 +1418,7 @@ ascli config echo -- --sample
 Options may have a (hardcoded) default value.
 
 Options can be placed anywhere on command line and are evaluated in order.
+Usually the last value evaluated overrides previous values, but some options are cumulative, e.g. `ts`.
 
 Options are typically optional: to change the default behavior.
 But some are mandatory, so they can be placed in a configuration file, for example: connection information.
@@ -1264,23 +1435,23 @@ Option `show_config` dry runs the configuration, and then returns currently set
 `ascli --show-config` outputs global options only, and `ascli [plugin] --show-config` outputs global and plugin default options.
 In addition, option `--show-config` can be added at the end of any full command line, this displays the options that would be used for the command.
 
-A parameter is typically designed as option if:
+A command line argument is typically designed as option if:
 
 - It is optional, or
-- It is a mandatory parameter that would benefit from being set persistently (i.e. in a configuration file or environment variable, e.g. URL and credentials).
+- It is a mandatory parameter with a default value that would benefit from being set persistently (i.e. in a configuration file or environment variable, e.g. URL and credentials).
 
 ### Interactive Input
 
-Some options and parameters are mandatory and other optional.
-By default, `ascli` will ask for missing mandatory options or parameters for interactive execution.
+Some options and **Command Parameters** are mandatory and other optional.
+By default, `ascli` will ask for missing mandatory options or **Command Parameters** for interactive execution.
 
 The behavior can be controlled with:
 
 - `--interactive=<yes|no>` (default=yes if STDIN is a terminal, else no)
-  - yes : missing mandatory parameters/options are asked to the user
-  - no : missing mandatory parameters/options raise an error message
+  - yes : missing mandatory parameters/arguments are asked to the user
+  - no : missing mandatory parameters/arguments raise an error message
 - `--ask-options=<yes|no>` (default=no)
-  - optional parameters/options are asked to user
+  - optional parameters/arguments are asked to user
 
 ### Output
 
@@ -1303,25 +1474,36 @@ Depending on action, the output will contain:
 #### Format of output
 
 By default, result of type single_object and object_list are displayed using format `table`.
-The table style can be customized with parameter: `table_style` (horizontal, vertical and intersection characters) and is `:.:` by default.
 
-In a table format, when displaying **Objects** (single, or list), by default, sub object are
-flattened (option `flat_hash`). So, object `{"user":{"id":1,"name":"toto"}}` will have attributes: `user.id` and `user.name`.
-Setting `flat_hash` to `false` will only display one field: `user` and value is the sub `Hash`.
-When in flatten mode, it is possible to filter fields by compound field name using dot as separator.
+The table style can be customized with option: `table_style` which expects a `Hash`, options are the ones described in gem [`terminal-table`](https://github.com/tj/terminal-table).
+
+For example, to display a table with thick unicode borders:
 
-Object lists are displayed one per line, with attributes as columns. Single objects are transposed: one attribute per line.
+```bash
+ascli config preset over --table-style=@ruby:'{border: :unicode_thick_edge}'
+```
+
+> **Note:** Other border styles exist, not limited to: `:unicode`, `:unicode_round`.
+
+In a table format, when displaying **Objects** (single, or list), by default, sub object are flattened (option `flat_hash`).
+For example, object `{"user":{"id":1,"name":"toto"}}` will have attributes: `user.id` and `user.name`.
+Setting option `flat_hash` to `false` will only display one field: `user` and value is the sub `Hash`.
+When in flatten mode, it is possible to filter fields using the option `fields` using the compound field name using `.` (dot) as separator.
+
+Object lists are displayed one per line, with attributes as columns.
+Single objects (or tables with a single result) are transposed: one attribute per line.
 If transposition of single object is not desired, use option: `transpose_single` set to `no`.
 
-The style of output can be set using the `format` parameter, supporting:
+The style of output can be set using the `format` option, supporting:
 
+- `table` : Text table (default)
 - `text` : Value as String
-- `table` : Text table
 - `ruby` : Ruby code
 - `json` : JSON code
 - `jsonpp` : JSON pretty printed
 - `yaml` : YAML
 - `csv` : Comma Separated Values
+- `image` : Image URL or Image data
 
 #### Verbosity of output
 
@@ -1342,31 +1524,31 @@ To hide secrets from output, set option `show_secrets` to `no`.
 
 #### Option: `fields`: Selection of output object properties
 
-By default, a table output will display one line per entry, and columns for each properties.
-Depending on the command, columns may include by default all properties, or only some selected properties.
+By default, a `table` output format will display one line per entry, and columns for each fields (attributes, properties).
+Depending on the command, columns may include by default all fields, or only some selected fields.
 It is possible to define specific columns to be displayed, by setting the `fields` option.
 
-The `fields` option can be either a comma separated list, or an extended value array.
+The `fields` option is a list that can be either a comma separated list or an extended value `Array`.
 
-Elements of the list can be:
+Individual elements of the list can be:
 
-- `DEF` : default display of columns (that's the default, when not set)
-- `ALL` : all columns available
-- `-`**property** : remove property from the current list
 - **property** : add property to the current list
-- A Ruby `RegEx` : using `@ruby:'/.../'`
+- `-`**property** : remove property from the current list
+- `DEF` : default list of properties (that's the default, when not set)
+- `ALL` : all properties
+- A Ruby `RegEx` : using `@ruby:'/.../'`, or `@re:...` add those matching to the list
 
 Examples:
 
-- `a,b,c` : the list of attributes specified as a comma separated list
-- `@json:'["a","b","c"]'` : Array extended value: same as above
-- `DEF,-a,b` : default property list, remove `a` and add `b`
+- `a,b,c` : the list of attributes specified as a comma separated list (overrides the all default)
+- `@json:'["a","b","c"]'` : `Array` extended value: same as above
+- `b,DEF,-a` : default property list, remove `a` and add `b` in first position
 - `@ruby:'/^server/'` : Display all properties whose name begin with `server`
 
 #### Option: `select`
 
 Table output (`object_list`) can be filtered using option `select`.
-This parameter is either a `Hash` or `Proc`.
+This option is either a `Hash` or `Proc`.
 The `Proc` takes as argument a line (`Hash`) in the table and is a Ruby lambda expression that returns `true` or `false`.
 
 Example:
@@ -1384,7 +1566,7 @@ ascli aoc admin res user list --fields=name,email,ats_admin --query=@json:'{"sor
 +-------------------------------+----------------------------------+-----------+
 ```
 
-> **Note:** `select` filters elements from the result of command, while the `query` parameters gives filtering parameters to the API when listing elements.
+> **Note:** Option `select` filters elements from the result of command, while the `query` option gives filtering parameters to the API when listing elements.
 
 In above example, the same result is obtained with option:
 
@@ -1440,7 +1622,8 @@ The following decoders are supported:
 | `re`     | String   | Regexp  | Ruby Regular Expression (short for `@ruby:/.../`) |
 | `ruby`   | String   | Any     | Execute specified Ruby code |
 | `secret` | None     | String  | Ask password interactively (hides input) |
-| `stdin`  | None     | String  | Read from stdin (no value on right) |
+| `stdin`  | None     | String  | Read from stdin in text mode (no value on right) |
+| `stdbin` | None     | String  | Read from stdin in binary mode (no value on right) |
 | `uri`    | String   | String  | Read value from specified URL, e.g. `--fpac=@uri:http://serv/f.pac` |
 | `val`    | String   | String  | Prevent decoders on the right to be decoded. e.g. `--key=@val:@file:foo` sets the option `key` to value `@file:foo`. |
 | `yaml`   | String   | Any     | Decode YAML |
@@ -1575,44 +1758,46 @@ Temporary files are deleted at the end of execution unless option: `clean_temp`
 
 ### Configuration file
 
-On the first execution of `ascli`, an empty configuration file is created in the configuration folder.
-Nevertheless, there is no mandatory information required in this file, the use of it is optional as any option can be provided on the command line.
+On the first execution of `ascli`, an empty configuration file is created in the configuration folder (`ascli config folder`).
+There is no mandatory information required in this file.
+The use of it is optional as any option can be provided on the command line.
 
-Although the file is a standard YAML file, `ascli` provides commands to read and modify it using the `config` command.
+Although the file is a standard `YAML` file, `ascli` provides commands to read and modify it using the `config` command.
 
-All options for `ascli` can be set on command line, or by env vars, or using [Option Preset](#option-preset)' in the configuration file.
+All options for `ascli` can be set on command line, or by env vars, or using [Option Preset](#option-preset) in the configuration file.
 
-A configuration file provides a way to define default values, especially for authentication parameters, thus avoiding to always having to specify those parameters on the command line.
+A configuration file provides a way to define default values, especially for authentication options, thus avoiding to always having to specify those options on the command line.
 
-The default configuration file is: `$HOME/.aspera/ascli/config.yaml` (this can be overridden with option `--config-file=path` or equivalent env var).
+The default configuration file is: `$HOME/.aspera/ascli/config.yaml` (this can be overridden with option `--config-file=path` or its env var).
 
-The configuration file is simply a catalog of pre-defined lists of options, called: [Option Preset](#option-preset)'. Then, instead of specifying some common options on the command line (e.g. address, credentials), it is possible to invoke the ones of a [Option Preset](#option-preset)' (e.g. `mypreset`) using the option: `-Pmypreset` or `--preset=mypreset`.
+The configuration file is a catalog of named lists of options, called: [Option Preset](#option-preset).
+Then, instead of specifying some common options on the command line (e.g. address, credentials), it is possible to invoke the ones of a [Option Preset](#option-preset) (e.g. `mypreset`) using the option `preset`: `--preset=mypreset` or its shortcut: `-Pmypreset`.
 
 #### Option Preset
 
-A [Option Preset](#option-preset)' is simply a collection of parameters and their associated values in a named section in the configuration file.
+A [Option Preset](#option-preset) is a collection of options and their associated values in a named section in the configuration file.
 
-A named [Option Preset](#option-preset)' can be modified directly using `ascli`, which will update the configuration file :
+A named [Option Preset](#option-preset) can be modified directly using `ascli`, which will update the configuration file :
 
 ```bash
 ascli config preset set|delete|show|initialize|update <option preset>
 ```
 
-The command `update` allows the easy creation of [Option Preset](#option-preset)' by simply providing the options in their command line format, e.g. :
+The command `update` allows the easy creation of [Option Preset](#option-preset) by simply providing the options in their command line format, e.g. :
 
 ```bash
 ascli config preset update demo_server --url=ssh://demo.asperasoft.com:33001 --username=asperaweb --password=my_password_here --ts=@json:'{"precalculate_job_size":true}'
 ```
 
-- This creates a [Option Preset](#option-preset)' `demo_server` with all provided options.
+- This creates a [Option Preset](#option-preset) `demo_server` with all provided options.
 
-The command `set` allows setting individual options in a [Option Preset](#option-preset)'.
+The command `set` allows setting individual options in a [Option Preset](#option-preset).
 
 ```bash
 ascli config preset set demo_server password my_password_here
 ```
 
-The command `initialize`, like `update` allows to set several parameters at once, but it deletes an existing configuration instead of updating it, and expects a [`Hash` Extended Value](#extended-value-syntax).
+The command `initialize`, like `update` allows to set several options at once, but it deletes an existing configuration instead of updating it, and expects a [`Hash` Extended Value](#extended-value-syntax).
 
 ```bash
 ascli config preset initialize demo_server @json:'{"url":"ssh://demo.asperasoft.com:33001","username":"asperaweb","password":"my_pass_here","ts":{"precalculate_job_size":true}}'
@@ -1624,7 +1809,7 @@ A full terminal based overview of the configuration can be displayed using:
 ascli config preset over
 ```
 
-A list of [Option Preset](#option-preset)' can be displayed using:
+A list of [Option Preset](#option-preset) can be displayed using:
 
 ```bash
 ascli config preset list
@@ -1647,6 +1832,15 @@ ascli config preset over
 ascli config preset list
 ```
 
+It is possible to load a [Option Preset](#option-preset) from within another [Option Preset](#option-preset) using the `preset` option.
+For example if `pcommon` is a preset with common options, and `pspecific` is a preset with specific options, then `pspecific` can load `pcommon` using:
+
+```bash
+ascli config preset set pspecific preset pcommon
+```
+
+When `pspecific` is loaded, then cumulative option `preset` will be set and it will also load `pcommon`.
+
 #### Special Option Preset: `config`
 
 This preset name is reserved and contains a single key: `version`. This is the version of `ascli` which created the file.
@@ -1686,7 +1880,7 @@ The default preset for `config` is read for any plugin invocation, this allows s
 When `ascli` starts, it looks for the `default` Option Preset and checks the value for `config`.
 If set, it loads the options independently of the plugin used.
 
-> **Note:** If no global default is set by the user, `ascli` will use `global_common_defaults` when setting global parameters (e.g. `config ascp use`)
+> **Note:** If no global default is set by the user, `ascli` will use `global_common_defaults` when setting global options (e.g. `config ascp use`)
 >
 > **Note:** If you don't know the name of the global preset, you can use `GLOBAL` to refer to it.
 
@@ -1735,6 +1929,8 @@ detect https://faspex4.example.com/path
 detect https://faspex5.example.com/path
 detect https://node.example.com/path
 detect https://shares.example.com/path shares
+detect https://tst.example.com/path faspio
+detect https://tst.example.com/path httpgw
 detect my_org aoc
 doc
 doc transfer-parameters
@@ -1760,10 +1956,11 @@ gem path
 gem version
 genkey my_key
 genkey my_key 4096
+image https://eudemo.asperademo.com/wallpaper.jpg
 initdemo
 open
-plugin create my_command
-plugin list
+plugins create my_command
+plugins list
 preset delete conf_name
 preset initialize conf_name @json:'{"p1":"v1","p2":"v2"}'
 preset list
@@ -1813,17 +2010,17 @@ demo_server:
 We can see here:
 
 - The configuration was created with `ascli` version 0.3.7
-- The default [Option Preset](#option-preset)' to load for `server` plugin is : `demo_server`
-- The [Option Preset](#option-preset)' `demo_server` defines some parameters: the URL and credentials
-- The default [Option Preset](#option-preset)' to load in any case is : `cli_default`
+- The default [Option Preset](#option-preset) to load for `server` plugin is : `demo_server`
+- The [Option Preset](#option-preset) `demo_server` defines some options: the URL and credentials
+- The default [Option Preset](#option-preset) to load in any case is : `cli_default`
 
-Two [Option Preset](#option-preset)' are reserved:
+Two [Option Preset](#option-preset) are reserved:
 
 - `config` contains a single value: `version` showing the version used to create the configuration file.
   It is used to check compatibility.
-- `default` is reserved to define the default [Option Preset](#option-preset)' name used for known plugins.
+- `default` is reserved to define the default [Option Preset](#option-preset) name used for known plugins.
 
-The user may create as many [Option Preset](#option-preset)' as needed. For instance, a particular [Option Preset](#option-preset)' can be created for a particular application instance and contain URL and credentials.
+The user may create as many [Option Preset](#option-preset) as needed. For instance, a particular [Option Preset](#option-preset) can be created for a particular application instance and contain URL and credentials.
 
 Values in the configuration also follow the [Extended Value Syntax](#extended-value-syntax).
 
@@ -1833,7 +2030,7 @@ Values in the configuration also follow the [Extended Value Syntax](#extended-va
 ascli config preset set my_aoc_org private_key @val:@file:"$HOME/.aspera/ascli/my_private_key"
 ```
 
-This creates the [Option Preset](#option-preset)':
+This creates the [Option Preset](#option-preset):
 
 ```yaml
 my_aoc_org:
@@ -1849,20 +2046,20 @@ Some options are global, some options are available only for some plugins. (the
 Options are loaded using this algorithm:
 
 - If option `--no-default` (or `-N`) is specified, then no default value is loaded for the plugin
-- Else it looks for the name of the plugin as key in section `default`, the value is the name of the default [Option Preset](#option-preset)' for it, and loads it.
-- If option `--preset=<name or extended value hash>` is specified (or `-Pxxxx`), this reads the [Option Preset](#option-preset)' specified from the configuration file, or if the value is a `Hash`, it uses it as options values.
+- Else it looks for the name of the plugin as key in section `default`, the value is the name of the default [Option Preset](#option-preset) for it, and loads it.
+- If option `--preset=<name or extended value hash>` is specified (or `-Pxxxx`), this reads the [Option Preset](#option-preset) specified from the configuration file, or if the value is a `Hash`, it uses it as options values.
 - Environment variables are evaluated
 - Command line options are evaluated
 
-Parameters are evaluated in the order of command line.
+Options are evaluated in the order of command line.
 
-To avoid loading the default [Option Preset](#option-preset)' for a plugin, use: `-N`
+To avoid loading the default [Option Preset](#option-preset) for a plugin, use: `-N`
 
-On command line, words in parameter names are separated by a dash (`-`).
+On command line, words in option names are separated by a dash (`-`).
 In configuration file, separator is an underscore.
 E.g. `--xxx-yyy` on command line gives `xxx_yyy` in configuration file.
 
-The main plugin name is `config`, so it is possible to define a default [Option Preset](#option-preset)' for the main plugin with:
+The main plugin name is `config`, so it is possible to define a default [Option Preset](#option-preset) for the main plugin with:
 
 ```bash
 ascli config preset set cli_default interactive no
@@ -1872,7 +2069,7 @@ ascli config preset set cli_default interactive no
 ascli config preset set default config cli_default
 ```
 
-A [Option Preset](#option-preset)' value can be removed with `unset`:
+A [Option Preset](#option-preset) value can be removed with `unset`:
 
 ```bash
 ascli config preset unset cli_default interactive
@@ -1892,7 +2089,7 @@ ascli -N --preset=@json:'{"url":"_url_here_","password":"my_password_here","user
 
 #### Wizard
 
-The wizard is a command that asks the user for information and creates a [Option Preset](#option-preset)' with the provided information.
+The wizard is a command that asks the user for information and creates a [Option Preset](#option-preset) with the provided information.
 
 It takes an optional argument: the URL of the application, and an **option**: `query` which allows limiting the detection to a given plugin.
 
@@ -1914,7 +2111,7 @@ ascli shares repo browse / --url=https://10.25.0.6 --username=john --password=my
 
 This can also be provisioned in a configuration file:
 
-- Build [Option Preset](#option-preset)'
+- Build [Option Preset](#option-preset)
 
 ```bash
 ascli config preset set shares06 url https://10.25.0.6
@@ -1934,7 +2131,7 @@ or
 ascli config preset update shares06 --url=https://10.25.0.6 --username=john --password=my_password_here
 ```
 
-- Define this [Option Preset](#option-preset)' as the default [Option Preset](#option-preset)' for the specified plugin (`shares`)
+- Define this [Option Preset](#option-preset) as the default [Option Preset](#option-preset) for the specified plugin (`shares`)
 
 ```bash
 ascli config preset set default shares shares06
@@ -1946,7 +2143,7 @@ ascli config preset set default shares shares06
 ascli config preset overview
 ```
 
-- Execute a command on the shares application using default parameters
+- Execute a command on the shares application using default options
 
 ```bash
 ascli shares repo browse /
@@ -2039,7 +2236,7 @@ The lookup is done by comparing the service URL and username (or access key).
 
 #### Securing passwords and secrets
 
-A passwords can be saved in clear in a [Option Preset](#option-preset)' together with other account information (URL, username, etc...).
+A passwords can be saved in clear in a [Option Preset](#option-preset) together with other account information (URL, username, etc...).
 Example:
 
 ```bash
@@ -2060,25 +2257,31 @@ ascli config vault create myconf @json:'{"password":"my_password_here"}'
 
 ### Private Key
 
-Some applications allow the user to be authenticated using a private key (Server, AoC, Faspex5, ...).
-It consists in using a pair of keys: the private key and its associated public key.
-The same key can be used for multiple applications.
-Technically, a private key contains the public key, which can be extracted from it.
-The file containing the private key can optionally be protected by a passphrase.
+Some Aspera applications allow the user to be authenticated using [Public Key Cryptography](https://en.wikipedia.org/wiki/Public-key_cryptography):
+
+- for SSH: Server
+- for OAuth JWT: AoC, Faspex5, Faspex, Shares
+
+It consists in using a pair of associated keys: a private key and a public key.
+The same pair can be used for multiple applications.
+The file containing the private key (key pair) can optionally be protected by a passphrase.
 If the key is protected by a passphrase, then it will be prompted when used.
 (some plugins support option `passphrase`)
 
-The following commands use the shell variable `PRIVKEYFILE`.
+The following sample commands use the shell variable `KEY_PAIR_PATH`.
 Set it to the desired safe location of the private key.
-Typically, located in folder `$HOME/.ssh` or `$HOME/.aspera/ascli`:
+Typically, located in folder `$HOME/.ssh` or `$HOME/.aspera/ascli`.
+For example:
 
 ```bash
-PRIVKEYFILE=~/.aspera/ascli/my_private_key
+KEY_PAIR_PATH=~/.aspera/ascli/my_private_key
 ```
 
 Several methods can be used to generate a key pair.
 
-The format expected for private keys is [PEM](https://en.wikipedia.org/wiki/Privacy-Enhanced_Mail).
+The format expected for keys is [PEM](https://en.wikipedia.org/wiki/Privacy-Enhanced_Mail).
+
+If another format is used, such as `DER`, it can be converted to `PEM`, e.g. using `openssl`.
 
 #### `ascli` for key generation
 
@@ -2087,21 +2290,13 @@ For convenience, the public key is also extracted with extension `.pub`.
 The key is not passphrase protected.
 
 ```bash
-ascli config genkey ${PRIVKEYFILE} 4096
+ascli config genkey ${KEY_PAIR_PATH} 4096
 ```
 
-> **Note:** `ascli` uses the `openssl` library.
-
 To display the public key of a private key:
 
 ```bash
-ascli config pubkey @file:${PRIVKEYFILE}
-```
-
-To display the version of **openssl** used in `ascli`:
-
-```bash
-ascli config echo @ruby:OpenSSL::OPENSSL_VERSION --format=text
+ascli config pubkey @file:${KEY_PAIR_PATH}
 ```
 
 #### `ssh-keygen`
@@ -2109,16 +2304,16 @@ ascli config echo @ruby:OpenSSL::OPENSSL_VERSION --format=text
 Both private and public keys are generated, option `-N` is for passphrase.
 
 ```bash
-ssh-keygen -t rsa -b 4096 -m PEM -N '' -f ${PRIVKEYFILE}
+ssh-keygen -t rsa -b 4096 -m PEM -N '' -f ${KEY_PAIR_PATH}
 ```
 
 #### `openssl`
 
-To generate a private key with a passphrase the following can be used on any system:
+To generate a key pair with a passphrase the following can be used on any system:
 
 ```bash
-openssl genrsa -passout pass:_passphrase_here_ -out ${PRIVKEYFILE} 4096
-openssl rsa -pubout -in ${PRIVKEYFILE} -out ${PRIVKEYFILE}.pub
+openssl genrsa -passout pass:_passphrase_here_ -out ${KEY_PAIR_PATH} 4096
+openssl rsa -pubout -in ${KEY_PAIR_PATH} -out ${KEY_PAIR_PATH}.pub
 ```
 
 `openssl` is sometimes compiled to support option `-nodes` (no DES, i.e. no passphrase, e.g. on macOS).
@@ -2127,112 +2322,55 @@ In that case, add option `-nodes` instead of `-passout pass:_passphrase_here_` t
 If option `-nodes` is not available, the passphrase can be removed using this method:
 
 ```bash
-openssl rsa -passin pass:_passphrase_here_ -in ${PRIVKEYFILE} -out ${PRIVKEYFILE}.no_des
-mv ${PRIVKEYFILE}.no_des ${PRIVKEYFILE}
+openssl rsa -passin pass:_passphrase_here_ -in ${KEY_PAIR_PATH} -out ${KEY_PAIR_PATH}.no_des
+mv ${KEY_PAIR_PATH}.no_des ${KEY_PAIR_PATH}
 ```
 
 To change (or add) the passphrase for a key do:
 
 ```bash
-openssl rsa -des3 -in ${PRIVKEYFILE} -out ${PRIVKEYFILE}.with_des
-mv ${PRIVKEYFILE}.with_des ${PRIVKEYFILE}
+openssl rsa -des3 -in ${KEY_PAIR_PATH} -out ${KEY_PAIR_PATH}.with_des
+mv ${KEY_PAIR_PATH}.with_des ${KEY_PAIR_PATH}
 ```
 
-### SSL CA certificate bundle
-
-The SSL CA certificate bundle can be specified using option `cert_stores`, which is a list of files or folders, by default it uses Ruby's default certificate store.
-
-To display trusted certificate store locations:
-
-```bash
-ascli --show-config --fields=cert_stores
-```
-
-Use option `cert_stores` to modify the locations of certificate stores (files or folders).
-If you use this option, then default locations are not used.
-Default locations can be added using special value `DEF`.
-The value can be either an `Array` or `String` (path).
-Successive options add paths incrementally.
-All files of a folders are added.
+#### Using an application to generate a key pair
 
-`ascli` uses the Ruby `openssl` gem.
-By default it uses the system's `openssl` library, but JRuby uses its own implementation.
+Many applications are available, including on internet, to generate key pairs.
+For example: <https://cryptotools.net/rsagen>
 
-For example, on Linux to use the system's certificate store:
+> **Note:** Be careful that private keys are sensitive information, and shall be kept secret (like a password), so using online tools is risky.
 
-```bash
---cert-stores=$(openssl version -d|cut -f2 -d'"')/cert.pem
-```
-
-Certificates are checked against the [Ruby default certificate store](https://ruby-doc.org/stdlib-3.0.3/libdoc/openssl/rdoc/OpenSSL/X509/Store.html) `OpenSSL::X509::DEFAULT_CERT_FILE` and `OpenSSL::X509::DEFAULT_CERT_DIR`, which are typically the ones of `openssl` on Unix-like systems (Linux, macOS, etc..).
-Ruby's default values can be overridden using env vars: `SSL_CERT_FILE` and `SSL_CERT_DIR`.
-
-One can display those default values:
-
-```bash
-ascli config echo @ruby:OpenSSL::X509::DEFAULT_CERT_DIR --format=text
-ascli config echo @ruby:OpenSSL::X509::DEFAULT_CERT_FILE --format=text
-```
-
-`ascp` also needs to validate certificates when using **WSS** for transfer TCP part (instead of SSH).
-
-By default,`ascp` uses an hardcoded root location `OPENSSLDIR`.
-Original `ascp`'s hardcoded locations can be found using:
-
-```bash
-ascli config ascp info --fields=openssldir
-```
-
-E.g. on macOS: `/Library/Aspera/ssl`.
-Then trusted certificates are taken from `[OPENSSLDIR]/cert.pem` and files in `[OPENSSLDIR]/certs`.
-`ascli` overrides the default hardcoded location used by `ascp` for WSS and uses the same locations as specified in `cert_stores` (using the `-i` option of `ascp`).
+### Image and video thumbnails
 
-To update trusted root certificates for `ascli`:
-Display the trusted certificate store locations used by `ascli`.
-Typically done by updating the system's root certificate store.
+`ascli` can display thumbnails for images and videos in the terminal.
+This is available:
 
-An up-to-date version of the certificate bundle can also be retrieved with:
+- in the `thumbnail` command of `node` when using **gen4/access key** API.
+- when using the `show` command of `preview` plugin.
+- `coffee` and `image` commands of `config` plugin.
+- any displayed value which is an url to image can be displayed with option `format` set to `image`
 
-```bash
-ascli config echo @uri:https://curl.haxx.se/ca/cacert.pem --format=text
-```
+The following options can be specified in the option `image`:
 
-To download that certificate store:
+| Option     | Type    | Description |
+|------------|---------|-------------|
+| reserve    | Integer | Lines reserved to display a status |
+| text       | Bool    | Display text instead of image|
+| double     | Bool    | Display double text resolution (half characters) |
+| font_ratio | Float   | Font height/width ratio in terminal |
 
 ```bash
-ascli config echo @uri:https://curl.haxx.se/ca/cacert.pem --format=text --output=/tmp/cacert.pem
+ascli config image https://eudemo.asperademo.com/wallpaper.jpg --ui=text --image=@json:'{"text":true}'
 ```
 
-Then, use this store by setting the option `cert_stores` (or env var `SSL_CERT_FILE`).
-
-To trust a specific certificate (e.g. self-signed), **provided that the `CN` is correct**, save the certificate chain to a file:
-
 ```bash
-ascli config remote_certificate chain https://localhost:9092 --insecure=yes --output=myserver.pem
+curl -so - https://eudemo.asperademo.com/wallpaper.jpg | ascli config image @stdbin:
 ```
 
-> **Note:** Use command `name` to display the remote common name of the remote certificate.
-
-Then, use this file as certificate store (e.g. here, Node API):
-
 ```bash
-ascli config echo @uri:https://localhost:9092/ping --cert-stores=myserver.pem
+echo -n https://eudemo.asperademo.com/wallpaper.jpg | ascli config image @uri:@stdin:
 ```
 
-### Image and video thumbnails
-
-`ascli` can display thumbnails for images and videos in the terminal.
-This is available with the `thumbnail` command of `node` when using **gen4/access key** API.
-It's also available when using the `show` command of `preview` plugin.
-
-The following options can be specified in the option `query`:
-
-| Option     | Description |
-|------------|-------------|
-| text       | Display text instead of image (Bool) |
-| double     | Display double text resolution (half characters) (Bool) |
-| font_ratio | Font height/width ratio in terminal (Float) |
-
 ### Graphical Interactions: Browser and Text Editor
 
 Some actions may require the use of a graphical tool:
@@ -2250,9 +2388,7 @@ It is also possible to force the graphical mode with option --ui :
 
 The gem is equipped with traces, mainly for debugging and learning APIs.
 By default logging level is `warn` and the output channel is `stderr`.
-To increase debug level, use parameter `log_level` (e.g. using command line `--log-level=xx`, env var `ASCLI_LOG_LEVEL`, or a parameter in the configuration file).
-
-It is also possible to activate traces before log facility initialization using env var `ASCLI_LOG_LEVEL`.
+To increase debug level, use option `log_level` (e.g. using command line `--log-level=xx`, env var `ASCLI_LOG_LEVEL`, or an [Option Preset](#option-preset)).
 
 By default passwords and secrets are removed from logs.
 Use option `log_secrets` set to `yes` to reveal secrets in logs.
@@ -2332,21 +2468,33 @@ Refer to the following sections.
 
 #### Proxy for REST and HTTP Gateway
 
-REST API calls and transfers based on HTTP Gateway both use Ruby `Net::HTTP` gem.
+REST API calls and transfers based on HTTP Gateway both use Ruby's `Net::HTTP` class.
+Refer to [Ruby find proxy](https://rubyapi.org/3.0/o/uri/generic#method-i-find_proxy).
 
-There are two possibilities to define an HTTP proxy to be used when Ruby HTTP is used.
+When Ruby HTTP is used, there are two possibilities to define an HTTP proxy to be used .
 
-The `http_proxy` environment variable (**lower case**, preferred) can be set to the URL of the proxy.
+The `http_proxy` environment variable (**lower case**) can be set to the **URL** of the proxy (with optional credentials).
+Syntax is: `(http|https)://[user:password@]host:port`.
 E.g. `http://myproxy.org.net:3128`.
-Refer to [Ruby find proxy](https://rubyapi.org/3.0/o/uri/generic#method-i-find_proxy).
 
-> **Note:** Ruby expects a URL and `myproxy.org.net:3128` alone is **not** accepted.
+> **Note:** Ruby expects a URL and `myproxy.org.net:3128` alone is **not** valid.
+
+Credentials for proxy are optional but can also be specified:
 
 ```bash
-export http_proxy=http://proxy.example.com:3128
+export http_proxy=http://user:password@proxy.example.com:3128
+```
+
+Option `http_proxy` does the same (set env var) but on command line:
+
+```bash
+ascli --http-proxy=http://username:password@host:port ...
 ```
 
 Alternatively, the `fpac` option (function for proxy auto config) can be set to a [Proxy Auto Configuration (PAC)](https://en.wikipedia.org/wiki/Proxy_auto-config) javascript value.
+
+Note that proxy credentials are not supported in PAC files.
+
 To read the script from a URL (`http:`, `https:` and `file:`), use prefix: `@uri:`.
 A minimal script can be specified to define the use of a local proxy:
 
@@ -2381,7 +2529,7 @@ ascli config proxy_check --fpac=@uri:http://server/proxy.pac http://www.example.
 PROXY proxy.example.com:8080
 ```
 
-If the proxy requires credentials, then use option `proxy_credentials` with username and password provided as an `Array`:
+If the proxy found with the PAC requires credentials, then use option `proxy_credentials` with username and password provided as an `Array`:
 
 ```bash
 ascli --proxy-credentials=@json:'["__username_here__","__password_here__"]' ...
@@ -2397,7 +2545,7 @@ Only supported with the `direct` agent: To specify a proxy for legacy HTTP fallb
 
 #### FASP proxy (forward) for transfers
 
-To specify a FASP proxy (forward), set the [*transfer-spec*](#transfer-specification) parameter: `proxy` (only supported with the `direct` agent).
+To specify a FASP proxy (forward), set the [**transfer-spec**](#transfer-specification) parameter: `proxy` (only supported with the `direct` agent).
 
 For example, for an Aspera forward proxy not encrypted (HTTP) without authentication running on port 9091, the option would be:
 
@@ -2413,7 +2561,20 @@ Or, alternatively, (prefer transfer spec like above, generally):
 
 ### FASP configuration
 
-The `config` plugin also allows specification for the use of a local FASP **client**.
+`ascli` uses one of the transfer agents to execute transfers.
+
+By default it uses the `direct` agent, which is basically a local `ascp`.
+Nevertheless, `ascli` does not come with `ascp` installed.
+This is the reason why it is advised to install the Aspera Transfer SDK during installation (`ascli config ascp install`).
+
+By default, `ascli` uses the `ascp` binary found in **well known locations**, i.e. typical Aspera product installation paths.
+
+The way to specify the location of `ascp` is to use either options:
+
+- `ascp_path`
+- `use_product`
+
+The `config` plugin allows to find and specify the location of `ascp`.
 It provides the following commands for `ascp` subcommand:
 
 - `show` : shows the path of `ascp` used
@@ -2447,9 +2608,9 @@ ascli config ascp info
 
 By default, `ascli` uses any found local product with `ascp`, including Transfer SDK.
 
-To temporarily use an alternate `ascp` path use option `ascp_path` (`--ascp-path=`)
+To override and use an alternate `ascp` path use option `ascp_path` (`--ascp-path=`)
 
-For a permanent change, the command `config ascp use` sets the same parameter for the global default.
+For a permanent change, the command `config ascp use` sets the same option for the global default.
 
 Using a POSIX shell:
 
@@ -2477,7 +2638,10 @@ Saved to default global preset global_common_defaults
 
 If the path has spaces, read section: [Shell and Command line parsing](#command-line-parsing-special-characters).
 
-#### List locally installed Aspera Transfer products
+If option `ascp_path` is not set, then the product identified with option `use_product` is used.
+
+If `use_product` is not set, then the first product found is used,
+this is equivalent to using option: `--use-product=FIRST`.
 
 Locally installed Aspera products can be listed with:
 
@@ -2496,10 +2660,6 @@ ascli config ascp products list
 +---------------------------------------+----------------------------------------+
 ```
 
-#### Selection of local client for `ascp` for [`direct`](#agent-direct) agent
-
-If no `ascp` is selected, this is equivalent to using option: `--use-product=FIRST`.
-
 Using the option `use_product` finds the `ascp` binary of the selected product.
 
 To permanently use the `ascp` of a product:
@@ -2556,12 +2716,12 @@ Downloaded: IBMAsperaConnectInstaller-3.11.2.63.dmg
 
 Some of the actions on Aspera Applications lead to file transfers (upload and download) using the FASP protocol (`ascp`).
 
-When a transfer needs to be started, a [*transfer-spec*](#transfer-specification) has been internally prepared.
-This [*transfer-spec*](#transfer-specification) will be executed by a transfer client, here called **Transfer Agent**.
+When a transfer needs to be started, a [**transfer-spec**](#transfer-specification) has been internally prepared.
+This [**transfer-spec**](#transfer-specification) will be executed by a transfer client, here called **Transfer Agent**.
 
-There are currently 3 agents, set with option `transfer`:
+The following agents are supported and selected with option `transfer`:
 
-- [`direct`](#agent-direct) : execution of `ascp`
+- [`direct`](#agent-direct) : direct execution of `ascp` (local)
 - [`trsdk`](#agent-transfer-sdk) : use of Aspera Transfer SDK (local)
 - [`connect`](#agent-connect-client) : use Connect Client (local)
 - [`alpha`](#agent-desktop-client) : use the new Desktop Client (local)
@@ -2572,7 +2732,7 @@ There are currently 3 agents, set with option `transfer`:
 For example, a node agent executing an **upload**, or **package send** operation
 will effectively push files to the related server from the agent node.
 
-`ascli` standardizes on the use of a [*transfer-spec*](#transfer-specification) instead of **native** `ascp` options to provide parameters for a transfer session, as a common method for those three Transfer Agents.
+`ascli` standardizes on the use of a [**transfer-spec**](#transfer-specification) instead of **native** `ascp` options to provide parameters for a transfer session, as a common method for those three Transfer Agents.
 
 Specific options for agents are provided with option `transfer_info`, cumulatively.
 
@@ -2583,7 +2743,7 @@ This is the default agent for `ascli` (option `--transfer=direct`).
 `ascli` will search locally installed Aspera products, including SDK, and use `ascp` from that component.
 Refer to section [FASP](#fasp-configuration).
 
-The `transfer_info` option accepts the following optional parameters to control multi-session, Web Socket Session and Resume policy:
+The `transfer_info` option accepts the following optional parameters to control multi-session, Web Socket Session, Resume policy and add any argument to `ascp`:
 
 | Name                   | Type  | Description |
 |------------------------|-------|-------------|
@@ -2607,7 +2767,7 @@ max( sleep_max , sleep_initial * sleep_factor ^ iter_index )
 ```
 
 By default, Ruby's root CA store is used to validate any HTTPS endpoint used by `ascp` (e.g. WSS).
-In order to use a custom certificate store, use the `trusted_certs` parameter.
+In order to use a custom certificate store, use the `trusted_certs` option.
 To use `ascp`'s default, use option: `--transfer-info=@json:'{"trusted_certs":null}'`.
 
 Some transfer errors are considered **retry-able** (e.g. timeout) and some other not (e.g. wrong password).
@@ -2726,6 +2886,7 @@ There are no option for `transfer_info`.
 
 By specifying option: `--transfer=node`, `ascli` starts transfers in an Aspera Transfer Server using the Node API, either on a local or remote node.
 This is especially useful for direct node-to-node transfers.
+
 Parameters provided in option `transfer_info` are:
 
 | Name     | Type   | Description |
@@ -2735,7 +2896,7 @@ Parameters provided in option `transfer_info` are:
 | password | string | Password, secret or bearer token</br>Mandatory |
 | root_id  | string | Root file id</br>Mandatory only for bearer token |
 
-Like any other option, `transfer_info` can get its value from a pre-configured [Option Preset](#option-preset)' :
+Like any other option, `transfer_info` can get its value from a pre-configured [Option Preset](#option-preset) :
 
 ```bash
 --transfer-info=@preset:_name_here_
@@ -2749,12 +2910,14 @@ or be specified using the extended value syntax :
 
 If `transfer_info` is not specified and a default node has been configured (name in `node` for section `default`) then this node is used by default.
 
-If the `password` value begins with `Bearer` then the `username` is expected to be an access key and the parameter `root_id` is mandatory and specifies the root file id on the node.
+If the `password` value begins with `Bearer` then the `username` is expected to be an access key and the parameter `root_id` is mandatory and specifies the file id of the top folder to use on the node using this access key.
 It can be either the access key's root file id, or any authorized file id underneath it.
 
 #### Agent: HTTP Gateway
 
-If it possible to send using a HTTP gateway, in case use of FASP is not allowed.
+The Aspera HTTP Gateway is a service that allows to send and receive files using HTTPS.
+
+By specifying option: `--transfer=httpgw`, `ascli` will start transfers using the Aspera HTTP Gateway.
 
 Parameters provided in option `transfer_info` are:
 
@@ -2773,6 +2936,8 @@ ascli faspex package recv 323 --transfer=httpgw --transfer-info=@json:'{"url":"h
 
 > **Note:** The gateway only supports transfers authorized with a token.
 
+If the application, e.g. AoC or Faspex 5, is configured to use the HTTP Gateway, then `ascli` will automatically use the gateway URL if `--transfer=httpgw` is specified, so `transfer_info` becomes optional.
+
 #### Agent: Transfer SDK
 
 Another possibility is to use the Transfer SDK daemon (`asperatransferd`).
@@ -2783,7 +2948,7 @@ Options for `transfer_info` are:
 | Name     | Type   | Description |
 |----------|--------|-------------|
 | `url`      | string | IP address and port listened by the daemon</br>Mandatory<br/>Default: `:0` |
-| `external` | bool   | Use external daemon, do not start<br/>Default: `false` |
+| `external` | bool   | Use external daemon, do not start one.<br/>Default: `false` |
 | `keep`     | bool   | Keep the daemon running after exiting `ascli`<br/>Default: `false` |
 
 > **Note:** If port zero is specified in the URL, then the daemon will listen on a random available port. If no address is specified, then `127.0.0.1` is used.
@@ -2812,7 +2977,7 @@ On Windows the compilation may fail for various reasons (3.1.1):
 ### Transfer Specification
 
 Some commands lead to file transfer (upload/download).
-All parameters necessary for this transfer are described in a [*transfer-spec*](#transfer-specification) (Transfer Specification), such as:
+All parameters necessary for this transfer are described in a [**transfer-spec**](#transfer-specification) (Transfer Specification), such as:
 
 - Server address
 - Transfer user name
@@ -2820,11 +2985,11 @@ All parameters necessary for this transfer are described in a [*transfer-spec*](
 - File list
 - Etc...
 
-`ascli` builds the [*transfer-spec*](#transfer-specification) internally as a `Hash`.
+`ascli` builds the [**transfer-spec**](#transfer-specification) internally as a `Hash`.
 It is not necessary to provide additional parameters on the command line for this transfer.
 
-It is possible to modify or add any of the supported [*transfer-spec*](#transfer-specification) parameter using the `ts` option.
-The `ts` option accepts a [`Hash` Extended Value](#extended-value-syntax) containing one or several [*transfer-spec*](#transfer-specification) parameters.
+It is possible to modify or add any of the supported [**transfer-spec**](#transfer-specification) parameter using the `ts` option.
+The `ts` option accepts a [`Hash` Extended Value](#extended-value-syntax) containing one or several [**transfer-spec**](#transfer-specification) parameters.
 Multiple `ts` options on command line are cumulative, and the `Hash` value is deeply merged.
 To remove a (deep) key from transfer spec, set the value to `null`.
 
@@ -2834,15 +2999,15 @@ It is possible to specify `ascp` options when the `transfer` option is set to [`
 Example: `--transfer-info=@json:'{"ascp_args":["-l","100m"]}'`.
 This is especially useful for `ascp` command line parameters not supported in the transfer spec.
 
-The use of a [*transfer-spec*](#transfer-specification) instead of `ascp` parameters has the advantage of:
+The use of a [**transfer-spec**](#transfer-specification) instead of `ascp` command line arguments has the advantage of:
 
 - Common to all [Transfer Agent](#transfer-clients-agents)
 - Not dependent on command line limitations (special characters...)
 
 ### Transfer Parameters
 
-All standard [*transfer-spec*](#transfer-specification) parameters can be specified.
-[*transfer-spec*](#transfer-specification) can also be saved/overridden in the configuration file.
+All standard [**transfer-spec**](#transfer-specification) parameters can be specified.
+[**transfer-spec**](#transfer-specification) can also be saved/overridden in the configuration file.
 
 References:
 
@@ -2889,7 +3054,7 @@ Columns:
 | fasp_port | int | Y | Y | Y | Y | Y | Specifies fasp (UDP) port.<br/>(-O {int}) |
 | fasp_url | string | &nbsp; | &nbsp; | &nbsp; | &nbsp; | &nbsp; | Only used in Faspex.<br/>(&lt;ignored&gt;) |
 | file_checksum | string | Y | Y | &nbsp; | &nbsp; | &nbsp; | Enable checksum reporting for transferred files by specifying the hash to use.<br/>Allowed values: sha-512, sha-384, sha-256, sha1, md5, none<br/>(&lt;ignored&gt;) |
-| http_fallback | bool<br/>string | Y | Y | Y | Y | Y | When true(1), attempts to perform an HTTP transfer if a FASP transfer cannot be performed.<br/>(-y (conversion){bool}|{string}) |
+| http_fallback | bool<br/>string | Y | Y | Y | Y | Y | When true(1), attempts to perform an HTTP transfer if a FASP transfer cannot be performed.<br/>(-y (conversion){bool}\|{string}) |
 | http_fallback_port | int | Y | &nbsp; | &nbsp; | &nbsp; | &nbsp; | Specifies http port when no cipher is used<br/>(-t {int}) |
 | https_fallback_port | int | Y | Y | Y | Y | Y | Specifies https port when cipher is used<br/>(-t {int}) |
 | keepalive | bool | Y | &nbsp; | &nbsp; | &nbsp; | &nbsp; | The session is running in persistent session mode.<br/>(--keepalive) |
@@ -2960,7 +3125,7 @@ The destination folder is set by `ascli` by default to:
 - `.` for downloads
 - `/` for uploads
 
-It is specified by the [*transfer-spec*](#transfer-specification) parameter `destination_root`.
+It is specified by the [**transfer-spec**](#transfer-specification) parameter `destination_root`.
 As such, it can be modified with option: `--ts=@json:'{"destination_root":"<path>"}'`.
 The option `to_folder` provides an equivalent and convenient way to change this parameter:
 `--to-folder=<path>` .
@@ -2974,8 +3139,8 @@ By default the list of files to transfer is simply provided on the command line.
 The list of (source) files to transfer is specified by (extended value) option `sources` (default: `@args`).
 The list is either simply the list of source files, or a combined source/destination list (see below) depending on value of option `src_type` (default: `list`).
 
-In `ascli`, all transfer parameters, including file list, are provided to the transfer agent in a [*transfer-spec*](#transfer-specification) so that execution of a transfer is independent of the transfer agent (direct, connect, node, transfer sdk...).
-So, eventually, the list of files to transfer is provided to the transfer agent using the [*transfer-spec*](#transfer-specification) field: `"paths"` which is a list (array) of pairs of `"source"` (mandatory) and `"destination"` (optional).
+In `ascli`, all transfer parameters, including file list, are provided to the transfer agent in a [**transfer-spec**](#transfer-specification) so that execution of a transfer is independent of the transfer agent (direct, connect, node, transfer sdk...).
+So, eventually, the list of files to transfer is provided to the transfer agent using the [**transfer-spec**](#transfer-specification) field: `"paths"` which is a list (array) of pairs of `"source"` (mandatory) and `"destination"` (optional).
 The `sources` and `src_type` options provide convenient ways to populate the transfer spec with the source file list.
 
 Possible values for option `sources` are:
@@ -3396,7 +3561,7 @@ ascli server upload "faux:///mydir?file=testfile&count=1m&size=0&inc=2&seq=seque
 ```text
 ascli -h
 NAME
-        ascli -- a command line tool for Aspera Applications (v4.17.0)
+        ascli -- a command line tool for Aspera Applications (v4.18.1)
 
 SYNOPSIS
         ascli COMMANDS [OPTIONS] [ARGS]
@@ -3418,7 +3583,7 @@ COMMANDS
 OPTIONS
         Options begin with a '-' (minus), and value is provided on command line.
         Special values are supported beginning with special prefix @pfx:, where pfx is one of:
-        val, base64, csvt, env, file, uri, json, lines, list, none, path, re, ruby, secret, stdin, yaml, zlib, extend, preset, vault
+        val, base64, csvt, env, file, uri, json, lines, list, none, path, re, ruby, secret, stdin, stdbin, yaml, zlib, extend, preset, vault
         Dates format is 'DD-MM-YY HH:MM:SS', or 'now' or '-<num>h'
 
 ARGS
@@ -3427,20 +3592,21 @@ ARGS
 OPTIONS: global
         --interactive=ENUM           Use interactive input of missing params: [no], yes
         --ask-options=ENUM           Ask even optional options: [no], yes
-        --format=ENUM                Output format: text, nagios, ruby, json, jsonpp, yaml, [table], csv
+        --struct-parser=ENUM         Default parser when expected value is a struct: json, ruby
+        --format=ENUM                Output format: text, nagios, ruby, json, jsonpp, yaml, [table], csv, image
         --output=VALUE               Destination for results (String)
         --display=ENUM               Output only some information: [info], data, error
         --fields=VALUE               Comma separated list of: fields, or ALL, or DEF (String, Array, Regexp, Proc)
         --select=VALUE               Select only some items in lists: column, value (Hash, Proc)
-        --table-style=VALUE          Table display style
+        --table-style=VALUE          Table display style (Hash)
         --flat-hash=ENUM             Display deep values as additional keys: no, [yes]
         --transpose-single=ENUM      Single object fields output vertically: no, [yes]
         --show-secrets=ENUM          Show secrets on command output: [no], yes
+        --image=VALUE                Options for image display (Hash)
     -h, --help                       Show this message
         --bash-comp                  Generate bash completion for command
         --show-config                Display parameters used for the provided action
     -v, --version                    Display version
-    -w, --warnings                   Check for language warnings
         --ui=ENUM                    Method to start browser: text, [graphical]
         --log-level=ENUM             Log level: trace2, trace1, debug, info, [warn], error, fatal, unknown
         --logger=ENUM                Logging method: [stderr], stdout, syslog
@@ -3451,7 +3617,7 @@ OPTIONS: global
         --pid-file=VALUE             Write process identifier to file, delete on exit (String)
 
 COMMAND: config
-SUBCOMMANDS: ascp check_update coffee detect documentation echo email_test file flush_tokens folder gem genkey initdemo open plugins preset proxy_check pubkey remote_certificate smtp_settings throw vault wizard
+SUBCOMMANDS: ascp check_update coffee detect documentation echo email_test file flush_tokens folder gem genkey image initdemo open plugins preset proxy_check pubkey remote_certificate smtp_settings throw vault wizard
 OPTIONS:
         --home=VALUE                 Home folder for tool (String)
         --config-file=VALUE          Path to YAML file with preset configuration
@@ -3461,7 +3627,6 @@ OPTIONS:
         --query=VALUE                Additional filter for for some commands (list/delete) (Hash)
         --value=VALUE                Value for create, update, list filter (Hash) (deprecated: (4.14) Use positional value for create/modify or option: query for list/delete)
         --property=VALUE             Name of property to set (modify operation)
-        --id=VALUE                   Resource identifier (deprecated: (4.14) Use positional identifier after verb (modify,delete,show))
         --bulk=ENUM                  Bulk operation (only some): [no], yes
         --bfail=ENUM                 Bulk operation error handling: no, [yes]
     -N, --no-default                 Do not load default configuration for plugin
@@ -3485,9 +3650,10 @@ OPTIONS:
         --silent-insecure=ENUM       Issue a warning if certificate is ignored: no, [yes]
         --cert-stores=VALUE          List of folder with trusted certificates (Array, String)
         --http-options=VALUE         Options for HTTP/S socket (Hash)
+        --http-proxy=VALUE           URL for HTTP proxy with optional credentials (String)
         --cache-tokens=ENUM          Save and reuse OAuth tokens: no, [yes]
         --fpac=VALUE                 Proxy auto configuration script
-        --proxy-credentials=VALUE    HTTP proxy credentials (user and password) (Array)
+        --proxy-credentials=VALUE    HTTP proxy credentials for fpac. Array: user,password (Array)
         --ts=VALUE                   Override transfer spec values (Hash)
         --to-folder=VALUE            Destination folder for transferred files
         --sources=VALUE              How list of transferred files is provided (@args,@ts,Array)
@@ -3505,7 +3671,7 @@ OPTIONS:
 
 
 COMMAND: node
-SUBCOMMANDS: access_keys api_details asperabrowser async basic_token bearer_token browse central delete download events health http_node_download info license mkdir mkfile mklink rename search service simulator slash space ssync stream sync transfer upload watch_folder
+SUBCOMMANDS: access_keys api_details asperabrowser async basic_token bearer_token browse central delete download events health http_node_download info license mkdir mkfile mklink rename search service simulator slash space ssync stream sync transfer transport upload watch_folder
 OPTIONS:
         --url=VALUE                  URL of application, e.g. https://faspex.example.com/aspera/faspex
         --username=VALUE             User's name to log in
@@ -3518,28 +3684,32 @@ OPTIONS:
         --sync-info=VALUE            Information for sync instance and sessions (Hash)
 
 
-COMMAND: orchestrator
-SUBCOMMANDS: health info plugins processes workflow
+COMMAND: faspio
+SUBCOMMANDS: bridges health
 OPTIONS:
         --url=VALUE                  URL of application, e.g. https://faspex.example.com/aspera/faspex
         --username=VALUE             User's name to log in
         --password=VALUE             User's password
-        --result=VALUE               Specify result value as: 'work_step:parameter'
-        --synchronous=ENUM           Wait for completion: [no], yes
-        --ret-style=ENUM             How return type is requested in api: header, [arg], ext
-        --auth-style=ENUM            Authentication type: arg_pass, [head_basic], apikey
+        --auth=ENUM                  OAuth type of authentication: jwt, basic
+        --client-id=VALUE            OAuth client identifier
+        --private-key=VALUE          OAuth JWT RSA private key PEM value (prefix file path with @file:)
+        --passphrase=VALUE           OAuth JWT RSA private key passphrase
 
 
-COMMAND: bss
-SUBCOMMANDS: subscription
+COMMAND: orchestrator
+SUBCOMMANDS: health info plugins processes workflow
 OPTIONS:
         --url=VALUE                  URL of application, e.g. https://faspex.example.com/aspera/faspex
         --username=VALUE             User's name to log in
         --password=VALUE             User's password
+        --result=VALUE               Specify result value as: 'work_step:parameter'
+        --synchronous=ENUM           Wait for completion: [no], yes
+        --ret-style=ENUM             How return type is requested in api: header, [arg], ext
+        --auth-style=ENUM            Authentication type: arg_pass, [head_basic], apikey
 
 
 COMMAND: alee
-SUBCOMMANDS: entitlement
+SUBCOMMANDS: entitlement health
 OPTIONS:
         --url=VALUE                  URL of application, e.g. https://faspex.example.com/aspera/faspex
         --username=VALUE             User's name to log in
@@ -3587,6 +3757,12 @@ OPTIONS:
         --identity=VALUE             Authentication URL (https://iam.cloud.ibm.com/identity)
 
 
+COMMAND: httpgw
+SUBCOMMANDS: health info
+OPTIONS:
+        --url=VALUE                  URL of application, e.g. https://app.example.com/aspera/app
+
+
 COMMAND: faspex
 SUBCOMMANDS: address_book dropbox health login_methods me package source v4
 OPTIONS:
@@ -3649,9 +3825,9 @@ OPTIONS:
         --scope=VALUE                OAuth scope for AoC API calls
         --redirect-uri=VALUE         OAuth API client redirect URI
         --private-key=VALUE          OAuth JWT RSA private key PEM value (prefix file path with @file:)
-        --passphrase=VALUE           RSA private key passphrase
+        --passphrase=VALUE           RSA private key passphrase (String)
         --workspace=VALUE            Name of workspace (String, NilClass)
-        --new-user-option=VALUE      New user creation option for unknown package recipients
+        --new-user-option=VALUE      New user creation option for unknown package recipients (Hash)
         --validate-metadata=ENUM     Validate shared inbox metadata: no, [yes]
         --validator=VALUE            Identifier of validator (optional for central)
         --asperabrowserurl=VALUE     URL for simple aspera web ui
@@ -3725,7 +3901,7 @@ Aspera on Cloud and Faspex 5 rely on Oauth.
 By default plugins are looked-up in folders specified by (multi-value) option `plugin_folder`:
 
 ```bash
-ascli --show-config --select=@json:'{"key":"plugin_folder"}'
+ascli --show-config --fields=plugin_folder
 ```
 
 You can create the skeleton of a new plugin like this:
@@ -3805,7 +3981,7 @@ Several types of OAuth authentication are supported:
 
 The authentication method is controlled by option `auth`.
 
-For a **quick start**, follow the mandatory and sufficient section: [API Client Registration](#api-client-registration) (auth=web) as well as [[Option Preset](#option-preset)' for Aspera on Cloud](#configuration-for-aspera-on-cloud).
+For a **quick start**, follow the mandatory and sufficient section: [API Client Registration](#api-client-registration) (auth=web) as well as [[Option Preset](#option-preset) for Aspera on Cloud](#configuration-for-aspera-on-cloud).
 
 For a more convenient, browser-less, experience follow the [JWT](#authentication-with-private-key) section (auth=jwt) in addition to Client Registration.
 
@@ -3842,9 +4018,9 @@ Once the client is registered, a **Client ID** and **Secret** are created, these
 
 #### Configuration for Aspera on Cloud
 
-If you did not use the wizard, you can also manually create a [Option Preset](#option-preset)' for `ascli` in its configuration file.
+If you did not use the wizard, you can also manually create a [Option Preset](#option-preset) for `ascli` in its configuration file.
 
-Lets create a [Option Preset](#option-preset)' called: `my_aoc_org` using `ask` for interactive input (client info from previous step):
+Lets create a [Option Preset](#option-preset) called: `my_aoc_org` using `ask` for interactive input (client info from previous step):
 
 ```bash
 ascli config preset ask my_aoc_org url client_id client_secret
@@ -3858,7 +4034,7 @@ updated: my_aoc_org
 
 (This can also be done in one line using the command `config preset update my_aoc_org --url=...`)
 
-Define this [Option Preset](#option-preset)' as default configuration for the `aspera` plugin:
+Define this [Option Preset](#option-preset) as default configuration for the `aspera` plugin:
 
 ```bash
 ascli config preset set default aoc my_aoc_org
@@ -3949,9 +4125,9 @@ modified
 
 > **Note:** The `aspera user info show` command can be used to verify modifications.
 
-#### [Option Preset](#option-preset)' modification for JWT
+#### [Option Preset](#option-preset) modification for JWT
 
-To activate default use of JWT authentication for `ascli` using the [Option Preset](#option-preset)', do the following:
+To activate default use of JWT authentication for `ascli` using the [Option Preset](#option-preset), do the following:
 
 - Change auth method to JWT
 - Provide location of private key
@@ -3985,7 +4161,7 @@ In that case, it is possible to list those shared folder by using a value for op
 
 #### AoC: First Use
 
-Once client has been registered and [Option Preset](#option-preset)' created: `ascli` can be used:
+Once client has been registered and [Option Preset](#option-preset) created: `ascli` can be used:
 
 ```bash
 ascli aoc files br /
@@ -4188,7 +4364,7 @@ Options:
 #### Transfer: Using specific transfer ports
 
 By default transfer nodes are expected to use ports TCP/UDP 33001. The web UI enforces that.
-The option `default_ports` ([yes]/no) allows ascli to retrieve the server ports from an API call (download_setup) which reads the information from `aspera.conf` on the server.
+The option `default_ports` ([yes]/no) allows `ascli` to retrieve the server ports from an API call (download_setup) which reads the information from `aspera.conf` on the server.
 
 #### Using ATS
 
@@ -4588,7 +4764,7 @@ General syntax:
 ascli aoc packages send [package extended value] [other parameters such as file list and transfer parameters]
 ```
 
-Package creation parameter are sent as positional argument.
+Package creation parameter are sent as **Command Parameter**.
 Refer to the AoC package creation API, or display an existing package in JSON to list attributes.
 
 List allowed shared inbox destinations with:
@@ -4766,13 +4942,13 @@ ascli aoc files short_link public delete _id_
 
 It is possible to transfer files directly between organizations without having to first download locally and then upload...
 
-Although optional, the creation of [Option Preset](#option-preset)' is recommended to avoid placing all parameters in the command line.
+Although optional, the creation of [Option Preset](#option-preset) is recommended to avoid placing all parameters in the command line.
 
 Procedure to send a file from org1 to org2:
 
-- Get access to Organization 1 and create a [Option Preset](#option-preset)': e.g. `org1`, for instance, use the [Wizard](#configuration-using-wizard)
+- Get access to Organization 1 and create a [Option Preset](#option-preset): e.g. `org1`, for instance, use the [Wizard](#configuration-using-wizard)
 - Check that access works and locate the source file e.g. `mysourcefile`, e.g. using command `files browse`
-- Get access to Organization 2 and create a [Option Preset](#option-preset)': e.g. `org2`
+- Get access to Organization 2 and create a [Option Preset](#option-preset): e.g. `org2`
 - Check that access works and locate the destination folder `mydestfolder`
 - Execute the following:
 
@@ -4812,6 +4988,7 @@ For instructions, refer to section `find` for plugin `node`.
 admin analytics transfers nodes
 admin analytics transfers organization --query=@json:'{"status":"completed","direction":"receive"}' --notify-to=my_email_external --notify-template=@ruby:'%Q{From: <%=from_name%> <<%=from_email%>>\nTo: <<%=to%>>\nSubject: <%=ev["files_completed"]%> files received\n\n<%=ev.to_yaml%>}'
 admin analytics transfers users --once_only=yes
+admin application list
 admin ats access_key create --cloud=aws --region=my_region --params=@json:'{"id":"ak_aws","name":"my test key AWS","storage":{"type":"aws_s3","bucket":"my_bucket","credentials":{"access_key_id":"my_access_key","secret_access_key":"my_secret_key"},"path":"/"}}'
 admin ats access_key create --cloud=softlayer --region=my_region --params=@json:'{"id":"ak1ibmcloud","secret":"my_secret_here","name":"my test key","storage":{"type":"ibm-s3","bucket":"my_bucket","credentials":{"access_key_id":"my_access_key","secret_access_key":"my_secret_key"},"path":"/"}}'
 admin ats access_key delete ak1ibmcloud
@@ -4822,36 +4999,35 @@ admin ats cluster list
 admin ats cluster show --cloud=aws --region=eu-west-1
 admin ats cluster show 1f412ae7-869a-445c-9c05-02ad16813be2
 admin auth_providers list
-admin res application list
-admin res client list
-admin res client_access_key list
-admin res client_registration_token create @json:'{"data":{"name":"test_client_reg1","client_subject_scopes":["alee","aejd"],"client_subject_enabled":true}}'
-admin res client_registration_token delete client_reg_id
-admin res client_registration_token list
-admin res contact list
-admin res dropbox list
-admin res dropbox_membership list
-admin res group list
-admin res kms_profile list
-admin res node list
-admin res operation list
-admin res organization show
-admin res package list --http-options=@json:'{"read_timeout":120.0}'
-admin res saml_configuration list
-admin res self show
-admin res short_link list
-admin res user list
-admin res user modify %name:my_user_email @json:'{"deactivated":false}'
-admin res workspace_membership list
-admin resource node do %name:my_ak_name --secret=my_ak_secret browse /
-admin resource node do %name:my_ak_name --secret=my_ak_secret delete /folder1
-admin resource node do %name:my_ak_name --secret=my_ak_secret mkdir /folder1
-admin resource node do %name:my_ak_name --secret=my_ak_secret v3 access_key create @json:'{"id":"testsub1","storage":{"path":"/folder1"}}'
-admin resource node do %name:my_ak_name --secret=my_ak_secret v3 access_key delete testsub1
-admin resource node do %name:my_ak_name --secret=my_ak_secret v3 events
-admin resource workspace list
-admin resource workspace_membership list --fields=ALL --query=@json:'{"page":1,"per_page":50,"embed":"member","inherited":false,"workspace_id":11363,"sort":"name"}'
+admin client list
+admin client_access_key list
+admin client_registration_token create @json:'{"data":{"name":"test_client_reg1","client_subject_scopes":["alee","aejd"],"client_subject_enabled":true}}'
+admin client_registration_token delete client_reg_id
+admin client_registration_token list
+admin contact list
+admin dropbox list
+admin dropbox_membership list
+admin group list
+admin kms_profile list
+admin node do %name:my_ak_name --secret=my_ak_secret browse /
+admin node do %name:my_ak_name --secret=my_ak_secret delete /folder1
+admin node do %name:my_ak_name --secret=my_ak_secret mkdir /folder1
+admin node do %name:my_ak_name --secret=my_ak_secret v3 access_key create @json:'{"id":"testsub1","storage":{"path":"/folder1"}}'
+admin node do %name:my_ak_name --secret=my_ak_secret v3 access_key delete testsub1
+admin node do %name:my_ak_name --secret=my_ak_secret v3 events
+admin node list
+admin operation list
+admin organization show
+admin package list --http-options=@json:'{"read_timeout":120.0}'
+admin saml_configuration list
+admin self show
+admin short_link list
 admin subscription
+admin user list
+admin user modify %name:my_user_email @json:'{"deactivated":false}'
+admin workspace list
+admin workspace_membership list
+admin workspace_membership list --fields=ALL --query=@json:'{"page":1,"per_page":50,"embed":"member","inherited":false,"workspace_id":11363,"sort":"name"}'
 automation workflow action wf_id create @json:'{"name":"toto"}' \
 automation workflow create @json:'{"name":"test_workflow"}'
 automation workflow delete wf_id
@@ -4865,6 +5041,9 @@ files browse /
 files browse / --url=my_private_link
 files browse / --url=my_public_link_folder_no_pass
 files browse / --url=my_public_link_folder_pass --password=my_public_link_password
+files browse my_remote_file
+files browse my_remote_folder
+files browse my_remote_folder/
 files delete /testsrc
 files download --transfer=alpha testdst/test_file.bin
 files download --transfer=connect testdst/test_file.bin
@@ -4924,9 +5103,9 @@ user workspaces list
 
 ATS is usable either :
 
-- From an AoC subscription : ascli aoc admin ats : use AoC authentication
+- From an AoC subscription : `ascli aoc admin ats` : use AoC authentication
 
-- Or from an IBM Cloud subscription : ascli ats : use IBM Cloud API key authentication
+- Or from an IBM Cloud subscription : `ascli ats` : use IBM Cloud API key authentication
 
 ### IBM Cloud ATS : Creation of api key
 
@@ -5098,8 +5277,8 @@ mkdir my_upload_folder/target_hot
 mv my_upload_folder/200KB.2 my_upload_folder/to.delete
 sync admin status --sync-info=@json:'{"name":"sync2","local":{"path":"/data/local_sync"}}'
 sync admin status --sync-info=@json:'{"name":"sync2"}'
-sync admin status my_sync --sync-info=@json:'{"sessions":[{"name":"my_sync","local_dir":"/data/local_sync"}]}'
-sync start --sync-info=@json:'{"instance":{"quiet":false},"sessions":[{"name":"my_sync","direction":"pull","remote_dir":"my_inside_folder","local_dir":"/data/local_sync","reset":true}]}'
+sync admin status my_srv_sync --sync-info=@json:'{"sessions":[{"name":"my_srv_sync","local_dir":"/data/local_sync"}]}'
+sync start --sync-info=@json:'{"instance":{"quiet":false},"sessions":[{"name":"my_srv_sync","direction":"pull","remote_dir":"my_inside_folder","local_dir":"/data/local_sync","reset":true}]}'
 sync start --sync-info=@json:'{"name":"sync2","local":{"path":"/data/local_sync"},"remote":{"path":"my_inside_folder"},"reset":true,"quiet":false}'
 upload 'faux:///test1?100m' 'faux:///test2?100m' --to-folder=/Upload --ts=@json:'{"target_rate_kbps":1000000,"resume_policy":"none","precalculate_job_size":true}'
 upload 'faux:///test1?100m' 'faux:///test2?100m' --to-folder=/Upload --ts=@json:'{"target_rate_kbps":1000000,"resume_policy":"none","precalculate_job_size":true}' --transfer-info=@json:'{"quiet":false}' --progress=no
@@ -5203,7 +5382,7 @@ ascli server browse /aspera-test-dir-large
 ascli server download /aspera-test-dir-large/200MB
 ```
 
-`initdemo` creates a [Option Preset](#option-preset)' `demoserver` and set it as default for plugin `server`.
+`initdemo` creates a [Option Preset](#option-preset) `demoserver` and set it as default for plugin `server`.
 
 If an SSH private key is used for authentication with a passphrase, the passphrase needs to be provided to both options: `ssh_options`, for browsing, and `ts` for transfers:
 
@@ -5235,6 +5414,18 @@ Example:
 - `ascli node browse /` : list files with **gen3/node user** API
 - `ascli node access_key do self browse /` : list files with **gen4/access key** API
 
+#### Browse
+
+Native API parameters can be placed in option `query`.
+
+Special parameters can be placed in option `query` for "gen3" browse:
+
+| Parameter | Description |
+|-----------|-------------|
+| `recursive` | Recursively list files |
+| `max` | Maximum number of files to list |
+| `self` | Offset in the list |
+
 ### Operation `find` on **gen4/access key**
 
 The command `find <folder> [filter_expr]` is available for **gen4/access key**, under `access_keys do self`.
@@ -5337,7 +5528,7 @@ There are three sync types of operations:
 
 It is possible to start a FASPStream session using the node API:
 
-Use the command `ascli node stream create --ts=@json:<value>`, with [*transfer-spec*](#transfer-specification):
+Use the command `ascli node stream create --ts=@json:<value>`, with [**transfer-spec**](#transfer-specification):
 
 ```json
 {"direction":"send","source":"udp://233.3.3.4:3000?loopback=1&ttl=2","destination":"udp://233.3.3.3:3001/","remote_host":"localhost","remote_user":"stream","remote_password":"my_pass_here"}
@@ -5643,6 +5834,7 @@ sync start --sync-info=@json:'{"name":"my_node_sync2","reset":true,"direction":"
 sync start --sync-info=@json:'{"sessions":[{"name":"my_node_sync1","direction":"pull","local_dir":"/data/local_sync","remote_dir":"/aspera-test-dir-tiny","reset":true}]}'
 transfer list --query=@json:'{"active_only":true}'
 transfer sessions
+transport
 upload --to-folder=my_upload_folder --sources=@ts --ts=@json:'{"paths":[{"source":"/aspera-test-dir-small/10MB.2"}],"precalculate_job_size":true}' --transfer=node --transfer-info=@json:'{"url":"https://node.example.com/path@","username":"my_username","password":"my_password_here"}'
 upload --username=my_ak_name --password=my_ak_secret test_file.bin
 upload test_file.bin --to-folder=my_upload_folder --ts=@json:'{"target_rate_cap_kbps":10000}'
@@ -5664,7 +5856,7 @@ IBM Aspera's newer self-managed application.
 
 > **Note:** If you have a Faspex 5 public link, provide it, unchanged, through the option `url`
 
-For a quick start, one can use the wizard, which will help creating a [Option Preset](#option-preset)':
+For a quick start, one can use the wizard, which will help creating a [Option Preset](#option-preset):
 
 ```bash
 ascli config wizard
@@ -5802,24 +5994,30 @@ ascli config preset update f5boot --url=https://localhost/aspera/faspex --auth=b
 > **Note:** Add `ascli faspex5` in front of the commands:
 
 ```bash
-admin res accounts list
-admin res contacts list
-admin res jobs list
-admin res metadata_profiles list
-admin res node list
-admin res oauth_clients list
-admin res registrations list
-admin res saml_configs list
-admin res shared_inboxes invite %name:my_shared_box_name johnny@example.com
-admin res shared_inboxes list
-admin res shared_inboxes list --query=@json:'{"all":true}'
-admin res shared_inboxes members %name:my_shared_box_name create %name:john@example.com
-admin res shared_inboxes members %name:my_shared_box_name delete %name:john@example.com
-admin res shared_inboxes members %name:my_shared_box_name delete %name:johnny@example.com
-admin res shared_inboxes members %name:my_shared_box_name list
-admin res workgroups list
+admin accounts list
+admin clean_deleted
+admin contacts list
+admin distribution_lists create @json:'{"name":"test4","contacts":[{"name":"john@example.com"}]}'
+admin distribution_lists delete %name:test4
+admin distribution_lists list --query=@json:'{"type":"global"}'
+admin event app
+admin event web
+admin jobs list --query=@json:'{"job_type":"email","status":"failed"}' --fields=id,error_desc
+admin metadata_profiles list
+admin node list
+admin oauth_clients list
+admin registrations list
+admin saml_configs list
+admin shared_inboxes invite %name:my_shared_box_name johnny@example.com
+admin shared_inboxes list
+admin shared_inboxes list --query=@json:'{"all":true}'
+admin shared_inboxes members %name:my_shared_box_name create %name:john@example.com
+admin shared_inboxes members %name:my_shared_box_name delete %name:john@example.com
+admin shared_inboxes members %name:my_shared_box_name delete %name:johnny@example.com
+admin shared_inboxes members %name:my_shared_box_name list
 admin smtp show
 admin smtp test my_email_external
+admin workgroups list
 bearer_token
 gateway --pid-file=pid_f5_fxgw https://localhost:12346/aspera/faspex &
 health
@@ -5853,7 +6051,7 @@ user profile show
 ```
 
 Most commands are directly REST API calls.
-Parameters to commands are carried through option `query`, as extended value, for `list`, or through positional argument for creation.
+Parameters to commands are carried through option `query`, as extended value, for `list`, or through **Command Parameter** for creation.
 One can conveniently use the JSON format with prefix `@json:`.
 
 > **Note:** The API is listed in [Faspex 5 API Reference](https://developer.ibm.com/apis/catalog?search="faspex+5") under **IBM Aspera Faspex API**.
@@ -5880,7 +6078,7 @@ To select another inbox, use option `box` with one of the following values:
 
 ### Faspex 5: Send a package
 
-The `Hash` creation parameter provided to command `faspex5 packages send [extended value: Hash with package info ] [files...]` corresponds to the Faspex 5 API: `POST /packages`.
+The `Hash` creation **Command Parameter** provided to command `faspex5 packages send [extended value: Hash with package info ] [files...]` corresponds to the Faspex 5 API: `POST /packages`.
 
 The interface is the one of the API (Refer to Faspex5 API documentation, or look at request in browser).
 
@@ -5931,7 +6129,7 @@ Basically, add the field `metadata`, with one key per metadata and the value is
 
 ### Faspex 5: List packages
 
-Option `box` can be used to list packages from a specific box (see **Inbox selection** above).
+Option `box` can be used to list packages from a specific box (see [Inbox Selection](#faspex-5-inbox-selection) above).
 
 Option `query` can be used to filter the list of packages, based on native API parameters, directly sent to [Faspex 5 API `GET /packages`](https://developer.ibm.com/apis/catalog/aspera--ibm-aspera-faspex-5-0-api/api/API--aspera--ibm-aspera-faspex-api#getAllPackages).
 
@@ -5944,7 +6142,7 @@ Option `query` can be used to filter the list of packages, based on native API p
 | `max`     | Special | Maximum number of items to retrieve (stop pages when the maximum is passed) |
 | `pmax`    | Special | Maximum number of pages to request (stop pages when the maximum is passed) |
 
-A positional parameter in last position, of type `Proc`, can be used to filter the list of packages.
+A **Command Parameter** in last position, of type `Proc`, can be used to filter the list of packages.
 This advantage of this method is that the expression can be any test, even complex, as it is Ruby code.
 But the disadvantage is that the filtering is done in `ascli` and not in Faspex 5, so it is less efficient.
 
@@ -5972,7 +6170,7 @@ Option `query` is available.
 
 To list recursively add option `--query=@json:{"recursive":true}`.
 
-> **Note:** Option `recirsive` makes recursive API calls, so it can take a long time on large packages.
+> **Note:** Option `recursive` makes recursive API calls, so it can take a long time on large packages.
 
 To limit the number of items retrieved, use option `--query=@json:{"max":10}`.
 
@@ -5982,7 +6180,7 @@ To receive one, or several packages at once, use command `faspex5 packages recei
 Provide either a single package id, or an extended value `Array` of package ids, e.g. `@list:,1,2,3` as argument.
 
 The same options as for `faspex5 packages list` can be used to select the box and filter the packages to download.
-I.e. options `box` and `query`, as well as last positional parameter `Proc` (filter).
+I.e. options `box` and `query`, as well as last **Command Parameter** `Proc` (filter).
 
 Option `--once-only=yes` can be used, for "cargo-like" behavior.
 Special package id `INIT` initializes the persistency of already received packages when option `--once-only=yes` is used.
@@ -6004,6 +6202,7 @@ ascli faspex5 admin res workgroup list
 ```
 
 If you are admin or manager, add option: `--query=@json:'{"all":true}'`, this will list items you manage, even if you do not belong to them.
+Example:
 
 ```bash
 ascli faspex5 admin res shared list --query=@json:'{"all":true}' --fields=id,name
@@ -6021,10 +6220,10 @@ It is equivalent to:
 ascli faspex5 admin res shared_inboxes invite '%name:the shared inbox' @json:'{"email_address":"john@example.com"}'
 ```
 
-Other payload parameters are possible the `Hash` value:
+Other payload parameters are possible for `invite` in this last `Hash` **Command Parameter**:
 
 ```json
-{"description":"blah","prevent_http_upload":true,"custom_link_expiration_policy":false,"invitation_expires_after_upload":false,"set_invitation_link_expiration":false,"invitation_expiration_days":3
+{"description":"blah","prevent_http_upload":true,"custom_link_expiration_policy":false,"invitation_expires_after_upload":false,"set_invitation_link_expiration":false,"invitation_expiration_days":3}
 ```
 
 ### Faspex 5: Create Metadata profile
@@ -6085,6 +6284,37 @@ Public invitations are for external users, provide just the email address.
 
 Private invitations are for internal users, provide the user or shared inbox identifier through field `recipient_name`.
 
+### Faspex 5: Cleanup packages
+
+> **Note:** Operation requires admin level.
+
+Automated cleanup period can be displayed with:
+
+```bash
+ascli faspex5 admin configuration show --fields=days_before_deleting_package_records
+```
+
+This parameter can also be modified, for example:
+
+```bash
+ascli faspex5 admin configuration modify @json:'{"days_before_deleting_package_records":30}'
+```
+
+To start package purge, i.e. permanently remove packages marked for deletion older than `days_before_deleting_package_records`, use command:
+
+```bash
+ascli faspex5 admin clean_deleted
+```
+
+To delete all packages, one can use the following command:
+
+```bash
+ascli faspex5 packages list --box=ALL --format=yaml --fields=id | ascli faspex5 packages delete @yaml:@stdin:
+```
+
+> **Note:** Above command will mark all packages for deletion, and will be permanently removed after the configured period (`clean_deleted` command).
+> It is possible to add a filter to the list command to only delete packages matching some criteria, e.g. using `--select=@ruby:`.
+
 ### Faspex 5: Faspex 4-style postprocessing
 
 `ascli` provides command `postprocessing` in plugin `faspex5` to emulate Faspex 4 postprocessing.
@@ -6132,6 +6362,14 @@ Then, the postprocessing script executed will be `script1.sh`.
 
 Environment variables at set to the values provided by the web hook which are the same as Faspex 4 postprocessing.
 
+### Faspex 5: Missing commands
+
+If a command is missing, then it is still possible to execute command by calling directly the API on the command line using `curl`:
+
+```bash
+curl -H "Authorization: $(ascli ascli bearer)" https://faspex5.example.com/aspera/faspex/api/v5/api_endpoint_here
+```
+
 ## Plugin: `faspex`: IBM Aspera Faspex v4
 
 > **Note:** For full details on Faspex API, refer to: [Reference on Developer Site](https://developer.ibm.com/apis/catalog/?search=faspex)
@@ -6210,13 +6448,13 @@ The contents of `delivery_info` is directly the contents of the `send` v3 [API o
 Example:
 
 ```bash
-ascli faspex package send --delivery-info=@json:'{"title":"my title","recipients":["someuser@example.com"]}' --url=https://faspex.corp.com/aspera/faspex --username=foo --password=bar /tmp/file1 /home/bar/file2
+ascli faspex package send --delivery-info=@json:'{"title":"my title","recipients":["someuser@example.com"]}' /tmp/file1 /home/bar/file2
 ```
 
 If the recipient is a dropbox or workgroup: provide the name of the dropbox or workgroup preceded with `*` in the `recipients` field of the `delivery_info` option:
 `"recipients":["*MyDropboxName"]`
 
-Additional optional parameters in `delivery_info`:
+Additional optional parameters in mandatory option `delivery_info`:
 
 - Package Note: : `"note":"note this and that"`
 - Package Metadata: `"metadata":{"Meta1":"Val1","Meta2":"Val2"}`
@@ -6233,7 +6471,7 @@ The value is a `Hash` with the following keys:
 
 ### Email notification on transfer
 
-Like for any transfer, a notification can be sent by email using parameters: `notify_to` and `notify_template` .
+Like for any transfer, a notification can be sent by email using options: `notify_to` and `notify_template` .
 
 Example:
 
@@ -6368,12 +6606,14 @@ admin user ldap add the_name
 admin user local list
 admin user saml import @json:'{"id":"the_id","name_id":"the_name"}'
 files browse /
+files delete my_share1/new_folder
 files delete my_share1/test_file.bin
 files download --to-folder=. my_share1/test_file.bin
-files download --to-folder=. my_share1/test_file.bin --transfer=httpgw --transfer-info=@json:'{"url":"https://my_http_gw_fqdn_port/aspera/http-gwy"}'
-files upload --to-folder=my_share1 'faux:///testfile?1m' --transfer=httpgw --transfer-info=@json:'{"url":"https://my_http_gw_fqdn_port/aspera/http-gwy","synchronous":true,"api_version":"v1","upload_chunk_size":100000}'
+files download --to-folder=. my_share1/test_file.bin --transfer=httpgw --transfer-info=@json:'{"url":"https://tst.example.com/path@"}'
+files mkdir my_share1/new_folder
+files upload --to-folder=https://shares.share1 'faux:///testfile?1m' --transfer=httpgw --transfer-info=@json:'{"url":"my_example.com/path@","synchronous":true,"api_version":"v1","upload_chunk_size":100000}'
 files upload --to-folder=my_share1 test_file.bin
-files upload --to-folder=my_share1 test_file.bin --transfer=httpgw --transfer-info=@json:'{"url":"https://my_http_gw_fqdn_port/aspera/http-gwy"}'
+files upload --to-folder=my_share1 test_file.bin --transfer=httpgw --transfer-info=@json:'{"url":"https://tst.example.com/path@"}'
 health
 ```
 
@@ -6527,11 +6767,46 @@ node info --log-level=trace2
 node upload test_file.bin
 ```
 
+## Plugin: `httpgw`: HTTP Gateway
+
+### Httpgw sample commands
+
+> **Note:** Add `ascli httpgw` in front of the commands:
+
+```bash
+health
+```
+
+## Plugin: `faspio`: Faspio Gateway
+
+### Faspio sample commands
+
+> **Note:** Add `ascli faspio` in front of the commands:
+
+```bash
+bridges create @json:'{"name":"test1","local":{"protocol":"tcp","tls_enabled":false,"port":"3000","bind_address":"127.0.0.1"},"forward":{"protocol":"fasp","tls_enabled":false,"port":"3994","bind_address":"127.0.0.1","host":["10.0.0.1"]}}'
+bridges delete --bulk=yes @json:@stdin:
+bridges list
+health
+```
+
+## Plugin: `alee`: Aspera License Entitlement Engine
+
+Retrieve information on subscription.
+
+### Alee sample commands
+
+> **Note:** Add `ascli alee` in front of the commands:
+
+```bash
+health
+```
+
 ## Plugin: `preview`: Preview generator for AoC
 
 The `preview` generates thumbnails (office, images, video) and video previews on storage for use primarily in the Aspera on Cloud application.
 It uses the **node API** of Aspera HSTS and requires use of Access Keys and its **storage root**.
-Several parameters can be used to tune several aspects:
+Several options can be used to tune several aspects:
 
 - Methods for detection of new files needing generation
 - Methods for generation of video preview
@@ -6558,10 +6833,11 @@ asnodeadmin --reload
 
 If another folder is configured on the HSTS, then specify it to `ascli` using the option `previews_folder`.
 
-The HSTS node API limits any preview file to a parameter: `max_request_file_create_size_kb` (1 KB is 1024 bytes).
-This size is internally capped to `1<<24` Bytes (16777216) , i.e. 16384 KBytes.
+The HSTS node API limits any preview file to a parameter: `max_request_file_create_size_kb` (1 KB is 1024 Bytes).
+This size is internally capped to `1<<24` Bytes (16777216) , i.e. 16384 KB, i.e. 16MB.
 
-To change this parameter in `aspera.conf`, use `asconfigurator`. To display the value, use `asuserdata`:
+To change this parameter in `aspera.conf`, use `asconfigurator`.
+To display the value, use `asuserdata`:
 
 ```bash
 asuserdata -a | grep max_request_file_create_size_kb
@@ -6642,7 +6918,7 @@ chmod a+x /usr/bin/unoconv
 The preview generator should be executed as a non-user.
 When using object storage, any user can be used, but when using local storage it is usually better to use the user `xfer`, as uploaded files are under this identity: this ensures proper access rights. (we will assume this)
 
-Like any `ascli` commands, parameters can be passed on command line or using a configuration [Option Preset](#option-preset)'.
+Like any `ascli` commands, options can be passed on command line or using a configuration [Option Preset](#option-preset).
 The configuration file must be created with the same user used to run so that it is properly used on runtime.
 
 The `xfer` user has a special protected shell: `aspshell`, so in order to update the configuration, and when changing identity, specify an alternate shell.
@@ -6902,9 +7178,9 @@ Interesting `ascp` features are found in its arguments: (see `ascp` manual):
 - `ascp` has an option to send only files not modified since the last X seconds: `--exclude-newer-than`, `--exclude-older-than` (`exclude_newer_than`,`exclude_older_than`)
 - `--src-base` (`src_base`) if top level folder name shall not be created on destination
 
-> **Note:** `ascli` takes transfer parameters exclusively as a [*transfer-spec*](#transfer-specification), with `ts` option.
+> **Note:** `ascli` takes transfer parameters exclusively as a [**transfer-spec**](#transfer-specification), with `ts` option.
 >
-> **Note:** Most, but not all, native `ascp` arguments are available as standard [*transfer-spec*](#transfer-specification) parameters.
+> **Note:** Most, but not all, native `ascp` arguments are available as standard [**transfer-spec**](#transfer-specification) parameters.
 >
 > **Note:** Only for the [`direct`](#agent-direct) transfer agent (not others, like connect or node), native `ascp` arguments can be provided with parameter `ascp_args` of option `transfer_info` .
 
@@ -6914,11 +7190,11 @@ Virtually any transfer on a **repository** on a regular basis might emulate a ho
 
 > **Note:** File detection is not based on events (`inotify`, etc...), but on a simple folder scan on source side.
 >
-> **Note:** Parameters may be saved in a [Option Preset](#option-preset)' and used with `-P`.
+> **Note:** Options may be saved in a [Option Preset](#option-preset) and used with `-P`.
 
 #### Scheduling
 
-Once `ascli` parameters are defined, run the command using the OS native scheduler, e.g. every minutes, or 5 minutes, etc...
+Once `ascli` command line arguments are defined, run the command using the OS native scheduler, e.g. every minutes, or 5 minutes, etc...
 Refer to section [Scheduler](#scheduler). (on use of option `lock_port`)
 
 ### Example: Upload hot folder
@@ -7081,7 +7357,7 @@ Transfer is: <%=global_transfer_status%>
 
 This gem comes with a second executable tool providing a simplified standardized interface to start a FASP session: `asession`.
 
-It aims at simplifying the startup of a FASP session from a programmatic stand point as formatting a [*transfer-spec*](#transfer-specification) is:
+It aims at simplifying the startup of a FASP session from a programmatic stand point as formatting a [**transfer-spec**](#transfer-specification) is:
 
 - Common to Aspera Node API (HTTP POST /ops/transfer)
 - Common to Aspera Connect API (browser javascript startTransfer)
@@ -7091,7 +7367,7 @@ Hopefully, IBM integrates this directly in `ascp`, and this tool is made redunda
 
 This makes it easy to integrate with any language provided that one can spawn a sub process, write to its STDIN, read from STDOUT, generate and parse JSON.
 
-`ascli` expect one single argument: a session specification that contains parameters and a [*transfer-spec*](#transfer-specification).
+`ascli` expect one single argument: a session specification that contains parameters and a [**transfer-spec**](#transfer-specification).
 
 If no argument is provided, it assumes a value of: `@json:@stdin:`, i.e. a JSON formatted on stdin.
 
@@ -7103,7 +7379,7 @@ Top level parameters supported by `asession`:
 
 | parameter | description |
 |-----------|-------------|
-| `spec` | the [*transfer-spec*](#transfer-specification) |
+| `spec` | the [**transfer-spec**](#transfer-specification) |
 | `agent` | same parameters as transfer-info for agent `direct` |
 | `loglevel` | log level of `asession` |
 | `file_list_folder` | the folder used to store (for garbage collection) generated file lists. By default it is `[system tmp folder]/[username]_asession_filelists` |
@@ -7136,7 +7412,7 @@ asession < session.json
 
 `asession` also supports asynchronous commands (on the management port). Instead of the traditional text protocol as described in `ascp` manual, the format for commands is: one single line per command, formatted in JSON, where parameters shall be **snake** style, for example: `LongParameter` -&gt; `long_parameter`
 
-This is particularly useful for a persistent session ( with the [*transfer-spec*](#transfer-specification) parameter: `"keepalive":true` )
+This is particularly useful for a persistent session ( with the [**transfer-spec**](#transfer-specification) parameter: `"keepalive":true` )
 
 ```json
 asession
@@ -7205,7 +7481,7 @@ So, it evolved into `ascli`:
 
 - Portable: works on platforms supporting `ruby` (and `ascp`)
 - Easy to install with the `gem` utility
-- Supports transfers with multiple [Transfer Agents](#transfer-clients-agents), that&apos;s why transfer parameters moved from `ascp` command line to [*transfer-spec*](#transfer-specification) (more reliable , more standard)
+- Supports transfers with multiple [Transfer Agents](#transfer-clients-agents), that&apos;s why transfer parameters moved from `ascp` command line to [**transfer-spec**](#transfer-specification) (more reliable , more standard)
 - `ruby` is consistent with other Aspera products
 
 Over the time, a supported command line tool `aspera` was developed in C++, it was later on deprecated.
@@ -7215,7 +7491,7 @@ Enjoy a coffee on me:
 
 ```bash
 ascli config coffee --ui=text
-ascli config coffee --ui=text --query=@json:'{"text":"true"}'
+ascli config coffee --ui=text --image=@json:'{"text":true}'
 ascli config coffee
 ```
 
@@ -7244,11 +7520,13 @@ This also requires Ruby header files.
 If Ruby was installed as a Linux Packages, then also install Ruby development package:
 `ruby-dev` or `ruby-devel`, depending on distribution.
 
-### ED255519 key not supported
+### ED25519 key not supported
 
 ED25519 keys are deactivated since `ascli` version 0.9.24 as it requires additional gems that require native compilation and thus caused problems.
 This type of key will just be ignored.
 
+To re-activate, set env var `ASCLI_ENABLE_ED25519` to `true`.
+
 Without this deactivation, if such key was present in user's `.ssh` folder then the following error was generated:
 
 ```output
@@ -7258,4 +7536,5 @@ OpenSSH keys only supported if ED25519 is available
 Which meant that you do not have Ruby support for ED25519 SSH keys.
 You may either install the suggested Gems, or remove your ed25519 key from your `.ssh` folder to solve the issue.
 
-To re-activate, set env var `ASCLI_ENABLE_ED25519` to `true`.
+In addition, host keys of type: `ecdsa-sha2` and `ecdh-sha2` are also de-activated by default.
+To re-activate, set env var `ASCLI_ENABLE_ECDSHA2` to `true`.