aspera-cli 4.12.0 → 4.14.0

data/README.md

@@ -1,13 +1,12 @@
 # Command Line Interface for IBM Aspera products
 <!-- markdownlint-disable MD033 MD003 MD053 -->
-<!-- cSpell:ignore devkit zcvf zxvf noded secondfile filesize sedemo eudemo webmail csum eascp loglevel cronfile magick keepalive inotify eastus bluemix trev sshfp struct genkey passout ibmaspera unpermitted -->
-<!-- cSpell:ignoreRegExp /-P[a-z]+/g -->
-<!-- cSpell:ignoreRegExp /my[a-z]+/g -->
+<!-- cspell:ignore devkit zcvf zxvf noded secondfile filesize sedemo eudemo webmail csum eascp loglevel cronfile magick keepalive inotify eastus bluemix trev sshfp struct genkey passout ibmaspera unpermitted schtasks taskschd dascli -->
+
 [comment1]: # (Do not edit this README.md, edit docs/README.erb.md, for details, read docs/README.md)
 
 ##
 
-Version : 4.12.0
+Version : 4.14.0
 
 Laurent/2016-2023
 
@@ -19,9 +18,9 @@ Ruby Gem: [https://rubygems.org/gems/aspera-cli](https://rubygems.org/gems/asper
 
 Ruby Doc: [https://www.rubydoc.info/gems/aspera-cli](https://www.rubydoc.info/gems/aspera-cli)
 
-Minimum required Ruby version: >= 2.4.
+Minimum required Ruby version: >= 2.6.
 
-> **Deprecation notice**: the minimum Ruby version will be 2.7 in a future version.
+> **Deprecation notice**: the minimum Ruby version will be 3.0 in a future version.
 
 [Aspera APIs on IBM developer](https://developer.ibm.com/?size=30&q=aspera&DWContentType[0]=APIs&sort=title_asc)
 [Link 2](https://developer.ibm.com/apis/catalog/?search=aspera)
@@ -58,7 +57,7 @@ So it is designed for:
 If the need is to perform operations programmatically in languages such as: C, Go, Python, nodejs, ... then it is better to directly use [Aspera APIs](https://ibm.biz/aspera_api)
 
 - Product APIs (REST) : e.g. AoC, Faspex, node
-- Transfer SDK : with gRPC interface and language stubs (C, C++, Python, .NET/C#, java, ruby, etc...)
+- Transfer SDK : with gRPC interface and language stubs (C, C++, Python, .NET/C#, java, Ruby, etc...)
 
 Using APIs (application REST API and transfer SDK) will prove to be easier to develop and maintain.
 
@@ -93,7 +92,7 @@ ascli --version
 ```
 
 ```bash
-4.12.0
+4.14.0
 ```
 
 ### First use
@@ -104,8 +103,6 @@ If you want to test with Aspera on Cloud, jump to section: [Wizard](#aocwizard)
 
 To test with Aspera demo transfer server, setup the environment and then test:
 
-<!-- spellchecker: disable -->
-
 ```bash
 ascli config initdemo
 ```
@@ -115,18 +112,16 @@ ascli server browse /
 ```
 
 ```output
-:............:...........:......:........:...........................:.......................:
-:   zmode    :   zuid    : zgid :  size  :           mtime           :         name          :
-:............:...........:......:........:...........................:.......................:
-: dr-xr-xr-x : asperaweb : fasp : 4096   : 2014-04-10 19:44:05 +0200 : aspera-test-dir-tiny  :
-: drwxr-xr-x : asperaweb : fasp : 176128 : 2018-03-15 12:20:10 +0100 : Upload                :
-: dr-xr-xr-x : asperaweb : fasp : 4096   : 2015-04-01 00:37:22 +0200 : aspera-test-dir-small :
-: dr-xr-xr-x : asperaweb : fasp : 4096   : 2018-05-04 14:26:55 +0200 : aspera-test-dir-large :
-:............:...........:......:........:...........................:.......................:
++------------+-----------+-----------+-------+---------------------------+-----------------------+
+| zmode      | zuid      | zgid      | size  | mtime                     | name                  |
++------------+-----------+-----------+-------+---------------------------+-----------------------+
+| drwxr-xr-x | asperaweb | asperaweb | 90112 | 2023-04-05 15:31:21 +0200 | Upload                |
+| dr-xr-xr-x | asperaweb | asperaweb | 4096  | 2022-10-27 16:08:16 +0200 | aspera-test-dir-large |
+| dr-xr-xr-x | asperaweb | asperaweb | 4096  | 2022-10-27 16:08:17 +0200 | aspera-test-dir-small |
+| dr-xr-xr-x | asperaweb | asperaweb | 4096  | 2022-10-27 16:08:17 +0200 | aspera-test-dir-tiny  |
++------------+-----------+-----------+-------+---------------------------+-----------------------+
 ```
 
-<!-- spellchecker: enable -->
-
 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](#lprt) for the server's authentication options. The following example will:
 
 - create a [option preset](#lprt)
@@ -155,17 +150,17 @@ ascli server browse /aspera-test-dir-large
 ```
 
 ```output
-:............:...........:......:..............:...........................:............................:
-:   zmode    :   zuid    : zgid :     size     :           mtime           :            name            :
-:............:...........:......:..............:...........................:............................:
-: -rw-r--r-- : asperaweb : fasp : 209715200    : 2014-04-10 19:49:27 +0200 : 200MB                      :
-: -rw-r--r-- : asperaweb : fasp : 524288000    : 2014-04-10 19:44:15 +0200 : 500MB                      :
-: -rw-r--r-- : asperaweb : fasp : 5368709120   : 2014-04-10 19:45:52 +0200 : 5GB                        :
-: -rw-r--r-- : asperaweb : fasp : 500000000000 : 2017-06-14 20:09:57 +0200 : 500GB                      :
-: -rw-r--r-- : asperaweb : fasp : 1048576000   : 2014-04-10 19:49:23 +0200 : 1GB                        :
-: -rw-r--r-- : asperaweb : fasp : 104857600    : 2014-04-10 19:49:29 +0200 : 100MB                      :
-: -rw-r--r-- : asperaweb : fasp : 10737418240  : 2014-04-10 19:49:04 +0200 : 10GB                       :
-:............:...........:......:..............:...........................:............................:
++------------+-----------+-----------+--------------+---------------------------+-------+
+| zmode      | zuid      | zgid      | size         | mtime                     | name  |
++------------+-----------+-----------+--------------+---------------------------+-------+
+| -r-xr-x--- | asperaweb | asperaweb | 104857600    | 2022-10-27 16:06:38 +0200 | 100MB |
+| -r-xr-x--- | asperaweb | asperaweb | 10737418240  | 2022-10-27 16:08:12 +0200 | 10GB  |
+| -r-xr-x--- | asperaweb | asperaweb | 500000000000 | 2022-10-27 16:06:26 +0200 | 500GB |
+| -r-xr-x--- | asperaweb | asperaweb | 524288000    | 2022-10-27 14:53:00 +0200 | 500MB |
+| -r-xr-x--- | asperaweb | asperaweb | 1048576000   | 2022-10-27 16:06:37 +0200 | 1GB   |
+| -r-xr-x--- | asperaweb | asperaweb | 5368709120   | 2022-10-27 14:53:47 +0200 | 5GB   |
+| -r-xr-x--- | asperaweb | asperaweb | 209715200    | 2022-10-27 14:52:56 +0200 | 200MB |
++------------+-----------+-----------+--------------+---------------------------+-------+
 ```
 
 ```bash
@@ -185,7 +180,7 @@ Then, follow the section relative to the product you want to interact with ( Asp
 
 ## <a id="installation"></a>Installation
 
-It is possible to install *either* directly on the host operating system (Linux, Windows, macOS) or as a docker container.
+It is possible to install **either** directly on the host operating system (Linux, macOS, Windows) or as a container (`docker`).
 
 The direct installation is recommended and consists in installing:
 
@@ -193,28 +188,30 @@ The direct installation is recommended and consists in installing:
 - [aspera-cli](#the_gem)
 - [Aspera SDK (`ascp`)](#fasp_prot)
 
-Ruby version: >= 2.4.
+Ruby version: >= 2.6.
 
-> **Deprecation notice**: the minimum Ruby version will be 2.7 in a future version.
+> **Deprecation notice**: the minimum Ruby version will be 3.0 in a future version.
 
 The following sections provide information on the various installation methods.
 
 An internet connection is required for the installation. If you don't have internet for the installation, refer to section [Installation without internet access](#offline_install).
 
-### Docker container
+### Container
 
-The image is: [martinlaurent/ascli](https://hub.docker.com/r/martinlaurent/ascli).
+The container image is: [martinlaurent/ascli](https://hub.docker.com/r/martinlaurent/ascli).
 The container contains: Ruby, `ascli` and the Aspera Transfer SDK.
-To use the container, ensure that you have `docker` (or `podman`) installed.
+To use the container, ensure that you have `podman` (or `docker`) installed.
 
 ```bash
-docker --version
+podman --version
 ```
 
+#### Container: quick start
+
 **Wanna start quickly ?** With an interactive shell ? Execute this:
 
 ```bash
-docker run --tty --interactive --entrypoint bash martinlaurent/ascli:latest
+podman run --tty --interactive --entrypoint bash martinlaurent/ascli:latest
 ```
 
 Then, execute individual `ascli` commands such as:
@@ -232,18 +229,22 @@ That is simple, but there are limitations:
 - Any generated file in the container will be lost on container (shell) exit. Including configuration files and downloaded files.
 - No possibility to upload files located on the host system
 
-The container image is built from this [Dockerfile](Dockerfile): the entry point is `ascli` and the default command is `help`.
+#### Container: Details
+
+The container image is built from this [Dockerfile](Dockerfile.tmpl.erb): the entry point is `ascli` and the default command is `help`.
+
+If you want to run the image with a shell, execute with option: `--entrypoint bash`, and give argument `-l` (`bash` login option to override the `help` default argument)
 
-The container can also be execute for individual commands like this: (add `ascli` commands and options at the end of the command line, e.g. `-v` to display the version)
+The container can also 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
-docker run --rm --tty --interactive martinlaurent/ascli:latest
+podman run --rm --tty --interactive martinlaurent/ascli:latest
 ```
 
 For more convenience, you may define a shell alias:
 
 ```bash
-alias ascli='docker run --rm --tty --interactive martinlaurent/ascli:latest'
+alias ascli='podman run --rm --tty --interactive martinlaurent/ascli:latest'
 ```
 
 Then, you can execute the container like a local command:
@@ -253,11 +254,11 @@ ascli -v
 ```
 
 ```text
-4.12.0
+4.14.0
 ```
 
 In order to keep persistency of configuration on the host,
-you should mount your user's config folder to the container.
+you should specify your user's config folder as a volume for the container.
 To enable write access, a possibility is to run as `root` in the container (and set the default configuration folder to `/home/cliuser/.aspera/ascli`).
 Add options:
 
@@ -265,7 +266,7 @@ Add options:
 --user root --env ASCLI_HOME=/home/cliuser/.aspera/ascli --volume $HOME/.aspera/ascli:/home/cliuser/.aspera/ascli
 ```
 
-> **Note:** if you are using a `podman machine`, e.g. on Macos , make sure that the folder is also shared between the VM and the host, so that sharing is: container &rarr; VM &rarr; Host: `podman machine init ... --volume="/Users:/Users"`
+> **Note:** if you are using a `podman machine`, e.g. on macOS , make sure that the folder is also shared between the VM and the host, so that sharing is: container &rarr; VM &rarr; Host: `podman machine init ... --volume="/Users:/Users"`
 
 As shown in the quick start, if you prefer to keep a running container with a shell and `ascli` available,
 you can change the entry point, add option:
@@ -274,8 +275,8 @@ you can change the entry point, add option:
 --entrypoint bash
 ```
 
-You may also probably want that files downloaded in the container are in fact placed on the host.
-In this case you need also to mount the shared transfer folder:
+You may also probably want that files downloaded in the container are directed to the host.
+In this case you need also to specify the shared transfer folder as a volume:
 
 ```bash
 --volume $HOME/xferdir:/xferfiles
@@ -286,7 +287,7 @@ In this case you need also to mount the shared transfer folder:
 And if you want all the above, simply use all the options:
 
 ```bash
-alias asclish="docker 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 martinlaurent/ascli:latest"
 ```
 
 ```bash
@@ -297,6 +298,8 @@ mkdir -p $HOME/.aspera/ascli
 asclish
 ```
 
+#### Container: Sample start script
+
 A convenience sample script is also provided: download the script [`dascli`](../examples/dascli) from [the GIT repo](https://raw.githubusercontent.com/IBM/aspera-cli/main/examples/dascli) :
 
 > **Note:** If you have installed `ascli`, the script `dascli` can also be found: `cp $(ascli conf gem path)/../examples/dascli ascli`
@@ -305,8 +308,8 @@ Some environment variables can be set for this script to adapt its behavior:
 
 | env var      | description                        | default                  | example                  |
 |--------------|------------------------------------|--------------------------|--------------------------|
-| ASCLI_HOME | configuration folder (persistency) | `$HOME/.aspera/ascli` | `$HOME/.ascliconfig`     |
-| docker_args  | additional options to `docker`     | &lt;empty&gt;            | `--volume /Users:/Users` |
+| 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      |                          |
 | version      | container image version            | latest                   | `4.8.0.pre`              |
 
@@ -333,22 +336,88 @@ echo 'Local file to transfer' > $xferdir/samplefile.txt
 ```
 
 > **Note:** The local file (`samplefile.txt`) is specified relative to storage view from container (`/xferfiles`) mapped to the host folder `$HOME/xferdir`
+>
+> **Note:** Do not use too many volumes, as the AUFS limits the number.
+
+#### Container: Offline installation
+
+- First create the image archive:
+
+```bash
+podman pull martinlaurent/ascli
+podman save martinlaurent/ascli|gzip>ascli_image_latest.tar.gz
+```
+
+- Then, on air-gapped system:
+
+```bash
+podman load -i ascli_image_latest.tar.gz
+```
+
+#### Container: `aspera.conf`
+
+`ascp`'s configuration file `aspera.conf` is located in the container at: `/aspera_sdk/aspera.conf` (see Dockerfile).
+As the container is immutable, it is not recommended to modify this file.
+If one wants to change the content, it is possible to tell `ascp` to use another file using `ascp` option `-f`, e.g. by locating it on the host folder `$HOME/.aspera/ascli` mapped to the container folder `/home/cliuser/.aspera/ascli`:
+
+```bash
+echo '<CONF/>' > $HOME/.aspera/ascli/aspera.conf
+```
+
+Then, tell `ascp` to use that other conf file:
+
+```bash
+--transfer-info=@json:'{"ascp_args":["-f","/home/cliuser/.aspera/ascli/aspera.conf"]}'
+```
+
+#### Container: Singularity
+
+Singularity is another type of use of container.
+
+On Linux install:
+
+```console
+dnf install singularity-ce
+```
+
+Build an image like this:
+
+```bash
+singularity build ascli.sif docker://martinlaurent/ascli
+```
+
+The use like this:
+
+```bash
+singularity run ascli.sif
+```
+
+Or get a shell with access to the tool like this:
+
+```bash
+singularity shell ascli.sif
+```
 
 ### <a id="ruby"></a>Ruby
 
 Use this method to install on the native host.
 
-A ruby interpreter is required to run the tool or to use the gem and tool.
+A Ruby interpreter is required to run the tool or to use the gem and tool.
 
-Required Ruby version: >= 2.4.
+Required Ruby version: >= 2.6.
 
-> **Deprecation notice**: the minimum Ruby version will be 2.7 in a future version.
+> **Deprecation notice**: the minimum Ruby version will be 3.0 in a future version.
 
 *Ruby can be installed using any method* : rpm, yum, dnf, rvm, brew, windows installer, ... .
 
-Refer to the following sections for a proposed method for specific operating systems.
+In priority, refer to the official Ruby documentation:
+
+- [Download Ruby](https://www.ruby-lang.org/en/downloads/)
+- [Installation Guide](https://www.ruby-lang.org/en/documentation/installation/)
+
+Else, refer to the following sections for a proposed method for specific operating systems.
 
-The recommended installation method is `rvm` for systems with "bash-like" shell (Linux, macOS, Windows with cygwin, etc...).
+The recommended installation method is `rvm` for Unix-like systems (Linux, AIX, macOS, Windows with cygwin, etc...).
 If the generic install is not suitable (e.g. Windows, no cygwin), you can use one of OS-specific install method.
 If you have a simpler better way to install Ruby : use it !
 
@@ -356,7 +425,7 @@ If you have a simpler better way to install Ruby : use it !
 
 Use this method which provides more flexibility.
 
-Install "rvm": follow [https://rvm.io/](https://rvm.io/) :
+Install `rvm`: follow [https://rvm.io/](https://rvm.io/) :
 
 Execute the shell/curl command. As regular user, it install in the user's home: `~/.rvm` .
 
@@ -372,7 +441,7 @@ If you keep the same terminal (not needed if re-login):
 source ~/.rvm/scripts/rvm
 ```
 
-It is advised to get one of the pre-compiled ruby version, you can list with:
+It is advised to get one of the pre-compiled Ruby version, you can list with:
 
 ```bash
 rvm list --remote
@@ -381,10 +450,10 @@ rvm list --remote
 Install the chosen pre-compiled Ruby version:
 
 ```bash
-rvm install 2.7.2 --binary
+rvm install 3.2.2
 ```
 
-Ruby is now installed for the user, go on to Gem installation.
+Ruby is now installed for the user, go to [Gem installation](#the_gem).
 
 #### Generic: RVM: global installation (as root)
 
@@ -399,7 +468,7 @@ curl -sSL https://get.rvm.io | bash -s -- --path /usr/local
 
 As root, make sure this will not collide with other application using Ruby (e.g. Faspex).
 If so, one can rename the login script: `mv /etc/profile.d/rvm.sh /etc/profile.d/rvm.sh.ok`.
-To activate ruby (and ascli) later, source it:
+To activate Ruby (and ascli) later, source it:
 
 ```bash
 source /etc/profile.d/rvm.sh.ok
@@ -434,25 +503,36 @@ brew install ruby
 
 #### Linux: package
 
-If your Linux distribution provides a standard ruby package, you can use it provided that the version is compatible (check at beginning of section).
+If your Linux distribution provides a standard Ruby package, you can use it provided that the version supported.
 
-Example: RHEL 8 and 9: basic installation
+**Example:** RHEL 8+, Rocky Linux 8+, Centos 8 Stream: with extensions to compile native gems
 
-```bash
-yum module install ruby:3.1
-```
+- Check available ruby versions:
 
-Example: RHEL 8, Centos 8 Stream: with extensions to compile native gems
+  ```bash
+  dnf module list ruby
+  ```
 
-```bash
-yum install make automake gcc gcc-c++ kernel-devel
-yum install redhat-rpm-config
-dnf module reset ruby
-dnf module enable ruby:3.1
-dnf module -y install ruby:3.1/common
-```
+- If ruby was already installed with an older version, remove it:
 
-Other examples:
+  ```bash
+  dnf module -y reset ruby
+  ```
+
+- Install packages needed to build native gems:
+  
+    ```bash
+    dnf install -y make automake gcc gcc-c++ kernel-devel
+    ```
+
+- Enable the Ruby version you want:
+
+  ```bash
+  dnf module -y enable ruby:3.1
+  dnf install -y ruby-devel
+  ```
+
+**Other examples:**
 
 ```bash
 yum install -y ruby ruby-devel rubygems ruby-json
@@ -462,7 +542,7 @@ yum install -y ruby ruby-devel rubygems ruby-json
 apt install -y ruby ruby-dev rubygems ruby-json
 ```
 
-One can cleanup the whole yum-installed ruby environment like this to uninstall:
+One can cleanup the whole yum-installed Ruby environment like this to uninstall:
 
 ```bash
 gem uninstall $(ls $(gem env gemdir)/gems/|sed -e 's/-[^-]*$//'|sort -u)
@@ -475,7 +555,7 @@ For example for AIX, one can look at:
 
 <https://www.ibm.com/support/pages/aix-toolbox-open-source-software-downloads-alpha#R>
 
-If your Unix does not provide a pre-built ruby, you can get it using one of those
+If your Unix does not provide a pre-built Ruby, you can get it using one of those
 [methods](https://www.ruby-lang.org/en/documentation/installation/).
 
 For instance to build from source, and install in `/opt/ruby` :
@@ -502,7 +582,7 @@ If you already have a Java JVM on your system (`java`), it is possible to use `j
 
 <https://www.jruby.org/download>
 
-> **Note:** Using jruby the startup time is longer than the native ruby, but the transfer speed is not impacted (executed by `ascp` binary).
+> **Note:** Using jruby the startup time is longer than the native Ruby, but the transfer speed is not impacted (executed by `ascp` binary).
 
 ### <a id="the_gem"></a>`aspera-cli` gem
 
@@ -518,9 +598,10 @@ To upgrade to the latest version:
 gem update aspera-cli
 ```
 
-`ascli` checks every week if a new version is available and notify the user in a WARN log. To de-activate this feature set the option `version_check_days` to `0`, or specify a different period in days.
+`ascli` checks every week if a new version is available and notify the user in a WARN log.
+To de-activate this feature, globally set the option `version_check_days` to `0`, or specify a different period in days.
 
-To check manually:
+To check if a new version is available (independently of `version_check_days`):
 
 ```bash
 ascli conf check_update
@@ -556,7 +637,6 @@ If the embedded method is not used, the following packages are also suitable:
 
 - IBM Aspera Connect Client (Free)
 - IBM Aspera Desktop Client (Free)
-- IBM Aspera CLI (Free)
 - IBM Aspera High Speed Transfer Server (Licensed)
 - IBM Aspera High Speed Transfer EndPoint (Licensed)
 
@@ -670,27 +750,72 @@ Moreover all `ascp` options are supported either through transfer spec parameter
 `ascli` is typically executed in a shell, either interactively or in a script.
 `ascli` receives its arguments from this shell (through Operating System).
 
-#### Shell parsing for Linux, Unix, Macos
+#### Shell parsing for Unix-like systems: Linux, macOS, AIX
 
-On Linux and Unix environments, this is typically a POSIX shell (bash, zsh, ksh, sh).
+Linux command line parsing is easy: It is fully documented in the shell's documentation.
+
+On Unix-like environments, this is typically a POSIX shell (bash, zsh, ksh, sh).
 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).
-Then it builds a list of arguments and then `ascli` (Ruby) is executed.
+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`.
-So special character handling (quotes, spaces, env vars, ...) is first done in the shell.
+So special character handling (quotes, spaces, env vars, ...) is handled by the shell for any command executed.
 
 #### Shell parsing for Windows
 
-On Windows, `cmd.exe` is typically used.
-Windows process creation does not receive the list of arguments but just the whole line.
-It's up to the program to parse arguments. Ruby follows the Microsoft C/C++ parameter parsing rules.
+MS Windows command line parsing is not easy: It is not hasndled by the shell (`cmd.exe`), not handled by the operating system, but it is handled by the application (here Ruby).
+
+As far as `ascli` is concerned: it is close to a Linux shell parsing.
+
+Thanksfully, `ascli` provides a command to check the value of an argument after parsing: `config echo`.
+One can also run `ascli` with option `--log-level=debug` to display the command line after parsing.
+
+The following examples give the same result on Windows:
+
+- single quote protects the double quote
+
+  ```cmd
+   conf echo @json:'{"url":"https://..."}'
+  ```
+
+- triple double quotes are replaced with a single double quote
+
+  ```cmd
+   conf echo @json:{"""url""":"""https://..."""}
+  ```
+
+- double quote is escaped with backslash within double quotes
+
+  ```cmd
+   conf echo @json:"{\"url\":\"https://...\"}"
+  ```
+
+On Windows, `cmd.exe` is typically used to start .
+`cmd.exe` handles some special characters: `^"<>|%&`.
+Basically it handles I/O redirections (`<>|`), shell variables (`%`), multiple commands (`&`) and handles those special characters from the command line.
+Eventually, all those special characters are removed from the command line unless escaped with `^` or `"`.
+`"` are kept and given to the program.
+
+Then, Windows `CreateProcess` is called with just the whole command line as a single string, unlike Unix-like systems where the command line is split into arguments by the shell.
+
+It's up to the program to split arguments:
 
 - [Windows: How Command Line Parameters Are Parsed](https://daviddeley.com/autohotkey/parameters/parameters.htm#RUBY)
-- [Understand Quoting and Escaping of Windows Command Line Arguments](http://www.windowsinspired.com/understanding-the-command-line-string-and-arguments-received-by-a-windows-program/)
+- [Understand Quoting and Escaping of Windows Command Line Arguments](https://web.archive.org/web/20190316094059/http://www.windowsinspired.com/understanding-the-command-line-string-and-arguments-received-by-a-windows-program/)
+
+ is a Ruby program, so Ruby parses the command line into arguments and provides them to the program.
+Ruby vaguely follows the Microsoft C/C++ parameter parsing rules.
+(See `w32_cmdvector` in Ruby source [`win32.c`](https://github.com/ruby/ruby/blob/master/win32/win32.c#L1766)) : <!--cspell:disable-line-->
+
+- space characters: split arguments (space, tab, newline)
+- backslash: `\` escape single special character
+- globbing characters: `*?[]{}` for file globbing
+- double quotes: `"`
+- single quotes: `'`
 
 #### Extended Values (JSON, Ruby, ...)
 
-Some of the CLI parameters are expected to be [Extended Values](#extended), i.e. not a simple strings, but a complex structure (Hash, Array).
+Some of the `ascli` parameters are expected to be [Extended Values](#extended), i.e. not a simple strings, but a complex structure (Hash, Array).
 Typically, the `@json:` modifier is used, it expects a JSON string. JSON itself has some special syntax: for example `"` is used to denote strings.
 
 #### Testing Extended Values
@@ -703,12 +828,12 @@ Example: The shell parses three arguments (as strings: `1`, `2` and `3`), so the
 ascli conf echo 1 2 3
 ```
 
-```bash
+```ruby
 "1"
 ERROR: Argument: unprocessed values: ["2", "3"]
 ```
 
-`config echo` displays the value of the first argument using Ruby syntax: it surrounds a string with `"` and add `\` before special characters.
+`config echo` displays the value of the **first** argument using Ruby syntax: it surrounds a string with `"` and add `\` before special characters.
 
 > **Note:** It gets its value after shell command line parsing and `ascli` extended value parsing.
 
@@ -719,7 +844,7 @@ Depending on the case, a different `format` is used to display the actual value.
 For example, in the simple string `Hello World`, the space character is special for the shell, so it must be escaped so that a single value is represented.
 
 Double quotes are processed by the shell to create a single string argument.
-For POSIX shells, single quotes can also be used in this case, or protect the special character ` ` (space) with a backslash. <!-- markdownlint-disable-line -->
+For **POSIX shells**, single quotes can also be used in this case, or protect the special character ` ` (space) with a backslash. <!-- markdownlint-disable-line -->
 
 ```bash
 ascli conf echo "Hello World" --format=text
@@ -736,7 +861,7 @@ Hello World
 To be evaluated by shell, the shell variable must not be in single quotes.
 Even if the variable contains spaces it makes only one argument to `ascli` because word parsing is made before variable expansion by shell.
 
-> **Note:** we use a simple variable here: the variable is not necessarily an environment variable.
+> **Note:** we use a shell variable here: the variable is not necessarily an environment variable (`export`).
 
 ```bash
 MYVAR="Hello World"
@@ -819,6 +944,22 @@ ascli conf echo @ruby:"{'title'=>gets.chomp}" --format=json
 
 `gets` is Ruby's method of terminal input (terminated by `\n`), and `chomp` removes the trailing `\n`.
 
+#### Command line arguments from a file
+
+If you need to provide a list of command line argument from lines that are in a file, on Linux you can use the `xargs` command:
+
+```bash
+xargs -a lines.txt -d \\n ascli conf echo
+```
+
+This is equivalent to execution of:
+
+```bash
+ascli conf echo [line1] [line2] [line3] ...
+```
+
+If there are spaces in the lines, those are not taken as separator, as we provide option `-d \\n` to `xargs`.
+
 #### Extended value using special characters read from environmental variables or files
 
 Using a text editor or shell: create a file `title.txt` (and env var) that contains exactly the text required: `Test " ' & \` :
@@ -841,7 +982,7 @@ ascli conf echo @env:MYTITLE --format=text
 Test " ' & \
 ```
 
-If the value to be used is in a more complex structure, then the `@ruby:` modifier can be used: it allows any ruby code in expression, including reading from file or env var. In those cases, there is no character to protect because values are not parsed by the shell, or JSON or even Ruby.
+If the value to be used is in a more complex structure, then the `@ruby:` modifier can be used: it allows any Ruby code in expression, including reading from file or env var. In those cases, there is no character to protect because values are not parsed by the shell, or JSON or even Ruby.
 
 ```bash
 ascli conf echo @ruby:"{'title'=>File.read('title.txt')}" --format=json
@@ -852,25 +993,50 @@ ascli conf echo @ruby:"{'title'=>ENV['MYTITLE']}" --format=json
 {"title":"Test \" ' & \\"}
 ```
 
-### Arguments : Commands and options
+### Commands, Options, Positional Values
+
+Command line arguments are the units of command line, as parsed by the shell, typically separated by spaces (and called "argv").
 
-Arguments are the units of command line, as parsed by the shell, typically separated by spaces (and called "argv").
+`ascli` considers three types of command line arguments:
 
-There are two types of command line arguments: Commands and Options. Example :
+- Commands
+- Options
+- Positional Values
 
 ```bash
 ascli command subcommand --option-name=VAL1 VAL2
 ```
 
 - executes *command*: `command subcommand`
-- with one *option*: `option_name`
-- this option is given a *value* of: `VAL1`
-- the command has one additional *argument*: `VAL2`
+- with one *option*: `option_name`and its *value*: `VAL1`
+- the command has one additional mandatory *argument*: `VAL2`
 
-When the value of a command, option or argument is constrained by a fixed list of values, it is possible to use the first letters of the value only, provided that it uniquely identifies a value. For example `ascli conf ov` is the same as `ascli config overview`.
+When the value of a command, option or argument is constrained by a fixed list of values.
+It is possible to use the first letters of the value only, provided that it uniquely identifies a value.
+For example `ascli conf ov` is the same as `ascli config overview`.
 
 The value of options and arguments is evaluated with the [Extended Value Syntax](#extended).
 
+#### Commands
+
+Commands are typically entity types or verbs to act on those entities.
+
+Example:
+
+```bash
+ascli conf ascp info
+```
+
+- `ascli` is the executable executed by the shell
+- `conf` is the first level command, and is also the name f the plugin to be used
+- `ascp` is the second level command, and is also the name of the component (singleton)
+- `info` is the third level command, and is also the action to be performed
+
+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 a wrong , or no command is provided when expected, an error message is displayed and the list of supported commands is displayed.
+
 #### Options
 
 All options, e.g. `--log-level=debug`, are command line arguments that:
@@ -878,7 +1044,7 @@ 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, provided that it is unique. E.g. `--log-l=debug` is the same as `--log-level=debug`
+- can be used by prefix, provided that it is unique. E.g. `--log-l=debug` is the same as `--log-level=debug` (avoid)
 
 Exceptions:
 
@@ -886,17 +1052,24 @@ Exceptions:
 - some options (flags) don't take a value, e.g. `-r`
 - the special option `--` stops option processing and is ignored, following command line arguments are taken as arguments, including the ones starting with a `-`. Example:
 
-```bash
-ascli config echo -- --sample
-```
+  ```bash
+  ascli config echo -- --sample
+  ```
 
-```bash
-"--sample"
-```
+  ```bash
+  "--sample"
+  ```
 
 > **Note:** Here, `--sample` is taken as an argument, and not as an option, due to `--`.
 
-Options can be optional or mandatory, with or without (hardcoded) default value. Options can be placed anywhere on command line and evaluated in order.
+Options may have an (hardcoded) default value.
+
+Options can be placed anywhere on command line and evaluated in order.
+
+Options are typically either:
+
+- optional : typically to change the default behavior
+- mandatory : typically, connection information are options that are mandatory (so they can be placed in a config file)
 
 The value for *any* options can come from the following locations (in this order, last value evaluated overrides previous value):
 
@@ -908,9 +1081,16 @@ Environment variable starting with prefix: ASCLI_ are taken as option values, e.
 
 Options values can be displayed for a given command by providing the `--show-config` option: `ascli node --show-config`
 
-#### Commands and Arguments
+#### Positional Values
+
+Positional Values are typically mandatory values for a command, such as entity creation data.
+
+If a Positional Values begins with `-`, then either use the `@val:` syntax (see [Extended Values](#extended)), or use the `--` separator (see above).
 
-Command line arguments that are not options are either commands or arguments. If an argument must begin with `-`, then either use the `@val:` syntax (see [Extended Values](#extended)), or use the `--` separator (see above).
+The advantages of using a positional value 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 config file or environment variable like for options.
+Nevertheless, [Extended Values](#extended) syntax is supported, so it is possible to retrieve a value from the config file or environment variable.
 
 ### Interactive Input
 
@@ -972,16 +1152,26 @@ ascli aoc admin res user list --fields=name,email,ats_admin --query=@json:'{"sor
 ```
 
 ```output
-:...............................:..................................:...........:
-:             name              :              email               : ats_admin :
-:...............................:..................................:...........:
-: John Curtis                   : john@example.com                 : true      :
-: Laurent Martin                : laurent@example.com              : true      :
-:...............................:..................................:...........:
++-------------------------------+----------------------------------+-----------+
+|             name              |              email               | ats_admin |
++-------------------------------+----------------------------------+-----------+
+| John Curtis                   | john@example.com                 | true      |
+| Laurent Martin                | laurent@example.com              | true      |
++-------------------------------+----------------------------------+-----------+
 ```
 
 > **Note:** `select` filters selected elements from the result of API calls, while the `query` parameters gives filtering parameters to the API when listing elements.
 
+#### entity identifier
+
+When a command is executed on a single entity, the entity is identified by a unique identifier that follows the command: e.g. `ascli aoc admin res user show 1234` where `1234` is the user identifier.
+
+> **Note:** The legacy option `id` is deprecated: `--id=1234` as it does not provide the possibility to have sub-entities.
+
+Only some commands provide the following capability: If the entity can also be uniquely identified by a name, then the name can be used instead of the identifier, using the **percent selector**: `ascli aoc admin res user show %name:john` where `john` is the user name.
+
+Syntax: `%<field>:<value>`
+
 #### Verbosity of output
 
 Output messages are categorized in 3 types:
@@ -1012,38 +1202,38 @@ By default, a table output will display one line per entry, and columns for each
 
 ### <a id="extended"></a>Extended Value Syntax
 
-Usually, values of options and arguments are specified by a simple string. But sometime it is convenient to read a value from a file, or decode it, or have a value more complex than a string (e.g. Hash table).
+Some options and arguments are specified by a simple string.
+But sometime it is convenient to read a value from a file, or decode it, or have a value more complex than a string (e.g. Hash table).
 
 The extended value syntax is:
 
 ```bash
-<0 or more decoders><0 or 1 reader><nothing or some text value>
+<0 or more decoders><nothing or some text value>
 ```
 
-The difference between reader and decoder is order and cardinality.
-Both act like a function of value on right hand side.
-Decoders are at the beginning of the value, followed by a single optional reader, followed by the optional value.
-
-The following "readers" are supported (returns value in []):
+Decoders act like a function of value on right hand side.
+Decoders are recognized by the prefix: `@` and suffix `:`
 
-- @val:VALUE   : [String] prevent further special prefix processing, e.g. `--username=@val:laurent` sets the option `username` to value `laurent`.
-- @file:PATH   : [String] read value from a URL, e.g. `--fpac=@uri:http://serv/f.pac`
-- @uri:URL     : [String] read value from a file (prefix `~/` is replaced with the users home folder), e.g. `--key=@file:~/.ssh/mykey`
-- @path:PATH   : [String] performs path expansion (prefix `~/` is replaced with the users home folder), e.g. `--config-file=@path:~/sample_config.yml`
-- @env:ENVVAR  : [String] read from a named env var, e.g.--password=@env:MYPASSVAR
-- @stdin:      : [String] read from stdin (no value on right)
-- @preset:NAME : [Hash] get whole option preset value by name. Sub-values can also be used using `.` as separator. e.g. `foo.bar` is `conf[foo][bar]`
+The following decoders are supported:
 
-In addition it is possible to decode a value, using one or multiple decoders :
-
-- @base64: [String] decode a base64 encoded string
-- @json: [any] decode JSON values (convenient to provide complex structures)
-- @zlib: [String] un-compress data
-- @ruby: [any] execute ruby code
-- @csvt: [Array] decode a titled CSV value
-- @lines: [Array] split a string in multiple lines and return an array
-- @list: [Array] split a string in multiple items taking first character as separator and return an array
-- @incps: [Hash] include values of presets specified by key `incps` in input hash
+| decoder | parameter | returns | description |
+|---------|-----------|---------|-------------|
+| base64  | String    | String  | decode a base64 encoded string
+| csvt    | String    | Array   | decode a titled CSV value
+| env     | String    | String  | read from a named env var name, e.g.--password=@env:MYPASSVAR
+| file    | String    | String  | read value from specified file (prefix `~/` is replaced with the users home folder), e.g. `--key=@file:~/.ssh/mykey` |
+| incps   | Hash      | Hash    | include values of presets specified by key `incps` in input hash
+| json    | String    | any     | decode JSON values (convenient to provide complex structures)
+| lines   | String    | Array   | split a string in multiple lines and return an array
+| list    | String    | Array   | split a string in multiple items taking first character as separator and return an array
+| path    | String    | String  | performs path expansion on specified path (prefix `~/` is replaced with the users home folder), e.g. `--config-file=@path:~/sample_config.yml` |
+| preset  | String    | Hash    | get whole option preset value by name. Sub-values can also be used using `.` as separator. e.g. `foo.bar` is `conf[foo][bar]`
+| 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)
+| 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`. |
+| zlib    | String    | String  | un-compress data
 
 To display the result of an extended value, use the `config echo` command.
 
@@ -1076,12 +1266,12 @@ ascli config echo @csvt:@file:test.csv
 ```
 
 ```output
-:......:.....................:
-: name :        email        :
-:......:.....................:
-: lolo : laurent@example.com :
-: toto : titi@tutu.tata      :
-:......:.....................:
++------+---------------------+
+| name |        email        |
++------+---------------------+
+| lolo | laurent@example.com |
+| toto | titi@tutu.tata      |
++------+---------------------+
 ```
 
 Example: create a hash and include values from preset named "config" of config file in this hash
@@ -1111,7 +1301,7 @@ It is also possible to provide a [Extended Value](#extended) in a file using `@j
 
 `ascli` configuration and other runtime files (token cache, file lists, persistency files, SDK) are stored `[config folder]`: `[User's home folder]/.aspera/ascli`.
 
-Note: `[User's home folder]` is found using ruby's `Dir.home` (`rb_w32_home_dir`).
+Note: `[User's home folder]` is found using Ruby's `Dir.home` (`rb_w32_home_dir`).
 It uses the `HOME` env var primarily, and on MS Windows it also looks at `%HOMEDRIVE%%HOMEPATH%` and `%USERPROFILE%`. `ascli` sets the env var `%HOME%` to the value of `%USERPROFILE%` if set and exists. So, on Windows `%USERPROFILE%` is used as it is more reliable than `%HOMEDRIVE%%HOMEPATH%`.
 
 The [config folder] can be displayed using :
@@ -1211,9 +1401,9 @@ ascli config open
 Older format for commands are still supported:
 
 ```bash
-ascli config id <name> set|delete|show|initialize|update
-ascli config over
-ascli config list
+ascli config preset set|delete|show|initialize|update <name>
+ascli config preset over
+ascli config preset list
 ```
 
 #### <a id="lprtconf"></a>Special Option preset: config
@@ -1242,15 +1432,39 @@ ascli config preset get default _plugin_name_
 "_default_preset_for_plugin_"
 ```
 
-#### <a id="config"></a>Plugin: `config`: CLI Configuration
+#### <a id="config"></a>Plugin: `config`: Configuration
+
+Plugin `config` provides general commands for `ascli`:
+
+- Option preset, config file operations
+- wizard
+- vault
+- ascp
+
+The default configuration for `config` is read for any plugin invocation, this allows setting global options, such as `--log-level` or `--interactive`.
+When `ascli` starts, it looks for the `default` Option preset and checks the value for `config`.
+If set, it loads the option values for any plugin used.
+
+> **Note:** If no global default is set by the user, the tool will use `global_common_defaults` when setting global parameters (e.g. `conf ascp use`)
 
-Plugin `config` is used to configure `ascli` and also contains global options.
+Show current default (global) Option preset (`config` plugin):
 
-When `ascli` starts, it looks for the `default` Option preset and if there is a value for `config`, if so, it loads the option values for any plugin used.
+```console
+$ ascli conf preset get default config
+global_common_defaults
+```
+
+```bash
+ascli conf preset set global_common_defaults version_check_days 0
+```
 
-If no global default is set by the user, the tool will use `global_common_defaults` when setting global parameters (e.g. `conf ascp use`)
+If the default global Option preset is not set:
+
+```bash
+ascli conf preset set default config global_common_defaults
+```
 
-Sample commands
+#### Config sample commands
 
 ```bash
 config ascp connect info 'Aspera Connect for Windows'
@@ -1265,9 +1479,11 @@ config ascp products list
 config ascp show
 config ascp spec
 config check_update
+config coffee
+config coffee --ui=text
+config detect --url=https://faspex4.example.com/path
 config detect --url=https://my_aoc_org.ibmaspera.com
-config detect --url=my_faspex_url
-config detect --url=my_node_url
+config detect --url=https://node_simple.example.com/path
 config doc
 config doc transfer-parameters
 config echo 'hello'
@@ -1280,7 +1496,7 @@ config echo @uri:/etc/hosts
 config echo @uri:file:/etc/hosts
 config echo @uri:http://www.ibm.com
 config echo @uri:https://www.ibm.com
-config echo @val:@file:yo
+config echo @val:@file:no_such_file
 config echo @zlib:@stdin:
 config email_test --notif-to=my_recipient_email
 config export
@@ -1313,15 +1529,15 @@ demo_server:
 
 We can see here:
 
-- The configuration was created with CLI version 0.3.7
+- The configuration was created with `ascli` version 0.3.7
 - the default [option preset](#lprt) to load for `server` plugin is : `demo_server`
 - the [option preset](#lprt) `demo_server` defines some parameters: the URL and credentials
 - the default [option preset](#lprt) to load in any case is : `cli_default`
 
 Two [option presets](#lprt) are reserved:
 
-- `config` contains a single value: `version` showing the CLI
-version used to create the configuration file. It is used to check compatibility.
+- `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](#lprt) name used for known plugins.
 
 The user may create as many [option presets](#lprt) as needed. For instance, a particular [option preset](#lprt) can be created for a particular application instance and contain URL and credentials.
@@ -1351,7 +1567,7 @@ 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 is loaded for the plugin
+- 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](#lprt) for it, and loads it.
 - If option `--preset=<name or extended value hash>` is specified (or `-Pxxxx`), this reads the [option preset](#lprt) specified from the configuration file, or of the value is a Hash, it uses it as options values.
 - Environment variables are evaluated
@@ -1433,7 +1649,7 @@ ascli config preset set default shares shares06
 - Display the content of configuration file in table format
 
 ```bash
-ascli config overview
+ascli config preset overview
 ```
 
 - Execute a command on the shares application using default parameters
@@ -1530,13 +1746,13 @@ Some applications allow the user to be authenticated using a private key (Server
 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 private key can be protected by a passphrase or not.
-If the key is protected by a passphrase, then it will be prompted.
+The file containing the private key 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`.
 Set it to the desired safe location of the private key.
-Typically, in `$HOME/.ssh` or `$HOME/.aspera/ascli`:
+Typically, located in folder `$HOME/.ssh` or `$HOME/.aspera/ascli`:
 
 ```bash
 PRIVKEYFILE=~/.aspera/ascli/my_private_key
@@ -1544,6 +1760,8 @@ PRIVKEYFILE=~/.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).
+
 #### `ascli` for key generation
 
 The generated key is of type RSA, by default: 4096 bit.
@@ -1565,45 +1783,51 @@ ssh-keygen -t rsa -b 4096 -m PEM -N '' -f ${PRIVKEYFILE}
 #### `openssl`
 
 To generate a private key pair with a passphrase the following can be used on any system:
-<!-- spellchecker: disable -->
+
 ```bash
-openssl genrsa -passout pass:_passphrase_here_ -out ${PRIVKEYFILE}.protected 4096
+openssl genrsa -passout pass:_passphrase_here_ -out ${PRIVKEYFILE} 4096
 openssl rsa -pubout -in ${PRIVKEYFILE} -out ${PRIVKEYFILE}.pub
 ```
-<!-- spellchecker: enable -->
 
 `openssl` is sometimes compiled to support option `-nodes` (no DES, i.e. no passphrase, e.g. on macOS).
 In that case, add option `-nodes` instead of `-passout pass:_passphrase_here_` to generate a key without passphrase.
 
 If option `-nodes` is not available, the passphrase can be removed using this method:
 
-<!-- spellchecker: disable -->
 ```bash
-openssl rsa -passin pass:_passphrase_here_ -in ${PRIVKEYFILE}.protected -out ${PRIVKEYFILE}
-rm -f ${PRIVKEYFILE}.protected
+openssl rsa -passin pass:_passphrase_here_ -in ${PRIVKEYFILE} -out ${PRIVKEYFILE}.no_des
+mv ${PRIVKEYFILE}.no_des ${PRIVKEYFILE}
 ```
-<!-- spellchecker: enable -->
 
 To change (or add) the passphrase for a key do:
 
 ```bash
-openssl rsa -des3 -in old_file -out new_file
+openssl rsa -des3 -in ${PRIVKEYFILE} -out ${PRIVKEYFILE}.with_des
+mv ${PRIVKEYFILE}.with_des ${PRIVKEYFILE}
 ```
 
 ### <a id="certificates"></a>SSL CA certificate bundle
 
-`ascli` uses ruby `openssl` gem, which uses the `openssl` library.
-Certificates are checked against the ruby default certificates [OpenSSL::X509::DEFAULT_CERT_FILE](https://ruby-doc.org/stdlib-3.0.3/libdoc/openssl/rdoc/OpenSSL/X509/Store.html), which are typically the ones of `openssl` on Unix systems (Linux, macOS, etc..).
-The environment variables `SSL_CERT_FILE` and `SSL_CERT_DIR` are used if defined.
+`ascli` uses the Ruby `openssl` gem, which uses the `openssl` library.
+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..).
+
+To display the current root certificate store locations:
 
-`ascp` also needs to validate certificates when using WSS.
-By default, `ascp` uses primarily certificates from hard-coded path (e.g. on macOS: `/Library/Aspera/ssl`).
-`ascli` overrides and sets the default ruby certificate path as well for `ascp` using `-i` switch.
-So to update certificates, update ruby's `openssl` gem, or use env vars `SSL_CERT_*`.
+```bash
+ascli conf echo @ruby:'[OpenSSL::X509::DEFAULT_CERT_FILE,OpenSSL::X509::DEFAULT_CERT_DIR]'
+```
+
+Ruby's default values can be overridden by env vars: `SSL_CERT_FILE` and `SSL_CERT_DIR`.
+
+`ascp` also needs to validate certificates when using **WSS**.
+By default, `ascp` uses primarily certificates from hard-coded path (e.g. on macOS: `/Library/Aspera/ssl`) for WSS.
+`ascli` overrides and sets the default Ruby certificate path as well for `ascp` using `-i` switch.
+
+To update `ascli` trusted root certificates, just update your system's root certificates or use env vars specified here above.
 
 ### Plugins
 
-The CLI tool uses a plugin mechanism.
+`ascli` uses a plugin mechanism.
 The first level command (just after `ascli` on the command line) is the name of the concerned plugin which will execute the command.
 Each plugin usually represents commands sent to a specific application.
 For instance, the plugin `faspex` allows operations on the application "Aspera Faspex".
@@ -1684,20 +1908,20 @@ Examples:
 - display debugging log on `stdout`:
 
 ```bash
-ascli conf over --log-level=debug --logger=stdout
+ascli conf pre over --log-level=debug --logger=stdout
 ```
 
 - log errors to `syslog`:
 
 ```bash
-ascli conf over --log-level=error --logger=syslog
+ascli conf pre over --log-level=error --logger=syslog
 ```
 
 When `ascli` is used interactively in a shell, the shell itself will usually log executed commands in the history file.
 
 ### Learning Aspera Product APIs (REST)
 
-This CLI uses REST APIs.
+`ascli` uses mainly Aspera applications REST APIs.
 To display HTTP calls, use argument `-r` or `--rest-debug`, this is useful to display exact content of HTTP requests and responses.
 
 In order to get traces of execution, use argument : `--log-level=debug`
@@ -1706,7 +1930,7 @@ In order to get traces of execution, use argument : `--log-level=debug`
 
 If the server does not provide a valid certificate, use option: `--insecure=yes`.
 
-Ruby HTTP socket parameters can be adjusted.
+HTTP socket parameters can be adjusted using option `http_options`:
 
 | parameter            | default |
 |----------------------|---------|
@@ -1716,8 +1940,8 @@ Ruby HTTP socket parameters can be adjusted.
 | `keep_alive_timeout` | 2       |
 
 Values are in set *seconds* and can be of type either integer or float.
-Default values are the ones of Ruby.
-For details refer to the Ruby library: [`Net::HTTP`](https://ruby-doc.org/stdlib/libdoc/net/http/rdoc/Net/HTTP.html).
+Default values are the ones of Ruby:
+refer to the Ruby library: [`Net::HTTP`](https://ruby-doc.org/stdlib/libdoc/net/http/rdoc/Net/HTTP.html).
 
 Like any other option, those can be set either on command line, or in config file, either in a global preset or server-specific one.
 
@@ -1734,7 +1958,7 @@ Some actions may require the use of a graphical tool:
 - a browser for Aspera on Cloud authentication (web auth method)
 - a text editor for configuration file edition
 
-By default the CLI will assume that a graphical environment is available on windows, and on other systems, rely on the presence of the "DISPLAY" environment variable.
+By default `ascli` assumes that a graphical environment is available on windows, and on other systems, rely on the presence of the `DISPLAY` environment variable.
 It is also possible to force the graphical mode with option --ui :
 
 - `--ui=graphical` forces a graphical environment, a browser will be opened for URLs or a text editor for file edition.
@@ -1814,7 +2038,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*](#transferspec) parameter: `EX_fasp_proxy_url` (only supported with the `direct` agent).
+To specify a FASP proxy (forward), set the [*transfer-spec*](#transferspec) parameter: `proxy` (only supported with the `direct` agent).
 
 ### <a id="client"></a>FASP configuration
 
@@ -1870,7 +2094,7 @@ Saved to default global preset global_common_defaults
 
 Windows:
 
-```bash
+```text
 ascli config ascp use C:\Users\admin\.aspera\ascli\sdk\ascp.exe
 ```
 
@@ -1891,14 +2115,14 @@ ascli config ascp products list
 ```
 
 ```output
-:.........................................:................................................:
-:                  name                   :                    app_root                    :
-:.........................................:................................................:
-: Aspera Connect                          : /Users/laurent/Applications/Aspera Connect.app :
-: IBM Aspera CLI                          : /Users/laurent/Applications/Aspera CLI         :
-: IBM Aspera High-Speed Transfer Endpoint : /Library/Aspera                                :
-: Aspera Drive                            : /Applications/Aspera Drive.app                 :
-:.........................................:................................................:
++---------------------------------------+----------------------------------------+
+| name                                  | app_root                               |
++---------------------------------------+----------------------------------------+
+| IBM Aspera SDK                        | /Users/laurent/.aspera/ascli/sdk       |
+| Aspera Connect                        | /Applications/Aspera Connect.app       |
+| IBM Aspera CLI                        | /Users/laurent/Applications/Aspera CLI |
+| IBM Aspera High-Speed Transfer Server | /Library/Aspera                        |
++---------------------------------------+----------------------------------------+
 ```
 
 #### Selection of local client for `ascp` for [`direct`](#agt_direct) agent
@@ -1964,7 +2188,7 @@ Some of the actions on Aspera Applications lead to file transfers (upload and do
 When a transfer needs to be started, a [*transfer-spec*](#transferspec) has been internally prepared.
 This [*transfer-spec*](#transferspec) will be executed by a transfer client, here called **Transfer Agent**.
 
-There are currently 3 agents:
+There are currently 3 agents, set with option `transfer`:
 
 - [`direct`](#agt_direct) : a local execution of `ascp`
 - [`connect`](#agt_connect) : use of a local Connect Client
@@ -1978,6 +2202,8 @@ will effectively push files to the related server from the agent node.
 
 `ascli` standardizes on the use of a [*transfer-spec*](#transferspec) 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.
+
 #### <a id="agt_direct"></a>Direct
 
 The `direct` agent directly executes a local `ascp`.
@@ -2052,22 +2278,82 @@ In addition to standard methods described in section [File List](#file_list), it
 >
 > **Note:** Those methods have limitations: they apply **only** to the [`direct`](#agt_direct) transfer agent (i.e. local `ascp`) and not for Aspera on Cloud.
 
+This agent supports a local configuration file: `aspera.conf` where Virtual links can be configured:
+
+On a server (HSTS), the following commands can be used to set a global virtual link:
+
+```bash
+asconfigurator -x 'set_trunk_data;id,1;trunk_name,in;trunk_capacity,45000;trunk_on,true'
+asconfigurator -x 'set_trunk_data;id,2;trunk_name,out;trunk_capacity,45000;trunk_on,true'
+asconfigurator -x 'set_node_data;transfer_in_bandwidth_aggregate_trunk_id,1'
+asconfigurator -x 'set_node_data;transfer_out_bandwidth_aggregate_trunk_id,2'
+```
+
+But this command is not available on clients, so edit the file `aspera.conf`, you can find the location with: `ascli conf ascp info --fields=aspera_conf` and modify the sections `default` and `trunks` like this for a global 100 Mbps virtual link:
+
+```xml
+<?xml version='1.0' encoding='UTF-8'?>
+<CONF version="2">
+    <default>
+        <transfer>
+            <in>
+                <bandwidth>
+                    <aggregate>
+                        <trunk_id>1</trunk_id>
+                    </aggregate>
+                </bandwidth>
+            </in>
+            <out>
+                <bandwidth>
+                    <aggregate>
+                        <trunk_id>2</trunk_id>
+                    </aggregate>
+                </bandwidth>
+            </out>
+        </transfer>
+    </default>
+    <trunks>
+        <trunk>
+            <id>1</id>
+            <name>in</name>
+            <on>true</on>
+            <capacity>
+                <schedule format="ranges">1000000</schedule>
+            </capacity>
+        </trunk>
+        <trunk>
+            <id>2</id>
+            <name>out</name>
+            <capacity>
+                <schedule format="ranges">1000000</schedule>
+            </capacity>
+            <on>true</on>
+        </trunk>
+    </trunks>
+</CONF>
+```
+
+It is also possible to set a schedule with different time and days, for example for the value of `schedule`:
+
+```text
+start=08 end=19 days=mon,tue,wed,thu capacity=900000;1000000
+```
+
 #### <a id="agt_connect"></a>IBM Aspera Connect Client GUI
 
 By specifying option: `--transfer=connect`, `ascli` will start transfers using the locally installed Aspera Connect Client. There are no option for `transfer_info`.
 
 #### <a id="agt_node"></a>Aspera Node API : Node to node transfers
 
-By specifying option: `--transfer=node`, the CLI will start transfers in an Aspera
-Transfer Server using the Node API, either on a local or remote node.
+By specifying option: `--transfer=node`, `ascli` starts transfers in an Aspera Transfer Server using the Node API, either on a local or remote node.
 Parameters provided in option `transfer_info` are:
 
-| Name | Type | Description |
-|------|------|-------------|
-| url | string | URL of the node API</br>Mandatory |
+| Name     | Type   | Description |
+|----------|--------|-------------|
+| url      | string | URL of the node API</br>Mandatory |
 | username | string | node api user or access key</br>Mandatory |
 | password | string | password, secret or bearer token</br>Mandatory |
-| root_id | string | password or secret</br>Mandatory only for bearer token |
+| root_id  | string | password or secret</br>Mandatory only for bearer token |
 
 Like any other option, `transfer_info` can get its value from a pre-configured [option preset](#lprt) :
 `--transfer-info=@preset:_name_here_` or be specified using the extended value syntax :
@@ -2088,11 +2374,13 @@ Parameters provided in option `transfer_info` are:
 | url                    | string | URL of the HTTP GW</br>Mandatory      |
 | upload_bar_refresh_sec | float  | Refresh rate for upload progress bar  |
 | upload_chunk_size      | int    | Size in bytes of chunks for upload    |
+| api_version            | string | v1 or v2, for force use of version    |
+| synchronous            | bool   | wait for each message acknowledgment  |
 
 Example:
 
 ```bash
-ascli faspex package recv --id=323 --transfer=httpgw --transfer-info=@json:'{"url":"https://asperagw.example.com:9443/aspera/http-gwy/v1"}'
+ascli faspex package recv 323 --transfer=httpgw --transfer-info=@json:'{"url":"https://asperagw.example.com:9443/aspera/http-gwy"}'
 ```
 
 > **Note:** The gateway only supports transfers authorized with a token.
@@ -2120,8 +2408,8 @@ On Windows the compilation may fail for various reasons (3.1.1):
 
 ### <a id="transferspec"></a>Transfer Specification
 
-Some commands lead to file transfer (upload/download), all parameters necessary for this transfer
-is described in a [*transfer-spec*](#transferspec) (Transfer Specification), such as:
+Some commands lead to file transfer (upload/download).
+All parameters necessary for this transfer are described in a [*transfer-spec*](#transferspec) (Transfer Specification), such as:
 
 - server address
 - transfer user name
@@ -2129,9 +2417,16 @@ is described in a [*transfer-spec*](#transferspec) (Transfer Specification), suc
 - file list
 - etc...
 
-`ascli` builds a default [*transfer-spec*](#transferspec) internally, so it is not necessary to provide additional parameters on the command line for this transfer.
+`ascli` builds the [*transfer-spec*](#transferspec) internally, so it is not necessary to provide additional parameters on the command line for this transfer.
+
+The [*transfer-spec*](#transferspec) is a Hash (dictionary), so it is described on the command line with the [Extended Value Syntax](#extended).
+
+It is possible to modify or add any of the supported [*transfer-spec*](#transferspec) parameter using the `ts` option.
+The `ts` option accepts a [Structured Value](#native) containing one or several [*transfer-spec*](#transferspec) parameters in a `Hash`.
+Multiple `ts` options on command line are cumulative, and Hash is deeply merged.
+To remove a (deep) key from transfer spec, set the value to `null`.
 
-If needed, it is possible to modify or add any of the supported [*transfer-spec*](#transferspec) parameter using the `ts` option. The `ts` option accepts a [Structured Value](#native) containing one or several [*transfer-spec*](#transferspec) parameters. Multiple `ts` options on command line are cumulative.
+> **Note:** Default transfer spec values can be displayed with command: `config ascp info --flat-hash=no` under field `ts`.
 
 It is possible to specify `ascp` options when the `transfer` option is set to [`direct`](#agt_direct) using `transfer_info` option parameter: `ascp_args`.
 Example: `--transfer-info=@json:'{"ascp_args":["-l","100m"]}'`.
@@ -2142,8 +2437,6 @@ The use of a [*transfer-spec*](#transferspec) instead of `ascp` parameters has t
 - common to all [Transfer Agent](#agents)
 - not dependent on command line limitations (special characters...)
 
-A [*transfer-spec*](#transferspec) is a Hash table, so it is described on the command line with the [Extended Value Syntax](#extended).
-
 ### <a id="transferparams"></a>Transfer Parameters
 
 All standard [*transfer-spec*](#transferspec) parameters can be specified.
@@ -2173,18 +2466,7 @@ Columns:
 Fields with EX_ prefix are extensions to transfer agent [`direct`](#agt_direct). (only in `ascli`).
 
 | Field | Type | D | N | C | Description |
-|-------|------|---|---|---|-------------|
-| EX_ascp_args | array | Y | &nbsp; | &nbsp; | Add native command line arguments to ascp |
-| EX_at_rest_password | string | Y | &nbsp; | &nbsp; | DEPRECATED: Prefer to use standard parameter: content_protection_password<br/>(env:ASPERA_SCP_FILEPASS) |
-| EX_file_list | string | Y | &nbsp; | &nbsp; | source file list |
-| EX_file_pair_list | string | Y | &nbsp; | &nbsp; | source file pair list |
-| EX_http_proxy_url | string | Y | &nbsp; | &nbsp; | Specify the proxy server address used by HTTP Fallback<br/>(-x {string}) |
-| EX_http_transfer_jpeg | int | Y | &nbsp; | &nbsp; | HTTP transfers as JPEG file<br/>(-j {int}) |
-| EX_license_text | string | Y | &nbsp; | &nbsp; | License file text override.<br/>By default ascp looks for license file near executable.<br/>(env:ASPERA_SCP_LICENSE) |
-| EX_no_read | bool | Y | &nbsp; | &nbsp; | no read source<br/>(--no-read) |
-| EX_no_write | bool | Y | &nbsp; | &nbsp; | no write on destination<br/>(--no-write) |
-| EX_proxy_password | string | Y | &nbsp; | &nbsp; | Password used for Aspera proxy server authentication.<br/>May be overridden by password in URL EX_fasp_proxy_url.<br/>(env:ASPERA_PROXY_PASS) |
-| EX_ssh_key_paths | array | Y | &nbsp; | &nbsp; | Use public key authentication for SSH and specify the private key file paths<br/>(-i {array}) |
+| ----- | ---- | - | - | - | ----------- |
 | apply_local_docroot | bool | Y | &nbsp; | &nbsp; | (--apply-local-docroot) |
 | authentication | string | &nbsp; | &nbsp; | Y | value=token for SSH bypass keys, else password asked if not provided. |
 | cipher | string | Y | Y | Y | In transit encryption type.<br/>Allowed values: none, aes-128, aes-192, aes-256, aes-128-cfb, aes-192-cfb, aes-256-cfb, aes-128-gcm, aes-192-gcm, aes-256-gcm<br/>(-c (conversion){enum}) |
@@ -2244,7 +2526,7 @@ Fields with EX_ prefix are extensions to transfer agent [`direct`](#agt_direct).
 | source_root_id | string | &nbsp; | Y | &nbsp; | The file ID of the source root directory. Required when using Bearer token auth for the source node. |
 | src_base | string | Y | Y | &nbsp; | Specify the prefix to be stripped off from each source object.<br/>The remaining portion of the source path is kept intact at the destination.<br/>Special care must be taken when used with cloud storage.<br/>(--src-base64 (conversion){string}) |
 | ssh_port | int | Y | Y | Y | Specifies SSH (TCP) port. Default: local:22, other:33001<br/>(-P {int}) |
-| ssh_private_key | string | Y | &nbsp; | &nbsp; | Private key used for SSH authentication.<br/>Shall look like: -----BEGIN RSA PRIV4TE KEY-----&sol;nMII...<br/>Note the JSON encoding: &sol;n for newlines.<br/>(env:ASPERA_SCP_KEY) |
+| ssh_private_key | string | Y | &nbsp; | &nbsp; | Private key used for SSH authentication.<br/>Shall look like: -----BEGIN RSA PRIV4TE KEY-----\nMII...<br/>Note the JSON encoding: \n for newlines.<br/>(env:ASPERA_SCP_KEY) |
 | ssh_private_key_passphrase | string | Y | &nbsp; | &nbsp; | The passphrase associated with the transfer user's SSH private key. Available as of 3.7.2.<br/>(env:ASPERA_SCP_PASS) |
 | sshfp | string | Y | Y | Y | Check it against server SSH host key fingerprint<br/>(--check-sshfp {string}) |
 | symlink_policy | string | Y | Y | Y | Handle source side symbolic links<br/>Allowed values: follow, copy, copy+force, skip<br/>(--symbolic-links {enum}) |
@@ -2257,6 +2539,17 @@ Fields with EX_ prefix are extensions to transfer agent [`direct`](#agt_direct).
 | use_ascp4 | bool | Y | Y | &nbsp; | specify version of protocol |
 | wss_enabled | bool | Y | Y | Y | Server has Web Socket service enabled |
 | wss_port | int | Y | Y | Y | TCP port used for websocket service feed |
+| EX_ascp_args | array | Y | &nbsp; | &nbsp; | DEPRECATED: Use parameter ascp_args in option transfer_info<br/>Add native command line arguments to ascp |
+| EX_at_rest_password | string | Y | &nbsp; | &nbsp; | DEPRECATED: Use standard spec parameter: content_protection_password<br/>Content protection password<br/>(env:ASPERA_SCP_FILEPASS) |
+| EX_file_list | string | Y | &nbsp; | &nbsp; | source file list |
+| EX_file_pair_list | string | Y | &nbsp; | &nbsp; | source file pair list |
+| EX_http_proxy_url | string | Y | &nbsp; | &nbsp; | Specify the proxy server address used by HTTP Fallback<br/>(-x {string}) |
+| EX_http_transfer_jpeg | int | Y | &nbsp; | &nbsp; | HTTP transfers as JPEG file<br/>(-j {int}) |
+| EX_license_text | string | Y | &nbsp; | &nbsp; | License file text override.<br/>By default ascp looks for license file near executable.<br/>(env:ASPERA_SCP_LICENSE) |
+| EX_no_read | bool | Y | &nbsp; | &nbsp; | no read source<br/>(--no-read) |
+| EX_no_write | bool | Y | &nbsp; | &nbsp; | no write on destination<br/>(--no-write) |
+| EX_proxy_password | string | Y | &nbsp; | &nbsp; | Password used for Aspera proxy server authentication.<br/>May be overridden by password in URL provided in parameter: proxy.<br/>(env:ASPERA_PROXY_PASS) |
+| EX_ssh_key_paths | array | Y | &nbsp; | &nbsp; | Use public key authentication for SSH and specify the private key file paths<br/>(-i {array}) |
 
 #### Destination folder for transfers
 
@@ -2331,7 +2624,7 @@ So, by default, the list of files to transfer will be simply specified on the co
     --sources=@lines:@stdin:
     ```
 
-  - Using ruby code (one path per line in file)
+  - Using Ruby code (one path per line in file)
 
     ```ruby
     --sources=@ruby:'File.read("myfilelist.txt").split("\n")'
@@ -2363,11 +2656,63 @@ ascli server upload --src-type=pair ~/Documents/Samples/200KB.1 /Upload/sample1
 
 > **Note:** There are some specific rules to specify a file list when using **Aspera on Cloud**, refer to the AoC plugin section.
 
+#### Source directory structure on destination
+
+This section is not specific to `ascli`, it is `ascp` behaviour.
+
+The transfer destination is normally expected to designate a destination folder.
+
+But there is one exception: The destination specifies the new item name when the following are met:
+
+- there is a single source item (file or folder)
+- transfer spec `create_dir` is not set to `true` (`ascp` option `-d` not provided)
+- destination is not an existing folder
+- the `dirname` of destination is an existing folder
+
+For this reason it is recommended to set `create_dir` to `true` for consistent behaviour between single and multiple items transfer, this is the default in `ascli`.
+
+If a simple source file list is provided (no `destination` in `paths`, i.e. no `file_pair_list` provided), the destination folder is used as destination folder for each source file, and source file folder names are not preserved.
+
+The inner structure of source items that are folder is preserved on destination.
+
+A leading `/` on destination is ignored (relative to docroot) unless docroot is not set (relative to home).
+
+In the following table source folder `d3` contains 2 files: `f1` and `d4/f2`.
+
+| Source files | Destination | Folders on Dest.  |`create_dir`| Destination Files           |
+|--------------|-------------|-------------------|------------|-----------------------------|
+| f1           | d/f         | -                 | false      | Error: `d` does not exist.  |
+| f1           | d/f         | d                 | false      | d/f    (renamed)            |
+| f1           | d/f/.       | d                 | false      | d/f    (renamed)            |
+| f1           | d/f         | d/f               | false      | d/f/f1                      |
+| f1 f2        | d           | d                 | false      | d/f1 d/f2                   |
+| d3           | d           | -                 | false      | d/f1 d/f2  (renamed)        |
+| f1           | d           | -                 | true       | d/f1                        |
+| f1 f2        | d           | -                 | true       | d/f1 d/f2                   |
+| d1/f1 d2/f2  | d           | -                 | true       | d/f1 d/f2                   |
+| d3           | d           | -                 | true       | d/d3/f1 d/d3/d4/f2          |
+
+If a file par list is provided then it is possible to rename or specify a different destination folder for each source (relative to the destination).
+
+If transfer spec has a `src_base`, it has the side effect that the simple source file list is considered as a file pair list, and so the lower structure of source folders is preserved on destination.
+
+| Source files      | Destination |`src_base`| Destination Files           |
+|-------------------|-------------|----------|-----------------------------|
+| d1/d2/f2 d1/d3/f3 | d           | d1       | d/d2/f2 d/d3/f3             |
+
+Advanced Example: Send files `./file1` and `./folder2/files2` to server (e.g. `/Upload`) and keep the original file names and folders, i.e. send `file1` to `/Upload/file1` and `files2` to `/Upload/folder2/files2`.
+
+- If files are specified as `./file1 ./folder2/files2`, then destination will be: `/Upload/file1 /Upload/files2`
+- One possibility is to specify a file pair list: `--src-type=pair file1 file1 folder2/files2 folder2/files2`
+- Another possibility is to specify a source base: `--src-base=$PWD $PWD/file1 $PWD/folder2/files2` (note that `.` cannot be used as source base)
+- Similarly, create a temporary soft link (Linux): `ln -s . tmp_base` and use `--src-base=tmp_base tmp_base/file1 tmp_base/folder2/files2`
+- One can also similarly use `--sources=@ts` and specify the list of files in the `paths` field of transfer spec with both `source` and `destination` for each file.
+
 #### <a id="multisession"></a>Support of multi-session
 
-Multi session, i.e. starting a transfer of a file set using multiple sessions (one `ascp` process per session) is supported on "direct" and "node" agents, not yet on connect.
+Multi session, i.e. starting a transfer of a file set using multiple sessions (one `ascp` process per session) is supported on `direct` and `node` agents, not yet on connect.
 
-- when agent=node :
+- `--transfer=node`
 
 ```bash
 --ts=@json:'{"multi_session":10,"multi_session_threshold":1}'
@@ -2375,7 +2720,7 @@ Multi session, i.e. starting a transfer of a file set using multiple sessions (o
 
 Multi-session is directly supported by the node daemon.
 
-- when agent=direct :
+- `--transfer=direct`
 
 ```bash
 --ts=@json:'{"multi_session":5,"multi_session_threshold":1,"resume_policy":"none"}'
@@ -2389,11 +2734,10 @@ When multi-session is used, one separate UDP port is used per session (refer to
 
 #### Content protection
 
-Also known as Client-side encryption at rest (CSEAR), content protection allows a client to send files to a server
-which will store them encrypted (upload), and decrypt files as they are being downloaded from a server, both
-using a passphrase, only known by users sharing files. Files stay encrypted on server side.
+Also known as Client-side encryption at rest (CSEAR), content protection allows a client to send files to a server which will store them encrypted (upload), and decrypt files as they are being downloaded from a server, both using a passphrase, only known by users sharing files.
+Files stay encrypted on server side.
 
-activating CSEAR consists in using transfer spec parameters:
+Activating CSEAR consists in using transfer spec parameters:
 
 - `content_protection` : activate encryption (`encrypt` for upload) or decryption (`decrypt` for download)
 - `content_protection_password` : the passphrase to be used.
@@ -2430,15 +2774,58 @@ Example: parameter to download a faspex package and decrypt on the fly
 --ts=@json:'{"precalculate_job_size":true}'
 ```
 
-### <a id="scheduling"></a>Scheduling
+### <a id="scheduler"></a>Scheduler
 
 It is useful to configure automated scheduled execution.
+`ascli` does not provide an internal scheduler.
+Instead, use the service provided by the Operating system:
 
-#### <a id="locking"></a>Locking for exclusive execution
+#### Windows Scheduler
 
-It is also useful to ensure that `ascli` is not executed several times in parallel.
+Windows provides the [Task Scheduler](https://docs.microsoft.com/en-us/windows/win32/taskschd/task-scheduler-start-page).
+It can be configured:
 
-For instance when `ascli` is executed automatically on a schedule basis, one generally desire that a new execution is not started if a previous execution is still running because an on-going operation may last longer than the scheduling period:
+- Using utility [`schtasks.exe`](https://learn.microsoft.com/fr-fr/windows-server/administration/windows-commands/schtasks-create)
+
+- Using powershell function [scheduletasks](https://learn.microsoft.com/en-us/powershell/module/scheduledtasks)
+
+- Using `taskschd.msc` (UI)
+
+#### Unix-like Scheduler
+
+Unix-like systems (Linux, ...) provide cron, configured using a [crontab](https://www.man7.org/linux/man-pages/man5/crontab.5.html)
+
+Linux also provides `anacron`, if tasks are hourly or daily.
+
+For example, on Linux it is convenient to create a wrapping script, e.g. `cron_ascli` that will setup the environment (e.g. Ruby) to properly start `ascli`:
+
+```bash
+#!/bin/bash
+# load the ruby environment
+. /etc/profile.d/rvm.sh
+rvm use 2.6 --quiet
+# set a timeout protection, just in case ascli is frozen 
+tmout=30m
+# forward arguments to ascli
+exec timeout ${tmout} ascli "${@}"
+```
+
+Example of cronjob created for user `xfer`.
+
+```bash
+crontab<<EOF
+0    * * * *  /home/xfer/cron_ascli preview scan --logger=syslog --display=error
+2-59 * * * *  /home/xfer/cron_ascli preview trev --logger=syslog --display=error
+EOF
+```
+
+> **Note:** The logging options are kept here in the cronfile instead of conf file to allow execution on command line with output on command line.
+
+### <a id="locking"></a>Locking for exclusive execution
+
+In some cases one needs to ensure that `ascli` is not executed several times in parallel.
+
+When `ascli` is executed automatically on a schedule basis, one generally desires that a new execution is not started if a previous execution is still running because an on-going operation may last longer than the scheduling period:
 
 - Executing instances may pile-up and kill the system
 - The same file may be transferred by multiple instances at the same time.
@@ -2456,7 +2843,7 @@ Usually the OS native scheduler already provides some sort of protection against
 `ascli` natively supports a locking mechanism with option `lock_port`.
 (Technically, this opens a local TCP server port, and fails if this port is already used, providing a local lock. Lock is released when process exits).
 
-Example:
+Testing `ascli` locking:
 
 Run this same command in two separate terminals within less than 30 seconds:
 
@@ -2470,18 +2857,6 @@ The first instance will sleep 30 seconds, the second one will immediately exit l
 WARN -- : Another instance is already running (Address already in use - bind(2) for "127.0.0.1" port 12345).
 ```
 
-#### <a id="scheduler"></a>Scheduler
-
-`ascli` does not provide an internal scheduler.
-
-Instead, use the service provided by the Operating system:
-
-- Windows: [Task Scheduler](https://docs.microsoft.com/en-us/windows/win32/taskschd/task-scheduler-start-page)
-- Linux/Unix: [cron](https://www.man7.org/linux/man-pages/man5/crontab.5.html)
-- etc...
-
-Linux also provides `anacron`, if tasks are hourly or daily.
-
 ### "Proven&ccedil;ale"
 
 `ascp`, the underlying executable implementing Aspera file transfer using FASP, has a capability to not only access the local file system (using system's `open`,`read`,`write`,`close` primitives), but also to do the same operations on other data storage such as S3, Hadoop and others. This mechanism is call *PVCL*. Several *PVCL* adapters are available, some are embedded in `ascp`
@@ -2524,10 +2899,13 @@ One of the adapters, used in this manual, for testing, is `faux`. It is a pseudo
 
 ### <a id="faux_testing"></a>`faux:` for testing
 
-This is an extract of the man page of `ascp`. This feature is a feature of `ascp`, not `ascli`.
+This is an extract of the man page of `ascp`.
+This feature is a feature of `ascp`, not `ascli`.
 
 This adapter can be used to simulate a file or a directory.
 
+To discard data at the destination, the destination argument is set to `faux://`.
+
 To send uninitialized data in place of an actual source file, the source file is replaced with an argument of the form:
 
 ```bash
@@ -2581,8 +2959,6 @@ The sequence parameter is applied as follows:
 
 Filenames generated are of the form: `<file>_<00000 ... count>_<filesize>`
 
-To discard data at the destination, the destination argument is set to `faux://` .
-
 Examples:
 
 - Upload 20 gibibytes of random data to file myfile to directory /Upload
@@ -2608,7 +2984,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.12.0)
+        ascli -- a command line tool for Aspera Applications (v4.14.0)
 
 SYNOPSIS
         ascli COMMANDS [OPTIONS] [ARGS]
@@ -2631,59 +3007,59 @@ 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:
-        base64, json, zlib, ruby, csvt, lines, list, incps, vault, val, file, path, env, uri, stdin, preset
+        base64, csvt, env, file, json, lines, list, path, ruby, secret, stdin, uri, val, zlib, preset, incps, vault
         Dates format is 'DD-MM-YY HH:MM:SS', or 'now' or '-<num>h'
 
 ARGS
         Some commands require mandatory arguments, e.g. a path.
 
 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
-        --display=ENUM               output only some information: [info], data, error
-        --fields=VALUE               comma separated list of fields, or ALL, or DEF
-        --select=VALUE               select only some items in lists, extended value: hash (column, value)
-        --table-style=VALUE          table display style
-        --flat-hash=ENUM             display hash 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
-    -h, --help                       Show this message.
-        --bash-comp                  generate bash completion for command
-        --show-config                Display parameters used for the provided action.
-    -r, --rest-debug                 more debug for HTTP calls
-    -v, --version                    display version
-    -w, --warnings                   check for language warnings
-        --ui=ENUM                    method to start browser: text, [graphical]
+        --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
+        --display=ENUM               Output only some information: [info], data, error
+        --fields=VALUE               Comma separated list of fields, or ALL, or DEF
+        --select=VALUE               Select only some items in lists: column, value (Hash)
+        --table-style=VALUE          Table display style
+        --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
+    -h, --help                       Show this message
+        --bash-comp                  Generate bash completion for command
+        --show-config                Display parameters used for the provided action
+    -r, --rest-debug                 More debug for HTTP calls (REST)
+    -v, --version                    Display version
+    -w, --warnings                   Check for language warnings
+        --ui=ENUM                    Method to start browser: text, [graphical]
         --log-level=ENUM             Log level: debug, info, [warn], error, fatal, unknown
-        --logger=ENUM                logging method: [stderr], stdout, syslog
-        --lock-port=VALUE            prevent dual execution of a command, e.g. in cron
-        --http-options=VALUE         options for http socket (extended value)
-        --insecure=ENUM              do not validate HTTPS certificate: no, [yes]
-        --once-only=ENUM             process only new items (some commands): [no], yes
-        --log-secrets=ENUM           show passwords in logs: [no], yes
-        --cache-tokens=ENUM          save and reuse Oauth tokens: no, [yes]
+        --logger=ENUM                Logging method: [stderr], stdout, syslog
+        --lock-port=VALUE            Prevent dual execution of a command, e.g. in cron
+        --http-options=VALUE         Options for http socket (Hash)
+        --insecure=ENUM              Do not validate HTTPS certificate: [no], yes
+        --once-only=ENUM             Process only new items (some commands): [no], yes
+        --log-secrets=ENUM           Show passwords in logs: [no], yes
+        --cache-tokens=ENUM          Save and reuse Oauth tokens: no, [yes]
 
 COMMAND: config
-SUBCOMMANDS: ascp check_update coffee detect documentation echo email_test export_to_cli file flush_tokens folder gem genkey id initdemo list lookup open overview plugin preset proxy_check secure smtp_settings vault wizard
+SUBCOMMANDS: ascp check_update coffee detect documentation echo email_test file flush_tokens folder gem genkey initdemo open plugin preset proxy_check smtp_settings vault wizard
 OPTIONS:
-        --query=VALUE                additional filter for API calls (extended value) (some commands)
-        --value=VALUE                extended value for create, update, list filter
-        --property=VALUE             name of property to set
-        --id=VALUE                   resource identifier (modify,delete,show)
+        --query=VALUE                Additional filter for for some commands (list/delete) (Hash)
+        --value=VALUE                Value for create, update, list filter (Hash) (deprecated: 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: Use identifier after verb (modify,delete,show))
         --bulk=ENUM                  Bulk operation (only some): [no], yes
-        --bfail=ENUM                 Bulk operation error handling: [no], yes
-        --config-file=VALUE          read parameters from file in YAML format, current=/usershome/.aspera/ascli/config.yaml
-    -N, --no-default                 do not load default configuration for plugin
+        --bfail=ENUM                 Bulk operation error handling: no, [yes]
+        --config-file=VALUE          Read parameters from file in YAML format, current=/usershome/.aspera/ascli/config.yaml
+    -N, --no-default                 Do not load default configuration for plugin
         --override=ENUM              Wizard: override existing value: [no], yes
-        --use-generic-client=ENUM    Wizard: AoC: use global or org specific jwt client id: [no], yes
-        --default=ENUM               Wizard: set as default configuration for specified plugin (also: update): [no], yes
+        --use-generic-client=ENUM    Wizard: AoC: use global or org specific jwt client id: no, [yes]
+        --default=ENUM               Wizard: set as default configuration for specified plugin (also: update): no, [yes]
         --test-mode=ENUM             Wizard: skip private key check step: [no], yes
-    -P, --presetVALUE                load the named option preset from current config file
+    -P, --presetVALUE                Load the named option preset from current config file
         --pkeypath=VALUE             Wizard: path to private key for JWT
         --ascp-path=VALUE            Path to ascp
         --use-product=VALUE          Use ascp from specified product
-        --smtp=VALUE                 SMTP configuration (extended value: hash)
+        --smtp=VALUE                 SMTP configuration (Hash)
         --fpac=VALUE                 Proxy auto configuration script
         --proxy-credentials=VALUE    HTTP proxy credentials (Array with user and password)
         --secret=VALUE               Secret for access keys
@@ -2695,65 +3071,63 @@ OPTIONS:
         --notif-template=VALUE       Email ERB template for notification of transfers
         --version-check-days=VALUE   Period in days to check new version (zero to disable)
         --plugin-folder=VALUE        Folder where to find additional plugins
-        --ts=VALUE                   Override transfer spec values (Hash, e.g. use @json: prefix), current={"create_dir"=>true}
+        --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)
-        --src-type=ENUM              Type of file list: list, pair
-        --transfer=ENUM              Type of transfer agent: direct, node, connect, httpgw, trsdk
-        --transfer-info=VALUE        Parameters for transfer agent
-        --progress=ENUM              Type of progress bar: none, native, multi
+        --src-type=ENUM              Type of file list: [list], pair
+        --transfer=ENUM              Type of transfer agent: [direct], node, connect, httpgw, trsdk
+        --transfer-info=VALUE        Parameters for transfer agent (Hash)
+        --progress=ENUM              Type of progress bar: none, [native], multi
 
 
 COMMAND: shares
-SUBCOMMANDS: admin health repository
+SUBCOMMANDS: admin files health
 OPTIONS:
         --url=VALUE                  URL of application, e.g. https://org.asperafiles.com
-        --username=VALUE             username to log in
-        --password=VALUE             user's password
-        --type=ENUM                  Type of user/group for operations: any, local, ldap, saml
+        --username=VALUE             Username to log in
+        --password=VALUE             User's password
+        --type=ENUM                  Type of user/group for operations: [any], local, ldap, saml
 
 
 COMMAND: node
-SUBCOMMANDS: access_key api_details asperabrowser async basic_token browse central delete download events health info license mkdir mkfile mklink rename search service space stream sync transfer upload watch_folder
+SUBCOMMANDS: access_key api_details asperabrowser async basic_token browse central delete download events health info license mkdir mkfile mklink rename search service space ssync stream sync transfer upload watch_folder
 OPTIONS:
         --url=VALUE                  URL of application, e.g. https://org.asperafiles.com
-        --username=VALUE             username to log in
-        --password=VALUE             user's password
-        --validator=VALUE            identifier of validator (optional for central)
+        --username=VALUE             Username to log in
+        --password=VALUE             User's password
+        --validator=VALUE            Identifier of validator (optional for central)
         --asperabrowserurl=VALUE     URL for simple aspera web ui
-        --sync-name=VALUE            sync name
-        --path=VALUE                 file or folder path for gen4 operation "file"
-        --token-type=ENUM            Type of token used for transfers: aspera, basic, hybrid
-        --default-ports=ENUM         use standard FASP ports or get from node api (gen4): [no], yes
+        --sync-name=VALUE            Sync name
+        --default-ports=ENUM         Use standard FASP ports or get from node api (gen4): no, [yes]
 
 
 COMMAND: orchestrator
 SUBCOMMANDS: health info plugins processes workflow
 OPTIONS:
         --url=VALUE                  URL of application, e.g. https://org.asperafiles.com
-        --username=VALUE             username to log in
-        --password=VALUE             user's password
-        --params=VALUE               parameters hash table, use @json:{"param":"value"}
-        --result=VALUE               specify result value as: 'work step:parameter'
-        --synchronous=ENUM           work step:parameter expected as result: [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
+        --username=VALUE             Username to log in
+        --password=VALUE             User's password
+        --params=VALUE               Start parameters (Hash)
+        --result=VALUE               Specify result value as: 'work step:parameter'
+        --synchronous=ENUM           Work step:parameter expected as result: [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: bss
 SUBCOMMANDS: subscription
 OPTIONS:
         --url=VALUE                  URL of application, e.g. https://org.asperafiles.com
-        --username=VALUE             username to log in
-        --password=VALUE             user's password
+        --username=VALUE             Username to log in
+        --password=VALUE             User's password
 
 
 COMMAND: alee
 SUBCOMMANDS: entitlement
 OPTIONS:
         --url=VALUE                  URL of application, e.g. https://org.asperafiles.com
-        --username=VALUE             username to log in
-        --password=VALUE             user's password
+        --username=VALUE             Username to log in
+        --password=VALUE             User's password
 
 
 COMMAND: ats
@@ -2769,18 +3143,21 @@ OPTIONS:
 
 
 COMMAND: faspex5
-SUBCOMMANDS: admin bearer_token gateway health package postprocessing shared_folders user version
+SUBCOMMANDS: admin bearer_token gateway health packages postprocessing shared_folders user version
 OPTIONS:
         --url=VALUE                  URL of application, e.g. https://org.asperafiles.com
-        --username=VALUE             username to log in
-        --password=VALUE             user's password
+        --username=VALUE             Username to log in
+        --password=VALUE             User's password
         --client-id=VALUE            OAuth client identifier
         --client-secret=VALUE        OAuth client secret
         --redirect-uri=VALUE         OAuth redirect URI for web authentication
-        --auth=ENUM                  OAuth type of authentication: boot, web, jwt
+        --auth=ENUM                  OAuth type of authentication: boot, link, web, [jwt]
         --private-key=VALUE          OAuth JWT RSA private key PEM value (prefix file path with @file:)
-        --passphrase=VALUE           RSA private key passphrase
-        --shared-folder=VALUE        Shared folder source for package files
+        --passphrase=VALUE           OAuth JWT RSA private key passphrase
+        --link=VALUE                 Public link authorization (specific operations)
+        --box=VALUE                  Package inbox, either shared inbox name or one of ["inbox", "inbox_history", "inbox_all", "inbox_all_history", "outbox", "outbox_history", "pending", "pending_history", "all"] or ALL
+        --shared-folder=VALUE        Send package with files from shared folder
+        --group-type=ENUM            Shared inbox or workgroup: [shared_inboxes], workgroups
 
 
 COMMAND: cos
@@ -2799,49 +3176,50 @@ COMMAND: faspex
 SUBCOMMANDS: address_book dropbox health login_methods me package source v4
 OPTIONS:
         --url=VALUE                  URL of application, e.g. https://org.asperafiles.com
-        --username=VALUE             username to log in
-        --password=VALUE             user's password
-        --link=VALUE                 public link for specific operation
-        --delivery-info=VALUE        package delivery information (extended value)
-        --source-name=VALUE          create package from remote source (by name)
+        --username=VALUE             Username to log in
+        --password=VALUE             User's password
+        --link=VALUE                 Public link for specific operation
+        --delivery-info=VALUE        Package delivery information (Hash)
+        --source-name=VALUE          Create package from remote source (by name)
         --storage=VALUE              Faspex local storage definition
-        --recipient=VALUE            use if recipient is a dropbox (with *)
-        --box=ENUM                   package box: inbox, archive, sent
+        --recipient=VALUE            Use if recipient is a dropbox (with *)
+        --box=ENUM                   Package box: [inbox], archive, sent
 
 
 COMMAND: preview
 SUBCOMMANDS: check events scan test trevents
 OPTIONS:
         --url=VALUE                  URL of application, e.g. https://org.asperafiles.com
-        --username=VALUE             username to log in
-        --password=VALUE             user's password
-        --skip-format=ENUM           skip this preview format (multiple possible): png, mp4
-        --folder-reset-cache=ENUM    force detection of generated preview by refresh cache: [no], header, read
-        --skip-types=VALUE           skip types in comma separated list
-        --previews-folder=VALUE      preview folder in storage root
-        --temp-folder=VALUE          path to temp folder
-        --skip-folders=VALUE         list of folder to skip
-        --case=VALUE                 basename of output for for test
-        --scan-path=VALUE            subpath in folder id to start scan in (default=/)
-        --scan-id=VALUE              folder id in storage to start scan in, default is access key main folder id
-        --mimemagic=ENUM             use Mime type detection of gem mimemagic: [no], yes
-        --overwrite=ENUM             when to overwrite result file: always, never, [mtime]
-        --file-access=ENUM           how to read and write files in repository: [local], remote
-        --max-size=VALUE             maximum size (in bytes) of preview file
-        --thumb-vid-scale=VALUE      png: video: size (ffmpeg scale argument)
-        --thumb-vid-fraction=VALUE   png: video: time percent position of snapshot
-        --thumb-img-size=VALUE       png: non-video: height (and width)
-        --thumb-text-font=VALUE      png: plaintext: font to render text with imagemagick convert (identify -list font)
-        --video-conversion=ENUM      mp4: method for preview generation: [reencode], blend, clips
-        --video-png-conv=ENUM        mp4: method for thumbnail generation: [fixed], animated
-        --video-start-sec=VALUE      mp4: start offset (seconds) of video preview
-        --video-scale=VALUE          mp4: video scale (ffmpeg)
-        --blend-keyframes=VALUE      mp4: blend: # key frames
-        --blend-pauseframes=VALUE    mp4: blend: # pause frames
-        --blend-transframes=VALUE    mp4: blend: # transition blend frames
-        --blend-fps=VALUE            mp4: blend: frame per second
-        --clips-count=VALUE          mp4: clips: number of clips
-        --clips-length=VALUE         mp4: clips: length in seconds of each clips
+        --username=VALUE             Username to log in
+        --password=VALUE             User's password
+        --skip-format=ENUM           Skip this preview format (multiple possible): png, mp4
+        --folder-reset-cache=ENUM    Force detection of generated preview by refresh cache: [no], header, read
+        --skip-types=VALUE           Skip types in comma separated list
+        --previews-folder=VALUE      Preview folder in storage root
+        --temp-folder=VALUE          Path to temp folder
+        --skip-folders=VALUE         List of folder to skip
+        --case=VALUE                 Basename of output for for test
+        --scan-path=VALUE            Subpath in folder id to start scan in (default=/)
+        --scan-id=VALUE              Folder id in storage to start scan in, default is access key main folder id
+        --mimemagic=ENUM             Use Mime type detection of gem mimemagic: [no], yes
+        --overwrite=ENUM             When to overwrite result file: always, never, [mtime]
+        --file-access=ENUM           How to read and write files in repository: [local], remote
+        --max-size=VALUE             Maximum size (in bytes) of preview file
+        --thumb-vid-scale=VALUE      Png: video: size (ffmpeg scale argument)
+        --thumb-vid-fraction=VALUE   Png: video: time percent position of snapshot
+        --thumb-img-size=VALUE       Png: non-video: height (and width)
+        --thumb-text-font=VALUE      Png: plaintext: font to render text with imagemagick convert (identify -list font)
+        --video-conversion=ENUM      Mp4: method for preview generation: [reencode], blend, clips
+        --video-png-conv=ENUM        Mp4: method for thumbnail generation: [fixed], animated
+        --video-scale=VALUE          Mp4: all: video scale (ffmpeg)
+        --video-start-sec=VALUE      Mp4: all: start offset (seconds) of video preview
+        --reencode-ffmpeg=VALUE      Mp4: reencode: options to ffmpeg
+        --blend-keyframes=VALUE      Mp4: blend: # key frames
+        --blend-pauseframes=VALUE    Mp4: blend: # pause frames
+        --blend-transframes=VALUE    Mp4: blend: # transition blend frames
+        --blend-fps=VALUE            Mp4: blend: frame per second
+        --clips-count=VALUE          Mp4: clips: number of clips
+        --clips-length=VALUE         Mp4: clips: length in seconds of each clips
 
 
 COMMAND: sync
@@ -2855,10 +3233,10 @@ COMMAND: aoc
 SUBCOMMANDS: admin automation bearer_token files gateway organization packages reminder servers tier_restrictions user
 OPTIONS:
         --url=VALUE                  URL of application, e.g. https://org.asperafiles.com
-        --username=VALUE             username to log in
-        --password=VALUE             user's password
-        --auth=ENUM                  OAuth type of authentication: web, jwt
-        --operation=ENUM             client operation for transfers: push, pull
+        --username=VALUE             Username to log in
+        --password=VALUE             User's password
+        --auth=ENUM                  OAuth type of authentication: web, [jwt]
+        --operation=ENUM             Client operation for transfers: [push], pull
         --client-id=VALUE            OAuth API client identifier
         --client-secret=VALUE        OAuth API client secret
         --redirect-uri=VALUE         OAuth API client redirect URI
@@ -2870,26 +3248,25 @@ OPTIONS:
         --link=VALUE                 Public link to shared resource
         --new-user-option=VALUE      New user creation option for unknown package recipients
         --from-folder=VALUE          Source folder for Folder-to-Folder transfer
-        --validate-metadata=ENUM     Validate shared inbox metadata: [no], yes
+        --validate-metadata=ENUM     Validate shared inbox metadata: no, [yes]
 
 COMMAND: node
-SUBCOMMANDS: access_key api_details asperabrowser async basic_token browse central delete download events health info license mkdir mkfile mklink rename search service space stream sync transfer upload watch_folder
+SUBCOMMANDS: access_key api_details asperabrowser async basic_token browse central delete download events health info license mkdir mkfile mklink rename search service space ssync stream sync transfer upload watch_folder
 OPTIONS:
-        --validator=VALUE            identifier of validator (optional for central)
+        --validator=VALUE            Identifier of validator (optional for central)
         --asperabrowserurl=VALUE     URL for simple aspera web ui
-        --sync-name=VALUE            sync name
-        --path=VALUE                 file or folder path for gen4 operation "file"
-        --token-type=ENUM            Type of token used for transfers: aspera, basic, hybrid
-        --default-ports=ENUM         use standard FASP ports or get from node api (gen4): [no], yes
+        --sync-name=VALUE            Sync name
+        --default-ports=ENUM         Use standard FASP ports or get from node api (gen4): no, [yes]
 
 
 COMMAND: server
 SUBCOMMANDS: browse cp delete df download du health info ls md5sum mkdir mv rename rm sync upload
 OPTIONS:
         --url=VALUE                  URL of application, e.g. https://org.asperafiles.com
-        --username=VALUE             username to log in
-        --password=VALUE             user's password
+        --username=VALUE             Username to log in
+        --password=VALUE             User's password
         --ssh-keys=VALUE             SSH key path list (Array or single)
+        --passphrase=VALUE           SSH private key passphrase
         --ssh-options=VALUE          SSH options (Hash)
 
 
@@ -2897,10 +3274,10 @@ COMMAND: console
 SUBCOMMANDS: health transfer
 OPTIONS:
         --url=VALUE                  URL of application, e.g. https://org.asperafiles.com
-        --username=VALUE             username to log in
-        --password=VALUE             user's password
-        --filter-from=DATE           only after date
-        --filter-to=DATE             only before date
+        --username=VALUE             Username to log in
+        --password=VALUE             User's password
+        --filter-from=DATE           Only after date
+        --filter-to=DATE             Only before date
 
 
 ```
@@ -2948,10 +3325,10 @@ For this, specify the option: `--use-generic-client=no`.
 
 This will guide you through the steps to create.
 
-If the wizard does not detect the application but you know the application, you can force it using option `value`:
+If the wizard does not detect the application but you know the application, you can force it using option `query`:
 
 ```bash
-ascli config wizard --value=aoc
+ascli config wizard --query=aoc
 ```
 
 ### <a id="aocmanual"></a>Configuration: using manual setup
@@ -2962,7 +3339,7 @@ ascli config wizard --value=aoc
 
 Several types of OAuth authentication are supported:
 
-- JSON Web Token (JWT) : authentication is secured by a private key (recommended for CLI)
+- JSON Web Token (JWT) : authentication is secured by a private key (recommended for `ascli`)
 - Web based authentication : authentication is made by user using a browser
 - URL Token : external users authentication with url tokens (public links)
 
@@ -3004,7 +3381,6 @@ If you did not use the wizard, you can also manually create a [option preset](#l
 
 Lets create an [option preset](#lprt) called: `my_aoc_org` using `ask` interactive input (client info from previous step):
 
-<!-- spellchecker: disable -->
 ```bash
 ascli config preset ask my_aoc_org url client_id client_secret
 option: url> https://myorg.ibmaspera.com/
@@ -3012,7 +3388,6 @@ option: client_id> my_client_id_here
 option: client_secret> my_client_secret_here
 updated: my_aoc_org
 ```
-<!-- spellchecker: enable -->
 
 (This can also be done in one line using the command `config preset update my_aoc_org --url=...`)
 
@@ -3051,11 +3426,11 @@ ascli aoc admin res client list
 ```
 
 ```output
-:............:...............:
-:     id     :  name         :
-:............:...............:
-: my_BJbQiFw : my-client-app :
-:............:...............:
++------------+---------------+
+|     id     |  name         |
++------------+---------------+
+| my_BJbQiFw | my-client-app |
++------------+---------------+
 ```
 
 ```bash
@@ -3087,12 +3462,12 @@ ascli aoc admin res user list
 ```
 
 ```output
-:........:................:
-:   id   :      name      :
-:........:................:
-: 109952 : Tech Support   :
-: 109951 : LAURENT MARTIN :
-:........:................:
++--------+----------------+
+|   id   |      name      |
++--------+----------------+
+| 109952 | Tech Support   |
+| 109951 | LAURENT MARTIN |
++--------+----------------+
 ```
 
 ```ruby
@@ -3221,7 +3596,7 @@ To execute an action on a specific resource, select it using one of those method
 
 - *recommended*: give id directly on command line *after the action*: `aoc admin res node show 123`
 - give name on command line *after the action*: `aoc admin res node show name abc`
-- provide option `id` : `aoc admin res node show --id=123`
+- provide option `id` : `aoc admin res node show 123`
 - provide option `name` : `aoc admin res node show --name=abc`
 
 #### <a id="res_create"></a>Creating a resource
@@ -3276,7 +3651,7 @@ The secret is provided using the `secret` option.
 For example in a command like:
 
 ```bash
-ascli aoc admin res node --id=123 --secret="my_secret_here" v3 info
+ascli aoc admin res node 123 --secret="my_secret_here" v3 info
 ```
 
 It is also possible to store secrets in the [secret vault](#vault) and then automatically find the related secret using the [config finder](#config_finder).
@@ -3334,6 +3709,36 @@ The option `default_ports` ([yes]/no) allows ascli to retrieve the server ports
 
 Refer to section "Examples" of [ATS](#ats) and substitute command `ats` with `aoc admin ats`.
 
+#### Files with type `link`
+
+Aspera on Cloud Shared folders are implemented through a special type of file: `link`.
+A `link` is the equivalent of a symbolic link on a file system: it points to another folder (not file).
+
+Listing a link (in terminal position of path) will information on the link itself, not the content of the folder it points to.
+To list the target folder content, add a `/` a the end of the path.
+
+Example:
+
+```console
+$ ascli aoc files br the_link
+Current Workspace: Default (default)
++------------+------+----------------+------+----------------------+--------------+
+| name       | type | recursive_size | size | modified_time        | access_level |
++------------+------+----------------+------+----------------------+--------------+
+| the_link   | link |                |      | 2021-04-28T09:17:14Z | edit         |
++------------+------+----------------+------+----------------------+--------------+
+```
+
+```console
+$ ascli aoc files br the_link/
+Current Workspace: Default (default)
++-------------+------+----------------+------+----------------------+--------------+
+| name        | type | recursive_size | size | modified_time        | access_level |
++-------------+------+----------------+------+----------------------+--------------+
+| file_inside | file |                |      | 2021-04-26T09:00:00Z | edit         |
++-------------+------+----------------+------+----------------------+--------------+
+```
+
 #### Example: Bulk creation of users
 
 ```bash
@@ -3341,29 +3746,27 @@ ascli aoc admin res user create --bulk=yes @json:'[{"email":"dummyuser1@example.
 ```
 
 ```output
-:.......:.........:
-:  id   : status  :
-:.......:.........:
-: 98398 : created :
-: 98399 : created :
-:.......:.........:
++-------+---------+
+|  id   | status  |
++-------+---------+
+| 98398 | created |
+| 98399 | created |
++-------+---------+
 ```
 
 #### Example: Find with filter and delete
 
-<!-- spellchecker: disable -->
-
 ```bash
 ascli aoc admin res user list --query='@json:{"q":"dummyuser"}' --fields=id,email
 ```
 
 ```output
-:.......:........................:
-:  id   :         email          :
-:.......:........................:
-: 98398 : dummyuser1@example.com :
-: 98399 : dummyuser2@example.com :
-:.......:........................:
++-------+------------------------+
+|  id   |         email          |
++-------+------------------------+
+| 98398 | dummyuser1@example.com |
+| 98399 | dummyuser2@example.com |
++-------+------------------------+
 ```
 
 ```bash
@@ -3379,20 +3782,18 @@ echo $thelist
 ```
 
 ```bash
-ascli aoc admin res user --bulk=yes --id=@json:"$thelist" delete
+ascli aoc admin res user delete @json:"$thelist" --bulk=yes
 ```
 
 ```output
-:.......:.........:
-:  id   : status  :
-:.......:.........:
-: 98398 : deleted :
-: 98399 : deleted :
-:.......:.........:
++-------+---------+
+|  id   | status  |
++-------+---------+
+| 98398 | deleted |
+| 98399 | deleted |
++-------+---------+
 ```
 
-<!-- spellchecker: enable -->
-
 #### Example: <a id="deactuser"></a>Find deactivated users since more than 2 years
 
 ```ruby
@@ -3408,13 +3809,13 @@ ascli aoc user workspaces list
 ```
 
 ```output
-:......:............................:
-:  id  :            name            :
-:......:............................:
-: 16   : Engineering                :
-: 17   : Marketing                  :
-: 18   : Sales                      :
-:......:............................:
++------+----------------------------+
+|  id  |            name            |
++------+----------------------------+
+| 16   | Engineering                |
+| 17   | Marketing                  |
+| 18   | Sales                      |
++------+----------------------------+
 ```
 
 #### Example: Create a sub access key in a "node"
@@ -3422,13 +3823,13 @@ ascli aoc user workspaces list
 Creation of a sub-access key is like creation of access key with the following difference: authentication to node API is made with accesskey (master access key) and only the path parameter is provided: it is relative to the storage root of the master key. (id and secret are optional)
 
 ```bash
-ascli aoc admin resource node --name=_node_name_ --secret=_secret_ v4 access_key create --value=@json:'{"storage":{"path":"/folder1"}}'
+ascli aoc admin resource node --name=_node_name_ --secret=_secret_ v4 access_key create @json:'{"storage":{"path":"/folder1"}}'
 ```
 
 #### Example: Display transfer events (ops/transfer)
 
 ```bash
-ascli aoc admin res node --secret=_secret_ v3 transfer list --value=@json:'[["q","*"],["count",5]]'
+ascli aoc admin res node --secret=_secret_ v3 transfer list --query=@json:'[["q","*"],["count",5]]'
 ```
 
 Examples of query (TODO: cleanup):
@@ -3454,16 +3855,16 @@ ascli aoc admin res workspace_membership list --fields=member_type,manager,membe
 ```
 
 ```output
-:.............:.........:..................................:
-: member_type : manager :           member.email           :
-:.............:.........:..................................:
-: user        : true    : john.curtis@email.com            :
-: user        : false   : laurent.martin.aspera@fr.ibm.com :
-: user        : false   : jean.dupont@me.com               :
-: user        : false   : another.user@example.com         :
-: group       : false   :                                  :
-: user        : false   : aspera.user@gmail.com            :
-:.............:.........:..................................:
++-------------+---------+----------------------------------+
+| member_type | manager |           member.email           |
++-------------+---------+----------------------------------+
+| user        | true    | john.curtis@email.com            |
+| user        | false   | laurent.martin.aspera@fr.ibm.com |
+| user        | false   | jean.dupont@me.com               |
+| user        | false   | another.user@example.com         |
+| group       | false   |                                  |
+| user        | false   | aspera.user@gmail.com            |
++-------------+---------+----------------------------------+
 ```
 
 Other query parameters:
@@ -3519,12 +3920,12 @@ ascli aoc admin res user list --fields=email --query=@json:'{"q":"last_login_at:
 ```
 
 ```output
-:...............................:
-:             email             :
-:...............................:
-: John.curtis@acme.com          :
-: Jean.Dupont@tropfort.com      :
-:...............................:
++-------------------------------+
+|             email             |
++-------------------------------+
+| John.curtis@acme.com          |
+| Jean.Dupont@tropfort.com      |
++-------------------------------+
 ```
 
 #### Example: List "Limited" users
@@ -3615,8 +4016,6 @@ ascli -Paoc_show aoc files transfer --from-folder='IBM Cloud SJ' --to-folder='AW
 
 #### Example: create registration key to register a node
 
-<!-- spellchecker: disable -->
-
 ```bash
 ascli aoc admin res client create @json:'{"data":{"name":"laurentnode","client_subject_scopes":["alee","aejd"],"client_subject_enabled":true}}' --fields=token --format=csv
 ```
@@ -3628,7 +4027,7 @@ jfqslfdjlfdjfhdjklqfhdkl
 #### Example: delete all registration keys
 
 ```bash
-ascli aoc admin res client list --fields=id --format=csv|ascli aoc admin res client delete --bulk=yes --id=@lines:@stdin:
+ascli aoc admin res client list --fields=id --format=csv|ascli aoc admin res client delete @lines:@stdin: --bulk=yes
 ```
 
 ```output
@@ -3642,8 +4041,6 @@ ascli aoc admin res client list --fields=id --format=csv|ascli aoc admin res cli
 +-----+---------+
 ```
 
-<!-- spellchecker: enable -->
-
 #### Example: Create a Node
 
 AoC nodes as actually composed with two related entities:
@@ -3715,12 +4112,13 @@ The webmail-like application.
 General syntax:
 
 ```bash
-ascli aoc packages send --value=[package extended value] [other parameters such as file list and transfer parameters]
+ascli aoc packages send [package extended value] [other parameters such as file list and transfer parameters]
 ```
 
 Notes:
 
-- The `value` option can contain any supported package creation parameter. Refer to the AoC package creation API, or display an existing package in JSON to list attributes.
+- Package creation parameter are sent as positional mandatory parameter.
+  Refer to the AoC package creation API, or display an existing package in JSON to list attributes.
 - List allowed shared inbox destinations with: `ascli aoc packages shared_inboxes list`
 - Use fields: `recipients` and/or `bcc_recipients` to provide the list of recipients: user or shared inbox.
   - Provide either ids as expected by API: `"recipients":[{"type":"dropbox","id":"1234"}]`
@@ -3732,19 +4130,19 @@ Notes:
 #### Example: Send a package with one file to two users, using their email
 
 ```bash
-ascli aoc packages send --value=@json:'{"name":"my title","note":"my note","recipients":["laurent.martin.aspera@fr.ibm.com","other@example.com"]}' my_file.dat
+ascli aoc packages send @json:'{"name":"my title","note":"my note","recipients":["laurent.martin.aspera@fr.ibm.com","other@example.com"]}' my_file.dat
 ```
 
 #### Example: Send a package to a shared inbox with metadata
 
 ```bash
-ascli aoc packages send --workspace=eudemo --value=@json:'{"name":"my pack title","recipients":["Shared Inbox With Meta"],"metadata":{"Project Id":"123","Type":"Opt2","CheckThose":["Check1","Check2"],"Optional Date":"2021-01-13T15:02:00.000Z"}}' ~/Documents/Samples/200KB.1
+ascli aoc packages send --workspace=eudemo @json:'{"name":"my pack title","recipients":["Shared Inbox With Meta"],"metadata":{"Project Id":"123","Type":"Opt2","CheckThose":["Check1","Check2"],"Optional Date":"2021-01-13T15:02:00.000Z"}}' ~/Documents/Samples/200KB.1
 ```
 
 It is also possible to use identifiers and API parameters:
 
 ```bash
-ascli aoc packages send --workspace=eudemo --value=@json:'{"name":"my pack title","recipients":[{"type":"dropbox","id":"12345"}],"metadata":[{"input_type":"single-text","name":"Project Id","values":["123"]},{"input_type":"single-dropdown","name":"Type","values":["Opt2"]},{"input_type":"multiple-checkbox","name":"CheckThose","values":["Check1","Check2"]},{"input_type":"date","name":"Optional Date","values":["2021-01-13T15:02:00.000Z"]}]}' ~/Documents/Samples/200KB.1
+ascli aoc packages send --workspace=eudemo @json:'{"name":"my pack title","recipients":[{"type":"dropbox","id":"12345"}],"metadata":[{"input_type":"single-text","name":"Project Id","values":["123"]},{"input_type":"single-dropdown","name":"Type","values":["Opt2"]},{"input_type":"multiple-checkbox","name":"CheckThose","values":["Check1","Check2"]},{"input_type":"date","name":"Optional Date","values":["2021-01-13T15:02:00.000Z"]}]}' ~/Documents/Samples/200KB.1
 ```
 
 #### Example: List packages in a given shared inbox
@@ -3755,7 +4153,7 @@ When user packages are listed, the following query is used:
 {"archived":false,"exclude_dropbox_packages":true,"has_content":true,"received":true}
 ```
 
-To list packages in a shared inbox, the query has to be specified with withe the shared inbox by name or its identifier.
+To list packages in a shared inbox, the query has to be specified with the the shared inbox by name or its identifier.
 Additional parameters can be specified, as supported by the API (to find out available filters, consult the API definition, or use the web interface in developer mode).
 The current workspace is added unless specified in the query.
 
@@ -3803,7 +4201,7 @@ ascli aoc files browse /src_folder
 Let's send a package with the file `10M.dat` from subfolder /src_folder in a package:
 
 ```bash
-ascli aoc files node_info /src_folder --format=json --display=data | ascli aoc packages send --value=@json:'{"name":"test","recipients":["laurent.martin.aspera@fr.ibm.com"]}' 10M.dat --transfer=node --transfer-info=@json:@stdin:
+ascli aoc files node_info /src_folder --format=json --display=data | ascli aoc packages send @json:'{"name":"test","recipients":["laurent.martin.aspera@fr.ibm.com"]}' 10M.dat --transfer=node --transfer-info=@json:@stdin:
 ```
 
 #### <a id="aoccargo"></a>Receive new packages only (Cargo)
@@ -3811,10 +4209,10 @@ ascli aoc files node_info /src_folder --format=json --display=data | ascli aoc p
 It is possible to automatically download new packages, like using Aspera Cargo:
 
 ```bash
-ascli aoc packages recv --id=ALL --once-only=yes --lock-port=12345
+ascli aoc packages recv ALL --once-only=yes --lock-port=12345
 ```
 
-- `--id=ALL` (case sensitive) will download all packages
+- `ALL` (case sensitive) will download all packages
 - `--once-only=yes` keeps memory of any downloaded package in persistency files located in the configuration folder
 - `--lock-port=12345` ensures that only one instance is started at the same time, to avoid running two downloads in parallel
 
@@ -3843,46 +4241,28 @@ ascli aoc files download <single file path>
 
 #### Shared folders
 
-Shared folder by users are managed through **permissions**.
+Shared folder created by users are managed through **permissions**.
 For creation, parameters are the same as for node api [permissions](https://developer.ibm.com/apis/catalog/aspera--aspera-node-api/api/API--aspera--node-api#post960739960).
-`ascli` expects the same payload for creation, but it will automatically populated required tags if needed.
-Also, the pseudo key `with` is added: it will lookup the name in the contacts and fill the proper type and id.
+`ascli` expects the same payload for creation, but it will automatically populate required tags if needed.
+Also, the pseudo key `with` is available: it will lookup the name in the contacts and fill the proper type and id.
 The pseudo parameter `link_name` allows changing default "shared as" name.
 
 - List permissions on a shared folder as user
 
 ```bash
-ascli aoc files file --path=/shared_folder_test1 perm list
+ascli aoc files perm /shared_folder_test1 list
 ```
 
 - Share a personal folder with other users
 
 ```bash
-ascli aoc files file --path=/shared_folder_test1 perm create @json:'{"with":"laurent"}'
+ascli aoc files perm /shared_folder_test1 create @json:'{"with":"laurent"}'
 ```
 
 - Revoke shared access
 
 ```bash
-ascli aoc files file --path=/shared_folder_test1 perm delete 6161
-```
-
-- List shared folders in node
-
-```bash
-ascli aoc admin res node --id=8669 shared_folders
-```
-
-- List shared folders in workspace
-
-```bash
-ascli aoc admin res workspace --id=10818 shared_folders
-```
-
-- List members of shared folder
-
-```bash
-ascli aoc admin res node --id=8669 v4 perm 82 show
+ascli aoc files perm /shared_folder_test1 delete 6161
 ```
 
 #### Cross Organization transfers
@@ -3917,42 +4297,52 @@ Explanation:
 
 #### Find Files
 
-The command `aoc files find [--value=expression]` will recursively scan storage to find files matching the expression criteria. It works also on node resource using the v4 command. (see examples)
+The command `aoc files find [--query=expression]` will recursively scan storage to find files matching the expression criteria. It works also on node resource using the v4 command. (see examples)
 
 The expression can be of 3 formats:
 
 - empty (default) : all files, equivalent to value: `exec:true`
-- not starting with `exec:` : the expression is a regular expression, using [Ruby Regex](https://ruby-doc.org/core/Regexp.html) syntax. equivalent to value: `exec:f['name'].match(/expression/)`
+- not starting with `exec:` : the expression is a regular expression, using [Ruby Regex](https://ruby-doc.org/core/Regexp.html) syntax, equivalent to value: `exec:f['name'].match(/expression/)`
 
-For instance, to find files with a special extension, use `--value='\.myext$'`
+  For instance, to find files with a special extension, use `--query='\.myext$'`
 
-- starting with `exec:` : the Ruby code after the prefix is executed for each entry found. The entry variable name is `f`. The file is displayed if the result of the expression is true;
+- starting with `exec:` : the Ruby code after the prefix is executed for each entry found. The entry variable name is `f`. The file is displayed if the result of the expression is true.
 
-Examples of expressions: (using like this: `--value=exec:'<expression>'`)
+Examples of expressions: (using like this: `--query=exec:'<expression>'`)
 
 - Find files more recent than 100 days
 
-```bash
-f["type"].eql?("file") and (DateTime.now-DateTime.parse(f["modified_time"]))<100
-```
+  ```ruby
+  f["type"].eql?("file") and (DateTime.now-DateTime.parse(f["modified_time"]))<100
+  ```
 
 - Find files older than 1 year on a given node and store in file list
 
-```bash
-ascli aoc admin res node --name='my node name' --secret='my_secret_here' v4 find / --fields=path --value='exec:f["type"].eql?("file") and (DateTime.now-DateTime.parse(f["modified_time"]))<100' --format=csv > my_file_list.txt
-```
+  ```ruby
+  f["type"].eql?("file") and (DateTime.now-DateTime.parse(f["modified_time"]))<100
+  ```
+
+  ```bash
+  ascli aoc admin res node --name='my node name' --secret='my_secret_here' v4 find / --fields=path --query='exec:<above expression here>' --format=csv > my_file_list.txt
+  ```
+
+- Find files larger than 1MB
+
+  ```ruby
+  f["type"].eql?("file") and f["size"].to_i>1000000
+  ```
 
 - Delete the files, one by one
 
-```bash
-cat my_file_list.txt|while read path;do echo ascli aoc admin res node --name='my node name' --secret='my_secret_here' v4 delete "$path" ;done
-```
+  ```bash
+  cat my_file_list.txt|while read path;do echo ascli aoc admin res node --name='my node name' --secret='my_secret_here' v4 delete "$path" ;done
+  ```
 
 - Delete the files in bulk
 
-```bash
-cat my_file_list.txt | ascli aoc admin res node --name='my node name' --secret='my_secret_here' v3 delete @lines:@stdin:
-```
+  ```bash
+  cat my_file_list.txt | ascli aoc admin res node --name='my node name' --secret='my_secret_here' v3 delete @lines:@stdin:
+  ```
 
 ### AoC sample commands
 
@@ -3991,18 +4381,18 @@ aoc admin res workspace_membership list
 aoc admin resource node --name=my_aoc_ak_name --secret=my_aoc_ak_secret do browse /
 aoc admin resource node --name=my_aoc_ak_name --secret=my_aoc_ak_secret do delete /folder1
 aoc admin resource node --name=my_aoc_ak_name --secret=my_aoc_ak_secret do mkdir /folder1
-aoc admin resource node --name=my_aoc_ak_name --secret=my_aoc_ak_secret do v3 access_key create --value=@json:'{"id":"testsub1","storage":{"path":"/folder1"}}'
+aoc admin resource node --name=my_aoc_ak_name --secret=my_aoc_ak_secret do v3 access_key create @json:'{"id":"testsub1","storage":{"path":"/folder1"}}'
 aoc admin resource node --name=my_aoc_ak_name --secret=my_aoc_ak_secret do v3 events
 aoc admin resource node do name my_aoc_ak_name --secret=my_aoc_ak_secret v3 access_key delete testsub1
 aoc admin resource workspace list
 aoc admin resource workspace_membership list --fields=ALL --query=@json:'{"page":1,"per_page":50,"embed":"member","inherited":false,"workspace_id":11363,"sort":"name"}'
 aoc admin subscription
-aoc automation workflow action my_wf_id create --value=@json:'{"name":"toto"}'
-aoc automation workflow create --value=@json:'{"name":"test_workflow"}'
+aoc automation workflow action my_wf_id create @json:'{"name":"toto"}' \
+aoc automation workflow create @json:'{"name":"test_workflow"}'
 aoc automation workflow delete my_wf_id
 aoc automation workflow list
+aoc automation workflow list --query=@json:'{"show_org_workflows":"true"}' --scope=admin:all
 aoc automation workflow list --select=@json:'{"name":"test_workflow"}' --fields=id --format=csv --display=data
-aoc automation workflow list --value=@json:'{"show_org_workflows":"true"}' --scope=admin:all
 aoc bearer_token --display=data --scope=user:all
 aoc faspex
 aoc files bearer /
@@ -4011,25 +4401,28 @@ aoc files browse /
 aoc files browse / --link=my_aoc_publink_folder
 aoc files delete /testsrc
 aoc files download --transfer=connect /200KB.1
-aoc files file modify --path=my_aoc_test_folder
-aoc files file permission --path=my_aoc_test_folder list
-aoc files file show --path=/200KB.1
-aoc files file show my_file_id
-aoc files find / --value='\.partial$'
+aoc files find / --query='\.partial$'
 aoc files http_node_download --to-folder=. /200KB.1
 aoc files mkdir /testsrc
+aoc files modify my_aoc_test_folder
+aoc files permission my_aoc_test_folder list
 aoc files rename /somefolder testdst
-aoc files short_link create --to-folder=/testdst --value=private
-aoc files short_link create --to-folder=/testdst --value=public
-aoc files short_link list --value=@json:'{"purpose":"shared_folder_auth_link"}'
-aoc files sync admin status --to-folder=/testdst --sync-info=@json:'{"sessions":[{"name":"s2","direction":"pull","local_dir":"syncdir","reset":true}]}'
-aoc files sync start --to-folder=/testdst --sync-info=@json:'{"sessions":[{"name":"s2","direction":"pull","local_dir":"syncdir","reset":true}]}'
+aoc files short_link create /testdst private
+aoc files short_link create testdst public
+aoc files short_link list /testdst private
+aoc files show %id:my_file_id
+aoc files show /200KB.1
+aoc files sync ad st --sync-info=@json:'{"name":"syncv2","reset":true,"direction":"pull","local":{"path":"my_local_sync_dir"},"remote":{"path":"/testdst"}}'
+aoc files sync ad st --sync-info=@json:'{"sessions":[{"name":"syncv1","direction":"pull","local_dir":"my_local_sync_dir","remote_dir":"/testdst","reset":true}]}'
+aoc files sync start --sync-info=@json:'{"name":"syncv2","reset":true,"direction":"pull","local":{"path":"my_local_sync_dir"},"remote":{"path":"/testdst"}}'
+aoc files sync start --sync-info=@json:'{"sessions":[{"name":"syncv1","direction":"pull","local_dir":"my_local_sync_dir","remote_dir":"/testdst","reset":true}]}'
+aoc files thumbnail my_aoc_media_file
 aoc files transfer --from-folder=/testsrc --to-folder=/testdst testfile.bin
 aoc files upload --to-folder=/ testfile.bin --link=my_aoc_publink_folder
 aoc files upload --to-folder=/testsrc testfile.bin
 aoc files upload Test.pdf --transfer=node --transfer-info=@json:@stdin:
 aoc files v3 info
-aoc gateway --value=https://localhost:12345/aspera/faspex & jobs -p
+aoc gateway https://localhost:12345/aspera/faspex
 aoc org --link=my_aoc_publink_recv_from_aocuser
 aoc organization
 aoc packages browse "my_package_id" /contents
@@ -4038,13 +4431,13 @@ aoc packages list --query=@json:'{"dropbox_name":"my_aoc_shbx_name","sort":"-rec
 aoc packages recv "my_package_id" --to-folder=.
 aoc packages recv ALL --to-folder=. --once-only=yes --lock-port=12345
 aoc packages recv ALL --to-folder=. --once-only=yes --lock-port=12345 --query=@json:'{"dropbox_name":"my_aoc_shbx_name","archived":false,"received":true,"has_content":true,"exclude_dropbox_packages":false,"include_draft":false}' --ts=@json:'{"resume_policy":"sparse_csum","target_rate_kbps":50000}'
-aoc packages send --value=@json:'{"name":"Important files delivery","recipients":["my_email_external_user"]}' --new-user-option=@json:'{"package_contact":true}' testfile.bin
-aoc packages send --value=@json:'{"name":"Important files delivery","recipients":["my_email_internal_user"],"note":"my note"}' testfile.bin
-aoc packages send --value=@json:'{"name":"Important files delivery"}' testfile.bin --link=my_aoc_publink_send_aoc_user --password=my_aoc_publink_send_use_pass
-aoc packages send --value=@json:'{"name":"Important files delivery"}' testfile.bin --link=my_aoc_publink_send_shd_inbox
-aoc packages send --workspace="my_aoc_shbx_ws" --value=@json:'{"name":"Important files delivery","recipients":["my_aoc_shbx_name"],"metadata":[{"input_type":"single-text","name":"Project Id","values":["123"]},{"input_type":"single-dropdown","name":"Type","values":["Opt2"]},{"input_type":"multiple-checkbox","name":"CheckThose","values":["Check1","Check2"]},{"input_type":"date","name":"Optional Date","values":["2021-01-13T15:02:00.000Z"]}]}' testfile.bin
-aoc packages send --workspace="my_aoc_shbx_ws" --value=@json:'{"name":"Important files delivery","recipients":["my_aoc_shbx_name"],"metadata":{"Project Id":"456","Type":"Opt2","CheckThose":["Check1","Check2"],"Optional Date":"2021-01-13T15:02:00.000Z"}}' testfile.bin
-aoc packages send --workspace="my_aoc_shbx_ws" --value=@json:'{"name":"Important files delivery","recipients":["my_aoc_shbx_name"]}' testfile.bin
+aoc packages send --workspace="my_aoc_shbx_ws" @json:'{"name":"Important files delivery","recipients":["my_aoc_shbx_name"],"metadata":[{"input_type":"single-text","name":"Project Id","values":["123"]},{"input_type":"single-dropdown","name":"Type","values":["Opt2"]},{"input_type":"multiple-checkbox","name":"CheckThose","values":["Check1","Check2"]},{"input_type":"date","name":"Optional Date","values":["2021-01-13T15:02:00.000Z"]}]}' testfile.bin
+aoc packages send --workspace="my_aoc_shbx_ws" @json:'{"name":"Important files delivery","recipients":["my_aoc_shbx_name"],"metadata":{"Project Id":"456","Type":"Opt2","CheckThose":["Check1","Check2"],"Optional Date":"2021-01-13T15:02:00.000Z"}}' testfile.bin
+aoc packages send --workspace="my_aoc_shbx_ws" @json:'{"name":"Important files delivery","recipients":["my_aoc_shbx_name"]}' testfile.bin
+aoc packages send @json:'{"name":"Important files delivery","recipients":["my_email_external_user"]}' --new-user-option=@json:'{"package_contact":true}' testfile.bin
+aoc packages send @json:'{"name":"Important files delivery","recipients":["my_email_internal_user"],"note":"my note"}' testfile.bin
+aoc packages send @json:'{"name":"Important files delivery"}' testfile.bin --link=my_aoc_publink_send_aoc_user --password=my_aoc_publink_send_use_pass
+aoc packages send @json:'{"name":"Important files delivery"}' testfile.bin --link=my_aoc_publink_send_shd_inbox
 aoc packages shared_inboxes list
 aoc remind --username=my_aoc_user_email
 aoc servers
@@ -4069,8 +4462,6 @@ If you are using ATS as part of AoC, then authentication is through AoC, not IBM
 
 First get your IBM Cloud APIkey. For instance, it can be created using the IBM Cloud web interface, or using command line:
 
-<!-- spellchecker: disable -->
-
 ```bash
 ibmcloud iam api-key-create mykeyname -d 'my sample key'
 ```
@@ -4090,6 +4481,7 @@ UUID          ApiKey-05b8fadf-e7fe-4bc4-93a9-6fd348c5ab1f
 ```
 
 References:
+<!-- spellchecker: disable -->
 
 - [https://console.bluemix.net/docs/iam/userid_keys.html#userapikey](https://console.bluemix.net/docs/iam/userid_keys.html#userapikey)
 - [https://ibm.ibmaspera.com/helpcenter/transfer-service](https://ibm.ibmaspera.com/helpcenter/transfer-service)
@@ -4098,8 +4490,6 @@ References:
 
 Then, to register the key by default for the ats plugin, create a preset. Execute:
 
-<!-- spellchecker: disable -->
-
 ```bash
 ascli config preset update my_ibm_ats --ibm-api-key=my_secret_api_key_here
 ```
@@ -4138,8 +4528,6 @@ ascli ats api_key create
 ascli config preset update my_ibm_ats --ats-key=ats_XXXXXXXXXXXXXXXXXXXXXXXX --ats-secret=YYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYY
 ```
 
-<!-- spellchecker: enable -->
-
 ### <a id="ats_params"></a>ATS Access key creation parameters
 
 When creating an ATS access key, the option `params` must contain an extended value with the creation parameters.
@@ -4176,7 +4564,7 @@ ascli ats access_key create --cloud=azure --region=eastus --params=@json:'{"id":
 delete all my access keys:
 
 ```bash
-for k in $(ascli ats access_key list --field=id --format=csv);do ascli ats access_key id $k delete;done
+ascli ats access_key list --field=id --format=csv | ascli ats access_key delete @lines:@stdin: --bulk=yes
 ```
 
 The parameters provided to ATS for access key creation are the ones of [ATS API](https://developer.ibm.com/apis/catalog?search=%22aspera%20ats%22) for the `POST /access_keys` endpoint.
@@ -4214,7 +4602,6 @@ then commands `ascp` (for transfers) and `ascmd` (for file operations) are execu
 ### Server sample commands
 
 ```bash
-server br /
 server browse /
 server browse NEW_SERVER_FOLDER/testfile.bin
 server browse folder_1/target_hot
@@ -4232,10 +4619,10 @@ server md5sum NEW_SERVER_FOLDER/testfile.bin
 server mkdir NEW_SERVER_FOLDER --logger=stdout
 server mkdir folder_1/target_hot
 server mv folder_1/200KB.2 folder_1/to.delete
-server sync admin status --sync-info=@json:'{"name":"sync2","local":{"path":"syncdir"}}'
-server sync admin status --sync-session=mysync --sync-info=@json:'{"sessions":[{"name":"mysync","local_dir":"syncdir"}]}'
-server sync start --sync-info=@json:'{"name":"sync2","local":{"path":"syncdir"},"remote":{"path":"'"NEW_SERVER_FOLDER"'"},"reset":true,"quiet":false}'
-server sync start --sync-info=@json:'{"sessions":[{"name":"mysync","direction":"pull","remote_dir":"'"NEW_SERVER_FOLDER"'","local_dir":"syncdir","reset":true}]}'
+server sync admin status --sync-info=@json:'{"name":"sync2","local":{"path":"my_local_sync_dir"}}'
+server sync admin status --sync-session=mysync --sync-info=@json:'{"sessions":[{"name":"mysync","local_dir":"my_local_sync_dir"}]}'
+server sync start --sync-info=@json:'{"name":"sync2","local":{"path":"my_local_sync_dir"},"remote":{"path":"'"NEW_SERVER_FOLDER"'"},"reset":true,"quiet":false}'
+server sync start --sync-info=@json:'{"sessions":[{"name":"mysync","direction":"pull","remote_dir":"'"NEW_SERVER_FOLDER"'","local_dir":"my_local_sync_dir","reset":true}]}'
 server upload --sources=@ts --ts=@json:'{"EX_ascp_args":["--file-list","'"filelist.txt"'"]}' --to-folder=NEW_SERVER_FOLDER 
 server upload --sources=@ts --ts=@json:'{"EX_ascp_args":["--file-pair-list","'"filepairlist.txt"'"]}'
 server upload --sources=@ts --ts=@json:'{"EX_file_list":"'"filelist.txt"'"}' --to-folder=NEW_SERVER_FOLDER
@@ -4266,7 +4653,7 @@ ascli server --url=ssh://_server_address_:33001 ... --ts=@json:'{"token":"Basic
 
 > **Note:** If you need to use the Aspera public keys, then specify an empty token: `--ts=@json:'{"token":""}'` : Aspera public SSH keys will be used, but the protocol will ignore the empty token.
 
-The value of the `ssh_keys` option can be a single value or an array.
+The value of the `ssh_keys` option can be a single value or an `Array`.
 Each value is a **path** to a private key and is expanded (`~` is replaced with the user's home folder).
 
 Examples:
@@ -4277,9 +4664,9 @@ ascli server --ssh-keys=@list:,~/.ssh/id_rsa
 ascli server --ssh-keys=@json:'["~/.ssh/id_rsa"]'
 ```
 
-For file operation command (browse, delete), the ruby SSH client library `Net::SSH` is used and provides several options settable using option `ssh_options`.
+For file operation command (browse, delete), the Ruby SSH client library `Net::SSH` is used and provides several options settable using option `ssh_options`.
 
-For a list of SSH client options, refer to the ruby documentation of [Net::SSH](http://net-ssh.github.io/net-ssh/Net/SSH.html#method-c-start).
+For a list of SSH client options, refer to the Ruby documentation of [Net::SSH](http://net-ssh.github.io/net-ssh/Net/SSH.html#method-c-start).
 
 Some of the 50 available SSH options:
 
@@ -4301,7 +4688,7 @@ or on Windows:
 ERROR -- net.ssh.authentication.agent: could not connect to ssh-agent: pageant process not running
 ```
 
-This means that your environment suggessts to use an agent but you don't have such an SSH agent running, then:
+This means that your environment suggests to use an agent but you don't have such an SSH agent running, then:
 
 - Check env var: `SSH_AGENT_SOCK`
 - Check your file: `$HOME/.ssh/config`
@@ -4315,6 +4702,9 @@ ascli server --ssh-options=@json:'{"use_agent": false}' ...
 
 > **Note:** This can also be set using a preset.
 
+If one of the SSH private keys is passphrase-protected, then option `passphrase` can be used.
+It is equivalent to setting both options `ssh_options.passphrase` and `ts.ssh_private_key_passphrase`.
+
 ### Other session channels for `server`
 
 URL schemes `local` and `https` are also supported (mainly for testing purpose).
@@ -4337,10 +4727,18 @@ ascli server download /aspera-test-dir-large/200MB
 
 `initdemo` creates a [option preset](#lprt) `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:
+
+```bash
+ascli server --url=ssh://_server_address_here_:33001 --username=_user_here_ --ssh_keys=_private_key_path_here_ --passphrase=_passphrase_here_
+```
+
 ## <a id="node"></a>Plugin: `node`: IBM Aspera High Speed Transfer Server Node
 
 This plugin gives access to capabilities provided by HSTS node API.
 
+> **Note:** capabilities of this plugin are used in other plugins which access to the node API, such as `aoc`.
+
 ### File Operations
 
 It is possible to:
@@ -4349,27 +4747,10 @@ It is possible to:
 - transfer (upload / download)
 - ...
 
-For transfers, it is possible to control how transfer is authorized using option: `token_type`:
-
-- `aspera` : api `<upload|download>_setup` is called to create the transfer spec including the Aspera token, used as is.
-- `hybrid` : same as `aspera`, but token is replaced with basic token like `basic`
-- `basic` : transfer spec is created like this:
-
-```json
-{
-  "remote_host": "<address of node url>",
-  "remote_user": "xfer",
-  "ssh_port": 33001,
-  "token": "Basic <base 64 encoded user/pass>",
-  "direction": "[send|receive]"
-}
-```
-
-> **Note:** the port is assumed to be the default Aspera SSH port `33001` and transfer user is assumed to be `xfer`.
-
 ### Central
 
-The central subcommand uses the "reliable query" API (session and file). It allows listing transfer sessions and transferred files.
+The central subcommand uses the "reliable query" API (session and file).
+It allows listing transfer sessions and transferred files.
 
 Filtering can be applied:
 
@@ -4398,16 +4779,12 @@ Refer to [Aspera documentation](https://download.asperasoft.com/download/docs/en
 - Start watchd and watchfolderd services running as a system user having access to files
 - configure a watchfolder to define automated transfers
 
-<!-- spellchecker: disable -->
-
 ```bash
 ascli node service create @json:'{"id":"mywatchd","type":"WATCHD","run_as":{"user":"user1"}}'
 ascli node service create @json:'{"id":"mywatchfolderd","type":"WATCHFOLDERD","run_as":{"user":"user1"}}'
 ascli node watch_folder create @json:'{"id":"mywfolder","source_dir":"/watch1","target_dir":"/","transport":{"host":"10.25.0.4","user":"user1","pass":"mypassword"}}'
 ```
 
-<!-- spellchecker: enable -->
-
 ### Out of Transfer File Validation
 
 Follow the Aspera Transfer Server configuration to activate this feature.
@@ -4417,11 +4794,11 @@ ascli node central file list --validator=ascli --data=@json:'{"file_transfer_fil
 ```
 
 ```output
-:..............:..............:............:......................................:
-: session_uuid :    file_id   :   status   :              path                    :
-:..............:..............:............:......................................:
-: 1a74444c-... : 084fb181-... : validating : /home/xfer.../PKG - my title/200KB.1 :
-:..............:..............:............:......................................:
++--------------+--------------+------------+--------------------------------------+
+| session_uuid |    file_id   |   status   |              path                    |
++--------------+--------------+------------+--------------------------------------+
+| 1a74444c-... | 084fb181-... | validating | /home/xfer.../PKG - my title/200KB.1 |
++--------------+--------------+------------+--------------------------------------+
 ```
 
 ```bash
@@ -4447,27 +4824,55 @@ ascli node download /share/sourcefile --to-folder=/destination_folder --preset=a
 
 This will get transfer information from the SHOD instance and tell the Azure ATS instance to download files.
 
+### node file information
+
+When node api is used with an **Access key**, extra information can be retrieved, such as preview.
+
+> **Note:** Display of preview on terminal requires installation of extra gem: `rmagick`
+
+```bash
+dnf install -y ImageMagick-devel
+gem install rmagick rainbow
+```
+
+For example it is possible to display the preview of a file, if it exists, using:
+
+```bash
+ascli aoc files thumbnail /preview_samples/Aspera.mpg
+```
+
+Using direct node access and an access key , one can do:
+
+```bash
+ascli node access_key do self thumbnail /preview_samples/Aspera.mpg
+```
+
+> **Note:** To specify the file by its file id, use the selector syntax: `%id:_file_id_here_`
+>
+> **Note:** To force textual display of the preview on iTerm, prefix command with: `env -u TERM_PROGRAM -u LC_TERMINAL`
+
 ### Create access key
 
 ```bash
-ascli node access_key create --value=@json:'{"id":"myaccesskey","secret":"my_secret_here","storage":{"type":"local","path":"/data/mydir"}}'
+ascli node access_key create @json:'{"id":"myaccesskey","secret":"my_secret_here","storage":{"type":"local","path":"/data/mydir"}}'
 ```
 
 ### Node sample commands
 
 ```bash
-node access_key create --value=@json:'{"id":"aoc_1","storage":{"type":"local","path":"/"}}'
-node access_key delete aoc_1
+node access_key create @json:'{"id":"testingAK1","storage":{"type":"local","path":"/"}}'
+node access_key delete testingAK1
 node access_key do my_aoc_ak_name browse /
 node access_key do my_aoc_ak_name delete /folder2
 node access_key do my_aoc_ak_name delete testfile1
 node access_key do my_aoc_ak_name download testfile1 --to-folder=.
-node access_key do my_aoc_ak_name file show --path=/testfile1
-node access_key do my_aoc_ak_name file show 1
 node access_key do my_aoc_ak_name find /
 node access_key do my_aoc_ak_name mkdir /folder1
 node access_key do my_aoc_ak_name node_info /
 node access_key do my_aoc_ak_name rename /folder1 folder2
+node access_key do my_aoc_ak_name show %id:1
+node access_key do my_aoc_ak_name show /testfile1
+node access_key do my_aoc_ak_name thumbnail /testfile1
 node access_key do my_aoc_ak_name upload 'faux:///testfile1?1k' --default_ports=no
 node access_key list
 node api_details
@@ -4481,10 +4886,9 @@ node basic_token
 node browse / -r
 node delete /todelete
 node delete @list:,folder_1/todelete,folder_1/tdlink,folder_1/delfile
-node delete folder_1/10MB.1
+node delete folder_1/10MB.2
 node delete testfile.bin
 node download testfile.bin --to-folder=.
-node download testfile.bin --to-folder=. --token-type=hybrid
 node health
 node info --fpac='function FindProxyForURL(url,host){return "DIRECT"}'
 node license
@@ -4492,27 +4896,30 @@ node mkdir folder_1/todelete
 node mkfile folder_1/delfile1 "hello world"
 node mklink folder_1/todelete folder_1/tdlink
 node rename folder_1 delfile1 delfile
-node search / --value=@json:'{"sort":"mtime"}'
+node search / --query=@json:'{"sort":"mtime"}'
 node service create @json:'{"id":"service1","type":"WATCHD","run_as":{"user":"user1"}}'
 node service delete service1
 node service list
 node space /
-node sync bandwidth my_syncid
-node sync counters my_syncid
-node sync create --value=@json:'{"configuration":{"name":"sync1","local":{"path":"my_local_path"},"remote":{"host":"my_host","port":my_port,"user":"my_username","pass":"my_password","path":"my_remote_path"}}}'
-node sync delete my_syncid
-node sync files my_syncid
-node sync list
-node sync show my_syncid
-node sync start my_syncid
-node sync state my_syncid
-node sync stop my_syncid
-node sync summary my_syncid
-node transfer list --value=@json:'{"active_only":true}'
-node upload --to-folder="folder_1" --sources=@ts --ts=@json:'{"paths":[{"source":"/aspera-test-dir-small/10MB.1"}],"precalculate_job_size":true}' --transfer=node --transfer-info=@json:'{"url":"my_node_url","username":"my_node_user","password":"my_node_pass_here"}'
-node upload --username=my_aoc_ak_name --password=my_aoc_ak_secret testfile.bin --token-type=basic
+node ssync bandwidth my_syncid
+node ssync counters my_syncid
+node ssync create @json:'{"configuration":{"name":"sync1","local":{"path":"my_local_path"},"remote":{"host":"my_host","port":my_port,"user":"my_username","pass":"my_password","path":"my_remote_path"}}}'
+node ssync delete my_syncid
+node ssync files my_syncid
+node ssync list
+node ssync show my_syncid
+node ssync start my_syncid
+node ssync state my_syncid
+node ssync stop my_syncid
+node ssync summary my_syncid
+node sync ad st --sync-info=@json:'{"name":"syncv2","reset":true,"direction":"pull","local":{"path":"my_local_sync_dir"},"remote":{"path":"/aspera-test-dir-tiny"}}'
+node sync ad st --sync-info=@json:'{"sessions":[{"name":"syncv1","direction":"pull","local_dir":"my_local_sync_dir","remote_dir":"/aspera-test-dir-tiny","reset":true}]}'
+node sync start --sync-info=@json:'{"name":"syncv2","reset":true,"direction":"pull","local":{"path":"my_local_sync_dir"},"remote":{"path":"/aspera-test-dir-tiny"}}'
+node sync start --sync-info=@json:'{"sessions":[{"name":"syncv1","direction":"pull","local_dir":"my_local_sync_dir","remote_dir":"/aspera-test-dir-tiny","reset":true}]}'
+node transfer list --query=@json:'{"active_only":true}'
+node upload --to-folder=folder_1 --sources=@ts --ts=@json:'{"paths":[{"source":"/aspera-test-dir-small/10MB.2"}],"precalculate_job_size":true}' --transfer=node --transfer-info=@json:'{"url":"my_node_url","username":"my_node_user","password":"my_node_pass_here"}'
+node upload --username=my_aoc_ak_name --password=my_aoc_ak_secret testfile.bin
 node upload testfile.bin --to-folder=folder_1 --ts=@json:'{"target_rate_cap_kbps":10000}'
-node upload testfile.bin --to-folder=folder_1 --ts=@json:'{"target_rate_cap_kbps":10000}' --token-type=hybrid
 ```
 
 ## <a id="faspex5"></a>Plugin: `faspex5`: IBM Aspera Faspex v5
@@ -4521,22 +4928,37 @@ IBM Aspera's newer self-managed application.
 
 3 authentication methods are supported:
 
-- jwt
-- web
-- boot
+- jwt : general purpose, private-key based authentication
+- link : public link authentication
+- web : requires authentication with web browser
+- boot : use authentication token copied from browser (experimental)
 
 ### Faspex 5 JWT authentication
 
-This is the **recommended** method to use.
+This is the general purpose and **recommended** method to use.
 
-For `jwt`, create an API client in Faspex with JWT support:
+Activation is in two steps:
 
-- Select a private key file: if you don't have any refer to section [Private Key](#private_key)
-- Navigate to the web UI: Admin &rarr; Configurations &rarr; API Clients &rarr; Create
-- Activate JWT
-- Paste **public** key in the appropriate section
-- Click on Create Button
-- Take note of Client Id (and Client Secret, but not used in current version)
+- The admninistrator must create an API client in Faspex with JWT support
+
+  This operation is generally done only once:
+
+  - As Admin, Navigate to the web UI: Admin &rarr; Configurations &rarr; API Clients &rarr; Create
+  - Give a name, like `ascli`
+  - Activate JWT
+  - There is an option to set a general public key allowing the owner of the private key to impersonate any user. Unless you want to do this, leave this field empty.
+  - Click on `Create` Button
+  - Take note of Client Id (and Client Secret, but not used in current version)
+
+- The user uses a private key and sets the public key in his faspex 5 profile
+
+  This operation is done by each user using the CLI.
+
+  - As user, click on the user logo, left to the app switcher on top right.
+  - Select `Account Settings`
+  - on the bottom in the text field: `Public key in PEM format` paste the **public** key corresponding to the private key used by the user.
+
+  **Note:** If you don't have any refer to section [Private Key](#private_key)
 
 Then use these options:
 
@@ -4548,19 +4970,31 @@ Then use these options:
 --private-key=@file:.../path/to/key.pem
 ```
 
-> **Note:** The `private_key` option must contain the PEM value of the private key which can be read from a file using the modifier: `@file:`, e.g. `@file:/path/to/key.pem`.
+> **Note:** The `private_key` option must contain the PEM **value** (not file path) of the private key which can be read from a file using the modifier: `@file:`, e.g. `@file:/path/to/key.pem`.
+
+As usual, typically a user will create preset to avoid having to type these options each time.
+
+Example:
+
+```bash
+ascli conf preset update myf5 --auth=jwt --client-id=_client_id_here_ --client-secret=my_secret_here --username=_username_here_ --private-key=@file:.../path/to/key.pem
+
+ascli conf preset set default faspx5 myf5
+
+ascli faspex5 user profile show
+```
 
 ### Faspex 5 web authentication
 
-For `web` method, create an API client in Faspex without JWT:
+The admninistrator must create an API client in Faspex for an external web app support:
 
-- Navigate to the web UI: Admin &rarr; Configurations &rarr; API Clients &rarr; Create
+- As Admin, Navigate to the web UI: Admin &rarr; Configurations &rarr; API Clients &rarr; Create
 - Do not Activate JWT
 - Set **Redirect URI** to `https://127.0.0.1:8888`
-- Click on Create Button
+- Click on `Create` Button
 - Take note of Client Id (and Client Secret, but not used in current version)
 
-Then use options:
+The user will use the following options:
 
 ```text
 --auth=web
@@ -4573,7 +5007,7 @@ Then use options:
 
 For `boot` method: (will be removed in future)
 
-- Open a Web Browser
+- As user: Open a Web Browser
 - Start developer mode
 - Login to Faspex 5
 - Find the first API call with `Authorization` header, and copy the value of the token (series of base64 values with dots)
@@ -4581,23 +5015,14 @@ For `boot` method: (will be removed in future)
 Use this token as password and use `--auth=boot`.
 
 ```bash
-ascli conf id f5boot update --url=https://localhost/aspera/faspex --auth=boot --password=_token_here_
+ascli conf preset update f5boot --url=https://localhost/aspera/faspex --auth=boot --password=_token_here_
 ```
 
-### Faspex 5 packages
-
-The `value` option provided to command `faspex5 package send` is the same as for the Faspex 5 API: `POST /packages`.
-
-In addition, `ascli` adds some convenience: the field `recipients` is normally an Array of Hash, each with field `name` and optionally `recipient_type`, but it is also possible to provide an Array of String, with simply a recipient name.
-Then `ascli` will lookup existing contacts, and if a single match is found will use it, and set the `name` and `recipient_type` accordingly.
-
-> **Note:** The lookup is case insensitive and on partial matches.
-
 ### Faspex 5 sample commands
 
 Most commands are directly REST API calls.
-Parameters to commands are carried through option `value`, as extended value.
-Usually using JSON format with prefix `@json:`.
+Parameters to commands are carried through option `query`, as extended value, for `list`, or through positional 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**.
 
@@ -4606,70 +5031,200 @@ faspex5 admin res accounts list
 faspex5 admin res contacts list
 faspex5 admin res jobs list
 faspex5 admin res metadata_profiles list
-faspex5 admin res node list --value=@json:'{"type":"received","subtype":"mypackages"}'
+faspex5 admin res node list 
 faspex5 admin res oauth_clients list
 faspex5 admin res registrations list
 faspex5 admin res saml_configs list
+faspex5 admin res shared_inboxes invite %name:'ascli shinbox' johnny@example.com
 faspex5 admin res shared_inboxes list
+faspex5 admin res shared_inboxes members %name:'ascli shinbox' create %name:john@example.com
+faspex5 admin res shared_inboxes members %name:'ascli shinbox' delete %name:john@example.com
+faspex5 admin res shared_inboxes members %name:'ascli shinbox' delete %name:johnny@example.com
+faspex5 admin res shared_inboxes members %name:'ascli shinbox' list
 faspex5 admin res workgroups list
+faspex5 admin smtp show
+faspex5 admin smtp test my_email_external
 faspex5 bearer_token
-faspex5 gateway --value=https://localhost:12345/aspera/faspex &\
+faspex5 gateway https://localhost:12345/aspera/faspex
 faspex5 health
-faspex5 package list --value=@json:'{"mailbox":"inbox","state":["released"]}'
-faspex5 package receive "my_package_id" --to-folder=.  --ts=@json:'{"content_protection_password":"abc123_yo"}'
-faspex5 package send --value=@json:'{"title":"test title","recipients":["my_shinbox"],"metadata":{"Options":"Opt1","TextInput":"example text"}}' testfile.bin
-faspex5 package send --value=@json:'{"title":"test title","recipients":[{"name":"my_f5_user"}]}' testfile.bin --ts=@json:'{"content_protection_password":"my_passphrase_here"}'
-faspex5 package show "my_package_id"
-faspex5 postprocessing --value=@json:'{"url":"https://localhost:8443/domain","processing":{"script_folder":"tests"},"certificate":{"key":"../local/k","cert":"../local/c","chain":"../local/ch"}}' &\
+faspex5 packages list --box=my_faspex5_shinbox
+faspex5 packages list --box=my_faspex5_workgroup --group-type=workgroups
+faspex5 packages list --query=@json:'{"mailbox":"inbox","state":["released"]}'
+faspex5 packages receive "my_package_id" --to-folder=.  --ts=@json:'{"content_protection_password":"abc123_yo"}'
+faspex5 packages receive --box=my_faspex5_shinbox "my_package_id" --to-folder=.
+faspex5 packages receive --box=my_faspex5_workgroup --group-type=workgroups "my_package_id" --to-folder=.
+faspex5 packages receive ALL --once-only=yes --to-folder=.
+faspex5 packages receive INIT --once-only=yes
+faspex5 packages send @json:'{"title":"test title","recipients":["my_shinbox"],"metadata":{"Options":"Opt1","TextInput":"example text"}}' testfile.bin
+faspex5 packages send @json:'{"title":"test title","recipients":["my_workgroup"]}' testfile.bin
+faspex5 packages send @json:'{"title":"test title","recipients":[{"name":"my_f5_user"}]}' testfile.bin --ts=@json:'{"content_protection_password":"my_passphrase_here"}'
+faspex5 packages show "my_package_id"
+faspex5 packages show --box=my_faspex5_shinbox "my_package_id"
+faspex5 packages show --box=my_faspex5_workgroup --group-type=workgroups "my_package_id"
+faspex5 postprocessing @json:'{"url":"https://localhost:8443/domain","processing":{"script_folder":"tests"},"certificate":{"key":"../local/k","cert":"../local/c","chain":"../local/ch"}}'
 faspex5 user profile modify @json:'{"preference":{"connect_disabled":false}}'
 faspex5 user profile show
 ```
 
-Other examples:
+### Faspex 5: inbox selection
+
+By default, package operations (send, receive, list) are done on the user's inbox.
+
+To select another inbox, use option `box` with one of the following values:
+
+- inbox
+- inbox_history
+- inbox_all
+- inbox_all_history
+- outbox
+- outbox_history
+- pending
+- pending_history
+- all
+- ALL (only admin)
+- name of a shared inbox or workgroup
+
+> **Note:** specify if the box is a shared inbox or a workgroup using option `group_type` with either `shared_inboxes` or `workgroups`
+
+### Faspex 5: Send a package
 
-- Send a package with metadata
+The `Hash` creation parameter provided to command `faspex5 packages send` corresponds to the Faspex 5 API: `POST /packages`.
+
+Required fields are `title` and `recipients`.
+Example using `@json:` format:
+
+```json
+{"title":"some title","recipients":[{"recipient_type":"user","name":"user@example.com"}]}
+```
+
+`recipient_type` is one of (Refer to API):
+
+- user
+- workgroup
+- external_user
+- distribution_list
+- shared_inbox
+
+`ascli` adds some convenience: The API expects the field `recipients` to be an `Array` of `Hash`, each with field `name` and optionally `recipient_type`.
+It is also possible to provide an `Array` of `String`, with simply a recipient name.
+Then `ascli` will lookup existing contacts among all possible types, use it if a single match is found, and set the `name` and `recipient_type` accordingly.
+Else an exception is sent.
+
+> **Note:** The lookup is case insensitive and on partial matches.
+
+```json
+{"title":"some title","recipients":["user@example.com"]}
+```
+
+If the lookup needs to be only on certain types, you can specify the field: `recipient_types` with either a single value or an Array of values (from the list above). e.g. :
+
+```json
+{"title":"test title","recipient_types":"user","recipients":["user1@example.com","user2@example.com"]}
+```
+
+### Faspex 5:  Send a package with metadata
 
 The interface is the one of the API (Refer to API documentation, or look at request in browser):
 
 ```bash
-ascli faspex5 package send --value=@json:'{"title":"test title","recipients":["ascli shared inbox"],"metadata":{"Confidential":"Yes","Drop menu":"Option 1"}}' 'faux:///test1?k1'
+ascli faspex5 packages send @json:'{"title":"test title","recipients":["my shared inbox"],"metadata":{"Confidential":"Yes","Drop menu":"Option 1"}}' 'faux:///test1?k1'
 ```
 
 Basically, add the field `metadata`, with one key per metadata and the value is directly the metadata value.
 
-- List all shared inboxes
+### Faspex 5: Receive a package
+
+The (numeric) identifier of the package t receive is given as argument to command `faspex5 packages receive`.
+
+> **Note:** option `box` applies.
+
+### Faspex 5: List packages
+
+The following parameters in option `query` are supported:
+
+- `q` : a filter on name (case insensitive, matches if value is contained in name)
+- `max` : maximum number of items to retrieve (stop pages when the maximum is passed)
+- `pmax` : maximum number of pages to request (stop pages when the maximum is passed)
+- `offset` : native api parameter, in general do not use (added by `ascli`)
+- `limit` : native api parameter, number of items par api call, in general do not use (added by `ascli`)
+
+Admin only: If the value `ALL` is provided to option `box`, then all packages are selected.
+
+### Faspex 5: List all shared inboxes
+
+```bash
+ascli faspex5 admin res shared list --query=@json:'{"all":true}' --fields=id,name
+```
+
+Shared inbox members can also be listed, added, removed, and external users can be invited to a shared inbox.
 
 ```bash
-ascli faspex5 admin res shared list --value=@json:'{"all":true}' --fields=id,name
+ascli faspex5 admin res shared_inboxes invite '%name:ascli shinbox' john@example.com
+```
+
+It is equivalent to:
+
+```bash
+ascli faspex5 admin res shared_inboxes invite '%name:ascli shinbox' @json:'{"email_address":"john@example.com"}'
+```
+
+Other payload parameters are possible in Hash format:
+
+```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
 ```
 
-- Create Metadata profile
+### Faspex 5: Create Metadata profile
 
 ```bash
-ascli faspex5 admin res metadata_profiles create --value=@json:'{"name":"the profile","default":false,"title":{"max_length":200,"illegal_chars":[]},"note":{"max_length":400,"illegal_chars":[],"enabled":false},"fields":[{"ordering":0,"name":"field1","type":"text_area","require":true,"illegal_chars":[],"max_length":100},{"ordering":1,"name":"fff2","type":"option_list","require":false,"choices":["opt1","opt2"]}]}'
+ascli faspex5 admin res metadata_profiles create @json:'{"name":"the profile","default":false,"title":{"max_length":200,"illegal_chars":[]},"note":{"max_length":400,"illegal_chars":[],"enabled":false},"fields":[{"ordering":0,"name":"field1","type":"text_area","require":true,"illegal_chars":[],"max_length":100},{"ordering":1,"name":"fff2","type":"option_list","require":false,"choices":["opt1","opt2"]}]}'
 ```
 
-- Create a Shared inbox with specific metadata profile
+### Faspex 5: Create a Shared inbox with specific metadata profile
 
 ```bash
-ascli faspex5 admin res shared create --value=@json:'{"name":"the shared inbox","metadata_profile_id":1}'
+ascli faspex5 admin res shared create @json:'{"name":"the shared inbox","metadata_profile_id":1}'
 ```
 
-- List content in Shared folder and send package from remote source
+### Faspex 5: List content in Shared folder and send package from remote source
 
 ```bash
 ascli faspex5 shared_folders list
 ```
 
+```markdown
++----+----------+---------+-----+
+| id | name     | node_id | ... |
++----+----------+---------+-----+
+| 3  | partages | 2       | ... |
++----+----------+---------+-----+
+```
+
 ```bash
-ascli faspex5 shared_folders br 3 /folder
+ascli faspex5 shared_folders br %name:partages /folder
 ```
 
 ```bash
-ascli faspex5 package send --value=@json:'{"title":"hello","recipients":[{"name":"_recipient_here_"}]}' --shared-folder=3 /folder/file
+ascli faspex5 packages send @json:'{"title":"hello","recipients":[{"name":"_recipient_here_"}]}' --shared-folder=%name:partages /folder/file
 ```
 
-### Faspex 4-style postprocessing script with Faspex 5
+> **Note:** The shared folder can be identified by its numerical `id` or by name using percent selector: `%<field>:<value>`. e.g. `--shared-folder=3`
+
+### Faspex 5: receive all packages (cargo)
+
+To receive all packages, only once, through persistency of already received packages:
+
+```bash
+ascli faspex5 packages receive ALL --once-only=yes
+```
+
+To initialize, and skip all current package so that next time `ALL` is used, only newer packages are downloaded:
+
+```bash
+ascli faspex5 packages receive INIT --once-only=yes
+```
+
+### Faspex 5: Faspex 4-style postprocessing
 
 `ascli` provides command `postprocessing` in plugin `faspex5` to emulate Faspex 4 postprocessing.
 It implements Faspex 5 web hooks, and calls a local script with the same environment as Faspex 4.
@@ -4677,19 +5232,19 @@ It implements Faspex 5 web hooks, and calls a local script with the same environ
 It is invoked like this:
 
 ```bash
-ascli faspex5 postprocessing --value=@json:'{"url":"http://localhost:8080/processing"}'
+ascli faspex5 postprocessing @json:'{"url":"http://localhost:8080/processing"}'
 ```
 
 The following parameters are supported:
 
 | parameter                  | type    | default                | description                                         |
 |----------------------------|---------|------------------------|-----------------------------------------------------|
-| url                        | string  | http://localhost:8080  | Defines the base url on which requests are listened |
+| url                        | string  | <http://localhost:8080>  | Defines the base url on which requests are listened |
 | certificate                | hash    | nil                    | used to define certificate if https is used         |
 | certificate.key            | string  | nil                    | path to private key file                            |
 | certificate.cert           | string  | nil                    | path to certificate                                 |
 | certificate.chain          | string  | nil                    | path to intermediary certificates                   |
-| processing                 | hash    | nil                    | behaviour of post processing                        |
+| processing                 | hash    | nil                    | behavior of post processing                        |
 | processing.script_folder   | string  | .                      | prefix added to script path                         |
 | processing.fail_on_error   | bool    | false                  | if true and process exit with non zero, then fail   |
 | processing.timeout_seconds | integer | 60                     | processing script is killed if takes more time      |
@@ -4704,7 +5259,7 @@ When a request is received the following happens:
 
 - the processor get the path of the url called
 - it removes the "domain
-- it pre-prends it with the value of `script_folder`
+- it prepends it with the value of `script_folder`
 - it executes the script
 - upon success, a success code is returned
 
@@ -4752,7 +5307,8 @@ As inboxes may be large, it is possible to use the following query parameters:
 
 The API is listed in [Faspex 4 API Reference](https://developer.ibm.com/apis/catalog/?search=faspex) under "Services (API v.3)".
 
-If no parameter `max` or `pmax` is provided, then all packages will be listed in the inbox, which result in paged API calls (using parameter: `count` and `page`). By default page is `0` (`10`), it can be increased to have less calls.
+If no parameter `max` or `pmax` is provided, then all packages will be listed in the inbox, which result in paged API calls (using parameter: `count` and `page`).
+By default `count` is `0` (`10`), it can be increased to issue less HTTP calls.
 
 #### Example: list packages in dropbox
 
@@ -4771,7 +5327,7 @@ The command is `package recv`, possible methods are:
 - provide a `faspe:` URI with option `link`
 
 ```bash
-ascli faspex package recv --id=12345
+ascli faspex package recv 12345
 ascli faspex package recv --link=faspe://...
 ```
 
@@ -4820,9 +5376,9 @@ In this example the notification template is directly provided on command line.
 Example:
 
 ```bash
-ascli faspex v4 dropbox create --value=@json:'{"dropbox":{"e_wg_name":"test1","e_wg_desc":"test1"}}'
+ascli faspex v4 dropbox create @json:'{"dropbox":{"e_wg_name":"test1","e_wg_desc":"test1"}}'
 ascli faspex v4 dropbox list
-ascli faspex v4 dropbox delete --id=36
+ascli faspex v4 dropbox delete 36
 ```
 
 ### Remote sources
@@ -4860,7 +5416,7 @@ It is possible to tell `ascli` to download newly received packages, much like th
 cargo client, or drive. Refer to the [same section](#aoccargo) in the Aspera on Cloud plugin:
 
 ```bash
-ascli faspex packages recv --id=ALL --once-only=yes --lock-port=12345
+ascli faspex packages recv ALL --once-only=yes --lock-port=12345
 ```
 
 ### Faspex 4 sample commands
@@ -4879,18 +5435,18 @@ faspex package list --recipient="*my_faspex_dbx" --format=csv --fields=package_i
 faspex package list --recipient="*my_faspex_wkg" --format=csv --fields=package_id --query=@json:'{"max":1}'
 faspex package recv "my_package_id" --to-folder=.
 faspex package recv "my_package_id" --to-folder=. --box=sent
-faspex package recv --to-folder=. --link="my_faspex_publink_recv_from_fxuser"
+faspex package recv --to-folder=. --link=https://app.example.com/recv_from_user_path
 faspex package recv ALL --to-folder=. --once-only=yes
 faspex package recv my_pkgid --recipient="*my_faspex_dbx" --to-folder=.
 faspex package recv my_pkgid --recipient="*my_faspex_wkg" --to-folder=.
 faspex package send --delivery-info=@json:'{"title":"Important files delivery","recipients":["*my_faspex_dbx"]}' testfile.bin
 faspex package send --delivery-info=@json:'{"title":"Important files delivery","recipients":["*my_faspex_wkg"]}' testfile.bin
 faspex package send --delivery-info=@json:'{"title":"Important files delivery","recipients":["my_email_internal_user","my_faspex_username"]}' testfile.bin
-faspex package send --link="my_faspex_publink_send_to_dropbox" --delivery-info=@json:'{"title":"Important files delivery"}' testfile.bin
-faspex package send --link="my_faspex_publink_send_to_fxuser" --delivery-info=@json:'{"title":"Important files delivery"}' testfile.bin
+faspex package send --link=https://app.example.com/send_to_dropbox_path --delivery-info=@json:'{"title":"Important files delivery"}' testfile.bin
+faspex package send --link=https://app.example.com/send_to_user_path --delivery-info=@json:'{"title":"Important files delivery"}' testfile.bin
 faspex source list
-faspex source name "my_source_name" info
-faspex source name "my_source_name" node br /
+faspex source name my_faspex_src info
+faspex source name my_faspex_src node br /
 faspex v4 dmembership list
 faspex v4 dropbox list
 faspex v4 metadata_profile list
@@ -4901,7 +5457,7 @@ faspex v4 workgroup list
 
 ## <a id="shares"></a>Plugin: `shares`: IBM Aspera Shares v1
 
-Aspera Shares supports the "node API" for the file transfer part. (Shares 1 and 2)
+Aspera Shares supports the "node API" for the file transfer part.
 
 ### Shares 1 sample commands
 
@@ -4910,20 +5466,20 @@ shares admin group list
 shares admin node list
 shares admin share list --fields=-status,status_message
 shares admin share user_permissions 1 list
-shares admin user add --type=ldap --value=the_name
-shares admin user app_authorizations 1 modify --value=@json:'{"app_login":true}'
+shares admin user add --type=ldap the_name
+shares admin user app_authorizations 1 modify @json:'{"app_login":true}'
 shares admin user app_authorizations 1 show
-shares admin user import --type=saml --value=@json:'{"id":"the_id","name_id":"the_name"}'
+shares admin user import --type=saml @json:'{"id":"the_id","name_id":"the_name"}'
 shares admin user list
 shares admin user share_permissions 1 list
 shares admin user share_permissions 1 show 1
+shares files browse /
+shares files delete my_shares_upload/testfile.bin
+shares files download --to-folder=. my_shares_upload/testfile.bin
+shares files download --to-folder=. my_shares_upload/testfile.bin --transfer=httpgw --transfer-info=@json:'{"url":"https://my_http_gw_fqdn/aspera/http-gwy"}'
+shares files upload --to-folder=my_shares_upload testfile.bin
+shares files upload --to-folder=my_shares_upload testfile.bin --transfer=httpgw --transfer-info=@json:'{"url":"https://my_http_gw_fqdn/aspera/http-gwy"}'
 shares health
-shares repository browse /
-shares repository delete my_shares_upload/testfile.bin
-shares repository download --to-folder=. my_shares_upload/testfile.bin
-shares repository download --to-folder=. my_shares_upload/testfile.bin --transfer=httpgw --transfer-info=@json:'{"url":"https://my_http_gw_fqdn/aspera/http-gwy"}'
-shares repository upload --to-folder=my_shares_upload testfile.bin
-shares repository upload --to-folder=my_shares_upload testfile.bin --transfer=httpgw --transfer-info=@json:'{"url":"https://my_http_gw_fqdn/aspera/http-gwy"}'
 ```
 
 ## <a id="console"></a>Plugin: `console`: IBM Aspera Console
@@ -4978,8 +5534,8 @@ If you have those parameters already, then following options shall be provided:
 For example, let us create a default configuration:
 
 ```bash
-ascli conf id mycos update --bucket=mybucket --endpoint=https://s3.us-east.cloud-object-storage.appdomain.cloud --apikey=abcdefgh --crn=crn:v1:bluemix:public:iam-identity::a/xxxxxxx
-ascli conf id default set cos mycos
+ascli conf preset update mycos --bucket=mybucket --endpoint=https://s3.us-east.cloud-object-storage.appdomain.cloud --apikey=abcdefgh --crn=crn:v1:bluemix:public:iam-identity::a/xxxxxxx
+ascli conf preset set default cos mycos
 ```
 
 Then, jump to the transfer example.
@@ -5011,8 +5567,6 @@ ibmcloud resource service-key _service_key_name_here_ --output JSON|jq '.[0].cre
 
 It consists in the following structure:
 
-<!-- spellchecker: disable -->
-
 ```json
 {
   "apikey": "my_api_key_here",
@@ -5029,8 +5583,6 @@ It consists in the following structure:
 }
 ```
 
-<!-- spellchecker: enable -->
-
 The field `resource_instance_id` is for option `crn`
 
 The field `apikey` is for option `apikey`
@@ -5046,8 +5598,8 @@ The required options for this method are:
 For example, let us create a default configuration:
 
 ```bash
-ascli conf id mycos update --bucket=laurent --service-credentials=@val:@json:@file:~/service_creds.json --region=us-south
-ascli conf id default set cos mycos
+ascli conf preset update mycos --bucket=laurent --service-credentials=@val:@json:@file:~/service_creds.json --region=us-south
+ascli conf preset set default cos mycos
 ```
 
 ### Operations, transfers
@@ -5076,20 +5628,30 @@ cos node upload testfile.bin
 
 ## <a id="async"></a>Plugin: `async`: IBM Aspera Sync
 
-A basic plugin to start an "async" using `ascli`.
-The main advantage over bare `async` command line is the possibility to use a configuration file, using `ascli` standard options.
+A basic plugin to start an `async` using `ascli`.
+The main advantage over bare `async` command line is the possibility to use a configuration file, using standard options of `ascli`.
 
-Also, the `sync` command is also made available through the `server sync` and `aoc files sync` commands.
-In this case, some of the `sync` parameters are fill from parameters of the related plugin.
+The `sync` command is also made available through the `server sync`, `aoc files sync` and `node sync` commands.
+In this case, some of the `sync` parameters are filled by the related plugin using transfer spec parameters (including token).
 
 > **Note:** All `sync` commands require an `async` enabled license and availability of the `async` executable (and `asyncadmin`).
->
-> **Note:** Two JSON syntax are supported for option `sync_info`.
-> The first is same sync payload as specified on the `async` option `--conf` or in the latest node API, this is the preferred syntax and allows a single session definition.
-> The second (legacy) is specific to `ascli` and allows definition of multiple sync sessions in a single command, although usually only one sync session is defined.
+
+Two JSON syntax are supported for option `sync_info`.
+
+### async native JSON
+
+It is the same payload as specified on the `async` option `--conf` or in the latest node API.
+This is the preferred syntax and allows a single session definition.
+But there is no progress output nor error messages.
 
 Documentation on Async node API can be found on [IBM Developer Portal](https://developer.ibm.com/apis/catalog?search=%22aspera%20sync%20api%22).
 
+### async options as JSON
+
+This is specific to `ascli`.
+It is based on a JSON representation of `async` command line options.
+It allows definition of multiple sync sessions in a single command, although usually only one sync session is defined.
+
 ### Sync sample commands
 
 ```bash
@@ -5165,7 +5727,7 @@ ascli preview check
 #### Image: ImageMagick and optipng
 
 ```bash
-yum install -y ImageMagick optipng
+dnf install -y ImageMagick optipng
 ```
 
 You may also install `ghostscript` which adds fonts to ImageMagick.
@@ -5194,7 +5756,6 @@ dnf install unoconv
 
 - Amazon Linux
 
-<!-- spellchecker: disable -->
 ```bash
 amazon-linux-extras enable libreoffice
 yum clean metadata
@@ -5203,15 +5764,17 @@ wget https://raw.githubusercontent.com/unoconv/unoconv/master/unoconv
 mv unoconv /usr/bin
 chmod a+x /usr/bin/unoconv
 ```
-<!-- spellchecker: enable -->
 
 ### Configuration
 
-The preview generator is run as a user, preferably a regular user (not root). 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)
+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](#lprt).  The configuration file must be created with the same user used to run so that it is properly used on runtime.
+Like any `ascli` commands, parameters can be passed on command line or using a configuration [option preset](#lprt).
+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 changing identity requires specification of alternate shell:
+The `xfer` user has a special protected shell: `aspshell`, so in order to update the configuration, and when changing identity, specify an alternate shell.
+E.g.:
 
 ```bash
 su -s /bin/bash - xfer
@@ -5232,11 +5795,17 @@ ascli -Ppreviewconf node browse /
 
 This shall list the contents of the storage root of the access key.
 
+### Options for generated files
+
+When generating preview files, some options are provided by default.
+Some values for the options can be modified on command line.
+For video preview, the whole set of options can be overridden with option `reencode_ffmpeg`: it is a Hash with two keys: `in` and `out`, each is an array of strings with the native options to `ffmpeg`.
+
 ### Execution
 
 The tool intentionally supports only a **one shot** mode (no infinite loop) in order to avoid having a hanging process or using too many resources (calling REST api too quickly during the scan or event method).
 It needs to be run on a regular basis to create or update preview files.
-For that use your best reliable scheduler, see [Scheduling](#scheduling).
+For that use your best reliable scheduler, see [Scheduler](#scheduler).
 
 Typically, for **Access key** access, the system/transfer is `xfer`. So, in order to be consistent have generate the appropriate access rights, the generation process should be run as user `xfer`.
 
@@ -5254,37 +5823,16 @@ On subsequent run it reads this file and check that previews are generated for t
 
 ### Configuration for Execution in scheduler
 
-Here is an example of configuration for use with `cron` on Linux.
-Adapt the scripts to your own needs.
-
-We assume here that a configuration preset was created as shown previously.
+Details are provided in section [Scheduler](#scheduler).
 
-Lets first setup a script that will be used in the scheduler and set up the environment.
+Shorter commands can be specified if a configuration preset was created as shown previously.
 
-Example of startup script `cron_ascli`, which sets the Ruby environment and adds some timeout protection:
+For example the timeout value can be differentiated depending on the option: event versus scan:
 
-<!-- spellchecker: disable -->
 ```bash
- #!/bin/bash
- # set a timeout protection, just in case
 case "$*" in *trev*) tmout=10m ;; *) tmout=30m ;; esac
-. /etc/profile.d/rvm.sh
-rvm use 2.6 --quiet
-exec timeout ${tmout} ascli "${@}"
-```
-<!-- spellchecker: enable -->
-
-Here the cronjob is created for user `xfer`.
-
-```bash
-crontab<<EOF
-0    * * * *  /home/xfer/cron_ascli preview scan --logger=syslog --display=error
-2-59 * * * *  /home/xfer/cron_ascli preview trev --logger=syslog --display=error
-EOF
 ```
 
-> **Note:** The logging options are kept here in the cronfile instead of conf file to allow execution on command line with output on command line.
-
 ### Candidate detection for creation or update (or deletion)
 
 The tool generates preview files using those commands:
@@ -5313,20 +5861,20 @@ ascli preview scan --skip-folders=@json:'["/not_here"]'
 
 The option `folder_reset_cache` forces the node service to refresh folder contents using various methods.
 
-When scanning the option `value` has the same behavior as for the `node find` command.
+When scanning the option `query` has the same behavior as for the `node find` command.
 
 For instance to filter out files beginning with `._` do:
 
 ```bash
-... --value='exec:!f["name"].start_with?("._") or f["name"].eql?(".DS_Store")'
+--query='exec:!f["name"].start_with?("._") or f["name"].eql?(".DS_Store")'
 ```
 
 ### Preview File types
 
 Two types of preview can be generated:
 
-- png: thumbnail
-- mp4: video preview (only for video)
+- `png`: thumbnail
+- `mp4`: video preview (only for video)
 
 Use option `skip_format` to skip generation of a format.
 
@@ -5379,10 +5927,10 @@ If the `mimemagic` gem complains about missing mime info file:
 
   - Close the `cmd` and restart a new one if needed to get refreshed env vars
 
-- Linux:
+- Linux RHEL 8+:
 
 ```bash
-yum install shared-mime-info
+dnf install shared-mime-info
 ```
 
 - macOS:
@@ -5391,7 +5939,7 @@ yum install shared-mime-info
 brew install shared-mime-info
 ```
 
-### Access to original files and preview creation
+### Generation: Read source files and write preview
 
 Standard open source tools are used to create thumbnails and video previews.
 Those tools require that original files are accessible in the local file system and also write generated files on the local file system.
@@ -5406,7 +5954,7 @@ If the preview generator does not have access to files on the file system (it is
 
 ```bash
 preview check --skip-types=office
-preview folder 1 --skip-types=office --log-level=info --file-access=remote --ts=@json:'{"target_rate_kbps":1000000}'
+preview scan --scan-id=1 --skip-types=office --log-level=info --file-access=remote --ts=@json:'{"target_rate_kbps":1000000}'
 preview scan --skip-types=office --log-level=info
 preview test --case=test mp4 my_file_mxf --video-conversion=blend --log-level=debug
 preview test --case=test mp4 my_file_mxf --video-conversion=clips --log-level=debug
@@ -5421,20 +5969,23 @@ preview trevents --once-only=yes --skip-types=office --log-level=info
 
 ## SMTP for email notifications
 
-Aspera CLI can send email, for that setup SMTP configuration. This is done with option `smtp`.
+`ascli` can send email, for that setup SMTP configuration. This is done with option `smtp`.
 
 The `smtp` option is a hash table (extended value) with the following fields:
 
+<!-- markdownlint-disable MD034 -->
 | field        | default             | example                    | description                      |
 |--------------|---------------------|----------------------------|----------------------------------|
 | `server`     | -                   | smtp.gmail.com             | SMTP server address              |
-| `tls`        | true                | false                      | use of TLS                       |
-| `port`       | TLS: 587<br/>25     | 587                        | port for service                 |
+| `tls`        | true                | true                       | enable STARTTLS (port 587)       |
+| `ssl`        | false               | false                      | enable TLS (port 465)            |
+| `port`       | 587 or 465 or 25    | 587                        | port for service                 |
 | `domain`     | domain of server    | gmail.com                  | email domain of user             |
 | `username`   | -                   | john@example.com           | user to authenticate on SMTP server, leave empty for open auth. |
 | `password`   | -                   | my_password_here           | password for above username      |
 | `from_email` | username if defined | johnny@example.com         | address used if receiver replies |
 | `from_name`  | same as email       | John Wayne                 | display name of sender           |
+<!-- markdownlint-enable MD034 -->
 
 ### Example of configuration
 
@@ -5548,7 +6099,7 @@ There are special "extended" [*transfer-spec*](#transferspec) parameters support
 | required additional components to `ascp` | Ruby<br/>Aspera | - | library<br/>(headers) | daemon |
 | startup | JSON on stdin<br/>(standard APIs:<br/>JSON.generate<br/>Process.spawn) | command line arguments | API | daemon |
 | events | JSON on stdout | none by default<br/>or need to open management port<br/>and proprietary text syntax | callback | callback |
-| platforms | any with ruby and `ascp` | any with `ascp` (and SDK if compiled) | any with `ascp` | any with `ascp` and transfer daemon |
+| platforms | any with Ruby and `ascp` | any with `ascp` (and SDK if compiled) | any with `ascp` | any with `ascp` and transfer daemon |
 
 ### Simple session
 
@@ -5642,11 +6193,11 @@ 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*](#transferspec), with `--ts` parameter.
+> **Note:** `ascli` takes transfer parameters exclusively as a [*transfer-spec*](#transferspec), with `ts` option.
 >
 > **Note:** Most, but not all, native `ascp` arguments are available as standard [*transfer-spec*](#transferspec) parameters.
 >
-> **Note:** Only for the [`direct`](#agt_direct) transfer agent (not others, like connect or node), native `ascp` arguments can be provided option `transfer_info` parameter `ascp_args`.
+> **Note:** Only for the [`direct`](#agt_direct) transfer agent (not others, like connect or node), native `ascp` arguments can be provided with parameter `ascp_args` of option `transfer_info` .
 
 #### server side and configuration
 
@@ -5659,7 +6210,7 @@ Virtually any transfer on a "repository" on a regular basis might emulate a hot
 #### Scheduling
 
 Once `ascli` parameters are defined, run the command using the OS native scheduler, e.g. every minutes, or 5 minutes, etc...
-Refer to section [Scheduling](#scheduling). (on use of option `lock_port`)
+Refer to section [Scheduler](#scheduler). (on use of option `lock_port`)
 
 ### Example: upload hot folder
 
@@ -5739,30 +6290,7 @@ Main components:
 - `Aspera::Fasp`: starting and monitoring transfers. It can be considered as a FASPManager class for Ruby.
 - `Aspera::Cli`: `ascli`.
 
-A working example can be found in the gem, example:
-
-```bash
-ascli config gem path
-```
-
-```bash
-cat $(ascli config gem path)/../examples/transfer.rb
-```
-
-This sample code shows some example of use of the API as well as REST API.
-Note: although nice, it's probably a good idea to use RestClient for REST.
-
-Example of use of the API of Aspera on Cloud:
-
-```ruby
-require 'aspera/aoc'
-
-aoc=Aspera::AoC.new(url: 'https://sedemo.ibmaspera.com',auth: :jwt, scope: 'user:all', private_key: File.read(File.expand_path('~/.aspera/ascli/aspera_on_cloud_key')),username: 'laurent.martin.aspera@fr.ibm.com',subpath: 'api/v1')
-
-aoc.read('self')
-```
-
-<https://github.com/IBM/aspera-cli/blob/main/examples/aoc.rb>
+Working examples can be found in repo: <https://github.com/laurent-martin/aspera-api-examples> in Ruby examples.
 
 ## Changes (Release notes)
 
@@ -5790,6 +6318,13 @@ So, it evolved into `ascli`:
 Over the time, a supported command line tool `aspera` was developed in C++, it was later on deprecated.
 It had the advantage of being relatively easy to installed, as a single executable (well, still using `ascp`), but it was too limited IMHO, and lacked a lot of the features of this CLI.
 
+Enjoy a coffee on me:
+
+```bash
+ascli conf coffee
+ascli conf coffee --ui=text
+```
+
 ## Common problems
 
 ### Error: "Remote host is not who we expected"
@@ -5810,7 +6345,7 @@ References: ES-1944 in release notes of 4.1 and to [HSTS admin manual section "C
 
 Some Ruby gems dependencies require compilation of native parts (C).
 This also requires Ruby header files.
-If Ruby was installed as a Linux Packages, then also install ruby development package:
+If Ruby was installed as a Linux Packages, then also install Ruby development package:
 `ruby-dev` ir `ruby-devel`, depending on distribution.
 
 ### ED255519 key not supported
@@ -5823,5 +6358,5 @@ Without this deactivation, if such key was present the following error was gener
 OpenSSH keys only supported if ED25519 is available
 ```
 
-Which meant that you do not have ruby support for ED25519 SSH keys.
+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.