aspera-cli 4.14.0 → 4.15.0

data/README.md

@@ -1,16 +1,20 @@
 # 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 schtasks taskschd dascli -->
+<!-- cspell:ignore Serban Antipolis -->
 
 [comment1]: # (Do not edit this README.md, edit docs/README.erb.md, for details, read docs/README.md)
 
-##
+[![Gem Version](https://badge.fury.io/rb/aspera-cli.svg)](https://badge.fury.io/rb/aspera-cli)
+[![unit tests](https://github.com/IBM/aspera-cli/actions/workflows/test.yml/badge.svg?branch=main)](https://github.com/IBM/aspera-cli/actions)
+[![CII Best Practices](https://bestpractices.coreinfrastructure.org/projects/5861/badge)](https://bestpractices.coreinfrastructure.org/projects/5861)
+
+## Introduction
 
-Version : 4.14.0
+Version : 4.15.0
 
 Laurent/2016-2023
 
-This gem provides the `ascli` Command Line Interface to IBM Aspera software.
+This gem provides the `ascli` CLI (Command Line Interface) to IBM Aspera software.
 
 `ascli` is a also great tool to learn Aspera APIs.
 
@@ -27,15 +31,13 @@ Minimum required Ruby version: >= 2.6.
 
 Release notes: see [CHANGELOG.md](CHANGELOG.md)
 
-[![CII Best Practices](https://bestpractices.coreinfrastructure.org/projects/5861/badge)](https://bestpractices.coreinfrastructure.org/projects/5861)
+A PDF version of this documentation is available here: [docs/Manual.pdf](docs/Manual.pdf).
 
-## BUGS, FEATURES, CONTRIBUTION
+### BUGS, FEATURES, CONTRIBUTION
 
 Refer to [BUGS.md](BUGS.md) and [CONTRIBUTING.md](CONTRIBUTING.md).
 
-One can also [create one's own plugin](#createownplugin).
-
-## <a id="when_to_use"></a>When to use and when not to use
+### <a id="when_to_use"></a>When to use and when not to use
 
 `ascli` is designed to be used as a command line tool to:
 
@@ -63,7 +65,7 @@ Using APIs (application REST API and transfer SDK) will prove to be easier to de
 
 For scripting and ad'hoc command line operations, `ascli` is perfect.
 
-## Notations, Shell, Examples
+### Notations, Shell, Examples
 
 Command line operations examples are shown using a shell such: `bash` or `zsh`.
 
@@ -92,7 +94,7 @@ ascli --version
 ```
 
 ```bash
-4.14.0
+4.15.0
 ```
 
 ### First use
@@ -112,14 +114,14 @@ ascli server browse /
 ```
 
 ```output
-+------------+-----------+-----------+-------+---------------------------+-----------------------+
-| 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  |
-+------------+-----------+-----------+-------+---------------------------+-----------------------+
++------------+--------+-----------+-------+---------------------------+-----------------------+
+| zmode      | zuid   | zgid      | size  | mtime                     | name                  |
++------------+--------+-----------+-------+---------------------------+-----------------------+
+| drwxr-xr-x | aspera | asperaweb | 90112 | 2023-04-05 15:31:21 +0200 | Upload                |
+| dr-xr-xr-x | aspera | asperaweb | 4096  | 2022-10-27 16:08:16 +0200 | aspera-test-dir-large |
+| dr-xr-xr-x | aspera | asperaweb | 4096  | 2022-10-27 16:08:17 +0200 | aspera-test-dir-small |
+| dr-xr-xr-x | aspera | asperaweb | 4096  | 2022-10-27 16:08:17 +0200 | aspera-test-dir-tiny  |
++------------+--------+-----------+-------+---------------------------+-----------------------+
 ```
 
 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:
@@ -168,7 +170,7 @@ ascli server download /aspera-test-dir-large/200MB
 ```
 
 ```output
-Time: 00:00:02 =========================================================== 100% 100 Mbps Time: 00:00:00
+Time: 00:00:02 ============================================= 100% 100 Mbps Time: 00:00:00
 complete
 ```
 
@@ -198,7 +200,7 @@ An internet connection is required for the installation. If you don't have inter
 
 ### Container
 
-The container 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 `podman` (or `docker`) installed.
 
@@ -206,7 +208,7 @@ To use the container, ensure that you have `podman` (or `docker`) installed.
 podman --version
 ```
 
-#### Container: quick start
+#### Container: Quick start
 
 **Wanna start quickly ?** With an interactive shell ? Execute this:
 
@@ -254,7 +256,7 @@ ascli -v
 ```
 
 ```text
-4.14.0
+4.15.0
 ```
 
 In order to keep persistency of configuration on the host,
@@ -306,12 +308,12 @@ A convenience sample script is also provided: download the script [`dascli`](../
 
 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/.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`              |
+| env var        | description                        | default                  | example                  |
+|----------------|------------------------------------|--------------------------|--------------------------|
+| `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`              |
 
 The wrapping script maps the folder `$ASCLI_HOME` on host to `/home/cliuser/.aspera/ascli` in the container.
 (value expected in the container).
@@ -337,7 +339,7 @@ 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.
+> **Note:** Do not use too many volumes, as the legacy `aufs` limits the number. (anyway, prefer to use `overlay2`)
 
 #### Container: Offline installation
 
@@ -364,7 +366,7 @@ If one wants to change the content, it is possible to tell `ascp` to use another
 echo '<CONF/>' > $HOME/.aspera/ascli/aspera.conf
 ```
 
-Then, tell `ascp` to use that other conf file:
+Then, tell `ascp` to use that other configuration file:
 
 ```bash
 --transfer-info=@json:'{"ascp_args":["-f","/home/cliuser/.aspera/ascli/aspera.conf"]}'
@@ -376,7 +378,7 @@ Singularity is another type of use of container.
 
 On Linux install:
 
-```console
+```bash
 dnf install singularity-ce
 ```
 
@@ -386,13 +388,13 @@ Build an image like this:
 singularity build ascli.sif docker://martinlaurent/ascli
 ```
 
-The use like this:
+Then, start `ascli` like this:
 
 ```bash
 singularity run ascli.sif
 ```
 
-Or get a shell with access to the tool like this:
+Or get a shell with access to `ascli` like this:
 
 ```bash
 singularity shell ascli.sif
@@ -402,13 +404,13 @@ singularity shell ascli.sif
 
 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 `ascli` or to use the gem and tool.
 
 Required Ruby version: >= 2.6.
 
 > **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, ... .
+**Ruby can be installed using any method** : rpm, yum, dnf, rvm, brew, Windows installer, ... .
 
 In priority, refer to the official Ruby documentation:
 
@@ -421,7 +423,7 @@ The recommended installation method is `rvm` for Unix-like systems (Linux, AIX,
 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 !
 
-#### Generic: RVM: single user installation (not root)
+#### Generic: RVM: Single user installation (not root)
 
 Use this method which provides more flexibility.
 
@@ -455,7 +457,7 @@ rvm install 3.2.2
 
 Ruby is now installed for the user, go to [Gem installation](#the_gem).
 
-#### Generic: RVM: global installation (as root)
+#### Generic: RVM: Global installation (as root)
 
 Follow the same method as single user install, but execute as "root".
 
@@ -467,7 +469,12 @@ 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`.
+If so, one can rename the login script:
+
+```bash
+mv /etc/profile.d/rvm.sh /etc/profile.d/rvm.sh.ok
+```
+
 To activate Ruby (and ascli) later, source it:
 
 ```bash
@@ -480,16 +487,69 @@ rvm version
 
 #### Windows: Installer
 
-Install Latest stable Ruby:
+Manual installation:
 
 - Navigate to [https://rubyinstaller.org/](https://rubyinstaller.org/) &rarr; **Downloads**.
-- Download the latest Ruby installer **with devkit**. (Msys2 is needed to install some native extensions, such as `grpc`)
+- Download the latest Ruby installer **"with devkit"**. (`Msys2` is needed to install some native extensions, such as `grpc`)
 - Execute the installer which installs by default in: `C:\RubyVV-x64` (VV is the version number)
-- At the end of the installation procedure, the Msys2 installer is automatically executed, select option 3 (msys and mingw)
+- At the end of the installation procedure, the `Msys2` installer is automatically executed, select option 3 (`Msys2` and mingw)
+- then install the aspera-cli gem and Aspera SDK (see next sections)
+
+Automated installation, with internet access:
+
+The ruby installer supports silent installation, to see the options, execute it with `/help`, or refer to the [Ruby Installer FAQ](https://github.com/oneclick/rubyinstaller2/wiki/FAQ)
+
+Download the ruby installer executable from <https://rubyinstaller.org/downloads/> and then install:
+
+```bat
+rubyinstaller-devkit-3.2.2-1-x64.exe /silent /currentuser /noicons /dir=C:\aspera-cli
+```
+
+Installation without network:
+
+It is essentially the same procedure, but instead of retrieving files from internet, one copies the files from a machine with internet access, and then install from those archives:
+
+- Download the `exe` ruby installer from <https://rubyinstaller.org/downloads/>
+- Create an archive with necessary gems: <https://help.rubygems.org/kb/rubygems/installing-gems-with-no-network>
+
+  ```bat
+  gem install aspera-cli -N -i my_gems
+  ```
+
+  Zip the files `*.gem` from folder `repo/my_gems`
+
+- Download the SDK from: <https://ibm.biz/aspera_sdk>
+
+Create a Zip with all those files, and transfer to the target system.
+
+Then, on the target system:
+
+- Unzip the archive
+- Execute the installer:
+
+```bat
+rubyinstaller-devkit-3.2.2-1-x64.exe /silent /currentuser /noicons /dir=C:\aspera-cli
+```
+
+- Install the gems:
+
+```bat
+gem install --force --local *.gem
+```
+
+- install the SDK
+
+```bash
+ascli conf ascp install --sdk-url=file:///sdk.zip
+```
 
-#### macOS: pre-installed or `brew`
+> **Note:** An example of installation script is provided: [docs/install.bat](docs/install.bat)
 
-macOS 10.13+ (High Sierra) comes with a recent Ruby. So you can use it directly. You will need to install aspera-cli using `sudo` :
+#### macOS: Pre-installed or `brew`
+
+macOS 10.13+ (High Sierra) comes with a recent Ruby.
+So you can use it directly.
+You will need to install aspera-cli using `sudo` :
 
 ```bash
 sudo gem install aspera-cli
@@ -501,7 +561,7 @@ Alternatively, if you use [Homebrew](https://brew.sh/) already you can install R
 brew install ruby
 ```
 
-#### Linux: package
+#### Linux: Package
 
 If your Linux distribution provides a standard Ruby package, you can use it provided that the version supported.
 
@@ -521,9 +581,9 @@ If your Linux distribution provides a standard Ruby package, you can use it prov
 
 - Install packages needed to build native gems:
   
-    ```bash
-    dnf install -y make automake gcc gcc-c++ kernel-devel
-    ```
+  ```bash
+  dnf install -y make automake gcc gcc-c++ kernel-devel
+  ```
 
 - Enable the Ruby version you want:
 
@@ -545,7 +605,7 @@ apt install -y ruby ruby-dev rubygems ruby-json
 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)
+gem uninstall -axI $(ls $(gem env gemdir)/gems/|sed -e 's/-[^-]*$//'|sort -u)
 ```
 
 #### Other Unixes (AIX)
@@ -582,7 +642,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 transfer speed is not impacted (executed by `ascp` binary).
 
 ### <a id="the_gem"></a>`aspera-cli` gem
 
@@ -624,11 +684,11 @@ ascli conf ascp install
 If a local SDK installation is preferred instead of fetching from internet: one can specify the location of the SDK file:
 
 ```bash
-curl -Lso SDK.zip https://ibm.biz/aspera_sdk
+curl -Lso sdk.zip https://ibm.biz/aspera_sdk
 ```
 
 ```bash
-ascli conf ascp install --sdk-url=file:///SDK.zip
+ascli conf ascp install --sdk-url=file:///sdk.zip
 ```
 
 The format is: `file:///<path>`, where `<path>` can be either a relative path (not starting with `/`), or an absolute path.
@@ -673,7 +733,7 @@ ascli conf --show-config --fields=sdk_url
 - Download the SDK archive from that URL.
 
 ```bash
-curl -Lso SDK.zip https://ibm.biz/aspera_sdk
+curl -Lso sdk.zip https://ibm.biz/aspera_sdk
 ```
 
 - Transfer those 2 files to the target system
@@ -687,7 +747,7 @@ tar zxvf rvm-ascli.tgz
 
 source ~/.rvm/scripts/rvm
 
-ascli conf ascp install --sdk-url=file:///SDK.zip
+ascli conf ascp install --sdk-url=file:///sdk.zip
 ```
 
 - Add those lines to shell init (`.profile`)
@@ -717,10 +777,10 @@ The `aspera-cli` Gem provides a command line interface (CLI) which interacts wit
 - Transfer parameters can be altered by modification of [*transfer-spec*](#transferspec), this includes requiring multi-session
 - Allows transfers from products to products, essentially at node level (using the node transfer agent)
 - Supports FaspStream creation (using Node API)
-- Supports Watchfolder creation (using Node API)
+- Supports "Watchfolder" creation (using Node API)
 - Additional command plugins can be written by the user
 - Supports download of faspex and Aspera on Cloud "external" links
-- Supports "legacy" ssh based FASP transfers and remote commands (ascmd)
+- Supports "legacy" ssh based FASP transfers and remote commands (`ascmd`)
 
 Basic usage is displayed by executing:
 
@@ -763,11 +823,13 @@ So special character handling (quotes, spaces, env vars, ...) is handled by the
 
 #### Shell parsing for Windows
 
-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).
+MS Windows command line parsing is not handled by the shell (`cmd.exe`), not handled by the operating system, but it is handled by the executable.
+Typically, Windows executables use the [microsoft library for this parsing](https://learn.microsoft.com/en-us/cpp/cpp/main-function-command-line-args).
 
-As far as `ascli` is concerned: it is close to a Linux shell parsing.
+As far as `ascli` is concerned: the executable is Ruby.
+It has its own parsing algorithm, close to a Linux shell parsing.
 
-Thanksfully, `ascli` provides a command to check the value of an argument after parsing: `config echo`.
+Thankfully, `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:
@@ -790,9 +852,9 @@ The following examples give the same result on Windows:
    conf echo @json:"{\"url\":\"https://...\"}"
   ```
 
-On Windows, `cmd.exe` is typically used to start .
+More details: 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.
+Basically it handles I/O redirection (`<>|`), 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.
 
@@ -809,20 +871,21 @@ Ruby vaguely follows the Microsoft C/C++ parameter parsing rules.
 
 - space characters: split arguments (space, tab, newline)
 - backslash: `\` escape single special character
-- globbing characters: `*?[]{}` for file globbing
+- globing characters: `*?[]{}` for file globing
 - double quotes: `"`
 - single quotes: `'`
 
 #### Extended Values (JSON, Ruby, ...)
 
-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.
+Some of the `ascli` parameters are expected to be [Extended Values](#extended), i.e. not a simple `String`, but a complex structure (`Hash`, `Array`).
+Typically, the `@json:` modifier is used, it expects a [JSON](https://www.json.org/) string.
+JSON itself has some special syntax: for example `"` is used to enclose a `String`.
 
 #### Testing Extended Values
 
 In case of doubt of argument values after parsing, one can test using command `config echo`. `config echo` takes exactly **one** argument which can use the [Extended Value](#extended) syntax. Unprocessed command line arguments are shown in the error message.
 
-Example: The shell parses three arguments (as strings: `1`, `2` and `3`), so the additional two arguments are not processed by the `echo` command.
+Example: The shell parses three arguments (as `String`: `1`, `2` and `3`), so the additional two arguments are not processed by the `echo` command.
 
 ```bash
 ascli conf echo 1 2 3
@@ -993,27 +1056,29 @@ ascli conf echo @ruby:"{'title'=>ENV['MYTITLE']}" --format=json
 {"title":"Test \" ' & \\"}
 ```
 
-### Commands, Options, Positional Values
+### Commands, Options, Positional Arguments
 
-Command line arguments are the units of command line, as parsed by the shell, typically separated by spaces (and called "argv").
+Command line arguments are the units of command line typically separated by spaces (the `argv` of C).
+The tokenization of the command line is typically done by the shell, refer to the previous section [Command Line Parsing](#parsing).
 
 `ascli` considers three types of command line arguments:
 
 - Commands
 - Options
-- Positional Values
+- Positional Arguments
+
+For example:
 
 ```bash
 ascli command subcommand --option-name=VAL1 VAL2
 ```
 
-- executes *command*: `command subcommand`
-- with one *option*: `option_name`and its *value*: `VAL1`
-- the command has one additional mandatory *argument*: `VAL2`
+- executes **command**: `command subcommand`
+- with one **option**: `option_name` and its **value**: `VAL1`
+- the command has one additional **positional 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`.
+If the value of a command, option or argument is constrained by a fixed list of values, then it is possible to use a few of the first letters of the value, provided that it uniquely identifies the value.
+For example `ascli conf pre ov` is the same as `ascli config preset overview`.
 
 The value of options and arguments is evaluated with the [Extended Value Syntax](#extended).
 
@@ -1032,10 +1097,12 @@ ascli conf ascp info
 - `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.
+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.
+If wrong, or no command is provided when expected, an error message is displayed and the list of supported commands is displayed.
+
+Some sub-commands appear after entity selection, e.g. `ascli aoc admin res node do 8669 browse /`: `browse` is a sub-command of `node`.
 
 #### Options
 
@@ -1049,16 +1116,16 @@ All options, e.g. `--log-level=debug`, are command line arguments that:
 Exceptions:
 
 - some options accept a short form, e.g. `-Ptoto` is equivalent to `--preset=toto`, refer to the manual or `-h`.
-- some options (flags) don't take a value, e.g. `-r`
+- some options (flags) don't take a value, e.g. `-N`
 - the special option `--` stops option processing and is ignored, following command line arguments are taken as arguments, including the ones starting with a `-`. 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 `--`.
 
@@ -1066,14 +1133,14 @@ Options may have an (hardcoded) default value.
 
 Options can be placed anywhere on command line and evaluated in order.
 
-Options are typically either:
+Options are typically:
 
-- 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)
+- optional : to change the default behavior
+- mandatory : so they can be placed in a config file, for example: connection information
 
-The value for *any* options can come from the following locations (in this order, last value evaluated overrides previous value):
+The value for **any** options can come from the following locations (in this order, last value evaluated overrides previous value):
 
-- [Configuration file](#configfile).
+- [Configuration file](#configfile)
 - Environment variable
 - Command line
 
@@ -1081,27 +1148,37 @@ 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`
 
-#### Positional Values
+Parameters are typically designed as options if:
+
+- it is a mandatory parameters that would benefit from being set in a config file or environment variable
+- it is optional
 
-Positional Values are typically mandatory values for a command, such as entity creation data.
+#### Positional Arguments
 
-If a Positional Values begins with `-`, then either use the `@val:` syntax (see [Extended Values](#extended)), or use the `--` separator (see above).
+Positional Arguments are typically mandatory values for a command, such as entity creation data.
 
-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.
+It could also be designed as an option, but since it is mandatory and typically creation parameters need not be set in a configuration file, then it is better to use a positional argument, and not define specific options.
+
+The advantages of using a positional argument instead of an option for the same are that the command line is shorter(no option name, just the position) and the value is clearly mandatory.
 
 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.
 
+If a Positional Arguments begins with `-`, then either use the `@val:` syntax (see [Extended Values](#extended)), or use the `--` separator (see above).
+
+Very few positional arguments are optional, they are located at the end of the command line.
+
 ### Interactive Input
 
-Some options and parameters are mandatory and other optional. By default, the tool will ask for missing mandatory options or parameters for interactive execution.
+Some options and parameters are mandatory and other optional.
+By default, `ascli` will ask for missing mandatory options or parameters for interactive execution.
 
 The behavior can be controlled with:
 
-- --interactive=&lt;yes|no&gt; (default=yes if STDIN is a terminal, else no)
+- `--interactive=<yes|no>` (default=yes if STDIN is a terminal, else no)
   - yes : missing mandatory parameters/options are asked to the user
   - no : missing mandatory parameters/options raise an error message
-- --ask-options=&lt;yes|no&gt; (default=no)
+- `--ask-options=<yes|no>` (default=no)
   - optional parameters/options are asked to user
 
 ### Output
@@ -1126,8 +1203,8 @@ By default, result of type single_object and object_list are displayed using for
 The table style can be customized with parameter: `table_style` (horizontal, vertical and intersection characters) and is `:.:` by default.
 
 In a table format, when displaying "objects" (single, or list), by default, sub object are
-flattened (option `flat_hash`). So, object {"user":{"id":1,"name":"toto"}} will have attributes: user.id and user.name.
-Setting `flat_hash` to `false` will only display one field: "user" and value is the sub hash table.
+flattened (option `flat_hash`). So, object `{"user":{"id":1,"name":"toto"}}` will have attributes: `user.id` and `user.name`.
+Setting `flat_hash` to `false` will only display one field: `user` and value is the sub `Hash`.
 When in flatten mode, it is possible to filter fields by "dotted" field name.
 
 Object lists are displayed one per line, with attributes as columns. Single objects are transposed: one attribute per line.
@@ -1143,32 +1220,14 @@ The style of output can be set using the `format` parameter, supporting:
 - `yaml` : YAML
 - `csv` : Comma Separated Values
 
-#### <a id="option_select"></a>Option: `select`: Filter on columns values for `object_list`
-
-Table output can be filtered using the `select` parameter. Example:
-
-```bash
-ascli aoc admin res user list --fields=name,email,ats_admin --query=@json:'{"sort":"name"}' --select=@json:'{"ats_admin":true}'
-```
-
-```output
-+-------------------------------+----------------------------------+-----------+
-|             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
+#### 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.
+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's 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.
+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>`
 
@@ -1189,67 +1248,122 @@ The option `display` controls the level of output:
 By default, secrets are removed from output: option `show_secrets` defaults to `no`, unless `display` is `data`, to allows piping results.
 To hide secrets from output, set option `show_secrets` to `no`.
 
-#### Selection of output object properties
+#### Option: `fields`: Selection of output object properties
+
+By default, a table output will display one line per entry, and columns for each properties.
+Depending on the command, columns may include by default all properties, or only some selected properties.
+It is possible to define specific columns to be displayed, by setting the `fields` option.
+
+The `fields` option can be either a comma separated list, or an extended value array.
+
+Elements of the list can be:
+
+- `DEF` : default display of columns (that's the default, when not set)
+- `ALL` : all columns available
+- -property : remove property from the current list
+- property : add property to the current list
+- a ruby `RegEx` : using `@ruby:'/.../'`
+
+Examples:
+
+- `a,b,c` : the list of attributes specified as a comma separated list
+- `@json:'["a","b","c"]'` : Array extended value: same as above
+- `DEF,-a,b` : default property list, remove `a` and add `b`
+- `@ruby:'/^server/'` : Display all properties whose name begin with `server`
+
+#### <a id="option_select"></a>Option: `select`: Filter on columns values for `object_list`
+
+Table output can be filtered using option `select`.
+This parameter is either a `Hash` or `Proc`.
+The `Proc` takes as argument a line (`Hash`) in the table and is a Ruby lambda expression that returns `true` or `false`.
+
+Example:
+
+```bash
+ascli aoc admin res user list --fields=name,email,ats_admin --query=@json:'{"sort":"name"}' --select=@json:'{"ats_admin":true}'
+```
+
+```output
++-------------------------------+----------------------------------+-----------+
+|             name              |              email               | ats_admin |
++-------------------------------+----------------------------------+-----------+
+| John Curtis                   | john@example.com                 | true      |
+| Laurent Martin                | laurent@example.com              | true      |
++-------------------------------+----------------------------------+-----------+
+```
+
+> **Note:** `select` filters elements from the result of command, while the `query` parameters gives filtering parameters to the API when listing elements.
 
-By default, a table output will display one line per entry, and columns for each entries. Depending on the command, columns may include by default all properties, or only some selected properties. It is possible to define specific columns to be displayed, by setting the `fields` option to one of the following value:
+In above example, the same result is obtained with option:
 
-- DEF : default display of columns (that's the default, when not set)
-- ALL : all columns available
-- a,b,c : the list of attributes specified by the comma separated list
-- Array extended value: for instance, @json:'["a","b","c"]' same as above
-- +a,b,c : add selected properties to the default selection.
-- -a,b,c : remove selected properties from the default selection.
+```bash
+--select=@ruby:'->(i){i["ats_admin"]}'
+```
 
 ### <a id="extended"></a>Extended Value Syntax
 
-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).
+Most options and arguments are specified by a simple string (e.g. username or url).
+Sometime it is convenient to read a value from a file: for example read the PEM value of a private key, or a list of files.
+Some options expect a more complex value such as `Hash` or `Array`.
 
-The extended value syntax is:
+The **Extended Value** Syntax allows to specify such values and even read values from other sources than the command line itself.
+
+The syntax is:
 
 ```bash
-<0 or more decoders><nothing or some text value>
+<0 or more decoders><some text value or nothing>
 ```
 
-Decoders act like a function of value on right hand side.
-Decoders are recognized by the prefix: `@` and suffix `:`
+Decoders act like a function with its parameter on right hand side and are recognized by the prefix: `@` and suffix `:`
 
 The following decoders are supported:
 
 | 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` |
+| `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`
+| `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
+| `none`  | None      | Nil     | A null value
+| `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
+| extend  | String    | String  | evaluates embedded extended value syntax in string
+| `re`    | String    | Regexp  | Ruby Regular Expression (short for `@ruby:/.../`)
+| `ruby`  | String    | Any     | execute specified Ruby code
 | secret  | None      | String  | Ask password interactively (hides input)
-| stdin   | None      | String  | read from stdin (no value on right)
-| 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
+| `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`.
+| `yaml`  | String    | Any     | decode YAML
+| `zlib`  | String    | String  | un-compress data
 
 To display the result of an extended value, use the `config echo` command.
 
+The `extend` decoder is useful to evaluate embedded extended value syntax in a string.
+It expects a `@` to close the embedded extended value syntax.
+
+Example: Create a `Hash` value with the convenient `@json:` decoder:
+
+```bash
+ascli config echo @json:'{"key1":"value1","key2":"value2"}'
+```
+
 Example: read the content of the specified file, then, base64 decode, then unzip:
 
 ```bash
 ascli config echo @zlib:@base64:@file:myfile.dat
 ```
 
-Example: Create a value as a hash, with one key and the value is read from a file:
+Example: Create a `Hash` value with one key and the value is read from a file:
 
 ```bash
 ascli config echo @ruby:'{"token_verification_key"=>File.read("mykey.txt")}'
 ```
 
-Example: read a csv file and create a list of hash for bulk provisioning:
+Example: read a csv file and create an `Array` of `Hash` for bulk provisioning:
 
 ```bash
 cat test.csv
@@ -1274,37 +1388,49 @@ ascli config echo @csvt:@file:test.csv
 +------+---------------------+
 ```
 
-Example: create a hash and include values from preset named "config" of config file in this hash
+Example: create a `Hash` with values coming from a preset named `config`
 
 ```bash
-ascli config echo @incps:@json:'{"hello":true,"incps":["config"]}'
+ascli config echo @json:@extend:'{"hello":true,"version":"@preset:config.version@"}'
 ```
 
-```bash
-{"version"=>"0.9", "hello"=>true}
+```output
++---------+-----------+
+| key     | value     |
++---------+-----------+
+| hello   | true      |
+| version | 4.14.0    |
++---------+-----------+
 ```
 
-> **Note:** `@incps:@json:'{"incps":["config"]}'` or `@incps:@ruby:'{"incps"=>["config"]}'` are equivalent to: `@preset:config`
-
-### <a id="native"></a>Structured Value
-
-Some options and parameters expect a [Extended Value](#extended), i.e. a value more complex than a simple string. This is usually a Hash table or an Array, which could also contain sub structures.
+Example: Create a `Hash` from YAML provided as **heredoc**:
 
-For instance, a [*transfer-spec*](#transferspec) is expected to be a [Extended Value](#extended).
-
-Structured values shall be described using the [Extended Value Syntax](#extended).
-A convenient way to specify a [Extended Value](#extended) is to use the `@json:` decoder, and describe the value in JSON format. The `@ruby:` decoder can also be used. For an array of hash tables, the `@csvt:` decoder can be used.
+```bash
+ascli conf echo @yaml:@stdin: --format=json<<EOF
+key1: value1
+key2:
+- item1
+- item2
+key3:
+  key4: value4
+  key5: value5
+EOF
+```
 
-It is also possible to provide a [Extended Value](#extended) in a file using `@json:@file:<path>`
+```json
+{"key1":"value1","key2":["item1","item2"],"key3":{"key4":"value4","key5":"value5"}}
+```
 
 ### <a id="conffolder"></a>Configuration and Persistency Folder
 
-`ascli` configuration and other runtime files (token cache, file lists, persistency files, SDK) are stored `[config folder]`: `[User's home folder]/.aspera/ascli`.
+`ascli` configuration and other runtime files (token cache, file lists, persistency files, SDK) are stored by default in `[User's home folder]/.aspera/ascli`.
 
-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%`.
+> **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 :
+The configuration folder can be displayed using :
 
 ```bash
 ascli config folder
@@ -1314,7 +1440,7 @@ ascli config folder
 /Users/kenji/.aspera/ascli
 ```
 
-It can be overridden using the environment variable `ASCLI_HOME`.
+It can be overridden using option `home`.
 
 Example (Windows):
 
@@ -1326,11 +1452,17 @@ ascli config folder
 C:\Users\Kenji\.aspera\ascli
 ```
 
-When OAuth is used (AoC, Faspex4 api v4, Faspex5) `ascli` keeps a cache of generated bearer tokens in `[config folder]/persist_store` by default.
+When OAuth is used (AoC, Faspex4 api v4, Faspex5) `ascli` keeps a cache of generated bearer tokens in folder `persist_store` in configuration folder by default.
 Option `cache_tokens` (**yes**/no) allows to control if Oauth tokens are cached on file system, or generated for each request.
-The command `config flush_tokens` deletes all existing tokens.
+The command `config flush_tokens` clears that cache.
 Tokens are kept on disk for a maximum of 30 minutes (`TOKEN_CACHE_EXPIRY_SEC`) and garbage collected after that.
-Tokens that can be refreshed are refreshed. Else tokens are re-generated if expired.
+When a token has expired, then a new token is generated, either using a refresh_token if it is available, or by the default method.
+
+### Temporary files
+
+Some temporary files may be needed during runtime.
+The temporary folder may be specified with option: `temp_folder`.
+Temporary files are deleted at the end of execution unless option: `clean_temp` is set to `no`.
 
 ### <a id="configfile"></a>Configuration file
 
@@ -1371,7 +1503,7 @@ The command `set` allows setting individual options in a [option preset](#lprt).
 ascli config preset set demo_server password my_password_here
 ```
 
-The command `initialize`, like `update` allows to set several parameters at once, but it deletes an existing configuration instead of updating it, and expects a [*Structured Value*](#native).
+The command `initialize`, like `update` allows to set several parameters at once, but it deletes an existing configuration instead of updating it, and expects a [`Hash` Extended Value](#extended).
 
 ```bash
 ascli config preset initialize demo_server @json:'{"url":"ssh://demo.asperasoft.com:33001","username":"asperaweb","password":"my_pass_here","ts":{"precalculate_job_size":true}}'
@@ -1406,11 +1538,11 @@ ascli config preset over
 ascli config preset list
 ```
 
-#### <a id="lprtconf"></a>Special Option preset: config
+#### <a id="lprtconf"></a>Special Option preset: `config`
 
 This preset name is reserved and contains a single key: `version`. This is the version of `ascli` which created the file.
 
-#### <a id="lprtdef"></a>Special Option preset: default
+#### <a id="lprtdef"></a>Special Option preset: `default`
 
 This preset name is reserved and contains an array of key-value , where the key is the name of a plugin, and the value is the name of another preset.
 
@@ -1439,13 +1571,15 @@ Plugin `config` provides general commands for `ascli`:
 - Option preset, config file operations
 - wizard
 - vault
-- ascp
+- `ascp`
 
-The default configuration for `config` is read for any plugin invocation, this allows setting global options, such as `--log-level` or `--interactive`.
+The default preset 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.
+If set, it loads the options independently of the 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`)
+> **Note:** If no global default is set by the user, `ascli` will use `global_common_defaults` when setting global parameters (e.g. `conf ascp use`)
+>
+> **Note:** If you don't know the name of the global preset, you can use `GLOBAL` to refer to it.
 
 Show current default (global) Option preset (`config` plugin):
 
@@ -1455,13 +1589,14 @@ global_common_defaults
 ```
 
 ```bash
-ascli conf preset set global_common_defaults version_check_days 0
+ascli conf preset set GLOBAL version_check_days 0
 ```
 
-If the default global Option preset is not set:
+If the default global Option preset is not set, and you want to use a different name:
 
 ```bash
-ascli conf preset set default config global_common_defaults
+ascli conf preset set my_common_defaults version_check_days 0
+ascli conf preset set default config my_common_defaults
 ```
 
 #### Config sample commands
@@ -1473,45 +1608,76 @@ config ascp connect version 'Aspera Connect for Windows' download 'Windows Insta
 config ascp connect version 'Aspera Connect for Windows' list
 config ascp connect version 'Aspera Connect for Windows' open documentation
 config ascp errors
-config ascp info --sdk-folder=Tsdk_test_dir
-config ascp install --sdk-folder=Tsdk_test_dir
+config ascp info --sdk-folder=sdk_test_dir
+config ascp install
+config ascp install --sdk-folder=sdk_test_dir
 config ascp products list
+config ascp products use 'IBM Aspera Connect'
 config ascp show
 config ascp spec
+config ascp use /usr/bin/ascp
 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=https://node_simple.example.com/path
+config detect https://faspex4.example.com/path
+config detect https://faspex5.example.com/path
+config detect https://node.example.com/path
+config detect https://shares.example.com/path shares
+config detect my_org aoc
 config doc
 config doc transfer-parameters
-config echo 'hello'
 config echo @base64:SGVsbG8gV29ybGQK
 config echo @csvt:@stdin:
 config echo @env:USER
 config echo @lines:@stdin:
 config echo @list:,1,2,3
+config echo @secret:
 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:no_such_file
+config echo @uri:http://ifconfig.me
+config echo @uri:https://ifconfig.me
+config echo @vault:my_preset.password
 config echo @zlib:@stdin:
-config email_test --notif-to=my_recipient_email
-config export
+config echo hello
+config email_test --notify-to=my_email_external
 config flush_tokens
-config genkey mykey
-config plugin create mycommand T
+config folder
+config gem name
+config gem path
+config gem version
+config genkey my_key
+config genkey my_key 4096
+config initdemo
+config open
+config plugin create my_command
 config plugin list
-config proxy_check --fpac=@file:examples/proxy.pac https://eudemo.asperademo.com
-config wiz --url=https://my_aoc_org.ibmaspera.com --config-file=SAMPLE_CONFIG_FILE --pkeypath= --username=my_aoc_user_email --test-mode=yes
-config wiz --url=https://my_aoc_org.ibmaspera.com --config-file=SAMPLE_CONFIG_FILE --pkeypath= --username=my_aoc_user_email --test-mode=yes --use-generic-client=yes
+config preset delete conf_name
+config preset initialize conf_name @json:'{"p1":"v1","p2":"v2"}'
+config preset list
+config preset overview
+config preset set conf_name param value
+config preset set default shares conf_name
+config preset show conf_name
+config preset unset conf_name param
+config preset update conf_name --p1=v1 --p2=v2
+config proxy_check --fpac=@file:examples/proxy.pac https://eudemo.asperademo.com --proxy-credentials=@list:,user,pass
+config vault create my_label @json:'{"password":"my_password_here","description":"my secret"}'
+config vault delete my_label
+config vault list
+config vault show my_label
+config wizard https://console.example.com/path console
+config wizard https://faspex4.example.com/path faspex --username=test --password=test
+config wizard https://faspex5.example.com/path faspex5 --key-path=my_private_key
+config wizard https://node.example.com/path node --username=test --password=test
+config wizard https://orch.example.com/path orchestrator --username=test --password=test
+config wizard https://shares.example.com/path shares --username=test --password=test
+config wizard my_org aoc --key-path= --username=my_user_email
+config wizard my_org aoc --key-path= --username=my_user_email --use-generic-client=yes
 ```
 
 #### Format of file
 
-The configuration file is a hash in a YAML file. Example:
+The configuration file is a `Hash` in a YAML file. Example:
 
 ```yaml
 config:
@@ -1544,7 +1710,7 @@ The user may create as many [option presets](#lprt) as needed. For instance, a p
 
 Values in the configuration also follow the [Extended Value Syntax](#extended).
 
-Note: if the user wants to use the [Extended Value Syntax](#extended) inside the configuration file, using the `config preset update` command, the user shall use the `@val:` prefix. Example:
+> **Note:** if the user wants to use the [Extended Value Syntax](#extended) inside the configuration file, using the `config preset update` command, the user shall use the `@val:` prefix. Example:
 
 ```bash
 ascli config preset set my_aoc_org private_key @val:@file:"$HOME/.aspera/ascli/my_private_key"
@@ -1561,7 +1727,7 @@ my_aoc_org:
 
 So, the key file will be read only at execution time, but not be embedded in the configuration file.
 
-#### Options evaluation order
+#### Evaluation order of options
 
 Some options are global, some options are available only for some plugins. (the plugin is the first level command).
 
@@ -1569,7 +1735,7 @@ Options are loaded using this algorithm:
 
 - If option `--no-default` (or `-N`) is specified, then no default value is loaded for the plugin
 - else it looks for the name of the plugin as key in section `default`, the value is the name of the default [option preset](#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.
+- If option `--preset=<name or extended value hash>` is specified (or `-Pxxxx`), this reads the [option preset](#lprt) specified from the configuration file, or if the value is a `Hash`, it uses it as options values.
 - Environment variables are evaluated
 - Command line options are evaluated
 
@@ -1602,13 +1768,25 @@ Example: Define options using command line:
 ascli -N --url=_url_here_ --password=my_password_here --username=_name_here_ node --show-config
 ```
 
-Example: Define options using a hash:
+Example: Define options using a `Hash`:
 
 ```bash
 ascli -N --preset=@json:'{"url":"_url_here_","password":"my_password_here","username":"_name_here_"}' node --show-config
 ```
 
-#### Shares Examples
+#### Wizard
+
+The wizard is a command that asks the user for information and creates a [option preset](#lprt) with the provided information.
+
+It takes an optional argument: the URL of the application, and an **option**: `query` which allows limiting the detection to a given plugin.
+
+The simplest invocation is:
+
+```bash
+ascli config wizard
+```
+
+#### Example of configuration for a plugin
 
 For Faspex, Shares, Node (including ATS, Aspera Transfer Service), Console,
 only username/password and url are required (either on command line, or from config file).
@@ -1666,7 +1844,7 @@ A more secure option is to retrieve values from a secret vault.
 
 The vault is used with options `vault` and `vault_password`.
 
-`vault` defines the vault to be used and shall be a Hash, example:
+`vault` defines the vault to be used and shall be a `Hash`, example:
 
 ```json
 {"type":"system","name":"ascli"}
@@ -1728,14 +1906,17 @@ A passwords can be saved in clear in a [option preset](#lprt) together with othe
 Example:
 
 ```bash
-`ascli` conf preset update myconf --url=... --username=... --password=...
+ascli conf preset update myconf --url=... --username=... --password=...
 ```
 
 For a more secure storage one can do:
 
 ```bash
-`ascli` conf preset update myconf --url=... --username=... --password=@val:@vault:myconf.password
-`ascli` conf vault create myconf @json:'{"password":"my_password_here"}'
+ascli conf preset update myconf --url=... --username=... --password=@val:@vault:myconf.password
+```
+
+```bash
+ascli conf vault create myconf @json:'{"password":"my_password_here"}'
 ```
 
 > **Note:** use `@val:` in front of `@vault:` so that the extended value is not evaluated.
@@ -1764,7 +1945,7 @@ The format expected for private keys is [PEM](https://en.wikipedia.org/wiki/Priv
 
 #### `ascli` for key generation
 
-The generated key is of type RSA, by default: 4096 bit.
+The generated key is of type `RSA`, by default: **4096** bit.
 For convenience, the public key is also extracted with extension `.pub`.
 The key is not passphrase protected.
 
@@ -1772,6 +1953,14 @@ The key is not passphrase protected.
 ascli config genkey ${PRIVKEYFILE} 4096
 ```
 
+> **Note:** `ascli` uses the `openssl` library.
+
+To display the version of **openssl** used in `ascli`:
+
+```bash
+ascli config echo @ruby:OpenSSL::OPENSSL_VERSION
+```
+
 #### `ssh-keygen`
 
 Both private and public keys are generated, option `-N` is for passphrase.
@@ -1782,7 +1971,7 @@ 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:
+To generate a private key with a passphrase the following can be used on any system:
 
 ```bash
 openssl genrsa -passout pass:_passphrase_here_ -out ${PRIVKEYFILE} 4096
@@ -1808,83 +1997,99 @@ mv ${PRIVKEYFILE}.with_des ${PRIVKEYFILE}
 
 ### <a id="certificates"></a>SSL CA certificate bundle
 
-`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:
+To display trusted certificate store locations:
 
 ```bash
-ascli conf echo @ruby:'[OpenSSL::X509::DEFAULT_CERT_FILE,OpenSSL::X509::DEFAULT_CERT_DIR]'
+ascli --show-config --fields=cert_stores
 ```
 
-Ruby's default values can be overridden by env vars: `SSL_CERT_FILE` and `SSL_CERT_DIR`.
+To modify the locations of certificate store, use option `cert_stores`.
+If you use this option, then default locations are removed, but they can be added using special value `DEF`.
+The value can be either an `Array`, or successive options.
 
-`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.
+`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..).
+Ruby's default values can be overridden using env vars: `SSL_CERT_FILE` and `SSL_CERT_DIR`.
 
-To update `ascli` trusted root certificates, just update your system's root certificates or use env vars specified here above.
+> **Note:** One can display those values like this:
 
-### Plugins
+```bash
+ascli conf echo @ruby:OpenSSL::X509::DEFAULT_CERT_DIR --format=text
+ascli conf echo @ruby:OpenSSL::X509::DEFAULT_CERT_FILE --format=text
+```
 
-`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".
+`ascp` also needs to validate certificates when using **WSS**.
 
-Available plugins can be found using command:
+> **Note:** `ascli` overrides the default hardcoded location used by `ascp` for WSS (e.g. on macOS: `/Library/Aspera/ssl`) and uses the same locations as specified in `cert_stores` (using `-i` switch of `ascp`). Hardcoded locations can be found using:
 
 ```bash
-ascli conf plugin list
+strings $(ascli conf ascp info --fields=ascp)|grep -w OPENSSLDIR
 ```
 
-```output
-+--------------+--------------------------------------------------------+
-| plugin       | path                                                   |
-+--------------+--------------------------------------------------------+
-| shares       | ..../aspera-cli/lib/aspera/cli/plugins/shares.rb       |
-| node         | ..../aspera-cli/lib/aspera/cli/plugins/node.rb         |
-...
-+--------------+--------------------------------------------------------+
+or
+
+```bash
+ascli conf ascp info --fields=openssldir
 ```
 
-#### <a id="createownplugin"></a>Create your own plugin
+To update trusted root certificates for `ascli`:
+Display the trusted certificate store locations used by `ascli`.
+Typically done by updating the system's root certificate store.
 
-By default plugins are looked-up in folders specified by (multi-value) option `plugin_folder`:
+An up-to-date version of the certificate bundle can be retrieved with:
 
 ```bash
-ascli --show-config --select=@json:'{"key":"plugin_folder"}'
+ascli conf echo @uri:https://curl.haxx.se/ca/cacert.pem --format=text
 ```
 
-You can create the skeleton of a new plugin like this:
+To download that certificate store:
 
 ```bash
-ascli conf plugin create foo .
+ascli conf echo @uri:https://curl.haxx.se/ca/cacert.pem --format=text > /tmp/cacert.pem
 ```
 
-```output
-Created ./foo.rb
+Then, use this store by setting the  option `` or env var export SSL_CERT_FILE
+
+To trust a certificate (e.g. self-signed), provided that the `CN` is correct, save the certificate to a file:
+
+```bash
+ascli conf remote_certificate https://localhost:9092 > myserver.pem
 ```
 
+> **Note:** the saved certificate shows the CN as first line.
+
+Then, use this file as certificate store (e.g. here, Node API):
+
 ```bash
-ascli --plugin-folder=. foo
+ascli conf echo @uri:https://localhost:9092/ping --cert-stores=myserver.pem
 ```
 
-#### <a id="plugins"></a>Plugins: Application URL and Authentication
+### Image and video thumbnails
+
+`ascli` can display thumbnails for images and videos in the terminal.
+This is available with the `thumbnail` command of `node` when using **gen4/access key** API.
+It's also available when using the `show` command of `preview` plugin.
 
-`ascli` comes with several Aspera application plugins.
+The following options can be specified in the option `query`:
 
-REST APIs of Aspera legacy applications (Aspera Node, Faspex, Shares, Console, Orchestrator, Server) use simple username/password authentication: HTTP Basic Authentication.
+| option     | description |
+|------------|-------------|
+| text       | display text instead of image (Bool) |
+| double     | display double text resolution (half characters) (Bool) |
+| font_ratio | Font height/width ratio in terminal (Float) |
 
-Those are using options:
+### <a id="graphical"></a>Graphical Interactions: Browser and Text Editor
+
+Some actions may require the use of a graphical tool:
 
-- url
-- username
-- password
+- a browser for Aspera on Cloud authentication (web auth method)
+- a text editor for configuration file edition
 
-Those can be provided using command line, parameter set, env var, see section above.
+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 :
 
-Aspera on Cloud relies on Oauth, refer to the [Aspera on Cloud](#aoc) section.
+- `--ui=graphical` forces a graphical environment, a browser will be opened for URLs or a text editor for file edition.
+- `--ui=text` forces a text environment, the URL or file path to open is displayed on terminal.
 
 ### Logging, Debugging
 
@@ -1921,16 +2126,21 @@ When `ascli` is used interactively in a shell, the shell itself will usually log
 
 ### Learning Aspera Product APIs (REST)
 
-`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.
+`ascli` uses mainly REST APIs to interact with Aspera applications.
 
-In order to get traces of execution, use argument : `--log-level=debug`
+To get traces of execution, with dump of API calls, use argument : `--log-level=debug`.
+
+To display HTTP/S traffic set option `log_level` to `trace2`: `--log-level=trace2`.
+It will display the exact content of HTTP requests and responses.
 
 ### <a id="http_options"></a>HTTP socket parameters
 
-If the server does not provide a valid certificate, use option: `--insecure=yes`.
+To ignore SSL certificate for any address/port, use option: `insecure`, i.e. `--insecure=yes`.
+To ignore SSL certificate for specific address/port, use option `ignore_certificate`, set to an `Array` of URL for which certificate will be ignored (only the address and port are matched), e.g. `--ignore-certificate=@list:,https://127.0.0.1:9092`
+
+> **Note:** Ignoring certificate also applies to `ascp`'s wss.
 
-HTTP socket parameters can be adjusted using option `http_options`:
+HTTP connection parameters (not `ascp` wss) can be adjusted using option `http_options`:
 
 | parameter            | default |
 |----------------------|---------|
@@ -1939,9 +2149,9 @@ HTTP socket parameters can be adjusted using option `http_options`:
 | `open_timeout`       | 60      |
 | `keep_alive_timeout` | 2       |
 
-Values are in set *seconds* and can be of type either integer or float.
+Values are in set **seconds** and can be of type either integer or float.
 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).
+For a full list, 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.
 
@@ -1951,34 +2161,22 @@ Example:
 ascli aoc admin res package list --http-options=@json:'{"read_timeout":10.0}'
 ```
 
-### <a id="graphical"></a>Graphical Interactions: Browser and Text Editor
-
-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 `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.
-- `--ui=text` forces a text environment, the URL or file path to open is displayed on terminal.
-
 ### Proxy
 
 There are several types of network connections, each of them use a different mechanism to define a (forward) **proxy**:
 
-- Ruby HTTP: REST and HTTPGW client
-- Legacy Aspera HTTP/S Fallback
+- Ruby HTTP: REST and HTTP Gateway client
+- Legacy Aspera HTTP/S Fallback and `ascp` wss
 - Aspera FASP
 
 Refer to the following sections.
 
-### Proxy for REST and HTTPGW
+### Proxy for REST and HTTP Gateway
 
 There are two possibilities to define an HTTP proxy to be used when Ruby HTTP is used.
 
-The `http_proxy` environment variable (**lower case**, preferred) can be set to the URL of the proxy, e.g. `http://myproxy.org.net:3128`.
+The `http_proxy` environment variable (**lower case**, preferred) can be set to the URL of the proxy.
+E.g. `http://myproxy.org.net:3128`.
 Refer to [Ruby find proxy](https://rubyapi.org/3.0/o/uri/generic#method-i-find_proxy).
 
 > **Note:** Ruby expects a URL and `myproxy.org.net:3128` alone is **not** accepted.
@@ -2177,7 +2375,7 @@ ascli config ascp connect version 'Aspera Connect for Mac Intel' download enclos
 ```
 
 ```output
-Time: 00:00:02 =========================================================== 100% 27766 KB/sec Time: 00:00:02
+Time: 00:00:02 ============================================= 100% 27766 KB/sec Time: 00:00:02
 Downloaded: IBMAsperaConnectInstaller-3.11.2.63.dmg
 ```
 
@@ -2192,7 +2390,7 @@ 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
-- [`node`](#agt_node) : use of an Aspera Transfer Node (potentially *remote*).
+- [`node`](#agt_node) : use of an Aspera Transfer Node (potentially **remote**).
 - [`httpgw`](#agt_httpgw) : use of an Aspera HTTP Gateway
 - [`trsdk`](#agt_trsdk) : use of Aspera Transfer SDK
 
@@ -2200,7 +2398,7 @@ There are currently 3 agents, set with option `transfer`:
 For example, a node agent executing an "upload", or "package send" operation
 will effectively push files to the related server from the agent node.
 
-`ascli` standardizes on the use of a [*transfer-spec*](#transferspec) instead of *native* `ascp` options to provide parameters for a transfer session, as a common method for those three Transfer Agents.
+`ascli` standardizes on the use of a [*transfer-spec*](#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.
 
@@ -2209,23 +2407,23 @@ Specific options for agents are provided with option `transfer_info`, cumulative
 The `direct` agent directly executes a local `ascp`.
 This is the default agent for `ascli`.
 This is equivalent to option `--transfer=direct`.
-`ascli` will detect locally installed Aspera products, including SDK, and use `ascp` from that component.
+`ascli` will search locally installed Aspera products, including SDK, and use `ascp` from that component.
 Refer to section [FASP](#client).
 
 The `transfer_info` option accepts the following optional parameters to control multi-session, Web Socket Session and Resume policy:
 
 | Name                 | Type  | Description |
 |----------------------|-------|-------------|
-| wss                  | Bool  | Web Socket Session<br/>Enable use of web socket session in case it is available<br/>Default: true |
-| ascp_args            | Array | Array of strings with native ascp arguments<br/>Use this instead of deprecated `EX_ascp_args`.<br/>Default: [] |
-| spawn_timeout_sec    | Float | Multi session<br/>Verification time that `ascp` is running<br/>Default: 3 |
-| spawn_delay_sec      | Float | Multi session<br/>Delay between startup of sessions<br/>Default: 2 |
-| multi_incr_udp       | Bool  | Multi Session<br/>Increment UDP port on multi-session<br/>If true, each session will have a different UDP port starting at `fasp_port` (or default 33001)<br/>Else, each session will use `fasp_port` (or `ascp` default)<br/>Default: true |
-| resume               | Hash  | Resume<br/>parameters<br/>See below |
-| resume.iter_max      | int   | Resume<br/>Max number of retry on error<br/>Default: 7 |
-| resume.sleep_initial | int   | Resume<br/>First Sleep before retry<br/>Default: 2 |
-| resume.sleep_factor  | int   | Resume<br/>Multiplier of sleep period between attempts<br/>Default: 2 |
-| resume.sleep_max     | int   | Resume<br/>Default: 60 |
+| `wss`                | Bool  | Web Socket Session<br/>Enable use of web socket session in case it is available<br/>Default: true |
+| `ascp_args`          | Array | Array of strings with native `ascp` arguments<br/>Use this instead of deprecated `EX_ascp_args`.<br/>Default: [] |
+| `spawn_timeout_sec`  | Float | Multi session<br/>Verification time that `ascp` is running<br/>Default: 3 |
+| `spawn_delay_sec`    | Float | Multi session<br/>Delay between startup of sessions<br/>Default: 2 |
+| `multi_incr_udp`     | Bool  | Multi Session<br/>Increment UDP port on multi-session<br/>If true, each session will have a different UDP port starting at `fasp_port` (or default 33001)<br/>Else, each session will use `fasp_port` (or `ascp` default)<br/>Default: true |
+| `resume`             | Hash  | Resume<br/>parameters<br/>See below |
+| `resume.iter_max`    | int   | Resume<br/>Max number of retry on error<br/>Default: 7 |
+| `resume.sleep_initial` | int   | Resume<br/>First Sleep before retry<br/>Default: 2 |
+| `resume.sleep_factor`  | int   | Resume<br/>Multiplier of sleep period between attempts<br/>Default: 2 |
+| `resume.sleep_max`   | int   | Resume<br/>Default: 60 |
 
 In case of transfer interruption, the agent will **resume** a transfer up to `iter_max` time.
 Sleep between iterations is:
@@ -2234,7 +2432,7 @@ Sleep between iterations is:
 max( sleep_max , sleep_initial * sleep_factor ^ (iter_index-1) )
 ```
 
-Some transfer errors are considered "retryable" (e.g. timeout) and some other not (e.g. wrong password).
+Some transfer errors are considered **retry-able** (e.g. timeout) and some other not (e.g. wrong password).
 The list of known protocol errors and retry level can be listed:
 
 ```bash
@@ -2252,8 +2450,14 @@ ascli ... --transfer-info=@json:'{"spawn_delay_sec":2.5,"multi_incr_udp":false}'
 But it is preferred to use the option `transfer_info` with parameter `ascp_args`.
 
 This can be useful to activate logging using option `-L` of `ascp`.
-For example the option `--transfer-info=@json:'{"ascp_args":["-DDL-"]}'` will activate debug level 2 for `ascp` (`DD`), and display those logs on the terminal (`-`).
-This is useful if the transfer fails.
+For example, to activate debug level 2 for `ascp` (`DD`), and display those logs on the terminal (`-`):
+
+```bash
+--transfer-info=@json:'{"ascp_args":["-DDL-"]}'
+```
+
+This is useful to debug if a transfer fails.
+
 To store `ascp` logs in file `aspera-scp-transfer.log` in a folder, use `--transfer-info=@json:'{"ascp_args":["-L","/path/to/folder"]}'`.
 
 > **Note:** When transfer agent [`direct`](#agt_direct) is used, the list of files to transfer is provided to `ascp` using either `--file-list` or `--file-pair-list` and a file list (or pair) file generated in a temporary folder. (unless `--file-list` or `--file-pair-list` is provided using `transfer_info` parameter `ascp_args`).
@@ -2356,26 +2560,34 @@ Parameters provided in option `transfer_info` are:
 | 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 :
-`--transfer-info=@json:'{"url":"https://...","username":"_user_here_","password":"my_password_here"}'`
+
+```bash
+--transfer-info=@preset:_name_here_
+```
+
+or be specified using the extended value syntax :
+
+```bash
+--transfer-info=@json:'{"url":"https://...","username":"_user_here_","password":"my_password_here"}'
+```
 
 If `transfer_info` is not specified and a default node has been configured (name in `node` for section `default`) then this node is used by default.
 
-If the `password` value begins with `Bearer` then the `username` is expected to be an access key and the parameter `root_id` is mandatory and specifies the root file id on the node. It can be either the access key's root file id, or any authorized file id underneath it.
+If the `password` value begins with `Bearer` then the `username` is expected to be an access key and the parameter `root_id` is mandatory and specifies the root file id on the node.
+It can be either the access key's root file id, or any authorized file id underneath it.
 
 #### <a id="agt_httpgw"></a>HTTP Gateway
 
-If it possible to send using a HTTP gateway, in case FASP is not allowed.
+If it possible to send using a HTTP gateway, in case use of FASP is not allowed.
 
 Parameters provided in option `transfer_info` are:
 
 | Name                   | Type   | Description                           |
 |------------------------|--------|---------------------------------------|
 | 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  |
+| upload_chunk_size      | int    | Size in bytes of chunks for upload<br/>Default: 64000    |
+| api_version            | string | v1 or v2, for force use of version<br/>Default: v2       |
+| synchronous            | bool   | wait for each message acknowledgment<br/>Default: false  |
 
 Example:
 
@@ -2388,8 +2600,17 @@ ascli faspex package recv 323 --transfer=httpgw --transfer-info=@json:'{"url":"h
 #### <a id="agt_trsdk"></a>Transfer SDK
 
 Another possibility is to use the Transfer SDK daemon (`asperatransferd`).
+Set option `transfer` to `trsdk`.
+
+Options for `transfer_info` are:
+
+| Name     | Type   | Description |
+|----------|--------|-------------|
+| url      | string | IP address and port listened by the daemon</br>Mandatory<br/>Default: grpc://127.0.0.1:0 |
+| external | bool   | Use external daemon, do not start<br/>Default: false |
+| keep     | bool   | Keep the daemon running after exiting `ascli`<br/>Default: false |
 
-By default it will listen on local port `55002` on `127.0.0.1`.
+> **Note:** if port zero is specified in the URL, then the daemon will listen on a random available port.
 
 The gem `grpc` was removed from dependencies, as it requires compilation of a native part.
 So, to use the Transfer SDK you should install this gem:
@@ -2399,11 +2620,17 @@ gem install grpc
 ```
 
 On Windows the compilation may fail for various reasons (3.1.1):
+
 <!-- spellchecker: disable -->
+
 - `cannot find -lx64-ucrt-ruby310`
+
    &rarr; copy the file `[Ruby main dir]\lib\libx64-ucrt-ruby310.dll.a` to `[Ruby main dir]\lib\libx64-ucrt-ruby310.a` (remove the dll extension)
+  
 - `conflicting types for 'gettimeofday'`
+
   &rarr; edit the file `[Ruby main dir]/include/ruby-[version]/ruby/win32.h` and change the signature of `gettimeofday` to `gettimeofday(struct timeval *, void *)` ,i.e. change `struct timezone` to `void`
+
 <!-- spellchecker: enable -->
 
 ### <a id="transferspec"></a>Transfer Specification
@@ -2417,13 +2644,12 @@ All parameters necessary for this transfer are described in a [*transfer-spec*](
 - file list
 - etc...
 
-`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).
+`ascli` builds the [*transfer-spec*](#transferspec) internally as a `Hash`.
+It is not necessary to provide additional parameters on the command line for this transfer.
 
 It is possible to modify or add any of the supported [*transfer-spec*](#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.
+The `ts` option accepts a [`Hash` Extended Value](#extended) containing one or several [*transfer-spec*](#transferspec) parameters.
+Multiple `ts` options on command line are cumulative, and the `Hash` value is deeply merged.
 To remove a (deep) key from transfer spec, set the value to `null`.
 
 > **Note:** Default transfer spec values can be displayed with command: `config ascp info --flat-hash=no` under field `ts`.
@@ -2460,96 +2686,109 @@ Columns:
 - D=Direct (local `ascp` execution)
 - N=Node API
 - C=Connect Client
+- T=Transfer SDK
+- H=HTTP Gateway
 
 `ascp` argument or environment variable is provided in description.
 
 Fields with EX_ prefix are extensions to transfer agent [`direct`](#agt_direct). (only in `ascli`).
 
-| Field | Type | D | N | C | Description |
-| ----- | ---- | - | - | - | ----------- |
-| 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}) |
-| cipher_allowed | string | Y | Y | Y | returned by node API. Valid literals include "aes-128" and "none". |
-| content_protection | string | Y | Y | Y | Enable client-side encryption at rest. (CSEAR, content protection)<br/>Allowed values: encrypt, decrypt<br/>(--file-crypt {enum}) |
-| content_protection_password | string | Y | Y | Y | Specifies CSEAR password. (content protection)<br/>(env:ASPERA_SCP_FILEPASS) |
-| cookie | string | Y | Y | Y | Metadata for transfer specified by application<br/>(env:ASPERA_SCP_COOKIE) |
-| create_dir | bool | Y | Y | Y | Specifies whether to create new directories.<br/>(-d) |
-| delete_before_transfer | bool | Y | Y | Y | Before transfer, delete files that exist at the destination but not at the source.<br/>The source and destination arguments must be directories that have matching names.<br/>Objects on the destination that have the same name but different type or size as objects<br/>on the source are not deleted.<br/>(--delete-before-transfer) |
-| delete_source | bool | Y | Y | &nbsp; | Remove SRC files after transfer success<br/>(--remove-after-transfer) |
-| destination_root | string | Y | Y | Y | Destination root directory. |
-| dgram_size | int | Y | Y | Y | UDP datagram size in bytes<br/>(-Z {int}) |
-| direction | string | Y | Y | Y | Direction of transfer (on client side)<br/>Allowed values: send, receive<br/>(--mode (conversion){enum}) |
-| exclude_newer_than | int | Y | &nbsp; | &nbsp; | skip src files with mtime > arg<br/>(--exclude-newer-than {int}) |
-| exclude_older_than | int | Y | &nbsp; | &nbsp; | skip src files with mtime < arg<br/>(--exclude-older-than {int}) |
-| fasp_port | int | Y | Y | Y | Specifies fasp (UDP) port.<br/>(-O {int}) |
-| file_checksum | string | Y | Y | &nbsp; | Enable checksum reporting for transferred files by specifying the hash to use.<br/>Allowed values: sha-512, sha-384, sha-256, sha1, md5, none |
-| http_fallback | bool<br/>string | Y | Y | Y | When true(1), attempts to perform an HTTP transfer if a FASP transfer cannot be performed.<br/>(-y (conversion){bool}|{string}) |
-| http_fallback_port | int | Y | &nbsp; | &nbsp; | Specifies http port when no cipher is used<br/>(-t {int}) |
-| https_fallback_port | int | Y | Y | Y | Specifies https port when cipher is used<br/>(-t {int}) |
-| lock_min_rate | bool | Y | Y | Y | &nbsp; |
-| lock_min_rate_kbps | bool | Y | Y | Y | &nbsp; |
-| lock_rate_policy | bool | Y | Y | Y | &nbsp; |
-| lock_target_rate | bool | Y | Y | Y | &nbsp; |
-| lock_target_rate_kbps | bool | Y | Y | Y | &nbsp; |
-| min_rate_cap_kbps | int | Y | Y | Y | &nbsp; |
-| min_rate_kbps | int | Y | Y | Y | Set the minimum transfer rate in kilobits per second.<br/>(-m {int}) |
-| move_after_transfer | string | Y | Y | &nbsp; | The relative path to which the files will be moved after the transfer at the source side. Available as of 3.8.0.<br/>(--move-after-transfer {string}) |
-| multi_session | int | Y | Y | Y | Use multi-session transfer. max 128.<br/>Each participant on one host needs an independent UDP (-O) port.<br/>Large files are split between sessions only when transferring with resume_policy=none.<br/> |
-| multi_session_threshold | int | Y | Y | &nbsp; | Split files across multiple ascp sessions if their size in bytes is greater than or equal to the specified value.<br/>(0=no file is split)<br/>(--multi-session-threshold {int}) |
-| overwrite | string | Y | Y | Y | Overwrite destination files with the source files of the same name.<br/>Allowed values: never, always, diff, older, diff+older<br/>(--overwrite {enum}) |
-| password | string | &nbsp; | Y | &nbsp; | Password for local Windows user when transfer user associated with node api user is not the same as the one running asperanoded.<br/>Allows impersonating the transfer user and have access to resources (e.g. network shares).<br/>Windows only, node api only. |
-| paths | array | Y | Y | Y | Array of path to the source (required) and a path to the destination (optional). |
-| precalculate_job_size | bool | Y | Y | Y | Specifies whether to precalculate the job size.<br/>(--precalculate-job-size) |
-| preserve_access_time | bool | Y | Y | Y | (--preserve-access-time) |
-| preserve_acls | string | Y | &nbsp; | &nbsp; | Preserve access control lists.<br/>Allowed values: none, native, metafile<br/>(--preserve-acls {enum}) |
-| preserve_creation_time | bool | Y | Y | Y | (--preserve-creation-time) |
-| preserve_file_owner_gid | bool | Y | &nbsp; | &nbsp; | Preserve the group ID for a file owner<br/>(--preserve-file-owner-gid) |
-| preserve_file_owner_uid | bool | Y | &nbsp; | &nbsp; | Preserve the user ID for a file owner<br/>(--preserve-file-owner-uid) |
-| preserve_modification_time | bool | Y | Y | Y | (--preserve-modification-time) |
-| preserve_remote_acls | string | Y | &nbsp; | &nbsp; | Preserve remote access control lists.<br/>Allowed values: none, native, metafile<br/>(--remote-preserve-acls {enum}) |
-| preserve_source_access_time | bool | Y | &nbsp; | &nbsp; | Preserve the time logged for when the source file was accessed<br/>(--preserve-source-access-time) |
-| preserve_times | bool | Y | Y | Y | (--preserve-times) |
-| proxy | string | Y | &nbsp; | &nbsp; | Specify the address of the Aspera high-speed proxy server.<br/>dnat(s)://[user[:password]@]server:port<br/>Default ports for DNAT and DNATS protocols are 9091 and 9092.<br/>Password, if specified here, overrides the value of environment variable ASPERA_PROXY_PASS.<br/>(--proxy {string}) |
-| rate_policy | string | Y | Y | Y | The transfer rate policy to use when sharing bandwidth.<br/>Allowed values: low, fair, high, fixed<br/>(--policy {enum}) |
-| rate_policy_allowed | string | &nbsp; | &nbsp; | Y | Specifies most aggressive rate policy that is allowed.<br/>Returned by node API.<br/>Allowed values: low, fair, high, fixed |
-| remote_host | string | Y | Y | Y | IP or fully qualified domain name of the remote server<br/>(--host {string}) |
-| remote_password | string | Y | Y | Y | SSH session password<br/>(env:ASPERA_SCP_PASS) |
-| remote_user | string | Y | Y | Y | Remote user. Default value is "xfer" on node or connect.<br/>(--user {string}) |
-| remove_after_transfer | bool | Y | Y | &nbsp; | Remove SRC files after transfer success<br/>(--remove-after-transfer) |
-| remove_empty_directories | bool | Y | Y | &nbsp; | Specifies whether to remove empty directories.<br/>(--remove-empty-directories) |
-| remove_empty_source_directory | bool | Y | &nbsp; | &nbsp; | Remove empty source subdirectories and remove the source directory itself, if empty<br/>(--remove-empty-source-directory) |
-| remove_skipped | bool | Y | Y | Y | Must also have remove_after_transfer set to true, Defaults to false, if true, skipped files will be removed as well.<br/>(--remove-skipped) |
-| resume_policy | string | Y | Y | Y | If a transfer is interrupted or fails to finish, resume without re-transferring the whole files.<br/>Allowed values: none, attrs, sparse_csum, full_csum<br/>(-k (conversion){enum}) |
-| retry_duration | string<br/>int | &nbsp; | Y | Y | Specifies how long to wait before retrying transfer. (e.g. "5min") |
-| source_root | string | Y | Y | Y | Path to be prepended to each source path.<br/>This is either a conventional path or it can be a URI but only if there is no root defined.<br/>(--source-prefix64 (conversion){string}) |
-| 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-----\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}) |
-| tags | hash | Y | Y | Y | Metadata for transfer as JSON<br/>(--tags64 (conversion){hash}) |
-| target_rate_cap_kbps | int | &nbsp; | &nbsp; | Y | Returned by upload/download_setup node API. |
-| target_rate_kbps | int | Y | Y | Y | Specifies desired speed for the transfer.<br/>(-l {int}) |
-| target_rate_percentage | string | Y | Y | Y | &nbsp; |
-| title | string | &nbsp; | Y | Y | Title of the transfer |
-| token | string | Y | Y | Y | Authorization token: Bearer, Basic or ATM (Also arg -W)<br/>(env:ASPERA_SCP_TOKEN) |
-| 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}) |
+| Field | Type | D | N | C | T | H | Description |
+| ----- | ---- | - | - | - | - | - | ----------- |
+| apply_local_docroot | bool | Y | &nbsp; | &nbsp; | &nbsp; | &nbsp; | Apply local docroot to source paths.<br/>(--apply-local-docroot) |
+| authentication | string | &nbsp; | &nbsp; | Y | &nbsp; | &nbsp; | value=token for SSH bypass keys, else password asked if not provided.<br/>(<ignored>) |
+| cipher | string | Y | Y | 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}) |
+| cipher_allowed | string | Y | Y | Y | Y | Y | returned by node API. Valid literals include "aes-128" and "none".<br/>(<ignored>) |
+| compression | int | &nbsp; | &nbsp; | &nbsp; | &nbsp; | &nbsp; | ascp4 only, 0 / 1?<br/>(<ignored>) |
+| content_protection | string | Y | Y | Y | Y | Y | Enable client-side encryption at rest. (CSEAR, content protection)<br/>Allowed values: encrypt, decrypt<br/>(--file-crypt {enum}) |
+| content_protection_password | string | Y | Y | Y | Y | Y | Specifies CSEAR password. (content protection)<br/>(env:ASPERA_SCP_FILEPASS) |
+| cookie | string | Y | Y | Y | Y | Y | Metadata for transfer specified by application<br/>(env:ASPERA_SCP_COOKIE) |
+| create_dir | bool | Y | Y | Y | Y | Y | Specifies whether to create new directories.<br/>(-d) |
+| delete_before_transfer | bool | Y | Y | Y | Y | Y | Before transfer, delete files that exist at the destination but not at the source.<br/>The source and destination arguments must be directories that have matching names.<br/>Objects on the destination that have the same name but different type or size as objects<br/>on the source are not deleted.<br/>(--delete-before-transfer) |
+| delete_source | bool | Y | Y | &nbsp; | &nbsp; | &nbsp; | Remove SRC files after transfer success<br/>(--remove-after-transfer) |
+| destination_root | string | Y | Y | Y | Y | Y | Destination root directory.<br/>(<special>) |
+| destination_root_id | string | &nbsp; | &nbsp; | &nbsp; | &nbsp; | &nbsp; | The file ID of the destination root directory.<br/>Required when using Bearer token auth for the destination node.<br/>(<ignored>) |
+| dgram_size | int | Y | Y | Y | Y | Y | UDP datagram size in bytes<br/>(-Z {int}) |
+| direction | string | Y | Y | Y | Y | Y | Direction of transfer (on client side)<br/>Allowed values: send, receive<br/>(--mode (conversion){enum}) |
+| exclude_newer_than | int | Y | &nbsp; | &nbsp; | &nbsp; | &nbsp; | skip src files with mtime > arg<br/>(--exclude-newer-than {int}) |
+| exclude_older_than | int | Y | &nbsp; | &nbsp; | &nbsp; | &nbsp; | skip src files with mtime < arg<br/>(--exclude-older-than {int}) |
+| fasp_port | int | Y | Y | Y | Y | Y | Specifies fasp (UDP) port.<br/>(-O {int}) |
+| fasp_url | string | &nbsp; | &nbsp; | &nbsp; | &nbsp; | &nbsp; | Only used in Faspex.<br/>(<ignored>) |
+| file_checksum | string | Y | Y | &nbsp; | &nbsp; | &nbsp; | Enable checksum reporting for transferred files by specifying the hash to use.<br/>Allowed values: sha-512, sha-384, sha-256, sha1, md5, none<br/>(<ignored>) |
+| http_fallback | bool<br/>string | Y | Y | Y | Y | Y | When true(1), attempts to perform an HTTP transfer if a FASP transfer cannot be performed.<br/>(-y (conversion){bool}|{string}) |
+| http_fallback_port | int | Y | &nbsp; | &nbsp; | &nbsp; | &nbsp; | Specifies http port when no cipher is used<br/>(-t {int}) |
+| https_fallback_port | int | Y | Y | Y | Y | Y | Specifies https port when cipher is used<br/>(-t {int}) |
+| keepalive | bool | Y | &nbsp; | &nbsp; | &nbsp; | &nbsp; | The session is running in persistent session mode.<br/>(--keepalive) |
+| lock_min_rate | bool | Y | Y | Y | Y | Y | TODO: remove ?<br/>(<ignored>) |
+| lock_min_rate_kbps | bool | &nbsp; | &nbsp; | Y | &nbsp; | &nbsp; | If true, lock the minimum transfer rate to the value set for min_rate_kbps.<br/>If false, users can adjust the transfer rate up to the value set for target_rate_cap_kbps.<br/>(<ignored>) |
+| lock_rate_policy | bool | &nbsp; | &nbsp; | Y | &nbsp; | &nbsp; | If true, lock the rate policy to the default value.<br/>(<ignored>) |
+| lock_target_rate | bool | Y | Y | Y | Y | Y | TODO: remove ?<br/>(<ignored>) |
+| lock_target_rate_kbps | bool | Y | Y | Y | Y | Y | If true, lock the target transfer rate to the default value set for target_rate_kbps.<br/>If false, users can adjust the transfer rate up to the value set for target_rate_cap_kbps.<br/>(<ignored>) |
+| min_rate_cap_kbps | int | Y | Y | Y | Y | Y | The highest minimum rate that an incoming transfer can request, in kilobits per second.<br/>Client minimum rate requests that exceed the minimum rate cap are ignored.<br/>The default value of unlimited applies no cap to the minimum rate. (Default: 0)<br/>(<ignored>) |
+| min_rate_kbps | int | Y | Y | Y | Y | Y | Set the minimum transfer rate in kilobits per second.<br/>(-m {int}) |
+| move_after_transfer | string | Y | Y | &nbsp; | &nbsp; | &nbsp; | The relative path to which the files will be moved after the transfer at the source side. Available as of 3.8.0.<br/>(--move-after-transfer {string}) |
+| multi_session | int | Y | Y | Y | Y | Y | Use multi-session transfer. max 128.<br/>Each participant on one host needs an independent UDP (-O) port.<br/>Large files are split between sessions only when transferring with resume_policy=none.<br/><br/>(<special>) |
+| multi_session_threshold | int | Y | Y | &nbsp; | &nbsp; | &nbsp; | Split files across multiple ascp sessions if their size in bytes is greater than or equal to the specified value.<br/>(0=no file is split)<br/>(--multi-session-threshold {int}) |
+| obfuscate_file_names | bool | &nbsp; | &nbsp; | &nbsp; | &nbsp; | Y | HTTP Gateway obfuscates file names when set to true.<br/>(<ignored>) |
+| overwrite | string | Y | Y | Y | Y | Y | Overwrite destination files with the source files of the same name.<br/>Allowed values: never, always, diff, older, diff+older<br/>(--overwrite {enum}) |
+| password | string | &nbsp; | Y | &nbsp; | &nbsp; | &nbsp; | Password for local Windows user when transfer user associated with node api user is not the same as the one running asperanoded.<br/>Allows impersonating the transfer user and have access to resources (e.g. network shares).<br/>Windows only, node api only.<br/>(<ignored>) |
+| paths | array | Y | Y | Y | Y | Y | Array of path to the source (required) and a path to the destination (optional).<br/>(<special>) |
+| precalculate_job_size | bool | Y | Y | Y | Y | Y | Specifies whether to precalculate the job size.<br/>(--precalculate-job-size) |
+| preserve_access_time | bool | Y | Y | Y | Y | Y | Preserve the source-file access timestamps at the destination.<br/>Because source access times are updated by the transfer operation,<br/>the timestamp that is preserved is the one just before to the transfer.<br/>(--preserve-access-time) |
+| preserve_acls | string | Y | &nbsp; | &nbsp; | &nbsp; | &nbsp; | Preserve access control lists.<br/>Allowed values: none, native, metafile<br/>(--preserve-acls {enum}) |
+| preserve_creation_time | bool | Y | Y | Y | Y | Y | (Windows only) Preserve source-file creation timestamps at the destination.<br/>Only Windows systems retain information about creation time.<br/>If the destination is not a Windows computer, this option is ignored.<br/>(--preserve-creation-time) |
+| preserve_extended_attrs | string | &nbsp; | &nbsp; | &nbsp; | &nbsp; | &nbsp; | Preserve the extended attributes.<br/>Allowed values: none, native, metafile<br/>(--preserve-xattrs {enum}) |
+| preserve_file_owner_gid | bool | Y | &nbsp; | &nbsp; | &nbsp; | &nbsp; | Preserve the group ID for a file owner<br/>(--preserve-file-owner-gid) |
+| preserve_file_owner_uid | bool | Y | &nbsp; | &nbsp; | &nbsp; | &nbsp; | Preserve the user ID for a file owner<br/>(--preserve-file-owner-uid) |
+| preserve_modification_time | bool | Y | Y | Y | Y | Y | Set the modification time, the last time a file or directory was modified (written), of a transferred file<br/>to the modification of the source file or directory.<br/>Preserve source-file modification timestamps at the destination.<br/>(--preserve-modification-time) |
+| preserve_remote_acls | string | Y | &nbsp; | &nbsp; | &nbsp; | &nbsp; | Preserve remote access control lists.<br/>Allowed values: none, native, metafile<br/>(--remote-preserve-acls {enum}) |
+| preserve_source_access_time | bool | Y | &nbsp; | &nbsp; | &nbsp; | &nbsp; | Preserve the time logged for when the source file was accessed<br/>(--preserve-source-access-time) |
+| preserve_times | bool | &nbsp; | Y | &nbsp; | &nbsp; | &nbsp; | Preserve file timestamps.<br/>(--preserve-times) |
+| proxy | string | Y | &nbsp; | &nbsp; | &nbsp; | &nbsp; | Specify the address of the Aspera high-speed proxy server.<br/>dnat(s)://[user[:password]@]server:port<br/>Default ports for DNAT and DNATS protocols are 9091 and 9092.<br/>Password, if specified here, overrides the value of environment variable ASPERA_PROXY_PASS.<br/>(--proxy {string}) |
+| rate_policy | string | Y | Y | Y | Y | Y | The transfer rate policy to use when sharing bandwidth.<br/>Allowed values: low, fair, high, fixed<br/>(--policy {enum}) |
+| rate_policy_allowed | string | &nbsp; | &nbsp; | Y | &nbsp; | &nbsp; | Specifies most aggressive rate policy that is allowed.<br/>Returned by node API.<br/>Allowed values: low, fair, high, fixed<br/>(<ignored>) |
+| read_threads | int | &nbsp; | &nbsp; | &nbsp; | &nbsp; | &nbsp; | ascp4 only<br/>(<ignored>) |
+| remote_access_key | string | &nbsp; | &nbsp; | &nbsp; | &nbsp; | &nbsp; | The access key ID of the access key that was used to construct the bearer token that is used to authenticate to the remote node.<br/>(<ignored>) |
+| remote_host | string | Y | Y | Y | Y | Y | IP or fully qualified domain name of the remote server<br/>(--host {string}) |
+| remote_password | string | Y | Y | Y | Y | Y | SSH session password<br/>(env:ASPERA_SCP_PASS) |
+| remote_user | string | Y | Y | Y | Y | Y | Remote user. Default value is "xfer" on node or connect.<br/>(--user {string}) |
+| remove_after_transfer | bool | Y | Y | &nbsp; | &nbsp; | &nbsp; | Remove SRC files after transfer success<br/>(--remove-after-transfer) |
+| remove_empty_directories | bool | Y | Y | &nbsp; | &nbsp; | &nbsp; | Specifies whether to remove empty directories.<br/>(--remove-empty-directories) |
+| remove_empty_source_directory | bool | Y | &nbsp; | &nbsp; | &nbsp; | &nbsp; | Remove empty source subdirectories and remove the source directory itself, if empty<br/>(--remove-empty-source-directory) |
+| remove_skipped | bool | Y | Y | Y | &nbsp; | &nbsp; | Must also have remove_after_transfer set to true, Defaults to false, if true, skipped files will be removed as well.<br/>(--remove-skipped) |
+| resume_policy | string | Y | Y | Y | Y | Y | If a transfer is interrupted or fails to finish, resume without re-transferring the whole files.<br/>Allowed values: none, attrs, sparse_csum, full_csum<br/>(-k (conversion){enum}) |
+| retry_duration | string<br/>int | &nbsp; | Y | Y | &nbsp; | &nbsp; | Specifies how long to wait before retrying transfer. (e.g. "5min")<br/>(<ignored>) |
+| source_root | string | Y | Y | Y | Y | Y | Path to be prepended to each source path.<br/>This is either a conventional path or it can be a URI but only if there is no root defined.<br/>(--source-prefix64 (conversion){string}) |
+| source_root_id | string | &nbsp; | Y | &nbsp; | &nbsp; | &nbsp; | The file ID of the source root directory. Required when using Bearer token auth for the source node.<br/>(<ignored>) |
+| src_base | string | Y | Y | &nbsp; | &nbsp; | &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_args | string | &nbsp; | &nbsp; | &nbsp; | &nbsp; | &nbsp; | Array of arguments to pass to SSH. Use with caution.<br/>(<ignored>) |
+| ssh_port | int | Y | Y | Y | Y | Y | Specifies SSH (TCP) port. Default: local:22, other:33001<br/>(-P {int}) |
+| ssh_private_key | string | Y | &nbsp; | &nbsp; | &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; | &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 | Y | Y | Check it against server SSH host key fingerprint<br/>(--check-sshfp {string}) |
+| symlink_policy | string | Y | Y | Y | Y | Y | Handle source side symbolic links<br/>Allowed values: follow, copy, copy+force, skip<br/>(--symbolic-links {enum}) |
+| tags | hash | Y | Y | Y | Y | Y | Metadata for transfer as JSON<br/>(--tags64 (conversion){hash}) |
+| target_rate_cap_kbps | int | &nbsp; | &nbsp; | Y | &nbsp; | &nbsp; | Returned by upload/download_setup node API.<br/>(<ignored>) |
+| target_rate_kbps | int | Y | Y | Y | Y | Y | Specifies desired speed for the transfer.<br/>(-l {int}) |
+| target_rate_percentage | string | Y | Y | Y | Y | Y | TODO: remove ?<br/>(<ignored>) |
+| title | string | &nbsp; | Y | Y | &nbsp; | &nbsp; | Title of the transfer<br/>(<ignored>) |
+| token | string | Y | Y | Y | Y | Y | Authorization token: Bearer, Basic or ATM (Also arg -W)<br/>(env:ASPERA_SCP_TOKEN) |
+| use_ascp4 | bool | Y | Y | &nbsp; | &nbsp; | &nbsp; | specify version of protocol<br/>(<special>) |
+| use_system_ssh | string | &nbsp; | &nbsp; | &nbsp; | &nbsp; | &nbsp; | TODO, comment...<br/>(<ignored>) |
+| write_threads | int | &nbsp; | &nbsp; | &nbsp; | &nbsp; | &nbsp; | ascp4 only<br/>(<ignored>) |
+| wss_enabled | bool | Y | Y | Y | Y | Y | Server has Web Socket service enabled<br/>(<special>) |
+| wss_port | int | Y | Y | Y | Y | Y | TCP port used for websocket service feed<br/>(<special>) |
+| EX_ascp_args | array | Y | &nbsp; | &nbsp; | &nbsp; | &nbsp; | DEPRECATED: (4.13) Use option transfer_info.ascp_args<br/>Add native command line arguments to ascp<br/>(<special>) |
+| EX_at_rest_password | string | Y | &nbsp; | &nbsp; | &nbsp; | &nbsp; | DEPRECATED: (4.13) Use standard spec parameter: content_protection_password<br/>Content protection password<br/>(env:ASPERA_SCP_FILEPASS) |
+| EX_file_list | string | Y | &nbsp; | &nbsp; | &nbsp; | &nbsp; | DEPRECATED: (4.14) Use command line file list, or option transfer_info.ascp_args<br/>source file list<br/>(<special>) |
+| EX_file_pair_list | string | Y | &nbsp; | &nbsp; | &nbsp; | &nbsp; | DEPRECATED: (4.14) Use command line file pair list, or option transfer_info.ascp_args<br/>source file pair list<br/>(<special>) |
+| EX_http_proxy_url | string | Y | &nbsp; | &nbsp; | &nbsp; | &nbsp; | DEPRECATED: (4.14) TODO, use proxy option ?<br/>Specify the proxy server address used by HTTP Fallback<br/>(-x {string}) |
+| EX_http_transfer_jpeg | int | Y | &nbsp; | &nbsp; | &nbsp; | &nbsp; | DEPRECATED: (4.14) Use option transfer_info.ascp_args<br/>HTTP transfers as JPEG file<br/>(-j {int}) |
+| EX_license_text | string | Y | &nbsp; | &nbsp; | &nbsp; | &nbsp; | DEPRECATED: (4.14) Use env var ASPERA_SCP_LICENSE<br/>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; | &nbsp; | &nbsp; | DEPRECATED: (4.14) Use option transfer_info.ascp_args<br/>no read source<br/>(--no-read) |
+| EX_no_write | bool | Y | &nbsp; | &nbsp; | &nbsp; | &nbsp; | DEPRECATED: (4.14) Use option transfer_info.ascp_args<br/>no write on destination<br/>(--no-write) |
+| EX_proxy_password | string | Y | &nbsp; | &nbsp; | &nbsp; | &nbsp; | DEPRECATED: (4.14) Use env var ASPERA_PROXY_PASS<br/>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; | &nbsp; | &nbsp; | DEPRECATED: (4.14) Use option transfer_info.ascp_args<br/>Use public key authentication for SSH and specify the private key file paths<br/>(-i {array}) |
 
 #### Destination folder for transfers
 
@@ -2658,7 +2897,7 @@ ascli server upload --src-type=pair ~/Documents/Samples/200KB.1 /Upload/sample1
 
 #### Source directory structure on destination
 
-This section is not specific to `ascli`, it is `ascp` behaviour.
+This section is not specific to `ascli` it is `ascp` behavior.
 
 The transfer destination is normally expected to designate a destination folder.
 
@@ -2669,7 +2908,7 @@ But there is one exception: The destination specifies the new item name when the
 - 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`.
+For this reason it is recommended to set `create_dir` to `true` for consistent behavior 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.
 
@@ -2702,9 +2941,15 @@ If transfer spec has a `src_base`, it has the side effect that the simple source
 
 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`
+- 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)
+- 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.
 
@@ -2726,7 +2971,7 @@ Multi-session is directly supported by the node daemon.
 --ts=@json:'{"multi_session":5,"multi_session_threshold":1,"resume_policy":"none"}'
 ```
 
-Note: `resume_policy` set to `attr` may cause problems: `none` or `sparse_csum` shall be preferred.
+> **Note:** `resume_policy` set to `attr` may cause problems: `none` or `sparse_csum` shall be preferred.
 
 `ascli` starts multiple `ascp` for Multi-session using `direct` agent.
 
@@ -2774,6 +3019,14 @@ Example: parameter to download a faspex package and decrypt on the fly
 --ts=@json:'{"precalculate_job_size":true}'
 ```
 
+### Transfer progress bar
+
+File transfer operations are monitored and a progress bar is displayed on the terminal if option `progress_bar` (`Bool`) is set to `yes` (default if the output is a terminal).
+
+The same progress bar is used for any type of transfer, using `ascp`, server to server, using HTTPS, etc...
+
+To display the native progress bar of `ascp`, use `--progress-bar=no --transfer-info=@json:'{"quiet":false}'`.
+
 ### <a id="scheduler"></a>Scheduler
 
 It is useful to configure automated scheduled execution.
@@ -2787,7 +3040,7 @@ It can be configured:
 
 - 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 powershell function [`scheduletasks`](https://learn.microsoft.com/en-us/powershell/module/scheduledtasks)
 
 - Using `taskschd.msc` (UI)
 
@@ -2819,7 +3072,7 @@ crontab<<EOF
 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.
+> **Note:** The logging options are kept here in the cron file instead of conf file to allow execution on command line with output on command line.
 
 ### <a id="locking"></a>Locking for exclusive execution
 
@@ -2857,37 +3110,32 @@ 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).
 ```
 
-### "Proven&ccedil;ale"
+### "Proven&ccedil;al"
 
-`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`
-, some are provided om shared libraries and must be activated. (e.g. using `trapd`)
+`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 called **PVCL** (from **Proven&ccedil;al**, a restaurant located in Sophia Antipolis).
+Several **PVCL** adapters are available, one is embedded in `ascp`, the others are provided in shared libraries and must be activated.
 
-The list of supported *PVCL* adapters can be retrieved with command:
+The list of supported **PVCL** adapters can be retrieved with command:
 
 ```bash
-ascli conf ascp info
+ascli conf ascp info --fields=@re:'^pvcl'
 ```
 
 ```output
-+--------------------+-----------------------------------------------------------+
-| key                | value                                                     |
-+--------------------+-----------------------------------------------------------+
------8<-----snip-----8<-----
-| product_name       | IBM Aspera SDK                                            |
-| product_version    | 4.0.1.182389                                              |
-| process            | pvcl                                                      |
-| shares             | pvcl                                                      |
-| noded              | pvcl                                                      |
-| faux               | pvcl                                                      |
-| file               | pvcl                                                      |
-| stdio              | pvcl                                                      |
-| stdio-tar          | pvcl                                                      |
-+--------------------+-----------------------------------------------------------+
+process v1
+shares v1
+noded v1
+faux v1
+file v1
+stdio v1
+stdio-tar v1
 ```
 
 Here we can see the adapters: `process`, `shares`, `noded`, `faux`, `file`, `stdio`, `stdio-tar`.
 
-Those adapters can be used wherever a file path is used in `ascp` including configuration. They act as a pseudo "drive".
+Those adapters can be used wherever a file path is used in `ascp` including configuration.
+They act as a pseudo "drive".
 
 The simplified format is:
 
@@ -2895,7 +3143,8 @@ The simplified format is:
 <adapter>:///<sub file path>?<arg1>=<val1>&...
 ```
 
-One of the adapters, used in this manual, for testing, is `faux`. It is a pseudo file system allowing generation of file data without actual storage (on source or destination).
+One of the adapters, used in this manual, for testing, is `faux`.
+It is a pseudo file system allowing generation of file data without actual storage (on source or destination).
 
 ### <a id="faux_testing"></a>`faux:` for testing
 
@@ -2917,7 +3166,7 @@ where:
 - `filename` is the name that will be assigned to the file on the destination
 - `filesize` is the number of bytes that will be sent (in decimal).
 
-Note: characters `?` and `&` are shell special characters (wildcard and background), so `faux` file specification on command line should be protected (using quotes or `\`). If not, the shell may give error: `no matches found` or equivalent.
+> **Note:** characters `?` and `&` are shell special characters (wildcard and background), so `faux` file specification on command line should be protected (using quotes or `\`). If not, the shell may give error: `no matches found` or equivalent.
 
 For all sizes, a suffix can be added (case insensitive) to the size: k,m,g,t,p,e (values are power of 2, e.g. 1M is 2<sup>20</sup>, i.e. 1 mebibyte, not megabyte). The maximum allowed value is 8*2<sup>60</sup>. Very large `faux` file sizes (petabyte range and above) will likely fail due to lack of destination storage unless destination is `faux://`.
 
@@ -2961,7 +3210,7 @@ Filenames generated are of the form: `<file>_<00000 ... count>_<filesize>`
 
 Examples:
 
-- Upload 20 gibibytes of random data to file myfile to directory /Upload
+- Upload 20 gibibyte of random data to file `myfile` to directory /Upload
 
 ```bash
 ascli server upload faux:///myfile\?20g --to-folder=/Upload
@@ -2984,7 +3233,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.14.0)
+        ascli -- a command line tool for Aspera Applications (v4.15.0)
 
 SYNOPSIS
         ascli COMMANDS [OPTIONS] [ARGS]
@@ -2997,7 +3246,6 @@ DESCRIPTION
         source repo: https://github.com/IBM/aspera-cli
 
 ENVIRONMENT VARIABLES
-        ASCLI_HOME config folder, default: $HOME/.aspera/ascli
         Any option can be set as an environment variable, refer to the manual
 
 COMMANDS
@@ -3007,7 +3255,7 @@ COMMANDS
 OPTIONS
         Options begin with a '-' (minus), and value is provided on command line.
         Special values are supported beginning with special prefix @pfx:, where pfx is one of:
-        base64, csvt, env, file, json, lines, list, path, ruby, secret, stdin, uri, val, zlib, preset, incps, vault
+        val, base64, csvt, env, file, uri, json, lines, list, none, path, re, ruby, secret, stdin, yaml, zlib, extend, preset, vault
         Dates format is 'DD-MM-YY HH:MM:SS', or 'now' or '-<num>h'
 
 ARGS
@@ -3018,8 +3266,8 @@ OPTIONS: global
         --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)
+        --fields=VALUE               Comma separated list of: fields, or ALL, or DEF (String, Array, Regexp, Proc)
+        --select=VALUE               Select only some items in lists: column, value (Hash, Proc)
         --table-style=VALUE          Table display style
         --flat-hash=ENUM             Display deep values as additional keys: no, [yes]
         --transpose-single=ENUM      Single object fields output vertically: no, [yes]
@@ -3027,89 +3275,93 @@ OPTIONS: global
     -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
+        --log-level=ENUM             Log level: trace2, trace1, 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 (Hash)
-        --insecure=ENUM              Do not validate HTTPS certificate: [no], yes
+        --lock-port=VALUE            Prevent dual execution of a command, e.g. in cron (Integer)
         --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]
+        --clean-temp=ENUM            Cleanup temporary files on exit: no, [yes]
+        --pid-file=VALUE             Write process identifier to file, delete on exit (String)
 
 COMMAND: config
-SUBCOMMANDS: ascp check_update coffee detect documentation echo email_test file flush_tokens folder gem genkey initdemo open plugin preset proxy_check smtp_settings vault wizard
+SUBCOMMANDS: ascp check_update coffee detect documentation echo email_test file flush_tokens folder gem genkey initdemo open plugins preset proxy_check remote_certificate smtp_settings throw vault wizard
 OPTIONS:
+        --home=VALUE                 Home folder for tool (String)
+        --config-file=VALUE          Path to YAML file with preset configuration
+        --secret=VALUE               Secret for access keys
+        --vault=VALUE                Vault for secrets (Hash)
+        --vault-password=VALUE       Vault password
         --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)
+        --value=VALUE                Value for create, update, list filter (Hash) (deprecated: (4.14) Use positional value for create/modify or option: query for list/delete)
         --property=VALUE             Name of property to set (modify operation)
-        --id=VALUE                   Resource identifier (deprecated: Use identifier after verb (modify,delete,show))
+        --id=VALUE                   Resource identifier (deprecated: (4.14) Use positional identifier after verb (modify,delete,show))
         --bulk=ENUM                  Bulk operation (only some): [no], yes
         --bfail=ENUM                 Bulk operation error handling: no, [yes]
-        --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
+    -P, --presetVALUE                Load the named option preset from current config file
+        --version-check-days=VALUE   Period in days to check new version (zero to disable)
+        --plugin-folder=VALUE        Folder where to find additional plugins
         --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]
         --test-mode=ENUM             Wizard: skip private key check step: [no], yes
-    -P, --presetVALUE                Load the named option preset from current config file
-        --pkeypath=VALUE             Wizard: path to private key for JWT
+        --key-path=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 (Hash)
-        --fpac=VALUE                 Proxy auto configuration script
-        --proxy-credentials=VALUE    HTTP proxy credentials (Array with user and password)
-        --secret=VALUE               Secret for access keys
-        --vault=VALUE                Vault for secrets
-        --vault-password=VALUE       Vault password
         --sdk-url=VALUE              URL to get SDK
         --sdk-folder=VALUE           SDK folder path
-        --notif-to=VALUE             Email recipient for notification of transfers
-        --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
+        --progress-bar=ENUM          Display progress bar: [no], yes
+        --smtp=VALUE                 SMTP configuration (Hash)
+        --notify-to=VALUE            Email recipient for notification of transfers
+        --notify-template=VALUE      Email ERB template for notification of transfers
+        --insecure=ENUM              Do not validate any HTTPS certificate: [no], yes
+        --ignore-certificate=VALUE   List of HTTPS url where to no validate certificate (Array)
+        --cert-stores=VALUE          List of folder with trusted certificates (Array, String)
+        --http-options=VALUE         Options for HTTP/S socket (Hash)
+        --cache-tokens=ENUM          Save and reuse Oauth tokens: no, [yes]
+        --fpac=VALUE                 Proxy auto configuration script
+        --proxy-credentials=VALUE    HTTP proxy credentials (user and password) (Array)
         --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 (Hash)
-        --progress=ENUM              Type of progress bar: none, [native], multi
 
 
 COMMAND: shares
 SUBCOMMANDS: admin files health
 OPTIONS:
-        --url=VALUE                  URL of application, e.g. https://org.asperafiles.com
+        --url=VALUE                  URL of application, e.g. https://faspex.example.com/aspera/faspex
         --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 ssync stream sync transfer upload watch_folder
+SUBCOMMANDS: access_keys api_details asperabrowser async basic_token bearer_token browse central delete download events health http_node_download info license mkdir mkfile mklink rename search service slash space ssync stream sync transfer upload watch_folder
 OPTIONS:
-        --url=VALUE                  URL of application, e.g. https://org.asperafiles.com
+        --url=VALUE                  URL of application, e.g. https://faspex.example.com/aspera/faspex
         --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
         --default-ports=ENUM         Use standard FASP ports or get from node api (gen4): no, [yes]
+        --root-id=VALUE              File id of top folder if using bearer tokens
+        --sync-info=VALUE            Information for sync instance and sessions (Hash)
 
 
 COMMAND: orchestrator
 SUBCOMMANDS: health info plugins processes workflow
 OPTIONS:
-        --url=VALUE                  URL of application, e.g. https://org.asperafiles.com
+        --url=VALUE                  URL of application, e.g. https://faspex.example.com/aspera/faspex
         --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
+        --result=VALUE               Specify result value as: 'work_step:parameter'
+        --synchronous=ENUM           Wait for completion: [no], yes
         --ret-style=ENUM             How return type is requested in api: header, [arg], ext
         --auth-style=ENUM            Authentication type: arg_pass, [head_basic], apikey
 
@@ -3117,7 +3369,7 @@ OPTIONS:
 COMMAND: bss
 SUBCOMMANDS: subscription
 OPTIONS:
-        --url=VALUE                  URL of application, e.g. https://org.asperafiles.com
+        --url=VALUE                  URL of application, e.g. https://faspex.example.com/aspera/faspex
         --username=VALUE             Username to log in
         --password=VALUE             User's password
 
@@ -3125,7 +3377,7 @@ OPTIONS:
 COMMAND: alee
 SUBCOMMANDS: entitlement
 OPTIONS:
-        --url=VALUE                  URL of application, e.g. https://org.asperafiles.com
+        --url=VALUE                  URL of application, e.g. https://faspex.example.com/aspera/faspex
         --username=VALUE             Username to log in
         --password=VALUE             User's password
 
@@ -3145,19 +3397,18 @@ OPTIONS:
 COMMAND: faspex5
 SUBCOMMANDS: admin bearer_token gateway health packages postprocessing shared_folders user version
 OPTIONS:
-        --url=VALUE                  URL of application, e.g. https://org.asperafiles.com
+        --url=VALUE                  URL of application, e.g. https://faspex.example.com/aspera/faspex
         --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, link, web, [jwt]
+        --auth=ENUM                  OAuth type of authentication: boot, web, [jwt]
         --private-key=VALUE          OAuth JWT RSA private key PEM value (prefix file path with @file:)
         --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
+        --group-type=ENUM            Type of shared box: [shared_inboxes], workgroups
 
 
 COMMAND: cos
@@ -3175,21 +3426,21 @@ OPTIONS:
 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
+        --url=VALUE                  URL of application, e.g. https://faspex.example.com/aspera/faspex
         --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
+        --remote-source=VALUE        Remote source for package send (id or %name:)
+        --storage=VALUE              Faspex local storage definition (for browsing source)
         --recipient=VALUE            Use if recipient is a dropbox (with *)
         --box=ENUM                   Package box: [inbox], archive, sent
 
 
 COMMAND: preview
-SUBCOMMANDS: check events scan test trevents
+SUBCOMMANDS: check events scan show test trevents
 OPTIONS:
-        --url=VALUE                  URL of application, e.g. https://org.asperafiles.com
+        --url=VALUE                  URL of application, e.g. https://faspex.example.com/aspera/faspex
         --username=VALUE             Username to log in
         --password=VALUE             User's password
         --skip-format=ENUM           Skip this preview format (multiple possible): png, mp4
@@ -3198,7 +3449,7 @@ OPTIONS:
         --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
+        --base=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
@@ -3222,58 +3473,40 @@ OPTIONS:
         --clips-length=VALUE         Mp4: clips: length in seconds of each clips
 
 
-COMMAND: sync
-SUBCOMMANDS: admin start
-OPTIONS:
-        --sync-info=VALUE            Information for sync instance and sessions (Hash)
-        --sync-session=VALUE         Name of session to use for admin commands. default: first in parameters
-
-
 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
+        --url=VALUE                  URL of application, e.g. https://faspex.example.com/aspera/faspex
         --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
+        --scope=VALUE                OAuth scope for AoC API calls
         --redirect-uri=VALUE         OAuth API client redirect URI
         --private-key=VALUE          OAuth JWT RSA private key PEM value (prefix file path with @file:)
-        --scope=VALUE                OAuth scope for AoC API calls
         --passphrase=VALUE           RSA private key passphrase
-        --workspace=VALUE            Name of workspace
-        --name=VALUE                 Resource name (prefer to use keyword name)
-        --link=VALUE                 Public link to shared resource
+        --workspace=VALUE            Name of workspace (String, NilClass)
         --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]
 
-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 ssync stream sync transfer upload watch_folder
-OPTIONS:
-        --validator=VALUE            Identifier of validator (optional for central)
-        --asperabrowserurl=VALUE     URL for simple aspera web ui
-        --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
+        --url=VALUE                  URL of application, e.g. https://faspex.example.com/aspera/faspex
         --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)
+        --sync-info=VALUE            Information for sync instance and sessions (Hash)
 
 
 COMMAND: console
 SUBCOMMANDS: health transfer
 OPTIONS:
-        --url=VALUE                  URL of application, e.g. https://org.asperafiles.com
+        --url=VALUE                  URL of application, e.g. https://faspex.example.com/aspera/faspex
         --username=VALUE             Username to log in
         --password=VALUE             User's password
         --filter-from=DATE           Only after date
@@ -3286,19 +3519,74 @@ OPTIONS:
 
 ### Bulk creation and deletion of resources
 
-Bulk creation and deletion of resources are possible using option `bulk` (yes,no(default)).
-In that case, the operation expects an Array of Hash instead of a simple Hash using the [Extended Value Syntax](#extended).
+Bulk creation and deletion of resources are possible using option `bulk` (`yes`,`no`(default)).
+In that case, the operation expects an `Array` of `Hash` instead of a simple `Hash` using the [Extended Value Syntax](#extended).
 This option is available only for some of the resources: if you need it: try and see if the entities you try to create or delete support this option.
 
+### Plugins
+
+`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".
+
+Available plugins can be found using command:
+
+```bash
+ascli conf plugin list
+```
+
+```output
++--------------+--------+--------+-------------------------------------------------------+
+| plugin       | detect | wizard | path                                                  |
++--------------+--------+--------+-------------------------------------------------------+
+| shares       | Y      | Y      | .../aspera-cli/lib/aspera/cli/plugins/shares.rb       |
+| node         | Y      | Y      | .../aspera-cli/lib/aspera/cli/plugins/node.rb         |
+...
++--------------+--------+--------+-------------------------------------------------------+
+```
+
+Most plugins will take the URL option: `url` to identify their location.
+
+REST APIs of Aspera legacy applications (Aspera Node, Faspex 4, Shares, Console, Orchestrator) use simple username/password authentication: HTTP Basic Authentication using options: `username` and `password`.
+
+Aspera on Cloud and Faspex 5 rely on Oauth.
+
+By default plugins are looked-up in folders specified by (multi-value) option `plugin_folder`:
+
+```bash
+ascli --show-config --select=@json:'{"key":"plugin_folder"}'
+```
+
+You can create the skeleton of a new plugin like this:
+
+```bash
+ascli conf plugin create foo .
+```
+
+```output
+Created ./foo.rb
+```
+
+```bash
+ascli --plugin-folder=. foo
+```
+
 ## <a id="aoc"></a>Plugin: `aoc`: IBM Aspera on Cloud
 
-Aspera on Cloud uses the more advanced Oauth v2 mechanism for authentication (HTTP Basic authentication is not supported).
+Aspera on Cloud API requires the use of Oauth v2 mechanism for authentication (HTTP Basic authentication is not supported).
+
+It is recommended to use the wizard to set it up, although manual configuration is also possible.
+
+### <a id="aocwizard"></a>Configuration: Using Wizard
+
+`ascli` provides a configuration wizard.
 
-It is recommended to use the wizard to set it up, but manual configuration is also possible.
+The wizard guides you through the steps to create a new configuration preset for Aspera on Cloud.
 
-### <a id="aocwizard"></a>Configuration: using Wizard
+The first
 
-`ascli` provides a configuration wizard. Here is a sample invocation :
+Here is a sample invocation :
 
 ```text
 ascli config wizard
@@ -3306,7 +3594,7 @@ option: url> https://myorg.ibmaspera.com
 Detected: Aspera on Cloud
 Preparing preset: aoc_myorg
 Please provide path to your private RSA key, or empty to generate one:
-option: pkeypath>
+option: key_path>
 using existing key:
 /Users/myself/.aspera/ascli/aspera_aoc_key
 Using global client_id.
@@ -3323,15 +3611,13 @@ ascli aoc user profile show
 Optionally, it is possible to create a new organization-specific "integration", i.e. client application identification.
 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 `query`:
+If you already know the application, and want to limit the detection to it, provide url and plugin name:
 
 ```bash
-ascli config wizard --query=aoc
+ascli config wizard myorg aoc
 ```
 
-### <a id="aocmanual"></a>Configuration: using manual setup
+### <a id="aocmanual"></a>Configuration: Using manual setup
 
 > **Note:** If you used the wizard (recommended): skip this section.
 
@@ -3345,11 +3631,13 @@ Several types of OAuth authentication are supported:
 
 The authentication method is controlled by option `auth`.
 
-For a *quick start*, follow the mandatory and sufficient section: [API Client Registration](#clientreg) (auth=web) as well as [[option preset](#lprt) for Aspera on Cloud](#aocpreset).
+For a **quick start**, follow the mandatory and sufficient section: [API Client Registration](#clientreg) (auth=web) as well as [[option preset](#lprt) for Aspera on Cloud](#aocpreset).
 
 For a more convenient, browser-less, experience follow the [JWT](#jwt) section (auth=jwt) in addition to Client Registration.
 
-In Oauth, a "Bearer" token are generated to authenticate REST calls. Bearer tokens are valid for a period of time.`ascli` saves generated tokens in its configuration folder, tries to re-use them or regenerates them when they have expired.
+In Oauth, a "Bearer" token is generated to authenticate REST calls.
+Bearer tokens are valid for a period of time defined (by the AoC app, configurable by admin) at its creation.
+`ascli` saves generated tokens in its configuration folder, tries to re-use them or regenerates them when they have expired.
 
 #### <a id="clientreg"></a>Optional: API Client Registration
 
@@ -3371,7 +3659,7 @@ Let's start by a registration with web based authentication (auth=web):
   - leave the JWT part for now
 - Save
 
-Note: for web based authentication, `ascli` listens on a local port (e.g. specified by the redirect_uri, in this example: 12345), and the browser will provide the OAuth code there. For ``ascli`, HTTP is required, and 12345 is the default port.
+> **Note:** for web based authentication, `ascli` listens on a local port (e.g. specified by the redirect_uri, in this example: 12345), and the browser will provide the OAuth code there. For ``ascli`, HTTP is required, and 12345 is the default port.
 
 Once the client is registered, a "Client ID" and "Secret" are created, these values will be used in the next step.
 
@@ -3397,7 +3685,7 @@ Define this [option preset](#lprt) as default configuration for the `aspera` plu
 ascli config preset set default aoc my_aoc_org
 ```
 
-Note: Default `auth` method is `web` and default `redirect_uri` is `http://localhost:12345`. Leave those default values.
+> **Note:** Default `auth` method is `web` and default `redirect_uri` is `http://localhost:12345`. Leave those default values.
 
 #### <a id="jwt"></a>Activation of JSON Web Token (JWT) for direct authentication
 
@@ -3452,7 +3740,7 @@ Open the previously generated public key located here: `$HOME/.aspera/ascli/my_p
 - Open a web browser, log to your instance: `https://myorg.ibmaspera.com/`
 - Click on the user's icon (top right)
 - Select "Account Settings"
-- Paste the *Public Key* in the "Public Key" section
+- Paste the **Public Key** in the "Public Key" section
 - Click on "Submit"
 
 ##### Using command line
@@ -3478,7 +3766,7 @@ ascli aoc user profile modify @ruby:'{"public_key"=>File.read(File.expand_path("
 modified
 ```
 
-Note: the `aspera user info show` command can be used to verify modifications.
+> **Note:** the `aspera user info show` command can be used to verify modifications.
 
 #### [option preset](#lprt) modification for JWT
 
@@ -3491,13 +3779,26 @@ To activate default use of JWT authentication for `ascli` using the [option pres
 Execute:
 
 ```bash
-ascli config preset update my_aoc_org --auth=jwt --private-key=@val:@file:~/.aspera/ascli/my_private_key --username=laurent.martin.aspera@fr.ibm.com
+ascli config preset update my_aoc_org --auth=jwt --private-key=@val:@file:~/.aspera/ascli/my_private_key --username=someuser@example.com
 ```
 
-Note: the private key argument represents the actual PEM string. In order to read the content from a file, use the `@file:` prefix. But if the @file: argument is used as is, it will read the file and set in the config file. So to keep the "@file" tag in the configuration file, the `@val:` prefix is added.
+> **Note:** the private key argument represents the actual PEM string. In order to read the content from a file, use the `@file:` prefix. But if the @file: argument is used as is, it will read the file and set in the config file. So to keep the "@file" tag in the configuration file, the `@val:` prefix is added.
 
 After this last step, commands do not require web login anymore.
 
+#### Public and private links
+
+AoC gives the possibility to generate public links for both the `Files` and `Packages` modules.
+Public links embed the authorization of access.
+Provide the public link using option `url` alone.
+
+In addition, the `Files` application supports private links.
+Private links require the user to authenticate.
+So, provide the same options as for regular authentication, and provide the private link using option `url`.
+
+A user may not be part of any workspace, but still have access to shared folders (using private links).
+In that case, it is possible to list those shared folder by using a value for option `workspace` equal to `@none:` or `@json:null` or `@ruby:nil`.
+
 #### <a id="aocfirst"></a>First Use
 
 Once client has been registered and [option preset](#lprt) created: `ascli` can be used:
@@ -3542,7 +3843,9 @@ It allows actions (create, update, delete) on "resources": users, group, nodes,
 
 The command `aoc admin res <type> list` lists all entities of given type. It uses paging and multiple requests if necessary.
 
-The option `query` can be optionally used. It expects a Hash using [Extended Value Syntax](#extended), generally provided using: `--query=@json:{...}`. Values are directly sent to the API call and used as a filter on server side.
+The option `query` can be optionally used.
+It expects a `Hash` using [Extended Value Syntax](#extended), generally provided using: `--query=@json:{...}`.
+Values are directly sent to the API call and used as a filter on server side.
 
 The following parameters are supported:
 
@@ -3569,7 +3872,7 @@ Examples:
 - List users with `laurent` in name:
 
 ```bash
-ascli aoc admin res user list --query=--query=@json:'{"q":"laurent"}'
+ascli aoc admin res user list --query=@json:'{"q":"laurent"}'
 ```
 
 - List users who logged-in before a date:
@@ -3594,8 +3897,8 @@ Resources are identified by a unique `id`, as well as a unique `name` (case inse
 
 To execute an action on a specific resource, select it using one of those methods:
 
-- *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`
+- **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 123`
 - provide option `name` : `aoc admin res node show --name=abc`
 
@@ -3664,7 +3967,7 @@ The activity app can be queried with:
 ascli aoc admin analytics transfers
 ```
 
-It can also support filters and send notification using option `notif_to`. a template is defined using option `notif_template` :
+It can also support filters and send notification using option `notify_to`. a template is defined using option `notify_template` :
 
 `mytemplate.erb`:
 
@@ -3687,9 +3990,7 @@ The environment provided contains the following additional variable:
 Example:
 
 ```bash
-ascli aoc admin analytics transfers --once-only=yes --lock-port=12345 \
---query=@json:'{"status":"completed","direction":"receive"}' \
---notif-to=active --notif-template=@file:mytemplate.erb
+ascli aoc admin analytics transfers --once-only=yes --lock-port=12345 --query=@json:'{"status":"completed","direction":"receive"}' --notify-to=active --notify-template=@file:mytemplate.erb
 ```
 
 Options:
@@ -3770,19 +4071,7 @@ ascli aoc admin res user list --query='@json:{"q":"dummyuser"}' --fields=id,emai
 ```
 
 ```bash
-thelist=$(ascli aoc admin res user list --query='@json:{"q":"dummyuser"}' --fields=id --format=json --display=data|jq -cr 'map(.id)')
-```
-
-```bash
-echo $thelist
-```
-
-```json
-["113501","354061"]
-```
-
-```bash
-ascli aoc admin res user delete @json:"$thelist" --bulk=yes
+ascli aoc admin res user list --query='@json:{"q":"dummyuser"}' --fields=id --display=data --format=csv | ascli aoc admin res user delete @lines:@stdin: --bulk=yes
 ```
 
 ```output
@@ -3832,7 +4121,7 @@ ascli aoc admin resource node --name=_node_name_ --secret=_secret_ v4 access_key
 ascli aoc admin res node --secret=_secret_ v3 transfer list --query=@json:'[["q","*"],["count",5]]'
 ```
 
-Examples of query (TODO: cleanup):
+Examples of query:
 
 ```json
 {"q":"type(file_upload OR file_delete OR file_download OR file_rename OR folder_create OR folder_delete OR folder_share OR folder_share_via_public_link)","sort":"-date"}
@@ -3859,7 +4148,7 @@ ascli aoc admin res workspace_membership list --fields=member_type,manager,membe
 | member_type | manager |           member.email           |
 +-------------+---------+----------------------------------+
 | user        | true    | john.curtis@email.com            |
-| user        | false   | laurent.martin.aspera@fr.ibm.com |
+| user        | false   | someuser@example.com |
 | user        | false   | jean.dupont@me.com               |
 | user        | false   | another.user@example.com         |
 | group       | false   |                                  |
@@ -3934,7 +4223,7 @@ ascli aoc admin res user list --fields=email --query=@json:'{"q":"last_login_at:
 ascli aoc admin res user list --fields=email --select=@json:'{"member_of_any_workspace":false}'
 ```
 
-#### Example: create a group, add to workspace and add user to group
+#### Example: Create a group, add to workspace and add user to group
 
 - Create the group and take note of `id`
 
@@ -3979,7 +4268,7 @@ In this example, a user has access to a workspace where two shared folders are l
 First, setup the environment (skip if already done)
 
 ```bash
-ascli conf wizard --url=https://sedemo.ibmaspera.com --username=laurent.martin.aspera@fr.ibm.com
+ascli conf wizard --url=https://sedemo.ibmaspera.com --username=someuser@example.com
 ```
 
 ```output
@@ -4014,7 +4303,7 @@ Then, transfer between those:
 ascli -Paoc_show aoc files transfer --from-folder='IBM Cloud SJ' --to-folder='AWS Singapore' 100GB.file --ts=@json:'{"target_rate_kbps":"1000000","multi_session":10,"multi_session_threshold":1}'
 ```
 
-#### Example: create registration key to register a node
+#### Example: Create registration key to register a node
 
 ```bash
 ascli aoc admin res client create @json:'{"data":{"name":"laurentnode","client_subject_scopes":["alee","aejd"],"client_subject_enabled":true}}' --fields=token --format=csv
@@ -4024,7 +4313,7 @@ ascli aoc admin res client create @json:'{"data":{"name":"laurentnode","client_s
 jfqslfdjlfdjfhdjklqfhdkl
 ```
 
-#### Example: delete all registration keys
+#### Example: Delete all registration keys
 
 ```bash
 ascli aoc admin res client list --fields=id --format=csv|ascli aoc admin res client delete @lines:@stdin: --bulk=yes
@@ -4105,7 +4394,7 @@ In this case:
 
 ### Packages
 
-The webmail-like application.
+The web-mail-like application.
 
 #### Send a Package
 
@@ -4117,7 +4406,7 @@ ascli aoc packages send [package extended value] [other parameters such as file
 
 Notes:
 
-- Package creation parameter are sent as positional mandatory parameter.
+- Package creation parameter are sent as positional argument.
   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.
@@ -4130,7 +4419,7 @@ Notes:
 #### Example: Send a package with one file to two users, using their email
 
 ```bash
-ascli aoc packages send @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":["someuser@example.com","other@example.com"]}' my_file.dat
 ```
 
 #### Example: Send a package to a shared inbox with metadata
@@ -4166,7 +4455,7 @@ ascli aoc packages list --query=@json:'{"dropbox_name":"My Shared Inbox","archiv
 Using shared inbox identifier: first retrieve the id of the shared inbox, and then list packages with the appropriate filter.
 
 ```bash
-shared_box_id=$(ascli aoc packages shared_inboxes show name 'My Shared Inbox' --format=csv --display=data --fields=id --transpose-single=no)
+shared_box_id=$(ascli aoc packages shared_inboxes show --name='My Shared Inbox' --format=csv --display=data --fields=id --transpose-single=no)
 ```
 
 ```bash
@@ -4187,21 +4476,21 @@ Find files in Files app:
 ascli aoc files browse /src_folder
 ```
 
-```bash
-+------------------------------+--------+----------------+--------------+----------------------+--------------+
-| name                         | type   | recursive_size | size         | modified_time        | access_level |
-+------------------------------+--------+----------------+--------------+----------------------+--------------+
-| sample_video                 | link   |                |              | 2020-11-29T22:49:09Z | edit         |
-| 100G                         | file   |                | 107374182400 | 2021-04-21T18:19:25Z | edit         |
-| 10M.dat                      | file   |                | 10485760     | 2021-05-18T08:22:39Z | edit         |
-| Test.pdf                     | file   |                | 1265103      | 2022-06-16T12:49:55Z | edit         |
-+------------------------------+--------+----------------+--------------+----------------------+--------------+
+```text
++---------------+--------+----------------+--------------+----------------------+--------------+
+| name          | type   | recursive_size | size         | modified_time        | access_level |
++---------------+--------+----------------+--------------+----------------------+--------------+
+| sample_video  | link   |                |              | 2020-11-29T22:49:09Z | edit         |
+| 100G          | file   |                | 107374182400 | 2021-04-21T18:19:25Z | edit         |
+| 10M.dat       | file   |                | 10485760     | 2021-05-18T08:22:39Z | edit         |
+| Test.pdf      | file   |                | 1265103      | 2022-06-16T12:49:55Z | edit         |
++---------------+--------+----------------+--------------+----------------------+--------------+
 ```
 
 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 @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":["someuser@example.com"]}' 10M.dat --transfer=node --transfer-info=@json:@stdin:
 ```
 
 #### <a id="aoccargo"></a>Receive new packages only (Cargo)
@@ -4223,6 +4512,8 @@ Typically, one would execute this command on a regular basis, using the method o
 The Files application presents a **Home** folder to users in a given workspace.
 Files located here are either user's files, or shared folders.
 
+> **Note:** All commands under `files` are the same as under `access_keys do self` for plugin `node`, i.e. **gen4/access key** operations.
+
 #### Download Files
 
 The general download command is:
@@ -4242,8 +4533,10 @@ ascli aoc files download <single file path>
 #### Shared folders
 
 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).
+
+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 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.
 
@@ -4265,6 +4558,15 @@ ascli aoc files perm /shared_folder_test1 create @json:'{"with":"laurent"}'
 ascli aoc files perm /shared_folder_test1 delete 6161
 ```
 
+Public and Private short links can be managed with command:
+
+```bash
+ascli aoc files short_link private create _path_here_
+ascli aoc files short_link private list _path_here_
+ascli aoc files short_link public list _path_here_
+ascli aoc files short_link public delete _id_
+```
+
 #### Cross Organization transfers
 
 It is possible to transfer files directly between organizations without having to first download locally and then upload...
@@ -4297,59 +4599,22 @@ Explanation:
 
 #### Find Files
 
-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/)`
-
-  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.
-
-Examples of expressions: (using like this: `--query=exec:'<expression>'`)
-
-- Find files more recent than 100 days
-
-  ```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
-
-  ```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
+The command `aoc files find` allows to search for files in a given workspace.
 
-  ```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
-  ```
+It works also on `node` resource using the `v4` command:
 
-- Delete the files in bulk
+```bash
+ascli aoc admin res node --name='my node name' --secret='my_secret_here' v4 find ...
+```
 
-  ```bash
-  cat my_file_list.txt | ascli aoc admin res node --name='my node name' --secret='my_secret_here' v3 delete @lines:@stdin:
-  ```
+For instructions, refer to section `find` for plugin `node`.
 
 ### AoC sample commands
 
 ```bash
-aoc admin analytics transfers --query=@json:'{"status":"completed","direction":"receive"}' --notif-to=my_recipient_email --notif-template=@ruby:'%Q{From: <%=from_name%> <<%=from_email%>>\nTo: <<%=to%>>\nSubject: <%=ev["files_completed"]%> files received\n\n<%=ev.to_yaml%>}'
-aoc admin ats access_key create --cloud=aws --region=my_aws_bucket_region --params=@json:'{"id":"ak_aws","name":"my test key AWS","storage":{"type":"aws_s3","bucket":"my_aws_bucket_name","credentials":{"access_key_id":"my_aws_bucket_key","secret_access_key":"my_aws_bucket_secret"},"path":"/"}}'
-aoc admin ats access_key create --cloud=softlayer --region=my_icos_bucket_region --params=@json:'{"id":"ak1ibmcloud","secret":"my_secret_here","name":"my test key","storage":{"type":"ibm-s3","bucket":"my_icos_bucket_name","credentials":{"access_key_id":"my_icos_bucket_key","secret_access_key":"my_icos_bucket_secret"},"path":"/"}}'
+aoc admin analytics transfers organization --query=@json:'{"status":"completed","direction":"receive"}' --notify-to=my_email_external --notify-template=@ruby:'%Q{From: <%=from_name%> <<%=from_email%>>\nTo: <<%=to%>>\nSubject: <%=ev["files_completed"]%> files received\n\n<%=ev.to_yaml%>}'
+aoc admin ats access_key create --cloud=aws --region=my_bucket_region --params=@json:'{"id":"ak_aws","name":"my test key AWS","storage":{"type":"aws_s3","bucket":"my_bucket_name","credentials":{"access_key_id":"my_bucket_key","secret_access_key":"my_bucket_secret"},"path":"/"}}'
+aoc admin ats access_key create --cloud=softlayer --region=my_bucket_region --params=@json:'{"id":"ak1ibmcloud","secret":"my_secret_here","name":"my test key","storage":{"type":"ibm-s3","bucket":"my_bucket_name","credentials":{"access_key_id":"my_bucket_key","secret_access_key":"my_bucket_secret"},"path":"/"}}'
 aoc admin ats access_key delete ak1ibmcloud
 aoc admin ats access_key list --fields=name,id
 aoc admin ats access_key node ak1ibmcloud --secret=my_secret_here browse /
@@ -4362,7 +4627,7 @@ aoc admin res application list
 aoc admin res client list
 aoc admin res client_access_key list
 aoc admin res client_registration_token create @json:'{"data":{"name":"test_client_reg1","client_subject_scopes":["alee","aejd"],"client_subject_enabled":true}}'
-aoc admin res client_registration_token delete my_clt_reg_id
+aoc admin res client_registration_token delete client_reg_id
 aoc admin res client_registration_token list
 aoc admin res contact list
 aoc admin res dropbox list
@@ -4377,69 +4642,73 @@ aoc admin res saml_configuration list
 aoc admin res self show
 aoc admin res short_link list
 aoc admin res user list
+aoc admin res user modify %name:my_user_email @json:'{"deactivated":false}'
 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 @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 node do %name:my_ak_name --secret=my_ak_secret browse /
+aoc admin resource node do %name:my_ak_name --secret=my_ak_secret delete /folder1
+aoc admin resource node do %name:my_ak_name --secret=my_ak_secret mkdir /folder1
+aoc admin resource node do %name:my_ak_name --secret=my_ak_secret v3 access_key create @json:'{"id":"testsub1","storage":{"path":"/folder1"}}'
+aoc admin resource node do %name:my_ak_name --secret=my_ak_secret v3 access_key delete testsub1
+aoc admin resource node do %name:my_ak_name --secret=my_ak_secret v3 events
 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 @json:'{"name":"toto"}' \
+aoc automation workflow action wf_id create @json:'{"name":"toto"}' \
 aoc automation workflow create @json:'{"name":"test_workflow"}'
-aoc automation workflow delete my_wf_id
+aoc automation workflow delete 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 bearer_token --display=data --scope=user:all
-aoc faspex
 aoc files bearer /
 aoc files bearer_token_node / --cache-tokens=no
 aoc files browse /
-aoc files browse / --link=my_aoc_publink_folder
+aoc files browse / --url=my_private_link
+aoc files browse / --url=my_public_link_folder_no_pass
+aoc files browse / --url=my_public_link_folder_pass --password=my_public_link_password
 aoc files delete /testsrc
-aoc files download --transfer=connect /200KB.1
-aoc files find / --query='\.partial$'
-aoc files http_node_download --to-folder=. /200KB.1
+aoc files download --transfer=connect testdst/test_file.bin
+aoc files find / '\.partial$'
+aoc files http_node_download --to-folder=. testdst/test_file.bin
 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 /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 modify my_test_folder
+aoc files permission my_test_folder list
+aoc files rename /some_folder testdst
+aoc files short_link private create /testdst
+aoc files short_link private list /testdst
+aoc files short_link public create testdst
+aoc files show %id:aoc_file_id
+aoc files show /
+aoc files show testdst/test_file.bin
+aoc files sync admin status --sync-info=@json:'{"name":"my_aoc_sync2","reset":true,"direction":"pull","local":{"path":"/data/local_sync"},"remote":{"path":"/testdst"}}'
+aoc files sync admin status --sync-info=@json:'{"sessions":[{"name":"my_aoc_sync1","direction":"pull","local_dir":"/data/local_sync","remote_dir":"/testdst","reset":true}]}'
+aoc files sync start --sync-info=@json:'{"name":"my_aoc_sync2","reset":true,"direction":"pull","local":{"path":"/data/local_sync"},"remote":{"path":"/testdst"}}'
+aoc files sync start --sync-info=@json:'{"sessions":[{"name":"my_aoc_sync1","direction":"pull","local_dir":"/data/local_sync","remote_dir":"/testdst","reset":true}]}'
+aoc files thumbnail my_test_folder/video_file.mpg
+aoc files thumbnail my_test_folder/video_file.mpg --query=@json:'{"text":true,"double":true}'
+aoc files transfer push /testsrc --to-folder=/testdst test_file.bin
+aoc files upload --to-folder=/ test_file.bin --url=my_public_link_folder_no_pass
+aoc files upload --to-folder=/testsrc test_file.bin
+aoc files upload --workspace=my_other_workspace --to-folder=my_other_folder test_file.bin --transfer=node --transfer-info=@json:@stdin:
 aoc files v3 info
-aoc gateway https://localhost:12345/aspera/faspex
-aoc org --link=my_aoc_publink_recv_from_aocuser
+aoc gateway --pid-file=server_pid https://localhost:12345/aspera/faspex
+aoc org --url=my_public_link_recv_from_aoc_user
 aoc organization
-aoc packages browse "my_package_id" /contents
+aoc packages browse package_id3 /contents
 aoc packages list
-aoc packages list --query=@json:'{"dropbox_name":"my_aoc_shbx_name","sort":"-received_at","archived":false,"received":true,"has_content":true,"exclude_dropbox_packages":false}'
-aoc packages recv "my_package_id" --to-folder=.
+aoc packages list --query=@json:'{"dropbox_name":"my_shared_inbox_name","sort":"-received_at","archived":false,"received":true,"has_content":true,"exclude_dropbox_packages":false}'
 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 --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 recv ALL --to-folder=. --once-only=yes --lock-port=12345 --query=@json:'{"dropbox_name":"my_shared_inbox_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 recv package_id3 --to-folder=.
+aoc packages send --workspace=my_workspace_shared_inbox @json:'{"name":"Important files delivery","recipients":["my_shared_inbox_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"]}]}' test_file.bin
+aoc packages send --workspace=my_workspace_shared_inbox @json:'{"name":"Important files delivery","recipients":["my_shared_inbox_name"],"metadata":{"Project Id":"456","Type":"Opt2","CheckThose":["Check1","Check2"],"Optional Date":"2021-01-13T15:02:00.000Z"}}' test_file.bin
+aoc packages send --workspace=my_workspace_shared_inbox @json:'{"name":"Important files delivery","recipients":["my_shared_inbox_name"]}' test_file.bin
+aoc packages send @json:'{"name":"Important files delivery","recipients":["my_email_external"]}' --new-user-option=@json:'{"package_contact":true}' test_file.bin
+aoc packages send @json:'{"name":"Important files delivery","recipients":["my_email_internal"],"note":"my note"}' test_file.bin
+aoc packages send @json:'{"name":"Important files delivery"}' test_file.bin --url=my_public_link_send_aoc_user --password=my_public_link_send_use_pass
+aoc packages send @json:'{"name":"Important files delivery"}' test_file.bin --url=my_public_link_send_shared_inbox
 aoc packages shared_inboxes list
-aoc remind --username=my_aoc_user_email
+aoc remind --username=my_user_email
 aoc servers
 aoc user profile modify @json:'{"name":"dummy change"}'
 aoc user profile show
@@ -4455,7 +4724,7 @@ ATS is usable either :
 
 - or from an IBM Cloud subscription : ascli ats : use IBM Cloud API key authentication
 
-### IBM Cloud ATS : creation of api key
+### IBM Cloud ATS : Creation of api key
 
 This section is about using ATS with an IBM cloud subscription.
 If you are using ATS as part of AoC, then authentication is through AoC, not IBM Cloud.
@@ -4573,8 +4842,8 @@ The parameters provided to ATS for access key creation are the ones of [ATS API]
 
 ```bash
 ats access_key cluster ak2ibmcloud --secret=my_secret_here
-ats access_key create --cloud=aws --region=my_aws_bucket_region --params=@json:'{"id":"ak_aws","name":"my test key AWS","storage":{"type":"aws_s3","bucket":"my_aws_bucket_name","credentials":{"access_key_id":"my_aws_bucket_key","secret_access_key":"my_aws_bucket_secret"},"path":"/"}}'
-ats access_key create --cloud=softlayer --region=my_icos_bucket_region --params=@json:'{"id":"ak2ibmcloud","secret":"my_secret_here","name":"my test key","storage":{"type":"ibm-s3","bucket":"my_icos_bucket_name","credentials":{"access_key_id":"my_icos_bucket_key","secret_access_key":"my_icos_bucket_secret"},"path":"/"}}'
+ats access_key create --cloud=aws --region=my_bucket_region --params=@json:'{"id":"ak_aws","name":"my test key AWS","storage":{"type":"aws_s3","bucket":"my_bucket_name","credentials":{"access_key_id":"my_bucket_key","secret_access_key":"my_bucket_secret"},"path":"/"}}'
+ats access_key create --cloud=softlayer --region=my_bucket_region --params=@json:'{"id":"ak2ibmcloud","secret":"my_secret_here","name":"my test key","storage":{"type":"ibm-s3","bucket":"my_bucket_name","credentials":{"access_key_id":"my_bucket_key","secret_access_key":"my_bucket_secret"},"path":"/"}}'
 ats access_key delete ak2ibmcloud
 ats access_key delete ak_aws
 ats access_key entitlement ak2ibmcloud
@@ -4603,36 +4872,36 @@ then commands `ascp` (for transfers) and `ascmd` (for file operations) are execu
 
 ```bash
 server browse /
-server browse NEW_SERVER_FOLDER/testfile.bin
-server browse folder_1/target_hot
-server cp NEW_SERVER_FOLDER/testfile.bin folder_1/200KB.2
-server delete NEW_SERVER_FOLDER
-server delete folder_1/target_hot
-server delete folder_1/to.delete
+server browse my_inside_folder/test_file.bin
+server browse my_upload_folder/target_hot
+server cp my_inside_folder/test_file.bin my_upload_folder/200KB.2
+server delete my_inside_folder
+server delete my_upload_folder/to.delete
 server df
-server download NEW_SERVER_FOLDER/testfile.bin --to-folder=. --transfer-info=@json:'{"wss":false,"resume":{"iter_max":1}}'
-server download NEW_SERVER_FOLDER/testfile.bin --to-folder=folder_1 --transfer=node
+server download my_inside_folder/test_file.bin --to-folder=. --transfer-info=@json:'{"wss":false,"resume":{"iter_max":1}}'
+server download my_inside_folder/test_file.bin --to-folder=my_upload_folder --transfer=node
 server du /
-server health transfer --to-folder=folder_1 --format=nagios 
+server health transfer --to-folder=my_upload_folder --format=nagios
 server info
-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":"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
-server upload --sources=@ts --ts=@json:'{"EX_file_pair_list":"'"filepairlist.txt"'"}'
-server upload --sources=@ts --ts=@json:'{"paths":[{"source":"testfile.bin","destination":"NEW_SERVER_FOLDER/othername"}]}'
-server upload --src-type=pair --sources=@json:'["testfile.bin","NEW_SERVER_FOLDER/othername"]'
-server upload --src-type=pair testfile.bin NEW_SERVER_FOLDER/othername --notif-to=my_recipient_email --transfer-info=@json:'{"ascp_args":["-l","10m"]}'
-server upload --src-type=pair testfile.bin folder_1/with_options --ts=@json:'{"cipher":"aes-192-gcm","content_protection":"encrypt","content_protection_password":"my_secret_here","cookie":"biscuit","create_dir":true,"delete_before_transfer":false,"delete_source":false,"exclude_newer_than":1,"exclude_older_than":10000,"fasp_port":33001,"http_fallback":false,"multi_session":0,"overwrite":"diff+older","precalculate_job_size":true,"preserve_access_time":true,"preserve_creation_time":true,"rate_policy":"fair","resume_policy":"sparse_csum","symlink_policy":"follow"}'
-server upload --to-folder=folder_1/target_hot --lock-port=12345 --ts=@json:'{"EX_ascp_args":["--remove-after-transfer","--remove-empty-directories","--exclude-newer-than=-8","--src-base","source_hot"]}' source_hot
-server upload testfile.bin --to-folder=NEW_SERVER_FOLDER --ts=@json:'{"multi_session":3,"multi_session_threshold":1,"resume_policy":"none","target_rate_kbps":1500}' --transfer-info=@json:'{"spawn_delay_sec":2.5,"multi_incr_udp":false}' --progress=multi
+server md5sum my_inside_folder/test_file.bin
+server mkdir my_inside_folder --logger=stdout
+server mkdir my_upload_folder/target_hot
+server mv my_upload_folder/200KB.2 my_upload_folder/to.delete
+server sync admin status --sync-info=@json:'{"name":"sync2","local":{"path":"/data/local_sync"}}'
+server sync admin status --sync-info=@json:'{"name":"sync2"}'
+server sync admin status my_sync --sync-info=@json:'{"sessions":[{"name":"my_sync","local_dir":"/data/local_sync"}]}'
+server sync start --sync-info=@json:'{"instance":{"quiet":false},"sessions":[{"name":"my_sync","direction":"pull","remote_dir":"my_inside_folder","local_dir":"/data/local_sync","reset":true}]}'
+server sync start --sync-info=@json:'{"name":"sync2","local":{"path":"/data/local_sync"},"remote":{"path":"my_inside_folder"},"reset":true,"quiet":false}'
+server upload 'faux:///test1?100m' 'faux:///test2?100m' --to-folder=/Upload --ts=@json:'{"target_rate_kbps":1000000,"resume_policy":"none","precalculate_job_size":true}'
+server upload 'faux:///test1?100m' 'faux:///test2?100m' --to-folder=/Upload --ts=@json:'{"target_rate_kbps":1000000,"resume_policy":"none","precalculate_job_size":true}' --transfer-info=@json:'{"quiet":false}' --progress=no
+server upload 'test_file.bin' --to-folder=my_inside_folder --ts=@json:'{"multi_session":3,"multi_session_threshold":1,"resume_policy":"none","target_rate_kbps":100000}' --transfer-info=@json:'{"spawn_delay_sec":2.5,"multi_incr_udp":false}' --progress-bar=yes
+server upload --sources=@ts --transfer-info=@json:'{"ascp_args":["--file-list","filelist.txt"]}' --to-folder=my_inside_folder
+server upload --sources=@ts --transfer-info=@json:'{"ascp_args":["--file-pair-list","file_pair_list.txt"]}'
+server upload --sources=@ts --ts=@json:'{"paths":[{"source":"test_file.bin","destination":"my_inside_folder/other_name_4"}]}' --transfer=trsdk
+server upload --src-type=pair 'test_file.bin' my_inside_folder/other_name_2 --notify-to=my_email_external --transfer-info=@json:'{"ascp_args":["-l","100m"]}'
+server upload --src-type=pair --sources=@json:'["test_file.bin","my_inside_folder/other_name_3"]' --transfer-info=@json:'{"quiet":false}' --progress=no
+server upload --src-type=pair test_file.bin my_upload_folder/other_name_5 --ts=@json:'{"cipher":"aes-192-gcm","content_protection":"encrypt","content_protection_password":"my_secret_here","cookie":"biscuit","create_dir":true,"delete_before_transfer":false,"delete_source":false,"exclude_newer_than":1,"exclude_older_than":10000,"fasp_port":33001,"http_fallback":false,"multi_session":0,"overwrite":"diff+older","precalculate_job_size":true,"preserve_access_time":true,"preserve_creation_time":true,"rate_policy":"fair","resume_policy":"sparse_csum","symlink_policy":"follow"}'
+server upload --to-folder=my_upload_folder/target_hot --lock-port=12345 --transfer-info=@json:'{"ascp_args":["--remove-after-transfer","--remove-empty-directories","--exclude-newer-than=-8","--src-base","source_hot"]}' source_hot
 ```
 
 ### Authentication on Server with SSH session
@@ -4735,21 +5004,106 @@ ascli server --url=ssh://_server_address_here_:33001 --username=_user_here_ --ss
 
 ## <a id="node"></a>Plugin: `node`: IBM Aspera High Speed Transfer Server Node
 
-This plugin gives access to capabilities provided by HSTS node API.
+This plugin gives access to capabilities provided by the HSTS node API.
 
-> **Note:** capabilities of this plugin are used in other plugins which access to the node API, such as `aoc`.
+The authentication is `username` and `password` or `access_key` and `secret` through options: `username` and `password`.
+
+> **Note:** Capabilities of this plugin are used in other plugins which access to the node API, such as `aoc`, `ats`, `shares`.
 
 ### File Operations
 
-It is possible to:
+It is possible to do **gen3/node user** operations:
 
 - browse
-- transfer (upload / download)
+- transfer (upload / download / sync)
+- delete
 - ...
 
+When using an access key, so called **gen4/access key** API is also supported through sub commands using `access_keys do self`.
+
+Example:
+
+- `ascli node browse /` : list files with **gen3/node user** API
+- `ascli node access_key do self browse /` : list files with **gen4/access key** API
+
+### Operation `find` on **gen4/access key**
+
+The command `find <folder> [filter_expr]` is available for **gen4/access key**, under `access_keys do self`.
+
+The argument `<folder>` is mandatory and is the root from which search is performed.
+The argument `[filter_expr]` is optional and represent the matching criteria.
+
+It recursively scans storage to find files/folders matching a criteria and then returns a list of matching entries.
+
+`[filter_expr]` is either:
+
+- Optional (default) : all files and folder are selected
+- type `String` : the expression is similar to shell globing, refer to **Ruby** function: [`File.fnmatch`](https://ruby-doc.org/3.2.2/File.html#method-c-fnmatch)
+- Type `Proc` : the expression is a Ruby lambda that takes one argument: a `Hash` that contains the current folder entry to test. Refer to the following examples.
+
+Examples of expressions:
+
+- Find all files and folders under `/`
+
+  ```bash
+  ascli node access_keys do self find
+  ```
+
+- Find all text files `/Documents`
+
+  ```bash
+  ascli node access_keys do self find /Documents '*.txt'
+  ```
+
+The following are examples of `ruby_lambda` to be provided in the following template command:
+
+```bash
+ ascli node access_keys do self find / @ruby:'ruby_lambda'
+```
+
+> **Note:** Single quotes are used here above to protect the whole **Ruby** expression from the shell. Then double quotes are used for strings in the **Ruby** expression to not mix with the shell.
+
+- Find files more recent than 100 days
+
+  ```ruby
+  ->(f){f["type"].eql?("file") and (DateTime.now-DateTime.parse(f["modified_time"]))<100}
+  ```
+
+- Find files older than 1 year
+
+  ```ruby
+  ->(f){f["type"].eql?("file") and (DateTime.now-DateTime.parse(f["modified_time"]))>365}
+  ```
+
+- Find files larger than 1MB
+
+  ```ruby
+  ->(f){f["type"].eql?("file") and f["size"].to_i>1000000}
+  ```
+
+- Filter out files beginning with `._` or named `.DS_Store`:
+
+  ```ruby
+  ->(f){!(f["name"].start_with?("._") or f["name"].eql?(".DS_Store"))}
+  ```
+
+- Match files using a [Ruby Regex](https://ruby-doc.org/core/Regexp.html) : `\.gif$`
+
+  ```ruby
+  ->(f){f["name"].match?(/\.gif$/)}
+  ```
+
+`ascli` commands can be piped in order to combine operations, such as "find and delete":
+
+```bash
+ascli node access_keys do self find / @ruby:'->(f){f["type"].eql?("file") and (DateTime.now-DateTime.parse(f["modified_time"]))>365}' --fields=path --format=csv | ascli node --bulk=yes delete @lines:@stdin:
+```
+
+> **Note:** the pipe `|` character on the last line.
+
 ### Central
 
-The central subcommand uses the "reliable query" API (session and file).
+The central subcommand uses the **reliable query** API (session and file).
 It allows listing transfer sessions and transferred files.
 
 Filtering can be applied:
@@ -4758,26 +5112,36 @@ Filtering can be applied:
 ascli node central file list
 ```
 
-by providing the `validator` option, offline transfer validation can be done.
+By providing the `validator` option, offline transfer validation can be done.
+
+> **Note:** This API will probably be deprecated in the future.
+
+### Sync
+
+There are three sync types of operations:
+
+- `sync`: perform a local sync, by executing `async` locally
+- `async`: calls legacy async API on node : `/async`
+- `ssync` : calls newer async API on node : `/asyncs`
 
 ### FASP Stream
 
 It is possible to start a FASPStream session using the node API:
 
-Use the "node stream create" command, then arguments are provided as a [*transfer-spec*](#transferspec).
+Use the command `ascli node stream create --ts=@json:<value>`, with [*transfer-spec*](#transferspec):
 
-```bash
-ascli node stream create --ts=@json:'{"direction":"send","source":"udp://233.3.3.4:3000?loopback=1&ttl=2","destination":"udp://233.3.3.3:3001/","remote_host":"localhost","remote_user":"stream","remote_password":"my_pass_here"}' --preset=stream
+```json
+{"direction":"send","source":"udp://233.3.3.4:3000?loopback=1&ttl=2","destination":"udp://233.3.3.3:3001/","remote_host":"localhost","remote_user":"stream","remote_password":"my_pass_here"}
 ```
 
-### Watchfolder
+### "Watchfolder"
 
 Refer to [Aspera documentation](https://download.asperasoft.com/download/docs/entsrv/3.7.4/es_admin_linux/webhelp/index.html#watchfolder_external/dita/json_conf.html) for watch folder creation.
 
 `ascli` supports remote operations through the node API. Operations are:
 
-- Start watchd and watchfolderd services running as a system user having access to files
-- configure a watchfolder to define automated transfers
+- Start `watchd` and `watchfolderd` services running as a system user having access to files
+- configure a "watchfolder" to define automated transfers
 
 ```bash
 ascli node service create @json:'{"id":"mywatchd","type":"WATCHD","run_as":{"user":"user1"}}'
@@ -4835,21 +5199,21 @@ 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:
+For example, it is possible to display the preview of a file, if it exists, using an access key on node:
 
 ```bash
-ascli aoc files thumbnail /preview_samples/Aspera.mpg
+ascli node access_key do self thumbnail /preview_samples/Aspera.mpg
 ```
 
-Using direct node access and an access key , one can do:
+Previews are mainly used in AoC, this also works with AoC:
 
 ```bash
-ascli node access_key do self thumbnail /preview_samples/Aspera.mpg
+ascli aoc files 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`
+> **Note:** To force textual display of the preview on **iTerm**, prefix command with: `env -u TERM_PROGRAM -u LC_TERMINAL`
 
 ### Create access key
 
@@ -4857,24 +5221,163 @@ ascli node access_key do self thumbnail /preview_samples/Aspera.mpg
 ascli node access_key create @json:'{"id":"myaccesskey","secret":"my_secret_here","storage":{"type":"local","path":"/data/mydir"}}'
 ```
 
+> **Note:** The `id` and `secret` are optional.
+> If not provided, they will be generated and returned in the result.
+
+Access keys support extra overriding parameters using parameter: `configuration` and sub keys `transfer` and `server`. For example, an access key can be modified or created with the following options:
+
+```json
+{"configuration":{"transfer":{"target_rate_cap_kbps":500000}}}
+```
+
+The list of supported options can be displayed using command:
+
+```bash
+ascli node info --field=@ruby:'/^access_key_configuration_capabilities.*/'
+```
+
+### Generate and use bearer token
+
+Bearer tokens are part of the **gen4/access key** API.
+It follows the model of OAuth 2.
+For example they are used in Aspera on Cloud.
+This is also available for developers for any application integrating Aspera.
+In this API, files, users and groups are identified by an id (a String, e.g. `"125"`, not necessarily numerical).
+
+Bearer tokens are typically generated by the authentication application, and then recognized by the node API.
+A bearer token is authorized on the node by creating `permissions` on a **folder**.
+
+Bearer tokens can be generated using command `bearer_token`: it takes two arguments:
+
+- the private key used to sign the token
+- the token information, which is a `Hash` containing the following elements:
+
+| parameter                 | Default                     | type      | description                                              |
+| ------------------------  |-----------------------------|-----------|----------------------------------------------------------|
+| user_id                   | -                           | Mandatory | Identifier of user                                       |
+| scope                     | `node.<access_key>:<_scope>`| Mandatory | API scope, e.g. `node.<access_key>:<node scope>`         |
+| expires_at                | `now+<_validity>`           | Mandatory | Format: `%Y-%m-%dT%H:%M:%SZ` e.g. `2021-12-31T23:59:59Z` |
+| auth_type                 | `access_key`                | Optional  | `access_key`, `node_user`                                |
+| group_ids                 | -                           | Optional  | List of group ids                                        |
+| organization_id           | -                           | Optional  | Organization id                                          |
+| watermarking_json_base64  | -                           | Optional  | Watermarking information (not used)                      |
+| _scope                    | `user:all`                  | Special   | Either `user:all` or `admin:all`                         |
+| _validity                 | 86400                       | Special   | Validity in seconds from now.                            |
+
+> **Note:** For convenience, `ascli` provides additional parameters `_scope` and `_validity`.
+> They are not part of the API and are removed from the final payload.
+> They are used respectively to build the default value of `scope` and `expires_at`.
+
+#### Bearer token: Environment
+
+- If a self-managed Aspera node is used, then a "node user admin" must be created:
+  It has no `docroot` but has at least one file restriction (for testing, one can use `*` to accept creation of an access key with any storage root path).
+  Refer to the Aspera HSTS documentation.
+
+- If Cloud Pak for integration is used, then the node admin is created automatically.
+
+- If Aspera on Cloud or ATS is used, then the SaaS API for access key creation is used.
+
+- An access key shall be created to grant access for transfers to its storage.
+  The access_key and its secrets represent an administrative access to the storage as it has access rights to the whole storage of the access key.
+
+#### Bearer token: Preparation
+
+Let's assume that the access key was created, and a default configuration is set to use this **access key**.
+
+- Create a private key (organization key) that will be used to sign bearer tokens:
+
+  ```bash
+  my_private_pem=./myorgkey.pem
+  ascli conf genkey $my_private_pem
+  ```
+
+  > **Note:** This key is not used for authentication, it is used to sign bearer tokens.
+  > Refer to section [private key](#private_key) for more details on generation.
+
+- The corresponding public key shall be placed as an attribute of the **access key**:
+
+  ```bash
+  ascli node access_key set_bearer_key self @file:$my_private_pem
+  ```
+
+  > **Note:** Either the public or private key can be provided, and only the public key is used.
+  > This will enable to check the signature of the bearer token.
+
+  Alternatively, use the following equivalent command, as `ascli` kindly extracts the public key with extension `.pub`:
+
+  ```bash
+  ascli node access_key modify %id:self @ruby:'{token_verification_key: File.read("'$my_private_pem'.pub")}'
+  ```
+
+#### Bearer token: Configuration for user
+
+- Select a folder for which we want to grant access to a user, and get its identifier:
+
+  ```bash
+  my_folder_id=$(ascli node access_key do self show / --fields=id)
+  ```
+
+  > **Note:** Here we simply select `/`, but any folder can be selected in the access key storage.
+
+- Let's designate a user by its id:
+
+  ```bash
+  my_user_id=777
+  ```
+
+  > **Note:** This is an arbitrary identifier, typically managed by the web application.
+  > Not related to Linux user ids or anything else.
+
+- Grant this user access to the selected folder:
+
+  ```bash
+  ascli node access_key do self permission %id:$my_folder_id create @json:'{"access_type":"user","access_id":"'$my_user_id'"}'
+  ```
+
+- Create a Bearer token for the user:
+
+  ```bash
+  ascli node bearer_token @file:./myorgkey.pem @json:'{"user_id":"'$my_user_id'","_validity":3600}' > bearer.txt
+  ```
+
+#### Bearer token: User side
+
+Now, let's assume we are the user, the only information received are:
+
+- the url of the node API
+- a Bearer token
+- a file `id` for which we have access
+
+Let's use it:
+
+```bash
+ascli node -N --url=... --password="Bearer $(cat bearer.txt)" --root-id=$my_folder_id access_key do self br /
+```
+
 ### Node sample commands
 
 ```bash
-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 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 --url=https://tst.example.com/path --password="Bearer bearer_666" --root-id=root_id access_key do self br /
+node access_key create @json:'{"id":"my_username","secret":"my_password_here","storage":{"type":"local","path":"/"}}'
+node access_key delete my_username
+node access_key do my_ak_name browse /
+node access_key do my_ak_name delete /folder2
+node access_key do my_ak_name delete testfile1
+node access_key do my_ak_name download testfile1 --to-folder=.
+node access_key do my_ak_name find my_test_folder
+node access_key do my_ak_name find my_test_folder @ruby:'->(f){f["name"].end_with?(".jpg")}'
+node access_key do my_ak_name find my_test_folder exec:'f["name"].end_with?(".jpg")'
+node access_key do my_ak_name mkdir /folder1
+node access_key do my_ak_name node_info /
+node access_key do my_ak_name rename /folder1 folder2
+node access_key do my_ak_name show %id:1
+node access_key do my_ak_name show /testfile1
+node access_key do my_ak_name upload 'faux:///testfile1?1k' --default_ports=no
+node access_key do self permission %id:root_id create @json:'{"access_type":"user","access_id":"666"}'
+node access_key do self show / --fields=id
 node access_key list
+node access_key set_bearer_key self @file:my_private_key
 node api_details
 node async bandwidth 1
 node async counters 1
@@ -4883,55 +5386,107 @@ node async list
 node async show 1
 node async show ALL
 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.2
-node delete testfile.bin
-node download testfile.bin --to-folder=.
+node bearer_token @file:my_private_key @json:'{"user_id":"666"}'
+node browse / --log-level=trace2
+node delete @list:,my_upload_folder/a_folder,my_upload_folder/tdlink,my_upload_folder/a_file
+node delete my_upload_folder/test_file.bin
+node download my_upload_folder/test_file.bin --to-folder=.
 node health
 node info --fpac='function FindProxyForURL(url,host){return "DIRECT"}'
 node license
-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 mkdir my_upload_folder/a_folder
+node mkfile my_upload_folder/a_file1 "hello world"
+node mklink my_upload_folder/a_folder my_upload_folder/tdlink
+node rename my_upload_folder a_file1 a_file
 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 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 bandwidth %name:my_node_sync
+node ssync counters %name:my_node_sync
+node ssync create @json:'{"configuration":{"name":"my_node_sync","local":{"path":"my_local_path"},"remote":{"host":"my_host","port":my_port,"user":"my_username","pass":"my_password_here","path":"my_remote_path"}}}'
+node ssync delete %name:my_node_sync
+node ssync files %name:my_node_sync
 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 ssync show %name:my_node_sync
+node ssync start %name:my_node_sync
+node ssync state %name:my_node_sync
+node ssync stop %name:my_node_sync
+node ssync summary %name:my_node_sync
+node sync admin status --sync-info=@json:'{"name":"my_node_sync2","reset":true,"direction":"pull","local":{"path":"/data/local_sync"},"remote":{"path":"/aspera-test-dir-tiny"}}'
+node sync admin status --sync-info=@json:'{"sessions":[{"name":"my_node_sync1","direction":"pull","local_dir":"/data/local_sync","remote_dir":"/aspera-test-dir-tiny","reset":true}]}'
+node sync start --sync-info=@json:'{"name":"my_node_sync2","reset":true,"direction":"pull","local":{"path":"/data/local_sync"},"remote":{"path":"/aspera-test-dir-tiny"}}'
+node sync start --sync-info=@json:'{"sessions":[{"name":"my_node_sync1","direction":"pull","local_dir":"/data/local_sync","remote_dir":"/aspera-test-dir-tiny","reset":true}]}'
 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 transfer sessions
+node upload --to-folder=my_upload_folder --sources=@ts --ts=@json:'{"paths":[{"source":"/aspera-test-dir-small/10MB.2"}],"precalculate_job_size":true}' --transfer=node --transfer-info=@json:'{"url":"https://node.example.com/path@","username":"my_username","password":"my_password_here"}'
+node upload --username=my_ak_name --password=my_ak_secret test_file.bin
+node upload test_file.bin --to-folder=my_upload_folder --ts=@json:'{"target_rate_cap_kbps":10000}'
 ```
 
 ## <a id="faspex5"></a>Plugin: `faspex5`: IBM Aspera Faspex v5
 
 IBM Aspera's newer self-managed application.
 
-3 authentication methods are supported:
+3 authentication methods are supported (option `auth`):
+
+| Method       | Description                                                         |
+| ------------ | ------------------------------------------------------------------- |
+| `jwt`        | General purpose, private-key based authentication                   |
+| `web`        | Requires authentication with web browser                            |
+| `boot`       | Use authentication token copied from browser (experimental)         |
+| `public_link`| Public link authentication (set when option `url` is a public link) |
+
+> **Note:** If you have a Faspex 5 public link, provide it, unchanged, through the option `url`
+
+For a quick start, one can use the wizard, which will help creating a [option preset](#lprt):
 
-- 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)
+```bash
+ascli config wizard
+```
+
+```text
+argument: url> faspex5.example.com
+Multiple applications detected:
++---------+-------------------------------------------+-------------+
+| product | url                                       | version     |
++---------+-------------------------------------------+-------------+
+| faspex5 | https://faspex5.example.com/aspera/faspex | F5.0.6      |
+| server  | ssh://faspex5.example.com:22              | OpenSSH_8.3 |
++---------+-------------------------------------------+-------------+
+product> faspex5
+Using: Faspex at https://faspex5.example.com/aspera/faspex
+Please provide the path to your private RSA key, or nothing to generate one:
+option: key_path>
+Using existing key:
+/Users/someuser/.aspera/ascli/my_key
+option: username> someuser@example.com
+Ask the ascli client id and secret to your Administrator.
+Admin should login to: https://faspex5.example.com/aspera/faspex
+Navigate to: ::  → Admin → Configurations → API clients
+Create an API client with:
+- name: ascli
+- JWT: enabled
+Then, logged in as someuser@example.com go to your profile:
+() → Account Settings → Preferences -> Public Key in PEM:
+-----BEGIN PUBLIC KEY-----
+redacted
+-----END PUBLIC KEY-----
+Once set, fill in the parameters:
+option: client_id> _my_key_here_
+option: client_secret> ****
+Preparing preset: faspex5_example_com_user
+Setting config preset as default for faspex5
+Done.
+You can test with:
+ascli faspex5 user profile show
+Saving config file.
+```
+
+> **Note:** Include the public key `BEGIN` and `END` lines when pasting in the user profile.
+
+For details on the JWT method, see the following section.
 
 ### Faspex 5 JWT authentication
 
@@ -4939,7 +5494,7 @@ This is the general purpose and **recommended** method to use.
 
 Activation is in two steps:
 
-- The admninistrator must create an API client in Faspex with JWT support
+- The administrator must create an API client in Faspex with JWT support
 
   This operation is generally done only once:
 
@@ -4986,7 +5541,7 @@ ascli faspex5 user profile show
 
 ### Faspex 5 web authentication
 
-The admninistrator must create an API client in Faspex for an external web app support:
+The administrator must create an API client in Faspex for an external web app support:
 
 - As Admin, Navigate to the web UI: Admin &rarr; Configurations &rarr; API Clients &rarr; Create
 - Do not Activate JWT
@@ -5021,7 +5576,7 @@ ascli conf preset update f5boot --url=https://localhost/aspera/faspex --auth=boo
 ### Faspex 5 sample commands
 
 Most commands are directly REST API calls.
-Parameters to commands are carried through option `query`, as extended value, for `list`, or through positional parameter for creation.
+Parameters to commands are carried through option `query`, as extended value, for `list`, or through positional argument 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**.
@@ -5031,42 +5586,48 @@ 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 
+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 invite %name:my_shared_inbox_name 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 shared_inboxes members %name:my_shared_inbox_name create %name:john@example.com
+faspex5 admin res shared_inboxes members %name:my_shared_inbox_name delete %name:john@example.com
+faspex5 admin res shared_inboxes members %name:my_shared_inbox_name delete %name:johnny@example.com
+faspex5 admin res shared_inboxes members %name:my_shared_inbox_name list
 faspex5 admin res workgroups list
 faspex5 admin smtp show
 faspex5 admin smtp test my_email_external
 faspex5 bearer_token
-faspex5 gateway https://localhost:12345/aspera/faspex
+faspex5 gateway --pid-file=server_pid https://localhost:12345/aspera/faspex
 faspex5 health
-faspex5 packages list --box=my_faspex5_shinbox
-faspex5 packages list --box=my_faspex5_workgroup --group-type=workgroups
+faspex5 packages list --box=my_shared_inbox_name
+faspex5 packages list --box=my_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 --box=my_shared_inbox_name package_box_id1 --to-folder=.
+faspex5 packages receive --box=my_workgroup --group-type=workgroups workgroup_package_id1 --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 packages receive f5_p31 --to-folder=. --ts=@json:'{"content_protection_password":"my_secret_here"}'
+faspex5 packages send --shared-folder=%name:my_shared_folder_name @json:'{"title":"test title","recipients":["my_email_internal"]}' my_shared_folder_file
+faspex5 packages send @json:'{"title":"test title","recipients":["my_shared_inbox_name"],"metadata":{"Options":"Opt1","TextInput":"example text"}}' test_file.bin
+faspex5 packages send @json:'{"title":"test title","recipients":["my_workgroup"]}' test_file.bin
+faspex5 packages send @json:'{"title":"test title","recipients":[{"name":"my_username"}]my_meta}' test_file.bin --ts=@json:'{"content_protection_password":"my_passphrase_here"}'
+faspex5 packages show --box=my_shared_inbox_name package_box_id1
+faspex5 packages show --box=my_workgroup --group-type=workgroups workgroup_package_id1
+faspex5 packages show f5_p31
+faspex5 packages status f5_p31
+faspex5 postprocessing --pid-file=server_pid @json:'{"url":"https://localhost:8443/domain","processing":{"script_folder":"tests"}}'
+faspex5 shared browse %name:my_src
+faspex5 shared list
+faspex5 shared_folders browse %name:my_shared_folder_name
+faspex5 shared_folders list
 faspex5 user profile modify @json:'{"preference":{"connect_disabled":false}}'
 faspex5 user profile show
 ```
 
-### Faspex 5: inbox selection
+### Faspex 5: Inbox selection
 
 By default, package operations (send, receive, list) are done on the user's inbox.
 
@@ -5150,7 +5711,15 @@ The following parameters in option `query` are supported:
 
 Admin only: If the value `ALL` is provided to option `box`, then all packages are selected.
 
-### Faspex 5: List all shared inboxes
+### Faspex 5: List all shared inboxes and work groups
+
+If you are a regular user, to list work groups you belong to:
+
+```bash
+ascli faspex5 admin res workgroup list
+```
+
+If you are admin or manager, add option: `--query=@json:'{"all":true}'`, this will list items you manage, even if you do not belong to them.
 
 ```bash
 ascli faspex5 admin res shared list --query=@json:'{"all":true}' --fields=id,name
@@ -5159,16 +5728,16 @@ ascli faspex5 admin res shared list --query=@json:'{"all":true}' --fields=id,nam
 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_inboxes invite '%name:ascli shinbox' john@example.com
+ascli faspex5 admin res shared_inboxes invite '%name:the shared inbox' john@example.com
 ```
 
 It is equivalent to:
 
 ```bash
-ascli faspex5 admin res shared_inboxes invite '%name:ascli shinbox' @json:'{"email_address":"john@example.com"}'
+ascli faspex5 admin res shared_inboxes invite '%name:the shared inbox' @json:'{"email_address":"john@example.com"}'
 ```
 
-Other payload parameters are possible in Hash format:
+Other payload parameters are possible the `Hash` value:
 
 ```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
@@ -5210,7 +5779,7 @@ ascli faspex5 packages send @json:'{"title":"hello","recipients":[{"name":"_reci
 
 > **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)
+### Faspex 5: Receive all packages (cargo)
 
 To receive all packages, only once, through persistency of already received packages:
 
@@ -5310,7 +5879,7 @@ The API is listed in [Faspex 4 API Reference](https://developer.ibm.com/apis/cat
 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
+#### Example: List packages in dropbox
 
 ```bash
 ascli faspex package list --box=inbox --recipient='*my_dropbox' --query=@json:'{"max":20,"pmax":2,"count":20}'
@@ -5342,13 +5911,14 @@ if `id` is set to `ALL`, then all packages are downloaded, and if option `once_o
 
 ### Sending a Package
 
-The command is `faspex package send`. Package information (title, note, metadata, options) is provided in option `delivery_info`.
-The contents of `delivery_info` is directly the contents of the `send` v3 [API of Faspex 4](https://developer.ibm.com/apis/catalog/aspera--aspera-faspex-client-sdk/API%20v.3:%20Send%20Packages), consult it for extended supported parameters.
+The command is `faspex package send`.
+Package information (title, note, metadata, options) is provided in option `delivery_info`.
+The contents of `delivery_info` is directly the contents of the `send` v3 [API of Faspex 4](https://developer.ibm.com/apis/catalog/aspera--aspera-faspex-client-sdk/API%20v.3:%20Send%20Packages).
 
 Example:
 
 ```bash
-ascli faspex package send --delivery-info=@json:'{"title":"my title","recipients":["laurent.martin.aspera@fr.ibm.com"]}' --url=https://faspex.corp.com/aspera/faspex --username=foo --password=bar /tmp/file1 /home/bar/file2
+ascli faspex package send --delivery-info=@json:'{"title":"my title","recipients":["someuser@example.com"]}' --url=https://faspex.corp.com/aspera/faspex --username=foo --password=bar /tmp/file1 /home/bar/file2
 ```
 
 If the recipient is a dropbox or workgroup: provide the name of the dropbox or workgroup preceded with `*` in the `recipients` field of the `delivery_info` option:
@@ -5359,19 +5929,29 @@ Additional optional parameters in `delivery_info`:
 - Package Note: : `"note":"note this and that"`
 - Package Metadata: `"metadata":{"Meta1":"Val1","Meta2":"Val2"}`
 
+It is possible to send from a remote source using option `remote_source`, providing either the numerical id, or the name of the remote source using percent selector: `%name:<name>`.
+
+Remote source can be browsed if option `storage` is provided.
+`storage` is a `Hash` extended value.
+The key is the storage name, as listed in `source list` command.
+The value is a `Hash` with the following keys:
+
+- `node` is a `Hash` with keys: `url`, `username`, `password`
+- `path` is the subpath inside the node, as configured in Faspex
+
 ### Email notification on transfer
 
-Like for any transfer, a notification can be sent by email using parameters: `notif_to` and `notif_template` .
+Like for any transfer, a notification can be sent by email using parameters: `notify_to` and `notify_template` .
 
 Example:
 
 ```bash
-ascli faspex package send --delivery-info=@json:'{"title":"test pkg 1","recipients":["aspera.user1@gmail.com"]}' ~/Documents/Samples/200KB.1 --notif-to=aspera.user1@gmail.com --notif-template=@ruby:'%Q{From: <%=from_name%> <<%=from_email%>>\nTo: <<%=to%>>\nSubject: Package sent: <%=ts["tags"]["aspera"]["faspex"]["metadata"]["_pkg_name"]%> files received\n\nTo user: <%=ts["tags"]["aspera"]["faspex"]["recipients"].first["email"]%>}'
+ascli faspex package send --delivery-info=@json:'{"title":"test pkg 1","recipients":["aspera.user1@gmail.com"]}' ~/Documents/Samples/200KB.1 --notify-to=aspera.user1@gmail.com --notify-template=@ruby:'%Q{From: <%=from_name%> <<%=from_email%>>\nTo: <<%=to%>>\nSubject: Package sent: <%=ts["tags"]["aspera"]["faspex"]["metadata"]["_pkg_name"]%> files received\n\nTo user: <%=ts["tags"]["aspera"]["faspex"]["recipients"].first["email"]%>}'
 ```
 
 In this example the notification template is directly provided on command line. Package information placed in the message are directly taken from the tags in transfer spec. The template can be placed in a file using modifier: `@file:`
 
-### Operation on dropboxes
+### Operation on "dropboxes"
 
 Example:
 
@@ -5406,9 +5986,9 @@ my_faspex_node:
 
 In this example, a faspex storage named `my_storage` exists in Faspex, and is located
 under the docroot in `/mydir` (this must be the same as configured in Faspex).
-The node configuration name is "my_faspex_node" here.
+The node configuration name is `my_faspex_node` here.
 
-Note: the v4 API provides an API for nodes and shares.
+> **Note:** the v4 API provides an API for nodes and shares.
 
 ### Automated package download (cargo)
 
@@ -5423,30 +6003,30 @@ ascli faspex packages recv ALL --once-only=yes --lock-port=12345
 
 ```bash
 faspex address_book
-faspex dropbox list --recipient="*my_faspex_dbx"
-faspex dropbox list --recipient="*my_faspex_wkg"
+faspex dropbox list --recipient="*my_dbx"
 faspex health
 faspex login_methods
 faspex me
-faspex package list
 faspex package list --box=sent --fields=package_id --format=csv --display=data --query=@json:'{"max":1}'
 faspex package list --fields=package_id --format=csv --display=data --query=@json:'{"max":1}'
-faspex package list --recipient="*my_faspex_dbx" --format=csv --fields=package_id --query=@json:'{"max":1}'
-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 list --query=@json:'{"max":5}'
+faspex package list --recipient="*my_dbx" --format=csv --fields=package_id --query=@json:'{"max":1}'
+faspex package list --recipient="*my_wkg" --format=csv --fields=package_id --query=@json:'{"max":1}'
 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=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 package recv ALL --to-folder=. --once-only=yes --query=@json:'{"max":10}'
+faspex package recv f4_db_id1 --recipient="*my_dbx" --to-folder=.
+faspex package recv f4_db_id2 --recipient="*my_wkg" --to-folder=.
+faspex package recv f4_pri1 --to-folder=.
+faspex package recv f4_prs2 --to-folder=. --box=sent
+faspex package send --delivery-info=@json:'{"title":"Important files delivery","recipients":["*my_dbx"]}' test_file.bin
+faspex package send --delivery-info=@json:'{"title":"Important files delivery","recipients":["*my_wkg"]}' test_file.bin
+faspex package send --delivery-info=@json:'{"title":"Important files delivery","recipients":["my_email_internal","my_username"]}' test_file.bin
+faspex package send --delivery-info=@json:'{"title":"TIMESTAMP package remote","recipients":["my_email_internal"]}' --remote_source=%name:my_src sample_source.txt
+faspex package send --link=https://app.example.com/send_to_dropbox_path --delivery-info=@json:'{"title":"Important files delivery"}' test_file.bin
+faspex package send --link=https://app.example.com/send_to_user_path --delivery-info=@json:'{"title":"Important files delivery"}' test_file.bin
+faspex source info %name:my_src --storage=@preset:faspex4_storage
 faspex source list
-faspex source name my_faspex_src info
-faspex source name my_faspex_src node br /
+faspex source node %name:my_src br / --storage=@preset:faspex4_storage
 faspex v4 dmembership list
 faspex v4 dropbox list
 faspex v4 metadata_profile list
@@ -5464,21 +6044,23 @@ Aspera Shares supports the "node API" for the file transfer part.
 ```bash
 shares admin group list
 shares admin node list
-shares admin share list --fields=-status,status_message
+shares admin share list --fields=DEF,-status,status_message
 shares admin share user_permissions 1 list
 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 @json:'{"id":"the_id","name_id":"the_name"}'
 shares admin user list
+shares admin user list --type=local
 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 files delete my_share1/test_file.bin
+shares files download --to-folder=. my_share1/test_file.bin
+shares files download --to-folder=. my_share1/test_file.bin --transfer=httpgw --transfer-info=@json:'{"url":"https://my_http_gw_fqdn_port/aspera/http-gwy"}'
+shares files upload --to-folder=my_share1 'faux:///testfile?1m' --transfer=httpgw --transfer-info=@json:'{"url":"https://my_http_gw_fqdn_port/aspera/http-gwy","synchronous":true,"api_version":"v1","upload_chunk_size":100000}'
+shares files upload --to-folder=my_share1 test_file.bin
+shares files upload --to-folder=my_share1 test_file.bin --transfer=httpgw --transfer-info=@json:'{"url":"https://my_http_gw_fqdn_port/aspera/http-gwy"}'
 shares health
 ```
 
@@ -5490,7 +6072,7 @@ shares health
 console health
 console transfer current list
 console transfer smart list
-console transfer smart sub my_job_id @json:'{"source":{"paths":["my_file_name"]},"source_type":"user_selected"}'
+console transfer smart sub my_smart_id @json:'{"source":{"paths":["my_smart_file"]},"source_type":"user_selected"}'
 ```
 
 ## <a id="orchestrator"></a>Plugin: `orchestrator`:IBM Aspera Orchestrator
@@ -5502,14 +6084,14 @@ orchestrator health
 orchestrator info
 orchestrator plugins
 orchestrator processes
-orchestrator workflow details my_orch_workflow_id
-orchestrator workflow export my_orch_workflow_id
-orchestrator workflow inputs my_orch_workflow_id
+orchestrator workflow details my_workflow_id
+orchestrator workflow export my_workflow_id
+orchestrator workflow inputs my_workflow_id
 orchestrator workflow list
-orchestrator workflow start my_orch_workflow_id --params=@json:'{"Param":"world !"}'
-orchestrator workflow start my_orch_workflow_id --params=@json:'{"Param":"world !"}' --result=ResultStep:Complete_status_message
+orchestrator workflow start my_workflow_id @json:'{"Param":"world !"}'
+orchestrator workflow start my_workflow_id @json:'{"Param":"world !"}' --result=ResultStep:Complete_status_message
 orchestrator workflow status ALL
-orchestrator workflow status my_orch_workflow_id
+orchestrator workflow status my_workflow_id
 ```
 
 ## <a id="cos"></a>Plugin: `cos`: IBM Cloud Object Storage
@@ -5519,10 +6101,10 @@ It uses the same transfer service as Aspera on Cloud, called Aspera Transfer Ser
 Available ATS regions: [https://status.aspera.io](https://status.aspera.io)
 
 There are two possibilities to provide credentials.
-If you already have the endpoint, apikey and CRN, use the first method.
+If you already have the endpoint, API key and CRN, use the first method.
 If you don't have credentials but have access to the IBM Cloud console, then use the second method.
 
-### Using endpoint, apikey and Resource Instance ID (CRN)
+### Using endpoint, API key and Resource Instance ID (CRN)
 
 If you have those parameters already, then following options shall be provided:
 
@@ -5613,56 +6195,54 @@ ascli cos node info
 ascli cos node upload 'faux:///sample1G?1g'
 ```
 
-Note: we generate a dummy file `sample1G` of size 2GB using the `faux` PVCL (man `ascp` and section above), but you can of course send a real file by specifying a real file instead.
+> **Note:** we generate a dummy file `sample1G` of size 2GB using the `faux` PVCL (man `ascp` and section above), but you can of course send a real file by specifying a real file instead.
 
 ### COS sample commands
 
 ```bash
-cos --bucket=my_icos_bucket_name --endpoint=my_icos_bucket_endpoint --apikey=my_icos_bucket_apikey --crn=my_icos_resource_instance_id node info
-cos --bucket=my_icos_bucket_name --region=my_icos_bucket_region --service-credentials=@json:@file:service_creds.json node info
+cos --bucket=my_bucket_name --endpoint=my_bucket_endpoint --apikey=my_bucket_apikey --crn=my_resource_instance_id node info
+cos --bucket=my_bucket_name --region=my_bucket_region --service-credentials=@json:@file:service_creds.json node info
 cos node access_key show self
-cos node download testfile.bin --to-folder=.
-cos node info
-cos node upload testfile.bin
+cos node download test_file.bin --to-folder=.
+cos node info --log-level=trace2
+cos node upload test_file.bin
 ```
 
-## <a id="async"></a>Plugin: `async`: IBM Aspera Sync
+## <a id="async"></a>IBM Aspera Sync
+
+An interface for the `async` utility is provided in the following plugins:
+
+- server sync
+- node sync
+- aoc files sync (uses node)
+- shares files sync (uses node)
 
-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`.
+The main advantage over the `async` command line when using `server` is the possibility to use a configuration file, using standard options of `ascli`.
 
-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).
+In this case, some of the `sync` parameters are filled by the related plugin using transfer spec parameters (e.g. including token).
 
 > **Note:** All `sync` commands require an `async` enabled license and availability of the `async` executable (and `asyncadmin`).
 
 Two JSON syntax are supported for option `sync_info`.
 
-### async native JSON
+### async JSON: API format
 
-It is the same payload as specified on the `async` option `--conf` or in the latest node API.
+It is the same payload as specified on the option `--conf` of `async` or in node API `/asyncs`.
 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
+### async JSON: Options mapping
 
-This is specific to `ascli`.
+`ascli` defines a JSON equivalent to regular `async`options.
 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
-sync admin status --sync-info=@json:'{"sessions":[{"name":"test","local_dir":"contents"}]}'
-sync start --sync-info=@json:'{"instance":{"quiet":true},"sessions":[{"name":"test","reset":true,"remote_dir":"/sync_test","local_dir":"contents","host":"my_remote_host","tcp_port":33001,"user":"my_remote_user","private_key_paths":["my_local_user_key"]}]}'
-```
-
 ## <a id="preview"></a>Plugin: `preview`: Preview generator for AoC
 
 The `preview` generates thumbnails (office, images, video) and video previews on storage for use primarily in the Aspera on Cloud application.
-It uses the **node API** of Aspera HSTS and requires use of Access Keys and it's **storage root**.
+It uses the **node API** of Aspera HSTS and requires use of Access Keys and its **storage root**.
 Several parameters can be used to tune several aspects:
 
 - Methods for detection of new files needing generation
@@ -5684,7 +6264,7 @@ asconfigurator -x "server;preview_dir,previews"
 asnodeadmin --reload
 ```
 
-Note: the configuration `preview_dir` is *relative* to the storage root, no need leading or trailing `/`. In general just set the value to `previews`
+> **Note:** the configuration `preview_dir` is **relative** to the storage root, no need leading or trailing `/`. In general just set the value to `previews`
 
 If another folder is configured on the HSTS, then specify it to `ascli` using the option `previews_folder`.
 
@@ -5703,16 +6283,16 @@ asconfigurator -x "server; max_request_file_create_size_kb,16384"
 
 If you use a value different than 16777216, then specify it using option `max_size`.
 
-Note: the HSTS parameter (max_request_file_create_size_kb) is in *kiloBytes* while the generator parameter is in *Bytes* (factor of 1024).
+> **Note:** the HSTS parameter (`max_request_file_create_size_kb`) is in **kiloBytes** while the generator parameter is in **Bytes** (factor of 1024).
 
 ### <a id="prev_ext"></a>External tools: Linux
 
-The tool requires the following external tools available in the `PATH`:
+`ascli` requires the following external tools available in the `PATH`:
 
 - ImageMagick : `convert` `composite`
-- OptiPNG : `optipng`
-- FFmpeg : `ffmpeg` `ffprobe`
-- Libreoffice : `libreoffice`
+- "OptiPNG" : `optipng`
+- "FFmpeg" : `ffmpeg` `ffprobe`
+- "Libreoffice" : `libreoffice`
 
 Here shown on Redhat/CentOS.
 
@@ -5724,7 +6304,7 @@ To check if all tools are found properly, execute:
 ascli preview check
 ```
 
-#### Image: ImageMagick and optipng
+#### Image: ImageMagick and `optipng`
 
 ```bash
 dnf install -y ImageMagick optipng
@@ -5734,6 +6314,8 @@ You may also install `ghostscript` which adds fonts to ImageMagick.
 Available fonts, used to generate png for text, can be listed with `magick identify -list font`.
 Prefer ImageMagick version >=7.
 
+More info on ImageMagick at <https://imagemagick.org/>
+
 #### Video: FFmpeg
 
 The easiest method is to download and install the latest released version of ffmpeg with static libraries from [https://johnvansickle.com/ffmpeg/](https://johnvansickle.com/ffmpeg/)
@@ -5742,7 +6324,7 @@ The easiest method is to download and install the latest released version of ffm
 curl -s https://johnvansickle.com/ffmpeg/releases/ffmpeg-release-amd64-static.tar.xz|(mkdir -p /opt && cd /opt && rm -f ffmpeg /usr/bin/{ffmpeg,ffprobe} && rm -fr ffmpeg-*-amd64-static && tar xJvf - && ln -s ffmpeg-* ffmpeg && ln -s /opt/ffmpeg/{ffmpeg,ffprobe} /usr/bin)
 ```
 
-#### Office: Unoconv and Libreoffice
+#### Office: `unoconv` and Libreoffice
 
 If you don't want to have preview for office documents or if it is too complex you can skip office document preview generation by using option: `--skip-types=office`
 
@@ -5799,11 +6381,11 @@ This shall list the contents of the storage root of the access key.
 
 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`.
+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).
+`ascli` 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 [Scheduler](#scheduler).
 
@@ -5835,7 +6417,7 @@ case "$*" in *trev*) tmout=10m ;; *) tmout=30m ;; esac
 
 ### Candidate detection for creation or update (or deletion)
 
-The tool generates preview files using those commands:
+`ascli` generates preview files using those commands:
 
 - `trevents` : only recently uploaded files will be tested (transfer events)
 - `events` : only recently uploaded files will be tested (file events: not working)
@@ -5861,13 +6443,9 @@ 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 `query` has the same behavior as for the `node find` command.
-
-For instance to filter out files beginning with `._` do:
+When scanning the option `query` has the same behavior as for the `node access_keys do self find` command.
 
-```bash
---query='exec:!f["name"].start_with?("._") or f["name"].eql?(".DS_Store")'
-```
+Refer to that section for details.
 
 ### Preview File types
 
@@ -5896,28 +6474,28 @@ The mp4 video preview file is only for category `video`
 
 File type is primarily based on file extension detected by the node API and translated info a mime type returned by the node API.
 
-### mimemagic
+### `mimemagic`
 
 By default, the Mime type used for conversion is the one returned by the node API, based on file name extension.
 
 It is also possible to detect the mime type using option `mimemagic`.
 To use it, set option `mimemagic` to `yes`: `--mimemagic=yes`.
 
-This requires to manually install the mimemagic gem: `gem install mimemagic`.
+This requires to manually install the `mimemagic` gem: `gem install mimemagic`.
 
-In this case the `preview` command will first analyze the file content using mimemagic, and if no match, will try by extension.
+In this case the `preview` command will first analyze the file content using `mimemagic`, and if no match, will try by extension.
 
 If the `mimemagic` gem complains about missing mime info file:
 
 - any OS:
 
   - Examine the error message
-  - Download the file: [freedesktop.org.xml.in](https://gitlab.freedesktop.org/xdg/shared-mime-info/-/raw/master/data/freedesktop.org.xml.in)
-  - move and rename this file to one of the locations expected by mimemagic as specified in the error message
+  - Download the file: [`freedesktop.org.xml.in`](https://gitlab.freedesktop.org/xdg/shared-mime-info/-/raw/master/data/freedesktop.org.xml.in)
+  - move and rename this file to one of the locations expected by `mimemagic` as specified in the error message
 
 - Windows:
 
-  - Download the file: [freedesktop.org.xml.in](https://gitlab.freedesktop.org/xdg/shared-mime-info/-/raw/master/data/freedesktop.org.xml.in)
+  - Download the file: [`freedesktop.org.xml.in`](https://gitlab.freedesktop.org/xdg/shared-mime-info/-/raw/master/data/freedesktop.org.xml.in)
   - Place this file in the root of Ruby (or elsewhere): `C:\RubyVV-x64\freedesktop.org.xml.in`
   - Set a global variable using `SystemPropertiesAdvanced.exe` or using `cmd` (replace `VV` with version) to the exact path of this file:
 
@@ -5943,7 +6521,7 @@ brew install shared-mime-info
 
 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.
-The tool provides 2 ways to read and write files with the option: `file_access`
+`ascli` provides 2 ways to read and write files with the option: `file_access`
 
 If the preview generator is run on a system that has direct access to the file system, then the value `local` can be used. In this case, no transfer happen, source files are directly read from the storage, and preview files
 are directly written to the storage.
@@ -5956,14 +6534,14 @@ If the preview generator does not have access to files on the file system (it is
 preview check --skip-types=office
 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
-preview test --case=test mp4 my_file_mxf --video-conversion=reencode --log-level=debug
-preview test --case=test png my_file_dcm --log-level=debug
-preview test --case=test png my_file_docx --log-level=debug
-preview test --case=test png my_file_mxf --video-png-conv=animated --log-level=debug
-preview test --case=test png my_file_mxf --video-png-conv=fixed --log-level=debug
-preview test --case=test png my_file_pdf --log-level=debug
+preview show --base=test my_docx
+preview show --base=test my_mpg --video-png-conv=animated
+preview show --base=test my_mpg --video-png-conv=fixed
+preview show --base=test my_mpg mp4 --video-conversion=clips
+preview show --base=test my_mpg mp4 --video-conversion=reencode
+preview show --base=test my_pdf
+preview test --base=test my_dcm
+preview test --base=test my_mxf mp4 --video-conversion=blend --query=@json:'{"text":true,"double":true}'
 preview trevents --once-only=yes --skip-types=office --log-level=info
 ```
 
@@ -5971,7 +6549,7 @@ preview trevents --once-only=yes --skip-types=office --log-level=info
 
 `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:
+The `smtp` option is a `Hash` (extended value) with the following fields:
 
 <!-- markdownlint-disable MD034 -->
 | field        | default             | example                    | description                      |
@@ -6034,16 +6612,16 @@ Check settings with `smtp_settings` command. Send test email with `email_test`.
 
 ```bash
 ascli config --smtp=@preset:smtp_google smtp
-ascli config --smtp=@preset:smtp_google email --notif-to=sample.dest@example.com
+ascli config --smtp=@preset:smtp_google email --notify-to=sample.dest@example.com
 ```
 
 ### Notifications for transfer status
 
 An e-mail notification can be sent upon transfer success and failure (one email per transfer job, one job being possibly multi session, and possibly after retry).
 
-To activate, use option `notif_to`.
+To activate, use option `notify_to`.
 
-A default e-mail template is used, but it can be overridden with option `notif_template`.
+A default e-mail template is used, but it can be overridden with option `notify_template`.
 
 The environment provided contains the following additional variables:
 
@@ -6076,24 +6654,24 @@ Hopefully, IBM integrates this directly in `ascp`, and this tool is made redunda
 
 This makes it easy to integrate with any language provided that one can spawn a sub process, write to its STDIN, read from STDOUT, generate and parse JSON.
 
-The tool expect one single argument: a [*transfer-spec*](#transferspec).
+`ascli` expect one single argument: a [*transfer-spec*](#transferspec).
 
 If no argument is provided, it assumes a value of: `@json:@stdin:`, i.e. a JSON formatted [*transfer-spec*](#transferspec) on stdin.
 
-> **Note:** If JSON is the format, specify `@json:` to tell `ascli` to decode the hash using JSON syntax.
+> **Note:** If JSON is the format, specify `@json:` to tell `ascli` to decode the `Hash` using JSON syntax.
 
 During execution, it generates all low level events, one per line, in JSON format on stdout.
 
 There are special "extended" [*transfer-spec*](#transferspec) parameters supported by `asession`:
 
-- `EX_loglevel` to change log level of the tool
+- `EX_loglevel` to change log level of `ascli`
 - `EX_file_list_folder` to set the folder used to store (exclusively, because of garbage collection) generated file lists. By default it is `[system tmp folder]/[username]_asession_filelists`
 
 > **Note:** In addition, many "EX_" [*transfer-spec*](#transferspec) parameters are supported for the [`direct`](#agt_direct) transfer agent (used by `asession`), refer to section [*transfer-spec*](#transferspec).
 
 ### Comparison of interfaces
 
-| feature/tool | asession | `ascp` | FaspManager | Transfer SDK |
+| feature/tool | `asession` | `ascp` | FaspManager | Transfer SDK |
 |--------------|----------|--------|-------------|--------------|
 | language integration | any | any | C/C++<br/>C#/.net<br/>Go<br/>Python<br/>java<br/> | many |
 | required additional components to `ascp` | Ruby<br/>Aspera | - | library<br/>(headers) | daemon |
@@ -6203,7 +6781,7 @@ Interesting `ascp` features are found in its arguments: (see `ascp` manual):
 
 Virtually any transfer on a "repository" on a regular basis might emulate a hot folder.
 
-> **Note:** file detection is not based on events (inotify, etc...), but on a simple folder scan on source side.
+> **Note:** file detection is not based on events (`inotify`, etc...), but on a simple folder scan on source side.
 >
 > **Note:** parameters may be saved in a [option preset](#lprt) and used with `-P`.
 
@@ -6212,7 +6790,7 @@ Virtually any transfer on a "repository" on a regular basis might emulate a hot
 Once `ascli` parameters are defined, run the command using the OS native scheduler, e.g. every minutes, or 5 minutes, etc...
 Refer to section [Scheduler](#scheduler). (on use of option `lock_port`)
 
-### Example: upload hot folder
+### Example: Upload hot folder
 
 ```bash
 ascli server upload source_hot --to-folder=/Upload/target_hot --lock-port=12345 --ts=@json:'{"remove_after_transfer":true,"remove_empty_directories":true,"exclude_newer_than:-8,"src_base":"source_hot"}'
@@ -6223,7 +6801,7 @@ Source files are deleted after transfer.
 Growing files will be sent only once they don't grow anymore (based on an 8-second cool-off period).
 If a transfer takes more than the execution period, then the subsequent execution is skipped (`lock_port`) preventing multiple concurrent runs.
 
-### Example: unidirectional synchronization (upload) to server
+### Example: Unidirectional synchronization (upload) to server
 
 ```bash
 ascli server upload source_sync --to-folder=/Upload/target_sync --lock-port=12345 --ts=@json:'{"resume_policy":"sparse_csum","exclude_newer_than":-8,"src_base":"source_sync"}'
@@ -6231,11 +6809,10 @@ ascli server upload source_sync --to-folder=/Upload/target_sync --lock-port=1234
 
 This can also be used with other folder-based applications: Aspera on Cloud, Shares, Node:
 
-### Example: unidirectional synchronization (download) from Aspera on Cloud Files
+### Example: Unidirectional synchronization (download) from Aspera on Cloud Files
 
 ```bash
-ascli aoc files download . --to-folder=. --lock-port=12345 --progress=none --display=data \
---ts=@json:'{"resume_policy":"sparse_csum","target_rate_kbps":50000,"exclude_newer_than":-8,"delete_before_transfer":true}'
+ascli aoc files download . --to-folder=. --lock-port=12345 --progress-bar=no --display=data --ts=@json:'{"resume_policy":"sparse_csum","target_rate_kbps":50000,"exclude_newer_than":-8,"delete_before_transfer":true}'
 ```
 
 > **Note:** option `delete_before_transfer` will delete files locally, if they are not present on remote side.
@@ -6267,7 +6844,7 @@ Typically, the health check uses the REST API of the application with the follow
 `ascli` can be called by Nagios to check the health status of an Aspera server. The output can be made compatible to Nagios with option `--format=nagios` :
 
 ```bash
-ascli server health transfer --to-folder=/Upload --format=nagios --progress=none
+ascli server health transfer --to-folder=/Upload --format=nagios --progress-bar=no
 ```
 
 ```output
@@ -6305,8 +6882,8 @@ Also, because there was already the `ascp` tool, I thought of an extended tool :
 
 There were a few pitfalls:
 
-- The tool was written in the aging `perl` language while most Aspera web application products (but the Transfer Server) are written in `ruby`.
-- The tool was only for transfers, but not able to call other products APIs
+- `ascli` was written in the aging `perl` language while most Aspera web application products (but the Transfer Server) are written in `ruby`.
+- `ascli` was only for transfers, but not able to call other products APIs
 
 So, it evolved into `ascli`:
 
@@ -6346,7 +6923,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:
-`ruby-dev` ir `ruby-devel`, depending on distribution.
+`ruby-dev` or `ruby-devel`, depending on distribution.
 
 ### ED255519 key not supported