aspera-cli 4.16.0 → 4.17.0

data/README.md

@@ -10,7 +10,7 @@
 
 ## Introduction
 
-Version : 4.16.0
+Version : 4.17.0
 
 Laurent/2016-2024
 
@@ -37,7 +37,7 @@ A PDF version of this documentation is available here: [docs/Manual.pdf](docs/Ma
 
 Refer to [BUGS.md](BUGS.md) and [CONTRIBUTING.md](CONTRIBUTING.md).
 
-### <a id="when_to_use"></a>When to use and when not to use
+### When to use and when not to use
 
 `ascli` is designed to be used as a command line tool to:
 
@@ -52,7 +52,7 @@ It is designed for:
 `ascli` can be seen as a command line tool integrating:
 
 - A configuration file (`config.yaml`)
-- Advanced command line options ([Extended Value](#extended))
+- Advanced command line options ([Extended Value](#extended-value-syntax))
 - `curl` (for REST calls)
 - Aspera transfer (`ascp`)
 
@@ -75,10 +75,10 @@ Command line parameters in examples beginning with `my_`, e.g. `my_param_value`,
 `ascli` is an API **Client** toward the remote Aspera application **Server** (Faspex, HSTS, etc...)
 
 Some commands will start an Aspera-based transfer (e.g. `upload`).
-The transfer is not directly implemented in `ascli`, rather `ascli` uses one of the external Aspera Transfer Clients called **[Transfer Agents](#agents)**.
+The transfer is not directly implemented in `ascli`, rather `ascli` uses one of the external Aspera Transfer Clients called **[Transfer Agents](#transfer-clients-agents)**.
 
-> **Note:** A **[Transfer Agents](#agents)** is a client for the remote Transfer Server (HSTS).
-The **[Transfer Agents](#agents)** may be local or remote...
+> **Note:** A **[Transfer Agents](#transfer-clients-agents)** is a client for the remote Transfer Server (HSTS).
+The **[Transfer Agents](#transfer-clients-agents)** may be local or remote...
 For example a remote Aspera Server may be used as a transfer agent (using node API).
 i.e. using option `--transfer=node`
 
@@ -92,14 +92,14 @@ Once the gem is installed, `ascli` shall be accessible:
 
 ```console
 $ ascli --version
-4.16.0
+4.17.0
 ```
 
 ### First use
 
 Once installation is completed, you can proceed to the first use with a demo server:
 
-If you want to test with Aspera on Cloud, jump to section: [Wizard](#aocwizard).
+If you want to test with Aspera on Cloud, jump to section: [Wizard](#configuration-using-wizard).
 
 To test with Aspera demo transfer server, setup the environment and then test:
 
@@ -122,10 +122,10 @@ ascli server browse /
 +------------+--------+-----------+-------+---------------------------+-----------------------+
 ```
 
-If you want to use `ascli` with another server, and in order to make further calls more convenient, it is advised to define a [option preset](#lprt) for the server's authentication options.
+If you want to use `ascli` with another server, and in order to make further calls more convenient, it is advised to define a [Option Preset](#option-preset)' for the server's authentication options.
 The following example will:
 
-- Create a [option preset](#lprt)
+- Create a [Option Preset](#option-preset)'
 - Define it as default for the `server` plugin
 - List files in a folder
 - Download a file
@@ -177,19 +177,19 @@ complete
 
 ### Going further
 
-Get familiar with configuration, options, commands : [Command Line Interface](#cli).
+Get familiar with configuration, options, commands : [Command Line Interface](#command-line-interface).
 
 Then, follow the section relative to the product you want to interact with ( Aspera on Cloud, Faspex, ...) : [Application Plugins](plugins)
 
-## <a id="installation"></a>Installation
+## Installation
 
 It is possible to install **either** directly on the host operating system (Linux, macOS, Windows) or as a [container](#container) (`docker`, `podman`, `singularity`).
 
 The direct installation is recommended and consists in installing:
 
 - [Ruby](#ruby)
-- [aspera-cli](#the_gem)
-- [Aspera SDK (`ascp`)](#fasp_prot)
+- [aspera-cli](#ruby-gem)
+- [Aspera SDK (`ascp`)](#fasp-protocol)
 
 Ruby version: >= 2.6.
 
@@ -198,11 +198,11 @@ Ruby version: >= 2.6.
 The following sections provide information on the various installation methods.
 
 An internet connection is required for the installation.
-If you don't have internet for the installation, refer to section [Installation without internet access](#offline_install).
+If you don't have internet for the installation, refer to section [Installation without internet access](#installation-in-air-gapped-environment).
 
 A package with pre-installed Ruby, gem and ascp may also be provided.
 
-### <a id="ruby"></a>Ruby
+### Ruby
 
 Use this method to install on the native host (e.g. your Windows, macOS or Linux system).
 
@@ -253,7 +253,7 @@ Install the chosen pre-compiled Ruby version:
 rvm install 3.2.2
 ```
 
-Ruby is now installed for the user, go to [Gem installation](#the_gem).
+Ruby is now installed for the user, go to [Gem installation](#ruby-gem).
 
 Alternatively RVM can be installed system-wide, for this execute as `root`.
 It then installs by default in `/usr/local/rvm` for all users and creates `/etc/profile.d/rvm.sh`.
@@ -434,11 +434,34 @@ make
 make install
 ```
 
-If you already have a Java JVM on your system (`java`), it is possible to use `jruby`:
+#### JRuby
+
+`ascli` can also run with the [JRuby](https://www.jruby.org/) interpreter.
+All what is needed is a JVM (Java Virtual Machine) on your system (`java`).
+The JRuby package comes pre-complied and does not require compilation of native extensions.
+Use a version of JRuby compatible with Ruby version supported by `ascli`.
+Refer to [the wikipedia page](https://en.wikipedia.org/wiki/JRuby) to match JRuby and Ruby versions.
+Choose the latest version from:
 
 <https://www.jruby.org/download>
 
-> **Note:** Using `jruby`, the startup time is longer than the native Ruby, but transfer speed is not impacted (executed by `ascp` binary).
+> **Note:** The startup time is slightly longer using `jruby` than the native Ruby, refer to the [JRuby wiki](https://github.com/jruby/jruby/wiki) for details. This can be reduced by using the `--dev` option.
+> The transfer speed is not impacted (executed by `ascp` binary).
+>
+> **Note:** JRuby can be [installed](https://www.jruby.org/getting-started) using `rvm`.
+
+Example: start `ascli` with JRuby and reduce startup time:
+
+```bash
+export JRUBY_OPTS=--dev
+ascli -v
+```
+
+or
+
+```bash
+JRUBY_OPTS=--dev ascli -v
+```
 
 #### Optional gems
 
@@ -456,7 +479,7 @@ gem install rmagick grpc mimemagic
 
 > **Note:** Those are not installed as part of dependencies because they involve compilation of native code.
 
-### <a id="the_gem"></a>`aspera-cli` gem
+### Ruby Gem
 
 Once you have Ruby and rights to install gems, install the `aspera-cli` gem and its dependencies:
 
@@ -479,7 +502,7 @@ To check if a new version is available (independently of `version_check_days`):
 ascli config check_update
 ```
 
-### <a id="fasp_prot"></a>FASP Protocol
+### FASP Protocol
 
 Most file transfers will be executed using the **FASP** protocol, using `ascp`.
 Only two additional files are required to perform an Aspera Transfer, which are part of Aspera SDK:
@@ -516,13 +539,13 @@ For instance, Aspera Connect Client can be installed by visiting the page:
 [https://www.ibm.com/aspera/connect/](https://www.ibm.com/aspera/connect/).
 
 `ascli` will detect most of Aspera transfer products in standard locations and use the first one found by default.
-Refer to section [FASP](#client) for details on how to select a client or set path to the FASP protocol.
+Refer to section [FASP](#fasp-configuration) for details on how to select a client or set path to the FASP protocol.
 
 Several methods are provided to start a transfer.
-Use of a local client ([`direct`](#agt_direct) transfer agent) is one of them, but other methods are available.
-Refer to section: [Transfer Agents](#agents)
+Use of a local client ([`direct`](#agent-direct) transfer agent) is one of them, but other methods are available.
+Refer to section: [Transfer Agents](#transfer-clients-agents)
 
-### <a id="offline_install"></a>Installation in air gapped environment
+### Installation in air gapped environment
 
 > **Note:** No pre-packaged version is provided yet.
 
@@ -636,7 +659,7 @@ ascli -v
 ```
 
 ```text
-4.16.0
+4.17.0
 ```
 
 In order to keep persistency of configuration on the host, you should specify your user's configuration folder as a volume for the container.
@@ -779,7 +802,9 @@ Or get a shell with access to `ascli` like this:
 singularity shell ascli.sif
 ```
 
-## <a id="cli"></a>Command Line Interface: `ascli`
+## Command Line Interface
+
+The command line tool is: ``ascli``
 
 The `aspera-cli` gem provides a command line interface (CLI) which interacts with Aspera Products (mostly using REST APIs):
 
@@ -796,8 +821,8 @@ The `aspera-cli` gem provides a command line interface (CLI) which interacts wit
 - Supports commands to Aspera server products (on-premise and SaaS)
 - Any command line **options** (products URL, credentials or any option) can be provided on command line, in configuration file, in env var, in files, ...
 - Supports Commands, Option values and Parameters shortcuts
-- FASP [Transfer Agents](#agents) can be: local `ascp`, or Connect Client, or any transfer node
-- Transfer parameters can be altered by modification of [*transfer-spec*](#transferspec), this includes requiring multi-session
+- FASP [Transfer Agents](#transfer-clients-agents) can be: local `ascp`, or Connect Client, or any transfer node
+- Transfer parameters can be altered by modification of [*transfer-spec*](#transfer-specification), this includes requiring multi-session
 - 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)
@@ -828,16 +853,18 @@ Using `ascli` with plugin `server` for command line gives advantages over `ascp`
 
 Moreover all `ascp` options are supported either through transfer spec parameters (listed with `conf ascp spec`) and with the possibility to provide `ascp` arguments directly when the `direct` agent is used (`ascp_args` in `transfer_info`).
 
-### <a id="parsing"></a>Command line parsing, Special Characters
+### Command line parsing, Special Characters
 
 `ascli` is typically executed in a shell, either interactively or in a script.
 `ascli` receives its arguments from this shell (through the Operating System).
 
 #### Shell parsing for Unix-like systems: Linux, macOS, AIX
 
-Linux command line parsing is easy: It is fully documented in the shell's documentation.
+Linux command line parsing is easy:
+It is fully documented in the shell's documentation.
 
 On Unix-like environments, this is typically a POSIX shell (bash, zsh, ksh, sh).
+A c-shell (`csh`, `tcsh`) or other shell can also be used.
 In this environment the shell parses the command line, possibly replacing variables, etc...
 See [bash shell operation](https://www.gnu.org/software/bash/manual/bash.html#Shell-Operation).
 The shell builds the list of arguments and then `fork`/`exec` Ruby with that list.
@@ -846,7 +873,10 @@ Special character handling (quotes, spaces, env vars, ...) is handled by the she
 
 #### Shell parsing for Windows
 
-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.
+Command line parsing first depends on the shell used.
+MS Windows command line parsing is not like Unix-like systems simply because Windows does not provide a list of arguments to the executable (Ruby): it provides the whole command line as a single string, but the shell may interpret some special characters.
+
+So 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: the executable is Ruby.
@@ -855,7 +885,36 @@ It has its own parsing algorithm, close to a Linux shell parsing.
 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:
+It is also possible to display arguments received by Ruby using this command:
+
+```console
+C:> ruby -e 'puts ARGV' "Hello World" 1 2
+Hello World
+1
+2
+```
+
+Once the shell has dealt with the command line "special" characters for it, the shell calls Windows' `CreateProcess` with just the whole command line as a single string.
+(Unlike Unix-like systems where the command line is split into arguments by the shell.)
+
+It's up to the program to split arguments:
+
+- [Windows: How Command Line Parameters Are Parsed](https://daviddeley.com/autohotkey/parameters/parameters.htm#RUBY)
+- [Understand Quoting and Escaping of Windows Command Line Arguments](https://web.archive.org/web/20190316094059/http://www.windowsinspired.com/understanding-the-command-line-string-and-arguments-received-by-a-windows-program/)
+
+ is a Ruby program, so Ruby parses the command line into arguments and provides them to the program.
+Ruby vaguely follows the Microsoft C/C++ parameter parsing rules.
+(See `w32_cmdvector` in Ruby source [`win32.c`](https://github.com/ruby/ruby/blob/master/win32/win32.c#L1766)) : <!--cspell:disable-line-->
+
+- Space characters: split arguments (space, tab, newline)
+- Backslash: `\` escape single special character
+- Globing characters: `*?[]{}` for file globing
+- Double quotes: `"`
+- Single quotes: `'`
+
+#### Shell parsing for Windows: `cmd.exe`
+
+The following examples give the same result on Windows using `cmd.exe`:
 
 - Single quote protects the double quote
 
@@ -875,40 +934,49 @@ The following examples give the same result on Windows:
   ascli config echo @json:"{\"url\":\"https://...\"}"
   ```
 
-More details: on Windows, `cmd.exe` is typically used to start .
 `cmd.exe` handles some special characters: `^"<>|%&`.
 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.
 
-Then, the shell calls Windows' `CreateProcess` with just the whole command line as a single string.
-Unlike Unix-like systems where the command line is split into arguments by the shell.
+#### Shell parsing for Windows: Powershell
 
-It's up to the program to split arguments:
+For Powershell, it actually depends on the version of it.
 
-- [Windows: How Command Line Parameters Are Parsed](https://daviddeley.com/autohotkey/parameters/parameters.htm#RUBY)
-- [Understand Quoting and Escaping of Windows Command Line Arguments](https://web.archive.org/web/20190316094059/http://www.windowsinspired.com/understanding-the-command-line-string-and-arguments-received-by-a-windows-program/)
+A difficulty is that Powershell parses the command line for its own use and manages special characters, but then it passes the command line to the program (Ruby) as a single string, possibly without the special characters.
 
- is a Ruby program, so Ruby parses the command line into arguments and provides them to the program.
-Ruby vaguely follows the Microsoft C/C++ parameter parsing rules.
-(See `w32_cmdvector` in Ruby source [`win32.c`](https://github.com/ruby/ruby/blob/master/win32/win32.c#L1766)) : <!--cspell:disable-line-->
+Details can be found here:
 
-- Space characters: split arguments (space, tab, newline)
-- Backslash: `\` escape single special character
-- Globing characters: `*?[]{}` for file globing
-- Double quotes: `"`
-- Single quotes: `'`
+- [Passing arguments with quotes](https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_parsing?view=powershell-7.4#passing-arguments-that-contain-quote-characters)
+
+- [quoting rules](https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_quoting_rules?view=powershell-7.4)
+
+The following examples give the same result on Windows using Powershell:
+
+```console
+PS C:\> echo $psversiontable.psversion
+
+Major  Minor  Build  Revision
+-----  -----  -----  --------
+5      1      19041  4046
+
+PS C:\> ascli conf echo  --% @json:'{"k":"v","x":"y"}'
+
+PS C:\> ascli conf echo @json:'{"""k""":"""v""","""x""":"""y"""}'
+```
+
+> **Note:** The special powershell argument `--%` places powershell in legacy parsing mode.
 
 #### Extended Values (JSON, Ruby, ...)
 
-Some of the `ascli` parameters are expected to be [Extended Values](#extended), i.e. not a simple `String`, but a composite structure (`Hash`, `Array`).
+Some of the `ascli` parameters are expected to be [Extended Values](#extended-value-syntax), i.e. not a simple `String`, but a composite structure (`Hash`, `Array`).
 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.
+`config echo` takes exactly **one** argument which can use the [Extended Value](#extended-value-syntax) syntax.
 Unprocessed command line arguments are shown in the error message.
 
 Example:
@@ -927,7 +995,7 @@ ERROR: Argument: unprocessed values: ["2", "3"]
 
 > **Note:** It gets its value after shell command line parsing and `ascli` extended value parsing.
 
-In the following examples (using a POSIX shell, such as `bash`), several equivalent sample commands are provided.
+In the following examples (using a POSIX shell, such as `bash`), several equivalent commands are provided.
 For all example, most of special character handling is not specific to `ascli`:
 It depends on the underlying syntax: shell , JSON, etc...
 Depending on the case, a different `format` option is used to display the actual value.
@@ -978,7 +1046,8 @@ ascli config echo '"'
 "
 ```
 
-Double quote in JSON is a little tricky because `"` is special both for the shell and JSON. Both shell and JSON syntax allow to protect `"`, but only the shell allows protection using single quote.
+Double quote in JSON is a little tricky because `"` is special both for the shell and JSON.
+Both shell and JSON syntax allow to protect `"`, but only the shell allows protection using single quote.
 
 ```bash
 ascli config echo @json:'"\""' --format=text
@@ -990,7 +1059,8 @@ ascli config echo @ruby:\'\"\' --format=text
 "
 ```
 
-Here a single quote or a backslash protects the double quote to avoid shell processing, and then an additional `\` is added to protect the `"` for JSON. But as `\` is also shell special, then it is protected by another `\`.
+Here a single quote or a backslash protects the double quote to avoid shell processing, and then an additional `\` is added to protect the `"` for JSON.
+But as `\` is also shell special, then it is protected by another `\`.
   
 #### Shell and JSON or Ruby special characters in extended value
 
@@ -1087,7 +1157,7 @@ ascli config echo @ruby:"{'title'=>ENV['MYTITLE']}" --format=json
 ### Commands, Options, Positional Arguments
 
 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).
+The tokenization of the command line is typically done by the shell, refer to the previous section [Command Line Parsing](#command-line-parsing-special-characters).
 
 `ascli` handles three types of command line arguments:
 
@@ -1108,7 +1178,7 @@ ascli command subcommand --option-name=VAL1 VAL2
 If the value of a command, option or argument is constrained by a fixed list of values, then it is possible to use a few of the first letters of the value, provided that it uniquely identifies the value.
 For example `ascli config pre ov` is the same as `ascli config preset overview`.
 
-The value of options and arguments is evaluated with the [Extended Value Syntax](#extended).
+The value of options and arguments is evaluated with the [Extended Value Syntax](#extended-value-syntax).
 
 #### Commands
 
@@ -1142,9 +1212,9 @@ It could also be designed as an option, but since it is mandatory and typically
 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 configuration file or environment variable like for options.
-Nevertheless, [Extended Values](#extended) syntax is supported, so it is possible to retrieve a value from the configuration file or environment variable (using `@preset:`).
+Nevertheless, [Extended Values](#extended-value-syntax) syntax is supported, so it is possible to retrieve a value from the configuration file or environment variable (using `@preset:`).
 
-If a Positional Arguments begins with `-`, then either use the `@val:` syntax (see [Extended Values](#extended)), or use the `--` separator (see below).
+If a Positional Arguments begins with `-`, then either use the `@val:` syntax (see [Extended Values](#extended-value-syntax)), or use the `--` separator (see below).
 
 A few positional arguments are optional, they are located at the end of the command line.
 
@@ -1184,7 +1254,7 @@ But some are mandatory, so they can be placed in a configuration file, for examp
 
 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](#configuration-file)
 - Environment variable
 - Command line
 
@@ -1293,9 +1363,9 @@ Examples:
 - `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`
+#### Option: `select`
 
-Table output can be filtered using option `select`.
+Table output (`object_list`) 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`.
 
@@ -1336,7 +1406,7 @@ Syntax: `%<field>:<value>`
 
 > **Note:** The legacy option `id` is deprecated: `--id=1234` (options have a single value and thus do not provide the possibility to identify sub-entities)
 
-### <a id="extended"></a>Extended Value Syntax
+### Extended Value Syntax
 
 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.
@@ -1460,7 +1530,7 @@ EOF
 {"key1":"value1","key2":["item1","item2"],"key3":{"key4":"value4","key5":"value5"}}
 ```
 
-### <a id="conffolder"></a>Configuration and Persistency Folder
+### Configuration and Persistency Folder
 
 `ascli` configuration and other runtime files (token cache, file lists, persistency files, SDK) are stored by default in `[User's home folder]/.aspera/ascli`.
 
@@ -1503,46 +1573,46 @@ 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
+### Configuration file
 
 On the first execution of `ascli`, an empty configuration file is created in the configuration folder.
 Nevertheless, there is no mandatory information required in this file, the use of it is optional as any option can be provided on the command line.
 
 Although the file is a standard YAML file, `ascli` provides commands to read and modify it using the `config` command.
 
-All options for `ascli` can be set on command line, or by env vars, or using [option presets](#lprt) in the configuration file.
+All options for `ascli` can be set on command line, or by env vars, or using [Option Preset](#option-preset)' in the configuration file.
 
 A configuration file provides a way to define default values, especially for authentication parameters, thus avoiding to always having to specify those parameters on the command line.
 
 The default configuration file is: `$HOME/.aspera/ascli/config.yaml` (this can be overridden with option `--config-file=path` or equivalent env var).
 
-The configuration file is simply a catalog of pre-defined lists of options, called: [option presets](#lprt). Then, instead of specifying some common options on the command line (e.g. address, credentials), it is possible to invoke the ones of a [option preset](#lprt) (e.g. `mypreset`) using the option: `-Pmypreset` or `--preset=mypreset`.
+The configuration file is simply a catalog of pre-defined lists of options, called: [Option Preset](#option-preset)'. Then, instead of specifying some common options on the command line (e.g. address, credentials), it is possible to invoke the ones of a [Option Preset](#option-preset)' (e.g. `mypreset`) using the option: `-Pmypreset` or `--preset=mypreset`.
 
-#### <a id="lprt"></a>Option preset
+#### Option Preset
 
-A [option preset](#lprt) is simply a collection of parameters and their associated values in a named section in the configuration file.
+A [Option Preset](#option-preset)' is simply a collection of parameters and their associated values in a named section in the configuration file.
 
-A named [option preset](#lprt) can be modified directly using `ascli`, which will update the configuration file :
+A named [Option Preset](#option-preset)' can be modified directly using `ascli`, which will update the configuration file :
 
 ```bash
 ascli config preset set|delete|show|initialize|update <option preset>
 ```
 
-The command `update` allows the easy creation of [option preset](#lprt) by simply providing the options in their command line format, e.g. :
+The command `update` allows the easy creation of [Option Preset](#option-preset)' by simply providing the options in their command line format, e.g. :
 
 ```bash
 ascli config preset update demo_server --url=ssh://demo.asperasoft.com:33001 --username=asperaweb --password=my_password_here --ts=@json:'{"precalculate_job_size":true}'
 ```
 
-- This creates a [option preset](#lprt) `demo_server` with all provided options.
+- This creates a [Option Preset](#option-preset)' `demo_server` with all provided options.
 
-The command `set` allows setting individual options in a [option preset](#lprt).
+The command `set` allows setting individual options in a [Option Preset](#option-preset)'.
 
 ```bash
 ascli config preset set demo_server password my_password_here
 ```
 
-The command `initialize`, like `update` allows to set several parameters at once, but it deletes an existing configuration instead of updating it, and expects a [`Hash` Extended Value](#extended).
+The command `initialize`, like `update` allows to set several parameters at once, but it deletes an existing configuration instead of updating it, and expects a [`Hash` Extended Value](#extended-value-syntax).
 
 ```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}}'
@@ -1554,7 +1624,7 @@ A full terminal based overview of the configuration can be displayed using:
 ascli config preset over
 ```
 
-A list of [option preset](#lprt) can be displayed using:
+A list of [Option Preset](#option-preset)' can be displayed using:
 
 ```bash
 ascli config preset list
@@ -1577,11 +1647,11 @@ ascli config preset over
 ascli config preset list
 ```
 
-#### <a id="lprtconf"></a>Special Option preset: `config`
+#### 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`
+#### 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.
 
@@ -1603,24 +1673,24 @@ ascli config preset get default _plugin_name_
 "_default_preset_for_plugin_"
 ```
 
-#### <a id="config"></a>Plugin: `config`: Configuration
+#### Plugin: `config`: Configuration
 
 Plugin `config` provides general commands for `ascli`:
 
-- Option preset, configuration file operations
+- Option Preset, configuration file operations
 - `wizard`
 - `vault`
 - `ascp`
 
 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`.
+When `ascli` starts, it looks for the `default` Option Preset and checks the value for `config`.
 If set, it loads the options independently of the plugin used.
 
 > **Note:** If no global default is set by the user, `ascli` will use `global_common_defaults` when setting global parameters (e.g. `config ascp use`)
 >
 > **Note:** If 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):
+Show current default (global) Option Preset (`config` plugin):
 
 ```console
 $ ascli config preset get default config
@@ -1631,90 +1701,95 @@ global_common_defaults
 ascli config preset set GLOBAL version_check_days 0
 ```
 
-If the default global Option preset is not set, and you want to use a different name:
+If the default global Option Preset is not set, and you want to use a different name:
 
 ```bash
 ascli config preset set GLOBAL version_check_days 0
 ascli config preset set default config my_common_defaults
 ```
 
-#### Config sample commands
-
-```bash
-config ascp connect info 'Aspera Connect for Windows'
-config ascp connect list
-config ascp connect version 'Aspera Connect for Windows' download 'Windows Installer' --to-folder=.
-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=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 coffee --ui=text --query=@json:'{"text":"true"}'
-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 -- --special-string
-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://ifconfig.me
-config echo @uri:https://ifconfig.me
-config echo @vault:my_preset.password
-config echo @zlib:@stdin:
-config echo hello
-config email_test --notify-to=my_email_external
-config flush_tokens
-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 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 pubkey @file:my_key
-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=my_private_key --username=my_user_email
-config wizard my_org aoc --key-path=my_private_key --username=my_user_email --use-generic-client=yes
+### Config sample commands
+
+> **Note:** Add `ascli config` in front of the commands:
+
+```bash
+ascp connect info 'Aspera Connect for Windows'
+ascp connect list
+ascp connect version 'Aspera Connect for Windows' download 'Windows Installer' --to-folder=.
+ascp connect version 'Aspera Connect for Windows' list
+ascp connect version 'Aspera Connect for Windows' open documentation
+ascp errors
+ascp info --sdk-folder=sdk_test_dir
+ascp install
+ascp install --sdk-folder=sdk_test_dir
+ascp products list
+ascp products use 'IBM Aspera Connect'
+ascp show
+ascp spec
+ascp use /usr/bin/ascp
+check_update
+coffee
+coffee --ui=text
+coffee --ui=text --query=@json:'{"text":"true"}'
+detect https://faspex4.example.com/path
+detect https://faspex5.example.com/path
+detect https://node.example.com/path
+detect https://shares.example.com/path shares
+detect my_org aoc
+doc
+doc transfer-parameters
+echo -- --special-string
+echo @base64:SGVsbG8gV29ybGQK
+echo @csvt:@stdin:
+echo @env:USER
+echo @lines:@stdin:
+echo @list:,1,2,3
+echo @secret:
+echo @uri:/etc/hosts
+echo @uri:file:/etc/hosts
+echo @uri:http://ifconfig.me
+echo @uri:https://ifconfig.me
+echo @vault:my_preset.password
+echo @zlib:@stdin:
+echo hello
+email_test --notify-to=my_email_external
+flush_tokens
+folder
+gem name
+gem path
+gem version
+genkey my_key
+genkey my_key 4096
+initdemo
+open
+plugin create my_command
+plugin list
+preset delete conf_name
+preset initialize conf_name @json:'{"p1":"v1","p2":"v2"}'
+preset list
+preset overview
+preset set conf_name param value
+preset set default shares conf_name
+preset show conf_name
+preset unset conf_name param
+preset update conf_name --p1=v1 --p2=v2
+proxy_check --fpac=@file:examples/proxy.pac https://eudemo.asperademo.com --proxy-credentials=@list:,user,pass
+pubkey @file:my_key
+remote_certificate chain https://node.example.com/path
+remote_certificate name https://node.example.com/path
+remote_certificate only https://node.example.com/path
+vault create my_label @json:'{"password":"my_password_here","description":"my secret"}'
+vault delete my_label
+vault list
+vault show my_label
+wizard https://console.example.com/path console
+wizard https://faspex4.example.com/path faspex --username=test --password=test
+wizard https://faspex5.example.com/path faspex5 --key-path=my_private_key
+wizard https://node.example.com/path node --username=test --password=test
+wizard https://orch.example.com/path orchestrator --username=test --password=test
+wizard https://shares.example.com/path shares --username=test --password=test
+wizard my_org aoc --key-path=my_private_key --username=my_user_email
+wizard my_org aoc --key-path=my_private_key --username=my_user_email --use-generic-client=yes
 ```
 
 #### Format of file
@@ -1738,27 +1813,27 @@ demo_server:
 We can see here:
 
 - The configuration was created with `ascli` version 0.3.7
-- The default [option preset](#lprt) to load for `server` plugin is : `demo_server`
-- The [option preset](#lprt) `demo_server` defines some parameters: the URL and credentials
-- The default [option preset](#lprt) to load in any case is : `cli_default`
+- The default [Option Preset](#option-preset)' to load for `server` plugin is : `demo_server`
+- The [Option Preset](#option-preset)' `demo_server` defines some parameters: the URL and credentials
+- The default [Option Preset](#option-preset)' to load in any case is : `cli_default`
 
-Two [option presets](#lprt) are reserved:
+Two [Option Preset](#option-preset)' are reserved:
 
 - `config` contains a single value: `version` showing the version used to create the configuration file.
   It is used to check compatibility.
-- `default` is reserved to define the default [option preset](#lprt) name used for known plugins.
+- `default` is reserved to define the default [Option Preset](#option-preset)' name used for known plugins.
 
-The user may create as many [option presets](#lprt) as needed. For instance, a particular [option preset](#lprt) can be created for a particular application instance and contain URL and credentials.
+The user may create as many [Option Preset](#option-preset)' as needed. For instance, a particular [Option Preset](#option-preset)' can be created for a particular application instance and contain URL and credentials.
 
-Values in the configuration also follow the [Extended Value Syntax](#extended).
+Values in the configuration also follow the [Extended Value Syntax](#extended-value-syntax).
 
-> **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-value-syntax) 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"
 ```
 
-This creates the [option preset](#lprt):
+This creates the [Option Preset](#option-preset)':
 
 ```yaml
 my_aoc_org:
@@ -1774,20 +1849,20 @@ Some options are global, some options are available only for some plugins. (the
 Options are loaded using this algorithm:
 
 - If option `--no-default` (or `-N`) is specified, then no default value is loaded for the plugin
-- Else it looks for the name of the plugin as key in section `default`, the value is the name of the default [option preset](#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 if the value is a `Hash`, it uses it as options values.
+- Else it looks for the name of the plugin as key in section `default`, the value is the name of the default [Option Preset](#option-preset)' for it, and loads it.
+- If option `--preset=<name or extended value hash>` is specified (or `-Pxxxx`), this reads the [Option Preset](#option-preset)' specified from the configuration file, or if the value is a `Hash`, it uses it as options values.
 - Environment variables are evaluated
 - Command line options are evaluated
 
 Parameters are evaluated in the order of command line.
 
-To avoid loading the default [option preset](#lprt) for a plugin, use: `-N`
+To avoid loading the default [Option Preset](#option-preset)' for a plugin, use: `-N`
 
 On command line, words in parameter names are separated by a dash (`-`).
 In configuration file, separator is an underscore.
 E.g. `--xxx-yyy` on command line gives `xxx_yyy` in configuration file.
 
-The main plugin name is `config`, so it is possible to define a default [option preset](#lprt) for the main plugin with:
+The main plugin name is `config`, so it is possible to define a default [Option Preset](#option-preset)' for the main plugin with:
 
 ```bash
 ascli config preset set cli_default interactive no
@@ -1797,7 +1872,7 @@ ascli config preset set cli_default interactive no
 ascli config preset set default config cli_default
 ```
 
-A [option preset](#lprt) value can be removed with `unset`:
+A [Option Preset](#option-preset)' value can be removed with `unset`:
 
 ```bash
 ascli config preset unset cli_default interactive
@@ -1817,7 +1892,7 @@ ascli -N --preset=@json:'{"url":"_url_here_","password":"my_password_here","user
 
 #### Wizard
 
-The wizard is a command that asks the user for information and creates a [option preset](#lprt) with the provided information.
+The wizard is a command that asks the user for information and creates a [Option Preset](#option-preset)' with the provided information.
 
 It takes an optional argument: the URL of the application, and an **option**: `query` which allows limiting the detection to a given plugin.
 
@@ -1839,7 +1914,7 @@ ascli shares repo browse / --url=https://10.25.0.6 --username=john --password=my
 
 This can also be provisioned in a configuration file:
 
-- Build [option preset](#lprt)
+- Build [Option Preset](#option-preset)'
 
 ```bash
 ascli config preset set shares06 url https://10.25.0.6
@@ -1859,7 +1934,7 @@ or
 ascli config preset update shares06 --url=https://10.25.0.6 --username=john --password=my_password_here
 ```
 
-- Define this [option preset](#lprt) as the default [option preset](#lprt) for the specified plugin (`shares`)
+- Define this [Option Preset](#option-preset)' as the default [Option Preset](#option-preset)' for the specified plugin (`shares`)
 
 ```bash
 ascli config preset set default shares shares06
@@ -1877,7 +1952,7 @@ ascli config preset overview
 ascli shares repo browse /
 ```
 
-### <a id="vault"></a>Secret Vault
+### Secret Vault
 
 Secrets (e.g. passwords) are usually command options.
 They can be provided on command line, env vars, files etc.
@@ -1956,7 +2031,7 @@ Then secrets can be manipulated using commands:
 ascli config vault create mylabel @json:'{"password":"my_password_here","description":"for this account"}'
 ```
 
-#### <a id="config_finder"></a>Configuration Finder
+#### Configuration Finder
 
 When a secret is needed by a sub command, the command can search for existing configurations in the configuration file.
 
@@ -1964,7 +2039,7 @@ The lookup is done by comparing the service URL and username (or access key).
 
 #### Securing passwords and secrets
 
-A passwords can be saved in clear in a [option preset](#lprt) together with other account information (URL, username, etc...).
+A passwords can be saved in clear in a [Option Preset](#option-preset)' together with other account information (URL, username, etc...).
 Example:
 
 ```bash
@@ -1983,7 +2058,7 @@ ascli config vault create myconf @json:'{"password":"my_password_here"}'
 
 > **Note:** Use `@val:` in front of `@vault:` so that the extended value is not evaluated.
 
-### <a id="private_key"></a>Private Key
+### Private Key
 
 Some applications allow the user to be authenticated using a private key (Server, AoC, Faspex5, ...).
 It consists in using a pair of keys: the private key and its associated public key.
@@ -2063,7 +2138,9 @@ openssl rsa -des3 -in ${PRIVKEYFILE} -out ${PRIVKEYFILE}.with_des
 mv ${PRIVKEYFILE}.with_des ${PRIVKEYFILE}
 ```
 
-### <a id="certificates"></a>SSL CA certificate bundle
+### SSL CA certificate bundle
+
+The SSL CA certificate bundle can be specified using option `cert_stores`, which is a list of files or folders, by default it uses Ruby's default certificate store.
 
 To display trusted certificate store locations:
 
@@ -2071,40 +2148,50 @@ To display trusted certificate store locations:
 ascli --show-config --fields=cert_stores
 ```
 
-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.
+Use option `cert_stores` to modify the locations of certificate stores (files or folders).
+If you use this option, then default locations are not used.
+Default locations can be added using special value `DEF`.
+The value can be either an `Array` or `String` (path).
+Successive options add paths incrementally.
+All files of a folders are added.
+
+`ascli` uses the Ruby `openssl` gem.
+By default it uses the system's `openssl` library, but JRuby uses its own implementation.
+
+For example, on Linux to use the system's certificate store:
+
+```bash
+--cert-stores=$(openssl version -d|cut -f2 -d'"')/cert.pem
+```
 
-`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`.
 
-> **Note:** One can display those values like this:
+One can display those default values:
 
 ```bash
 ascli config echo @ruby:OpenSSL::X509::DEFAULT_CERT_DIR --format=text
 ascli config echo @ruby:OpenSSL::X509::DEFAULT_CERT_FILE --format=text
 ```
 
-`ascp` also needs to validate certificates when using **WSS**.
+`ascp` also needs to validate certificates when using **WSS** for transfer TCP part (instead of SSH).
 
-> **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:
+By default,`ascp` uses an hardcoded root location `OPENSSLDIR`.
+Original `ascp`'s hardcoded locations can be found using:
 
 ```bash
 ascli config ascp info --fields=openssldir
 ```
 
-or
-
-```bash
-strings $(ascli config ascp info --fields=ascp)|grep -w OPENSSLDIR
-```
+E.g. on macOS: `/Library/Aspera/ssl`.
+Then trusted certificates are taken from `[OPENSSLDIR]/cert.pem` and files in `[OPENSSLDIR]/certs`.
+`ascli` overrides the default hardcoded location used by `ascp` for WSS and uses the same locations as specified in `cert_stores` (using the `-i` option of `ascp`).
 
 To update trusted root certificates for `ascli`:
 Display the trusted certificate store locations used by `ascli`.
 Typically done by updating the system's root certificate store.
 
-An up-to-date version of the certificate bundle can be retrieved with:
+An up-to-date version of the certificate bundle can also be retrieved with:
 
 ```bash
 ascli config echo @uri:https://curl.haxx.se/ca/cacert.pem --format=text
@@ -2113,18 +2200,18 @@ ascli config echo @uri:https://curl.haxx.se/ca/cacert.pem --format=text
 To download that certificate store:
 
 ```bash
-ascli config echo @uri:https://curl.haxx.se/ca/cacert.pem --format=text > /tmp/cacert.pem
+ascli config echo @uri:https://curl.haxx.se/ca/cacert.pem --format=text --output=/tmp/cacert.pem
 ```
 
-Then, use this store by setting the  option `cert_stores` or env var `SSL_CERT_FILE`.
+Then, use this store by setting the option `cert_stores` (or env var `SSL_CERT_FILE`).
 
-To trust a specific certificate (e.g. self-signed), **provided that the `CN` is correct**, save the certificate to a file:
+To trust a specific certificate (e.g. self-signed), **provided that the `CN` is correct**, save the certificate chain to a file:
 
 ```bash
-ascli config remote_certificate https://localhost:9092 > myserver.pem
+ascli config remote_certificate chain https://localhost:9092 --insecure=yes --output=myserver.pem
 ```
 
-> **Note:** The saved certificate shows the CN as first line.
+> **Note:** Use command `name` to display the remote common name of the remote certificate.
 
 Then, use this file as certificate store (e.g. here, Node API):
 
@@ -2146,7 +2233,7 @@ The following options can be specified in the option `query`:
 | double     | Display double text resolution (half characters) (Bool) |
 | font_ratio | Font height/width ratio in terminal (Float) |
 
-### <a id="graphical"></a>Graphical Interactions: Browser and Text Editor
+### Graphical Interactions: Browser and Text Editor
 
 Some actions may require the use of a graphical tool:
 
@@ -2174,7 +2261,7 @@ Available loggers: `stdout`, `stderr`, `syslog`.
 
 Available levels: `debug`, `info`, `warn`, `error`.
 
-> **Note:** When using the `direct` agent (`ascp`), additional transfer logs can be activated using `ascp` options and `ascp_args`, see [`direct`](#agt_direct).
+> **Note:** When using the `direct` agent (`ascp`), additional transfer logs can be activated using `ascp` options and `ascp_args`, see [`direct`](#agent-direct).
 
 Examples:
 
@@ -2201,7 +2288,7 @@ To get traces of execution, with dump of API calls, use argument : `--log-level=
 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
+### HTTP socket parameters
 
 To ignore SSL certificate for **any** address/port, use option: `insecure`, i.e. `--insecure=yes`.
 To ignore SSL certificate for a list of 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`
@@ -2306,13 +2393,25 @@ ascli --proxy-credentials=@list::__username_here__:__password_here__ ...
 
 #### Proxy for Legacy Aspera HTTP/S Fallback
 
-Only supported with the `direct` agent: To specify a proxy for legacy HTTP fallback, use `ascp` native option `-x` and `ascp_args`: `--transfer-info=@json:'{"ascp_args":["-x","url_here"]}'`. Alternatively, set the [*transfer-spec*](#transferspec) parameter: `EX_http_proxy_url`.
+Only supported with the `direct` agent: To specify a proxy for legacy HTTP fallback, use `ascp` native option `-x` and `ascp_args`: `--transfer-info=@json:'{"ascp_args":["-x","url_here"]}'`.
 
 #### FASP proxy (forward) for transfers
 
-To specify a FASP proxy (forward), set the [*transfer-spec*](#transferspec) parameter: `proxy` (only supported with the `direct` agent).
+To specify a FASP proxy (forward), set the [*transfer-spec*](#transfer-specification) parameter: `proxy` (only supported with the `direct` agent).
+
+For example, for an Aspera forward proxy not encrypted (HTTP) without authentication running on port 9091, the option would be:
+
+```bash
+--ts=@json:'{"proxy":"dnat://proxy.example.org:9091"}'
+```
+
+Or, alternatively, (prefer transfer spec like above, generally):
+
+```bash
+--transfer-info=@json:'{"ascp_args":["--proxy","dnat://proxy.example.org:9091"]}'
+```
 
-### <a id="client"></a>FASP configuration
+### FASP configuration
 
 The `config` plugin also allows specification for the use of a local FASP **client**.
 It provides the following commands for `ascp` subcommand:
@@ -2344,7 +2443,7 @@ ascli config ascp info
 ...
 ```
 
-#### Selection of `ascp` location for [`direct`](#agt_direct) agent
+#### Selection of `ascp` location for [`direct`](#agent-direct) agent
 
 By default, `ascli` uses any found local product with `ascp`, including Transfer SDK.
 
@@ -2376,7 +2475,7 @@ Updated: global_common_defaults: ascp_path <- C:\Users\admin\.aspera\ascli\sdk\a
 Saved to default global preset global_common_defaults
 ```
 
-If the path has spaces, read section: [Shell and Command line parsing](#parsing).
+If the path has spaces, read section: [Shell and Command line parsing](#command-line-parsing-special-characters).
 
 #### List locally installed Aspera Transfer products
 
@@ -2397,7 +2496,7 @@ ascli config ascp products list
 +---------------------------------------+----------------------------------------+
 ```
 
-#### Selection of local client for `ascp` for [`direct`](#agt_direct) agent
+#### Selection of local client for `ascp` for [`direct`](#agent-direct) agent
 
 If no `ascp` is selected, this is equivalent to using option: `--use-product=FIRST`.
 
@@ -2453,58 +2552,64 @@ Time: 00:00:02 ============================================= 100% 27766 KB/sec T
 Downloaded: IBMAsperaConnectInstaller-3.11.2.63.dmg
 ```
 
-### <a id="agents"></a>Transfer Clients: Agents
+### Transfer Clients: Agents
 
 Some of the actions on Aspera Applications lead to file transfers (upload and download) using the FASP protocol (`ascp`).
 
-When a transfer needs to be started, a [*transfer-spec*](#transferspec) has been internally prepared.
-This [*transfer-spec*](#transferspec) will be executed by a transfer client, here called **Transfer Agent**.
+When a transfer needs to be started, a [*transfer-spec*](#transfer-specification) has been internally prepared.
+This [*transfer-spec*](#transfer-specification) will be executed by a transfer client, here called **Transfer Agent**.
 
 There are currently 3 agents, set with option `transfer`:
 
-- [`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**).
-- [`httpgw`](#agt_httpgw) : use of an Aspera HTTP Gateway
-- [`trsdk`](#agt_trsdk) : use of Aspera Transfer SDK
+- [`direct`](#agent-direct) : execution of `ascp`
+- [`trsdk`](#agent-transfer-sdk) : use of Aspera Transfer SDK (local)
+- [`connect`](#agent-connect-client) : use Connect Client (local)
+- [`alpha`](#agent-desktop-client) : use the new Desktop Client (local)
+- [`node`](#agent-node-api) : use an Aspera Transfer Node (**remote**).
+- [`httpgw`](#agent-http-gateway) : use an Aspera HTTP Gateway (**remote**)
 
 > **Note:** All transfer operations are seen from the point of view of the agent.
 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*](#transfer-specification) instead of **native** `ascp` options to provide parameters for a transfer session, as a common method for those three Transfer Agents.
 
 Specific options for agents are provided with option `transfer_info`, cumulatively.
 
-#### <a id="agt_direct"></a>Direct
+#### Agent: Direct
 
 The `direct` agent directly executes a local `ascp`.
 This is the default agent for `ascli` (option `--transfer=direct`).
 `ascli` will search locally installed Aspera products, including SDK, and use `ascp` from that component.
-Refer to section [FASP](#client).
+Refer to section [FASP](#fasp-configuration).
 
 The `transfer_info` option accepts the following optional parameters to control multi-session, Web Socket Session and Resume policy:
 
 | 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: [] |
+| `ascp_args`            | Array | Array of strings with native `ascp` arguments.<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 |
+| `trusted_certs`        | Array | List of repositories for trusted certificates. |
+| `resume`               | Hash  | Resume parameters. See below |
+| `resume.iter_max`      | int   | Max number of retry on error<br/>Default: 7 |
+| `resume.sleep_initial` | int   | First Sleep before retry<br/>Default: 2 |
+| `resume.sleep_factor`  | int   | Multiplier of sleep period between attempts<br/>Default: 2 |
+| `resume.sleep_max`     | int   | Default: 60 |
 
 In case of transfer interruption, the agent will **resume** a transfer up to `iter_max` time.
-Sleep between iterations is:
+Sleep between iterations is given by the following formula where `iter_index` is the current iteration index, starting at 0:
 
 ```bash
-max( sleep_max , sleep_initial * sleep_factor ^ (iter_index-1) )
+max( sleep_max , sleep_initial * sleep_factor ^ iter_index )
 ```
 
+By default, Ruby's root CA store is used to validate any HTTPS endpoint used by `ascp` (e.g. WSS).
+In order to use a custom certificate store, use the `trusted_certs` parameter.
+To use `ascp`'s default, use option: `--transfer-info=@json:'{"trusted_certs":null}'`.
+
 Some transfer errors are considered **retry-able** (e.g. timeout) and some other not (e.g. wrong password).
 The list of known protocol errors and retry level can be listed:
 
@@ -2519,9 +2624,6 @@ ascli ... --transfer-info=@json:'{"wss":true,"resume":{"iter_max":20}}'
 ascli ... --transfer-info=@json:'{"spawn_delay_sec":2.5,"multi_incr_udp":false}'
 ```
 
-> **Note:** The `direct` agent supports additional `transfer_spec` parameters starting with `EX_` (extended).
-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, to activate debug level 2 for `ascp` (`DD`), and display those logs on the terminal (`-`):
 
@@ -2533,15 +2635,9 @@ 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`).
+> **Note:** When transfer agent [`direct`](#agent-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`).
 
-In addition to standard methods described in section [File List](#file_list), it is possible to specify the list of file using those additional methods:
-
-- Using the pseudo [*transfer-spec*](#transferspec) parameter `EX_file_list`
-
-```bash
---sources=@ts --ts=@json:'{"EX_file_list":"file_list.txt"}'
-```
+In addition to standard methods described in section [File List](#list-of-files-for-transfers), it is possible to specify the list of file using those additional methods:
 
 - Using option `transfer_info` parameter `ascp_args`
 
@@ -2553,7 +2649,7 @@ In addition to standard methods described in section [File List](#file_list), it
 >
 > **Note:** Those 2 additional methods avoid the creation of a copy of the file list: if the standard options `--sources=@lines:@file:... --src-type=...` are used, then the file is list read and parsed, and a new file list is created in a temporary folder.
 >
-> **Note:** Those methods have limitations: they apply **only** to the [`direct`](#agt_direct) transfer agent (i.e. local `ascp`) and not for Aspera on Cloud.
+> **Note:** Those methods have limitations: they apply **only** to the [`direct`](#agent-direct) transfer agent (i.e. local `ascp`) and not for Aspera on Cloud.
 
 This agent supports a local configuration file: `aspera.conf` where Virtual links can be configured:
 
@@ -2616,13 +2712,20 @@ It is also possible to set a schedule with different time and days, for example
 start=08 end=19 days=mon,tue,wed,thu capacity=900000;1000000
 ```
 
-#### <a id="agt_connect"></a>IBM Aspera Connect Client GUI
+#### Agent: Connect Client
+
+By specifying option: `--transfer=connect`, `ascli` will start transfers using the locally installed **IBM Aspera Connect Client**.
+There are no option for `transfer_info`.
+
+#### Agent: Desktop Client
 
-By specifying option: `--transfer=connect`, `ascli` will start transfers using the locally installed Aspera Connect Client. There are no option for `transfer_info`.
+By specifying option: `--transfer=alpha`, `ascli` will start transfers using the locally installed **IBM Aspera Desktop Client**.
+There are no option for `transfer_info`.
 
-#### <a id="agt_node"></a>Aspera Node API : Node to node transfers
+#### Agent: Node API
 
 By specifying option: `--transfer=node`, `ascli` starts transfers in an Aspera Transfer Server using the Node API, either on a local or remote node.
+This is especially useful for direct node-to-node transfers.
 Parameters provided in option `transfer_info` are:
 
 | Name     | Type   | Description |
@@ -2632,7 +2735,7 @@ Parameters provided in option `transfer_info` are:
 | password | string | Password, secret or bearer token</br>Mandatory |
 | root_id  | string | Root file id</br>Mandatory only for bearer token |
 
-Like any other option, `transfer_info` can get its value from a pre-configured [option preset](#lprt) :
+Like any other option, `transfer_info` can get its value from a pre-configured [Option Preset](#option-preset)' :
 
 ```bash
 --transfer-info=@preset:_name_here_
@@ -2649,7 +2752,7 @@ If `transfer_info` is not specified and a default node has been configured (name
 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
+#### Agent: HTTP Gateway
 
 If it possible to send using a HTTP gateway, in case use of FASP is not allowed.
 
@@ -2670,7 +2773,7 @@ ascli faspex package recv 323 --transfer=httpgw --transfer-info=@json:'{"url":"h
 
 > **Note:** The gateway only supports transfers authorized with a token.
 
-#### <a id="agt_trsdk"></a>Transfer SDK
+#### Agent: Transfer SDK
 
 Another possibility is to use the Transfer SDK daemon (`asperatransferd`).
 Set option `transfer` to `trsdk`.
@@ -2706,10 +2809,10 @@ On Windows the compilation may fail for various reasons (3.1.1):
 
 <!-- spellchecker: enable -->
 
-### <a id="transferspec"></a>Transfer Specification
+### Transfer Specification
 
 Some commands lead to file transfer (upload/download).
-All parameters necessary for this transfer are described in a [*transfer-spec*](#transferspec) (Transfer Specification), such as:
+All parameters necessary for this transfer are described in a [*transfer-spec*](#transfer-specification) (Transfer Specification), such as:
 
 - Server address
 - Transfer user name
@@ -2717,29 +2820,29 @@ All parameters necessary for this transfer are described in a [*transfer-spec*](
 - File list
 - Etc...
 
-`ascli` builds the [*transfer-spec*](#transferspec) internally as a `Hash`.
+`ascli` builds the [*transfer-spec*](#transfer-specification) internally as a `Hash`.
 It is not necessary to provide additional parameters on the command line for this transfer.
 
-It is possible to modify or add any of the supported [*transfer-spec*](#transferspec) parameter using the `ts` option.
-The `ts` option accepts a [`Hash` Extended Value](#extended) containing one or several [*transfer-spec*](#transferspec) parameters.
+It is possible to modify or add any of the supported [*transfer-spec*](#transfer-specification) parameter using the `ts` option.
+The `ts` option accepts a [`Hash` Extended Value](#extended-value-syntax) containing one or several [*transfer-spec*](#transfer-specification) parameters.
 Multiple `ts` options on command line are cumulative, and the `Hash` value is deeply merged.
 To remove a (deep) key from transfer spec, set the value to `null`.
 
 > **Note:** Default transfer spec values can be displayed with command: `config ascp info --flat-hash=no` under field `ts`.
 
-It is possible to specify `ascp` options when the `transfer` option is set to [`direct`](#agt_direct) using `transfer_info` option parameter: `ascp_args`.
+It is possible to specify `ascp` options when the `transfer` option is set to [`direct`](#agent-direct) using `transfer_info` option parameter: `ascp_args`.
 Example: `--transfer-info=@json:'{"ascp_args":["-l","100m"]}'`.
 This is especially useful for `ascp` command line parameters not supported in the transfer spec.
 
-The use of a [*transfer-spec*](#transferspec) instead of `ascp` parameters has the advantage of:
+The use of a [*transfer-spec*](#transfer-specification) instead of `ascp` parameters has the advantage of:
 
-- Common to all [Transfer Agent](#agents)
+- Common to all [Transfer Agent](#transfer-clients-agents)
 - Not dependent on command line limitations (special characters...)
 
-### <a id="transferparams"></a>Transfer Parameters
+### Transfer Parameters
 
-All standard [*transfer-spec*](#transferspec) parameters can be specified.
-[*transfer-spec*](#transferspec) can also be saved/overridden in the configuration file.
+All standard [*transfer-spec*](#transfer-specification) parameters can be specified.
+[*transfer-spec*](#transfer-specification) can also be saved/overridden in the configuration file.
 
 References:
 
@@ -2764,48 +2867,46 @@ Columns:
 
 `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 | 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>) |
+| authentication | string | &nbsp; | &nbsp; | Y | &nbsp; | &nbsp; | value=token for SSH bypass keys, else password asked if not provided.<br/>(&lt;ignored&gt;) |
 | 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>) |
+| cipher_allowed | string | Y | Y | Y | Y | Y | returned by node API. Valid literals include "aes-128" and "none".<br/>(&lt;ignored&gt;) |
+| compression | int | &nbsp; | &nbsp; | &nbsp; | &nbsp; | &nbsp; | ascp4 only, 0 / 1?<br/>(&lt;ignored&gt;) |
 | 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>) |
+| destination_root | string | Y | Y | Y | Y | Y | Destination root directory.<br/>(&lt;special&gt;) |
+| 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/>(&lt;ignored&gt;) |
 | 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>) |
+| fasp_url | string | &nbsp; | &nbsp; | &nbsp; | &nbsp; | &nbsp; | Only used in Faspex.<br/>(&lt;ignored&gt;) |
+| file_checksum | string | Y | Y | &nbsp; | &nbsp; | &nbsp; | Enable checksum reporting for transferred files by specifying the hash to use.<br/>Allowed values: sha-512, sha-384, sha-256, sha1, md5, none<br/>(&lt;ignored&gt;) |
 | http_fallback | bool<br/>string | Y | Y | Y | Y | Y | When true(1), attempts to perform an HTTP transfer if a FASP transfer cannot be performed.<br/>(-y (conversion){bool}|{string}) |
 | http_fallback_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>) |
+| lock_min_rate | bool | Y | Y | Y | Y | Y | TODO: remove ?<br/>(&lt;ignored&gt;) |
+| 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/>(&lt;ignored&gt;) |
+| lock_rate_policy | bool | &nbsp; | &nbsp; | Y | &nbsp; | &nbsp; | If true, lock the rate policy to the default value.<br/>(&lt;ignored&gt;) |
+| lock_target_rate | bool | Y | Y | Y | Y | Y | TODO: remove ?<br/>(&lt;ignored&gt;) |
+| 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/>(&lt;ignored&gt;) |
+| 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/>(&lt;ignored&gt;) |
 | 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 | 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/>(&lt;special&gt;) |
 | 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>) |
+| obfuscate_file_names | bool | &nbsp; | &nbsp; | &nbsp; | &nbsp; | Y | HTTP Gateway obfuscates file names when set to true.<br/>(&lt;ignored&gt;) |
 | 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>) |
+| 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/>(&lt;ignored&gt;) |
+| paths | array | Y | Y | Y | Y | Y | Array of path to the source (required) and a path to the destination (optional).<br/>(&lt;special&gt;) |
 | 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}) |
@@ -2819,9 +2920,9 @@ Fields with EX_ prefix are extensions to transfer agent [`direct`](#agt_direct).
 | 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>) |
+| 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/>(&lt;ignored&gt;) |
+| read_threads | int | &nbsp; | &nbsp; | &nbsp; | &nbsp; | &nbsp; | ascp4 only<br/>(&lt;ignored&gt;) |
+| 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/>(&lt;ignored&gt;) |
 | 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}) |
@@ -2830,38 +2931,27 @@ Fields with EX_ prefix are extensions to transfer agent [`direct`](#agt_direct).
 | 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>) |
+| retry_duration | string<br/>int | &nbsp; | Y | Y | &nbsp; | &nbsp; | Specifies how long to wait before retrying transfer. (e.g. "5min")<br/>(&lt;ignored&gt;) |
 | 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>) |
+| 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/>(&lt;ignored&gt;) |
 | 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_args | string | &nbsp; | &nbsp; | &nbsp; | &nbsp; | &nbsp; | Array of arguments to pass to SSH. Use with caution.<br/>(&lt;ignored&gt;) |
 | 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_cap_kbps | int | &nbsp; | &nbsp; | Y | &nbsp; | &nbsp; | Returned by upload/download_setup node API.<br/>(&lt;ignored&gt;) |
 | 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>) |
+| target_rate_percentage | string | Y | Y | Y | Y | Y | TODO: remove ?<br/>(&lt;ignored&gt;) |
+| title | string | &nbsp; | Y | Y | &nbsp; | &nbsp; | Title of the transfer<br/>(&lt;ignored&gt;) |
 | 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}) |
+| use_ascp4 | bool | Y | Y | &nbsp; | &nbsp; | &nbsp; | specify version of protocol<br/>(&lt;special&gt;) |
+| use_system_ssh | string | &nbsp; | &nbsp; | &nbsp; | &nbsp; | &nbsp; | TODO, comment...<br/>(&lt;ignored&gt;) |
+| write_threads | int | &nbsp; | &nbsp; | &nbsp; | &nbsp; | &nbsp; | ascp4 only<br/>(&lt;ignored&gt;) |
+| wss_enabled | bool | Y | Y | Y | Y | Y | Server has Web Socket service enabled<br/>(&lt;special&gt;) |
+| wss_port | int | Y | Y | Y | Y | Y | TCP port used for websocket service feed<br/>(&lt;special&gt;) |
 
 #### Destination folder for transfers
 
@@ -2870,12 +2960,12 @@ The destination folder is set by `ascli` by default to:
 - `.` for downloads
 - `/` for uploads
 
-It is specified by the [*transfer-spec*](#transferspec) parameter `destination_root`.
+It is specified by the [*transfer-spec*](#transfer-specification) parameter `destination_root`.
 As such, it can be modified with option: `--ts=@json:'{"destination_root":"<path>"}'`.
 The option `to_folder` provides an equivalent and convenient way to change this parameter:
 `--to-folder=<path>` .
 
-#### <a id="file_list"></a>List of files for transfers
+#### List of files for transfers
 
 When uploading, downloading or sending files, the user must specify the list of files to transfer.
 
@@ -2884,8 +2974,8 @@ By default the list of files to transfer is simply provided on the command line.
 The list of (source) files to transfer is specified by (extended value) option `sources` (default: `@args`).
 The list is either simply the list of source files, or a combined source/destination list (see below) depending on value of option `src_type` (default: `list`).
 
-In `ascli`, all transfer parameters, including file list, are provided to the transfer agent in a [*transfer-spec*](#transferspec) so that execution of a transfer is independent of the transfer agent (direct, connect, node, transfer sdk...).
-So, eventually, the list of files to transfer is provided to the transfer agent using the [*transfer-spec*](#transferspec) field: `"paths"` which is a list (array) of pairs of `"source"` (mandatory) and `"destination"` (optional).
+In `ascli`, all transfer parameters, including file list, are provided to the transfer agent in a [*transfer-spec*](#transfer-specification) so that execution of a transfer is independent of the transfer agent (direct, connect, node, transfer sdk...).
+So, eventually, the list of files to transfer is provided to the transfer agent using the [*transfer-spec*](#transfer-specification) field: `"paths"` which is a list (array) of pairs of `"source"` (mandatory) and `"destination"` (optional).
 The `sources` and `src_type` options provide convenient ways to populate the transfer spec with the source file list.
 
 Possible values for option `sources` are:
@@ -2903,7 +2993,7 @@ So, by default, the list of files to transfer will be simply specified on the co
   ascli server upload --sources=@args --src-type=list ~/mysample.file secondfile
   ```
 
-- An [Extended Value](#extended) with type **Array of String**
+- An [Extended Value](#extended-value-syntax) with type **Array of String**
 
   > **Note:** extended values can be tested with the command `config echo`
 
@@ -3026,7 +3116,7 @@ Advanced Example: Send files `./file1` and `./folder2/files2` to server (e.g. `/
 - Similarly, create a temporary soft link (Linux): `ln -s . tmp_base` and use `--src-base=tmp_base tmp_base/file1 tmp_base/folder2/files2`
 - One can also similarly use `--sources=@ts` and specify the list of files in the `paths` field of transfer spec with both `source` and `destination` for each file.
 
-#### <a id="multisession"></a>Support of multi-session
+#### Multi-session transfer
 
 Multi session, i.e. starting a transfer of a file set using multiple sessions (one `ascp` process per session) is supported on `direct` and `node` agents, not yet on connect.
 
@@ -3100,7 +3190,7 @@ The same progress bar is used for any type of transfer, using `ascp`, server to
 
 To display the native progress bar of `ascp`, use `--progress-bar=no --transfer-info=@json:'{"quiet":false}'`.
 
-### <a id="scheduler"></a>Scheduler
+### Scheduler
 
 It is useful to configure automated scheduled execution.
 `ascli` does not provide an internal scheduler.
@@ -3147,7 +3237,7 @@ EOF
 
 > **Note:** Logging options are kept here in the cron file instead of configuration file to allow execution on command line with output on command line.
 
-### <a id="locking"></a>Locking for exclusive execution
+### Locking for exclusive execution
 
 In some cases one needs to ensure that `ascli` is not executed several times in parallel.
 
@@ -3219,7 +3309,7 @@ The simplified format is:
 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
+### `faux:` for testing
 
 This is an extract of the man page of `ascp`.
 This feature is a feature of `ascp`, not `ascli`.
@@ -3301,12 +3391,12 @@ ascli server upload /tmp/sample --to-folder=faux://
 ascli server upload "faux:///mydir?file=testfile&count=1m&size=0&inc=2&seq=sequential" --to-folder=/Upload
 ```
 
-### <a id="usage"></a>Usage
+### Usage
 
 ```text
 ascli -h
 NAME
-        ascli -- a command line tool for Aspera Applications (v4.16.0)
+        ascli -- a command line tool for Aspera Applications (v4.17.0)
 
 SYNOPSIS
         ascli COMMANDS [OPTIONS] [ARGS]
@@ -3395,14 +3485,14 @@ OPTIONS:
         --silent-insecure=ENUM       Issue a warning if certificate is ignored: no, [yes]
         --cert-stores=VALUE          List of folder with trusted certificates (Array, String)
         --http-options=VALUE         Options for HTTP/S socket (Hash)
-        --cache-tokens=ENUM          Save and reuse Oauth tokens: no, [yes]
+        --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: trsdk, [direct], httpgw, connect, node, alpha
+        --transfer=ENUM              Type of transfer agent: node, [direct], alpha, httpgw, connect, trsdk
         --transfer-info=VALUE        Parameters for transfer agent (Hash)
 
 
@@ -3410,7 +3500,7 @@ COMMAND: shares
 SUBCOMMANDS: admin files health
 OPTIONS:
         --url=VALUE                  URL of application, e.g. https://faspex.example.com/aspera/faspex
-        --username=VALUE             Username to log in
+        --username=VALUE             User's name to log in
         --password=VALUE             User's password
 
 
@@ -3418,7 +3508,7 @@ COMMAND: node
 SUBCOMMANDS: access_keys api_details asperabrowser async basic_token bearer_token browse central delete download events health http_node_download info license mkdir mkfile mklink rename search service simulator slash space ssync stream sync transfer upload watch_folder
 OPTIONS:
         --url=VALUE                  URL of application, e.g. https://faspex.example.com/aspera/faspex
-        --username=VALUE             Username to log in
+        --username=VALUE             User's name to log in
         --password=VALUE             User's password
         --validator=VALUE            Identifier of validator (optional for central)
         --asperabrowserurl=VALUE     URL for simple aspera web ui
@@ -3432,7 +3522,7 @@ COMMAND: orchestrator
 SUBCOMMANDS: health info plugins processes workflow
 OPTIONS:
         --url=VALUE                  URL of application, e.g. https://faspex.example.com/aspera/faspex
-        --username=VALUE             Username to log in
+        --username=VALUE             User's name to log in
         --password=VALUE             User's password
         --result=VALUE               Specify result value as: 'work_step:parameter'
         --synchronous=ENUM           Wait for completion: [no], yes
@@ -3444,7 +3534,7 @@ COMMAND: bss
 SUBCOMMANDS: subscription
 OPTIONS:
         --url=VALUE                  URL of application, e.g. https://faspex.example.com/aspera/faspex
-        --username=VALUE             Username to log in
+        --username=VALUE             User's name to log in
         --password=VALUE             User's password
 
 
@@ -3452,7 +3542,7 @@ COMMAND: alee
 SUBCOMMANDS: entitlement
 OPTIONS:
         --url=VALUE                  URL of application, e.g. https://faspex.example.com/aspera/faspex
-        --username=VALUE             Username to log in
+        --username=VALUE             User's name to log in
         --password=VALUE             User's password
 
 
@@ -3469,15 +3559,15 @@ OPTIONS:
 
 
 COMMAND: faspex5
-SUBCOMMANDS: admin bearer_token gateway health packages postprocessing shared_folders user version
+SUBCOMMANDS: admin bearer_token gateway health invitations packages postprocessing shared_folders user version
 OPTIONS:
         --url=VALUE                  URL of application, e.g. https://faspex.example.com/aspera/faspex
-        --username=VALUE             Username to log in
+        --username=VALUE             User's name to log in
         --password=VALUE             User's password
         --client-id=VALUE            OAuth client identifier
         --client-secret=VALUE        OAuth client secret
         --redirect-uri=VALUE         OAuth redirect URI for web authentication
-        --auth=ENUM                  OAuth type of authentication: boot, web, [jwt]
+        --auth=ENUM                  OAuth type of authentication: web, [jwt], boot
         --private-key=VALUE          OAuth JWT RSA private key PEM value (prefix file path with @file:)
         --passphrase=VALUE           OAuth JWT RSA private key passphrase
         --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
@@ -3489,19 +3579,19 @@ COMMAND: cos
 SUBCOMMANDS: node
 OPTIONS:
         --bucket=VALUE               Bucket name
-        --endpoint=VALUE             Storage endpoint url
+        --endpoint=VALUE             Storage endpoint (URL)
         --apikey=VALUE               Storage API key
-        --crn=VALUE                  Resource instance id
+        --crn=VALUE                  Resource instance id (CRN)
         --service-credentials=VALUE  IBM Cloud service credentials (Hash)
         --region=VALUE               Storage region
-        --identity=VALUE             Authentication url (https://iam.cloud.ibm.com/identity)
+        --identity=VALUE             Authentication URL (https://iam.cloud.ibm.com/identity)
 
 
 COMMAND: faspex
 SUBCOMMANDS: address_book dropbox health login_methods me package source v4
 OPTIONS:
         --url=VALUE                  URL of application, e.g. https://faspex.example.com/aspera/faspex
-        --username=VALUE             Username to log in
+        --username=VALUE             User's name to log in
         --password=VALUE             User's password
         --link=VALUE                 Public link for specific operation
         --delivery-info=VALUE        Package delivery information (Hash)
@@ -3515,7 +3605,7 @@ COMMAND: preview
 SUBCOMMANDS: check events scan show test trevents
 OPTIONS:
         --url=VALUE                  URL of application, e.g. https://faspex.example.com/aspera/faspex
-        --username=VALUE             Username to log in
+        --username=VALUE             User's name to log in
         --password=VALUE             User's password
         --skip-format=ENUM           Skip this preview format (multiple possible): png, mp4
         --folder-reset-cache=ENUM    Force detection of generated preview by refresh cache: [no], header, read
@@ -3551,7 +3641,7 @@ 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://faspex.example.com/aspera/faspex
-        --username=VALUE             Username to log in
+        --username=VALUE             User's name to log in
         --password=VALUE             User's password
         --auth=ENUM                  OAuth type of authentication: web, [jwt]
         --client-id=VALUE            OAuth API client identifier
@@ -3563,13 +3653,19 @@ OPTIONS:
         --workspace=VALUE            Name of workspace (String, NilClass)
         --new-user-option=VALUE      New user creation option for unknown package recipients
         --validate-metadata=ENUM     Validate shared inbox metadata: no, [yes]
+        --validator=VALUE            Identifier of validator (optional for central)
+        --asperabrowserurl=VALUE     URL for simple aspera web ui
+        --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: 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://faspex.example.com/aspera/faspex
-        --username=VALUE             Username to log in
+        --username=VALUE             User's name to log in
         --password=VALUE             User's password
         --ssh-keys=VALUE             SSH key path list (Array or single)
         --passphrase=VALUE           SSH private key passphrase
@@ -3581,7 +3677,7 @@ COMMAND: console
 SUBCOMMANDS: health transfer
 OPTIONS:
         --url=VALUE                  URL of application, e.g. https://faspex.example.com/aspera/faspex
-        --username=VALUE             Username to log in
+        --username=VALUE             User's name to log in
         --password=VALUE             User's password
         --filter-from=DATE           Only after date
         --filter-to=DATE             Only before date
@@ -3594,7 +3690,7 @@ 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).
+In that case, the operation expects an `Array` of `Hash` instead of a simple `Hash` using the [Extended Value Syntax](#extended-value-syntax).
 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
@@ -3646,13 +3742,13 @@ Created ./foo.rb
 ascli --plugin-folder=. foo
 ```
 
-## <a id="aoc"></a>Plugin: `aoc`: IBM Aspera on Cloud
+## Plugin: `aoc`: IBM Aspera on Cloud
 
 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
+### Configuration: Using Wizard
 
 `ascli` provides a configuration wizard.
 
@@ -3695,7 +3791,7 @@ ascli config wizard _your_instance_ aoc
 
 > **Note:** In above example, replace `_your_instance_` with the first part of your actual AoC URL: `https://_your_instance_.ibmaspera.com`.
 
-### <a id="aocmanual"></a>Configuration: Using manual setup
+### Configuration: Using manual setup
 
 > **Note:** If you used the wizard (recommended): skip this section.
 
@@ -3709,15 +3805,17 @@ 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](#api-client-registration) (auth=web) as well as [[Option Preset](#option-preset)' for Aspera on Cloud](#configuration-for-aspera-on-cloud).
 
-For a more convenient, browser-less, experience follow the [JWT](#jwt) section (auth=jwt) in addition to Client Registration.
+For a more convenient, browser-less, experience follow the [JWT](#authentication-with-private-key) section (auth=jwt) in addition to Client Registration.
 
 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
+#### API Client Registration
+
+> **Optional**
 
 If you use the built-in client_id and client_secret, skip this and do not set them in next section.
 
@@ -3742,11 +3840,11 @@ Let's start by a registration with web based authentication (auth=web):
 
 Once the client is registered, a **Client ID** and **Secret** are created, these values will be used in the next step.
 
-#### <a id="aocpreset"></a>[option preset](#lprt) for Aspera on Cloud
+#### Configuration for Aspera on Cloud
 
-If you did not use the wizard, you can also manually create a [option preset](#lprt) for `ascli` in its configuration file.
+If you did not use the wizard, you can also manually create a [Option Preset](#option-preset)' for `ascli` in its configuration file.
 
-Lets create a [option preset](#lprt) called: `my_aoc_org` using `ask` for interactive input (client info from previous step):
+Lets create a [Option Preset](#option-preset)' called: `my_aoc_org` using `ask` for interactive input (client info from previous step):
 
 ```bash
 ascli config preset ask my_aoc_org url client_id client_secret
@@ -3760,7 +3858,7 @@ updated: my_aoc_org
 
 (This can also be done in one line using the command `config preset update my_aoc_org --url=...`)
 
-Define this [option preset](#lprt) as default configuration for the `aspera` plugin:
+Define this [Option Preset](#option-preset)' as default configuration for the `aspera` plugin:
 
 ```bash
 ascli config preset set default aoc my_aoc_org
@@ -3768,12 +3866,12 @@ 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.
 
-#### <a id="jwt"></a>Activation of JSON Web Token (JWT) for direct authentication
+#### Authentication with private key
 
 For a Browser-less, Private Key-based authentication, use the following steps.
 
-In order to use JWT for Aspera on Cloud API client authentication,
-a [private/public key pair](#private_key) must be used.
+In order to use JSON Web Token (JWT) for Aspera on Cloud API client authentication,
+a [private/public key pair](#private-key) must be used.
 
 ##### API Client JWT activation
 
@@ -3851,9 +3949,9 @@ modified
 
 > **Note:** The `aspera user info show` command can be used to verify modifications.
 
-#### [option preset](#lprt) modification for JWT
+#### [Option Preset](#option-preset)' modification for JWT
 
-To activate default use of JWT authentication for `ascli` using the [option preset](#lprt), do the following:
+To activate default use of JWT authentication for `ascli` using the [Option Preset](#option-preset)', do the following:
 
 - Change auth method to JWT
 - Provide location of private key
@@ -3885,9 +3983,9 @@ So, provide the same options as for regular authentication, and provide the priv
 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
+#### AoC: First Use
 
-Once client has been registered and [option preset](#lprt) created: `ascli` can be used:
+Once client has been registered and [Option Preset](#option-preset)' created: `ascli` can be used:
 
 ```bash
 ascli aoc files br /
@@ -3930,7 +4028,7 @@ 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:{...}`.
+It expects a `Hash` using [Extended Value Syntax](#extended-value-syntax), 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:
@@ -3975,9 +4073,9 @@ ascli aoc admin res user list --query=@json:'{"member_of_any_workspace":false,"s
 
 Refer to the AoC API for full list of query parameters, or use the browser in developer mode with the web UI.
 
-> **Note:** The option `select` can also be used to further refine selection, refer to [section earlier](#option_select).
+> **Note:** The option `select` can also be used to further refine selection, refer to [section earlier](#option-select).
 
-#### <a id="res_select"></a>Selecting a resource
+#### Selecting a resource
 
 Resources are identified by a unique `id`, as well as a unique `name` (case insensitive).
 
@@ -3988,7 +4086,7 @@ To execute an action on a specific resource, select it using one of those method
 - Provide option `id` : `aoc admin res node show 123`
 - Provide option `name` : `aoc admin res node show --name=abc`
 
-#### <a id="res_create"></a>Creating a resource
+#### Creating a resource
 
 New resources (users, groups, workspaces, etc..) can be created using a command like:
 
@@ -4043,7 +4141,7 @@ For example in a command like:
 ascli aoc admin res node 123 --secret="my_secret_here" v3 info
 ```
 
-It is also possible to store secrets in the [secret vault](#vault) and then automatically find the related secret using the [config finder](#config_finder).
+It is also possible to store secrets in the [secret vault](#secret-vault) and then automatically find the related secret using the [config finder](#configuration-finder).
 
 #### Activity
 
@@ -4094,7 +4192,7 @@ The option `default_ports` ([yes]/no) allows ascli to retrieve the server ports
 
 #### Using ATS
 
-Refer to section **Examples** of [ATS](#ats) and substitute command `ats` with `aoc admin ats`.
+Refer to section **Examples** of [ATS](#plugin-ats-ibm-aspera-transfer-service) and substitute command `ats` with `aoc admin ats`.
 
 #### Files with type `link`
 
@@ -4169,7 +4267,7 @@ ascli aoc admin res user list --query='@json:{"q":"dummyuser"}' --fields=id --di
 +-------+---------+
 ```
 
-#### Example: <a id="deactuser"></a>Find deactivated users since more than 2 years
+#### Example: Find deactivated users since more than 2 years
 
 ```ruby
 ascli aoc admin res user list --query=@ruby:'{"deactivated"=>true,"q"=>"last_login_at:<#{(DateTime.now.to_time.utc-2*365*86400).iso8601}"}'
@@ -4248,7 +4346,7 @@ Other query parameters:
 {"workspace_membership_through":true,"include_indirect":true}
 ```
 
-#### Example: <a id="aoc_sample_member"></a>add all members of a workspace to another workspace
+#### Example: Add all members of a workspace to another workspace
 
 a- Get id of first workspace
 
@@ -4267,7 +4365,7 @@ WS2ID=$(ascli aoc admin res workspace list --query=@json:'{"q":"'"$WS2"'"}' --se
 c- Extract membership information
 
 ```bash
-ascli aoc admin res workspace_membership list --fields=manager,member_id,member_type,workspace_id --query=@json:'{"workspace_id":'"$WS1ID"'}' --format=jsonpp > ws1_members.json
+ascli aoc admin res workspace_membership list --fields=manager,member_id,member_type,workspace_id --query=@json:'{"workspace_id":'"$WS1ID"'}' --format=jsonpp --output=ws1_members.json
 ```
 
 d- Convert to creation data for second workspace:
@@ -4432,7 +4530,7 @@ So, for example, the creation of a node using ATS in IBM Cloud looks like (see o
 
 - Create the access key on ATS
 
-  The creation options are the ones of ATS API, refer to the [section on ATS](#ats_params) for more details and examples.
+  The creation options are the ones of ATS API, refer to the [section on ATS](#ats-access-key-creation-parameters) for more details and examples.
 
   ```bash
   ascli aoc admin ats access_key create --cloud=softlayer --region=eu-de --params=@json:'{"storage":{"type":"ibm-s3","bucket":"mybucket","credentials":{"access_key_id":"mykey","secret_access_key":"mysecret"},"path":"/"}}'
@@ -4461,7 +4559,7 @@ Creation of a node with a self-managed node is similar, but the command `aoc adm
 ### List of files to transfer
 
 Source files are provided as a list with the `sources` option.
-Refer to section [File list](#file_list)
+Refer to section [File list](#list-of-files-for-transfers)
 
 > **Note:** A special case is when the source files are located on **Aspera on Cloud** (i.e. using access keys and the `file id` API).
 
@@ -4490,17 +4588,26 @@ General syntax:
 ascli aoc packages send [package extended value] [other parameters such as file list and transfer parameters]
 ```
 
-Notes:
+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:
+
+```bash
+ascli aoc packages shared_inboxes list
+```
+
+Use fields: `recipients` and/or `bcc_recipients` to provide the list of recipients: **user** or **shared inbox**:
+
+- Provide either ids as expected by API: `"recipients":[{"type":"dropbox","id":"1234"}]`
+- or just names: `"recipients":[{"The Dest"}]`.
+
+ascli will resolve the list of email addresses and dropbox names to the expected type/id list, based on case insensitive partial match.
 
-- 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.
-  - Provide either ids as expected by API: `"recipients":[{"type":"dropbox","id":"1234"}]`
-  - or just names: `"recipients":[{"The Dest"}]` . ascli will resolve the list of email addresses and dropbox names to the expected type/id list, based on case insensitive partial match.
-- If a user recipient (email) is not already registered and the workspace allows external users, then the package is sent to an external user, and
-  - if the option `new_user_option` is `@json:{"package_contact":true}` (default), then a public link is sent and the external user does not need to create an account
-  - if the option `new_user_option` is `@json:{}`, then external users are invited to join the workspace
+If a user recipient (email) is not already registered and the workspace allows external users, then the package is sent to an external user, and:
+
+- if the option `new_user_option` is `@json:{"package_contact":true}` (default), then a public link is sent and the external user does not need to create an account
+- if the option `new_user_option` is `@json:{}`, then external users are invited to join the workspace
 
 #### Example: Send a package with one file to two users, using their email
 
@@ -4532,6 +4639,8 @@ To list packages in a shared inbox, the query has to be specified with the the s
 Additional parameters can be specified, as supported by the API (to find out available filters, consult the API definition, or use the web interface in developer mode).
 The current workspace is added unless specified in the query.
 
+> **Note:** By default, `exclude_dropbox_packages` is set to true for user packages, and to false for shared inbox packages. This can be overridden in the query.
+
 Using shared inbox name:
 
 ```bash
@@ -4579,7 +4688,7 @@ Let's send a package with the file `10M.dat` from subfolder /src_folder in a pac
 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)
+#### Receive new packages only (Cargo)
 
 It is possible to automatically download new packages, like using Aspera Cargo:
 
@@ -4657,13 +4766,13 @@ ascli aoc files short_link public delete _id_
 
 It is possible to transfer files directly between organizations without having to first download locally and then upload...
 
-Although optional, the creation of [option preset](#lprt) is recommended to avoid placing all parameters in the command line.
+Although optional, the creation of [Option Preset](#option-preset)' is recommended to avoid placing all parameters in the command line.
 
 Procedure to send a file from org1 to org2:
 
-- Get access to Organization 1 and create a [option preset](#lprt): e.g. `org1`, for instance, use the [Wizard](#aocwizard)
+- Get access to Organization 1 and create a [Option Preset](#option-preset)': e.g. `org1`, for instance, use the [Wizard](#configuration-using-wizard)
 - Check that access works and locate the source file e.g. `mysourcefile`, e.g. using command `files browse`
-- Get access to Organization 2 and create a [option preset](#lprt): e.g. `org2`
+- Get access to Organization 2 and create a [Option Preset](#option-preset)': e.g. `org2`
 - Check that access works and locate the destination folder `mydestfolder`
 - Execute the following:
 
@@ -4680,7 +4789,7 @@ Explanation:
 - `|` the standard output of the first command is fed into the second one
 - `-Porg2 aoc` use Aspera on Cloud plugin and load credentials for `org2`
 - `files upload mysourcefile` upload the file named `mysourcefile` (located in `org1`)
-- `--transfer=node` use transfer agent type `node` instead of default [`direct`](#agt_direct)
+- `--transfer=node` use transfer agent type `node` instead of default [`direct`](#agent-direct)
 - `--transfer-info=@json:@stdin:` provide `node` transfer agent information, i.e. node API credentials, those are expected in JSON format and read from standard input
 
 #### Find Files
@@ -4695,120 +4804,123 @@ ascli aoc admin res node --name='my node name' --secret='my_secret_here' v4 find
 
 For instructions, refer to section `find` for plugin `node`.
 
-### AoC sample commands
-
-```bash
-aoc admin analytics transfers nodes
-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 analytics transfers users --once_only=yes
-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 /
-aoc admin ats cluster clouds
-aoc admin ats cluster list
-aoc admin ats cluster show --cloud=aws --region=eu-west-1
-aoc admin ats cluster show 1f412ae7-869a-445c-9c05-02ad16813be2
-aoc admin auth_providers list
-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 client_reg_id
-aoc admin res client_registration_token list
-aoc admin res contact list
-aoc admin res dropbox list
-aoc admin res dropbox_membership list
-aoc admin res group list
-aoc admin res kms_profile list
-aoc admin res node list
-aoc admin res operation list
-aoc admin res organization show
-aoc admin res package list --http-options=@json:'{"read_timeout":120.0}'
-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 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 wf_id create @json:'{"name":"toto"}' \
-aoc automation workflow create @json:'{"name":"test_workflow"}'
-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 files bearer /
-aoc files bearer_token_node / --cache-tokens=no
-aoc files browse /
-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 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_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 --pid-file=pid_aocfxgw https://localhost:12345/aspera/faspex &
-aoc org --url=my_public_link_recv_from_aoc_user
-aoc organization
-aoc packages browse package_id3 /contents
-aoc packages list
-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 receive ALL --once-only=yes --to-folder=. --lock-port=12345
-aoc packages receive ALL --once-only=yes --to-folder=. --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 receive INIT --once-only=yes --query=@json:'{"dropbox_name":"my_shared_inbox_name"}'
-aoc packages receive package_id3 --to-folder=.
-aoc packages send --workspace=my_workspace_shared_inbox --validate-metadata=yes @json:'{"name":"$(notdir test) PACKAGE_TITLE_BASE","recipients":["my_shared_inbox_meta"],"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 --validate-metadata=yes @json:'{"name":"$(notdir test) PACKAGE_TITLE_BASE","recipients":["my_shared_inbox_meta"],"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 --validate-metadata=yes @json:'{"name":"$(notdir test) PACKAGE_TITLE_BASE","recipients":["my_shared_inbox_meta"],"metadata":{"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":"$(notdir test) PACKAGE_TITLE_BASE","recipients":["my_shared_inbox_name"]}' test_file.bin
-aoc packages send @json:'{"name":"$(notdir test) PACKAGE_TITLE_BASE","recipients":["my_email_external"]}' --new-user-option=@json:'{"package_contact":true}' test_file.bin
-aoc packages send @json:'{"name":"$(notdir test) PACKAGE_TITLE_BASE","recipients":["my_email_internal"],"note":"my note"}' test_file.bin
-aoc packages send @json:'{"name":"$(notdir test) PACKAGE_TITLE_BASE"}' test_file.bin --url=my_public_link_send_aoc_user --password=my_public_link_send_use_pass
-aoc packages send @json:'{"name":"$(notdir test) PACKAGE_TITLE_BASE"}' test_file.bin --url=my_public_link_send_shared_inbox
-aoc packages shared_inboxes list
-aoc remind --username=my_user_email
-aoc servers
-aoc user pref modify @json:'{"default_language":"en-us"}'
-aoc user pref show
-aoc user profile modify @json:'{"name":"dummy change"}'
-aoc user profile show
-aoc user workspaces current
-aoc user workspaces list
-```
-
-## <a id="ats"></a>Plugin: `ats`: IBM Aspera Transfer Service
+### Aoc sample commands
+
+> **Note:** Add `ascli aoc` in front of the commands:
+
+```bash
+admin analytics transfers nodes
+admin analytics transfers organization --query=@json:'{"status":"completed","direction":"receive"}' --notify-to=my_email_external --notify-template=@ruby:'%Q{From: <%=from_name%> <<%=from_email%>>\nTo: <<%=to%>>\nSubject: <%=ev["files_completed"]%> files received\n\n<%=ev.to_yaml%>}'
+admin analytics transfers users --once_only=yes
+admin ats access_key create --cloud=aws --region=my_region --params=@json:'{"id":"ak_aws","name":"my test key AWS","storage":{"type":"aws_s3","bucket":"my_bucket","credentials":{"access_key_id":"my_access_key","secret_access_key":"my_secret_key"},"path":"/"}}'
+admin ats access_key create --cloud=softlayer --region=my_region --params=@json:'{"id":"ak1ibmcloud","secret":"my_secret_here","name":"my test key","storage":{"type":"ibm-s3","bucket":"my_bucket","credentials":{"access_key_id":"my_access_key","secret_access_key":"my_secret_key"},"path":"/"}}'
+admin ats access_key delete ak1ibmcloud
+admin ats access_key list --fields=name,id
+admin ats access_key node ak1ibmcloud --secret=my_secret_here browse /
+admin ats cluster clouds
+admin ats cluster list
+admin ats cluster show --cloud=aws --region=eu-west-1
+admin ats cluster show 1f412ae7-869a-445c-9c05-02ad16813be2
+admin auth_providers list
+admin res application list
+admin res client list
+admin res client_access_key list
+admin res client_registration_token create @json:'{"data":{"name":"test_client_reg1","client_subject_scopes":["alee","aejd"],"client_subject_enabled":true}}'
+admin res client_registration_token delete client_reg_id
+admin res client_registration_token list
+admin res contact list
+admin res dropbox list
+admin res dropbox_membership list
+admin res group list
+admin res kms_profile list
+admin res node list
+admin res operation list
+admin res organization show
+admin res package list --http-options=@json:'{"read_timeout":120.0}'
+admin res saml_configuration list
+admin res self show
+admin res short_link list
+admin res user list
+admin res user modify %name:my_user_email @json:'{"deactivated":false}'
+admin res workspace_membership list
+admin resource node do %name:my_ak_name --secret=my_ak_secret browse /
+admin resource node do %name:my_ak_name --secret=my_ak_secret delete /folder1
+admin resource node do %name:my_ak_name --secret=my_ak_secret mkdir /folder1
+admin resource node do %name:my_ak_name --secret=my_ak_secret v3 access_key create @json:'{"id":"testsub1","storage":{"path":"/folder1"}}'
+admin resource node do %name:my_ak_name --secret=my_ak_secret v3 access_key delete testsub1
+admin resource node do %name:my_ak_name --secret=my_ak_secret v3 events
+admin resource workspace list
+admin resource workspace_membership list --fields=ALL --query=@json:'{"page":1,"per_page":50,"embed":"member","inherited":false,"workspace_id":11363,"sort":"name"}'
+admin subscription
+automation workflow action wf_id create @json:'{"name":"toto"}' \
+automation workflow create @json:'{"name":"test_workflow"}'
+automation workflow delete wf_id
+automation workflow list
+automation workflow list --query=@json:'{"show_org_workflows":"true"}' --scope=admin:all
+automation workflow list --select=@json:'{"name":"test_workflow"}' --fields=id --format=csv --display=data --output=test
+bearer_token --display=data --scope=user:all
+files bearer /
+files bearer_token_node / --cache-tokens=no
+files browse /
+files browse / --url=my_private_link
+files browse / --url=my_public_link_folder_no_pass
+files browse / --url=my_public_link_folder_pass --password=my_public_link_password
+files delete /testsrc
+files download --transfer=alpha testdst/test_file.bin
+files download --transfer=connect testdst/test_file.bin
+files find / '\.partial$'
+files http_node_download --to-folder=. testdst/test_file.bin
+files mkdir /testsrc
+files modify my_test_folder
+files permission my_test_folder list
+files rename /some_folder testdst
+files short_link private create /testdst
+files short_link private list /testdst
+files short_link public create testdst
+files show %id:aoc_file_id
+files show /
+files show testdst/test_file.bin
+files sync admin status --sync-info=@json:'{"name":"my_aoc_sync2","reset":true,"direction":"pull","local":{"path":"/data/local_sync"},"remote":{"path":"/testdst"}}'
+files sync admin status --sync-info=@json:'{"sessions":[{"name":"my_aoc_sync1","direction":"pull","local_dir":"/data/local_sync","remote_dir":"/testdst","reset":true}]}'
+files sync start --sync-info=@json:'{"name":"my_aoc_sync2","reset":true,"direction":"pull","local":{"path":"/data/local_sync"},"remote":{"path":"/testdst"}}'
+files sync start --sync-info=@json:'{"sessions":[{"name":"my_aoc_sync1","direction":"pull","local_dir":"/data/local_sync","remote_dir":"/testdst","reset":true}]}'
+files thumbnail my_test_folder/video_file.mpg
+files thumbnail my_test_folder/video_file.mpg --query=@json:'{"text":true,"double":true}'
+files transfer push /testsrc --to-folder=/testdst test_file.bin
+files upload --to-folder=/ test_file.bin --url=my_public_link_folder_no_pass
+files upload --to-folder=/testsrc test_file.bin
+files upload --workspace=my_other_workspace --to-folder=my_other_folder test_file.bin --transfer=node --transfer-info=@json:@stdin:
+files v3 info
+gateway --pid-file=pid_aocfxgw https://localhost:12345/aspera/faspex &
+org --url=my_public_link_recv_from_aoc_user
+organization
+packages browse package_id3 /contents
+packages list
+packages list --query=@json:'{"dropbox_name":"my_shared_inbox_name","sort":"-received_at","archived":false,"received":true,"has_content":true,"exclude_dropbox_packages":false}'
+packages receive ALL --once-only=yes --to-folder=. --lock-port=12345
+packages receive ALL --once-only=yes --to-folder=. --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}'
+packages receive INIT --once-only=yes --query=@json:'{"dropbox_name":"my_shared_inbox_name"}'
+packages receive package_id3 --to-folder=.
+packages send --workspace=my_workspace_shared_inbox --validate-metadata=yes @json:'{"name":"$(notdir test) PACKAGE_TITLE_BASE","recipients":["my_shared_inbox_meta"],"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
+packages send --workspace=my_workspace_shared_inbox --validate-metadata=yes @json:'{"name":"$(notdir test) PACKAGE_TITLE_BASE","recipients":["my_shared_inbox_meta"],"metadata":{"Project Id":"456","Type":"Opt2","CheckThose":["Check1","Check2"],"Optional Date":"2021-01-13T15:02:00.000Z"}}' test_file.bin
+packages send --workspace=my_workspace_shared_inbox --validate-metadata=yes @json:'{"name":"$(notdir test) PACKAGE_TITLE_BASE","recipients":["my_shared_inbox_meta"],"metadata":{"Type":"Opt2","CheckThose":["Check1","Check2"],"Optional Date":"2021-01-13T15:02:00.000Z"}}' test_file.bin
+packages send --workspace=my_workspace_shared_inbox @json:'{"name":"$(notdir test) PACKAGE_TITLE_BASE","recipients":["my_shared_inbox_name"]}' test_file.bin
+packages send @json:'{"name":"$(notdir test) PACKAGE_TITLE_BASE","recipients":["my_email_external"]}' --new-user-option=@json:'{"package_contact":true}' test_file.bin
+packages send @json:'{"name":"$(notdir test) PACKAGE_TITLE_BASE","recipients":["my_email_internal"],"note":"my note"}' test_file.bin
+packages send @json:'{"name":"$(notdir test) PACKAGE_TITLE_BASE"}' test_file.bin --url=my_public_link_send_aoc_user --password=my_public_link_send_use_pass
+packages send @json:'{"name":"$(notdir test) PACKAGE_TITLE_BASE"}' test_file.bin --url=my_public_link_send_shared_inbox
+packages shared_inboxes list
+remind --username=my_user_email
+servers
+user pref modify @json:'{"default_language":"en-us"}'
+user pref show
+user profile modify @json:'{"name":"dummy change"}'
+user profile show
+user workspaces current
+user workspaces list
+```
+
+## Plugin: `ats`: IBM Aspera Transfer Service
 
 ATS is usable either :
 
@@ -4889,7 +5001,7 @@ ascli ats api_key create
 ascli config preset update my_ibm_ats --ats-key=ats_XXXXXXXXXXXXXXXXXXXXXXXX --ats-secret=YYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYY
 ```
 
-### <a id="ats_params"></a>ATS Access key creation parameters
+### ATS Access key creation parameters
 
 When creating an ATS access key, the option `params` must contain an extended value with the creation parameters.
 Those are directly the parameters expected by the [ATS API](https://developer.ibm.com/apis/catalog?search=%22Aspera%20ATS%20API%22).
@@ -4930,28 +5042,30 @@ ascli ats access_key list --field=id --format=csv | ascli ats access_key delete
 
 The parameters provided to ATS for access key creation are the ones of [ATS API](https://developer.ibm.com/apis/catalog?search=%22aspera%20ats%22) for the `POST /access_keys` endpoint.
 
-### ATS sample commands
+### Ats sample commands
+
+> **Note:** Add `ascli ats` in front of the commands:
 
 ```bash
-ats access_key cluster ak2ibmcloud --secret=my_secret_here
-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
-ats access_key list --fields=name,id
-ats access_key node ak2ibmcloud browse / --secret=my_secret_here
-ats access_key show ak2ibmcloud
-ats api_key create
-ats api_key instances
-ats api_key list
-ats cluster clouds
-ats cluster list
-ats cluster show --cloud=aws --region=eu-west-1
-ats cluster show 1f412ae7-869a-445c-9c05-02ad16813be2
+access_key cluster ak2ibmcloud --secret=my_secret_here
+access_key create --cloud=aws --region=my_region --params=@json:'{"id":"ak_aws","name":"my test key AWS","storage":{"type":"aws_s3","bucket":"my_bucket","credentials":{"access_key_id":"my_access_key","secret_access_key":"my_secret_key"},"path":"/"}}'
+access_key create --cloud=softlayer --region=my_region --params=@json:'{"id":"ak2ibmcloud","secret":"my_secret_here","name":"my test key","storage":{"type":"ibm-s3","bucket":"my_bucket","credentials":{"access_key_id":"my_access_key","secret_access_key":"my_secret_key"},"path":"/"}}'
+access_key delete ak2ibmcloud
+access_key delete ak_aws
+access_key entitlement ak2ibmcloud
+access_key list --fields=name,id
+access_key node ak2ibmcloud browse / --secret=my_secret_here
+access_key show ak2ibmcloud
+api_key create
+api_key instances
+api_key list
+cluster clouds
+cluster list
+cluster show --cloud=aws --region=eu-west-1
+cluster show 1f412ae7-869a-445c-9c05-02ad16813be2
 ```
 
-## <a id="server"></a>Plugin: `server`: IBM Aspera High Speed Transfer Server (SSH)
+## Plugin: `server`: IBM Aspera High Speed Transfer Server (SSH)
 
 The `server` plugin is used for operations on Aspera HSTS using SSH authentication.
 It is the legacy way of accessing an Aspera Server, often used for server to server transfers.
@@ -4962,39 +5076,41 @@ then commands `ascp` (for transfers) and `ascmd` (for file operations) are execu
 
 ### Server sample commands
 
-```bash
-server browse /
-server browse / --password=@none: --ssh-options=@json:'{"number_of_password_prompts":0}' --ssh-keys=$aspera_key_path
-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 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=my_upload_folder --format=nagios
-server info
-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}' --ts=@json:'{"use_ascp4":true}' --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
+> **Note:** Add `ascli server` in front of the commands:
+
+```bash
+browse /
+browse / --password=@none: --ssh-options=@json:'{"number_of_password_prompts":0}' --ssh-keys=$aspera_key_path
+browse my_inside_folder/test_file.bin
+browse my_upload_folder/target_hot
+cp my_inside_folder/test_file.bin my_upload_folder/200KB.2
+delete my_inside_folder
+delete my_upload_folder/to.delete
+df
+download my_inside_folder/test_file.bin --to-folder=. --transfer-info=@json:'{"wss":false,"resume":{"iter_max":1}}'
+download my_inside_folder/test_file.bin --to-folder=my_upload_folder --transfer=node
+du /
+health transfer --to-folder=my_upload_folder --format=nagios
+info
+md5sum my_inside_folder/test_file.bin
+mkdir my_inside_folder --logger=stdout
+mkdir my_upload_folder/target_hot
+mv my_upload_folder/200KB.2 my_upload_folder/to.delete
+sync admin status --sync-info=@json:'{"name":"sync2","local":{"path":"/data/local_sync"}}'
+sync admin status --sync-info=@json:'{"name":"sync2"}'
+sync admin status my_sync --sync-info=@json:'{"sessions":[{"name":"my_sync","local_dir":"/data/local_sync"}]}'
+sync start --sync-info=@json:'{"instance":{"quiet":false},"sessions":[{"name":"my_sync","direction":"pull","remote_dir":"my_inside_folder","local_dir":"/data/local_sync","reset":true}]}'
+sync start --sync-info=@json:'{"name":"sync2","local":{"path":"/data/local_sync"},"remote":{"path":"my_inside_folder"},"reset":true,"quiet":false}'
+upload 'faux:///test1?100m' 'faux:///test2?100m' --to-folder=/Upload --ts=@json:'{"target_rate_kbps":1000000,"resume_policy":"none","precalculate_job_size":true}'
+upload 'faux:///test1?100m' 'faux:///test2?100m' --to-folder=/Upload --ts=@json:'{"target_rate_kbps":1000000,"resume_policy":"none","precalculate_job_size":true}' --transfer-info=@json:'{"quiet":false}' --progress=no
+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
+upload --sources=@ts --transfer-info=@json:'{"ascp_args":["--file-list","filelist.txt"]}' --to-folder=my_inside_folder
+upload --sources=@ts --transfer-info=@json:'{"ascp_args":["--file-pair-list","file_pair_list.txt"]}'
+upload --sources=@ts --ts=@json:'{"paths":[{"source":"test_file.bin","destination":"my_inside_folder/other_name_4"}]}' --transfer=trsdk
+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"]}'
+upload --src-type=pair --sources=@json:'["test_file.bin","my_inside_folder/other_name_3"]' --transfer-info=@json:'{"quiet":false}' --ts=@json:'{"use_ascp4":true}' --progress=no
+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"}'
+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
@@ -5087,7 +5203,7 @@ ascli server browse /aspera-test-dir-large
 ascli server download /aspera-test-dir-large/200MB
 ```
 
-`initdemo` creates a [option preset](#lprt) `demoserver` and set it as default for plugin `server`.
+`initdemo` creates a [Option Preset](#option-preset)' `demoserver` and set it as default for plugin `server`.
 
 If an SSH private key is used for authentication with a passphrase, the passphrase needs to be provided to both options: `ssh_options`, for browsing, and `ts` for transfers:
 
@@ -5095,7 +5211,7 @@ If an SSH private key is used for authentication with a passphrase, the passphra
 ascli server --url=ssh://_server_address_here_:33001 --username=_user_here_ --ssh_keys=_private_key_path_here_ --passphrase=_passphrase_here_
 ```
 
-## <a id="node"></a>Plugin: `node`: IBM Aspera High Speed Transfer Server Node
+## Plugin: `node`: IBM Aspera High Speed Transfer Server Node
 
 This plugin gives access to capabilities provided by the HSTS node API.
 
@@ -5221,7 +5337,7 @@ There are three sync types of operations:
 
 It is possible to start a FASPStream session using the node API:
 
-Use the command `ascli node stream create --ts=@json:<value>`, with [*transfer-spec*](#transferspec):
+Use the command `ascli node stream create --ts=@json:<value>`, with [*transfer-spec*](#transfer-specification):
 
 ```json
 {"direction":"send","source":"udp://233.3.3.4:3000?loopback=1&ttl=2","destination":"udp://233.3.3.3:3001/","remote_host":"localhost","remote_user":"stream","remote_password":"my_pass_here"}
@@ -5390,7 +5506,7 @@ Let's assume that the access key was created, and a default configuration is set
   ```
 
   > **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.
+  > 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**:
 
@@ -5435,7 +5551,7 @@ Let's assume that the access key was created, and a default configuration is set
 - 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
+  ascli node bearer_token @file:./myorgkey.pem @json:'{"user_id":"'$my_user_id'","_validity":3600}' --output=bearer.txt
   ```
 
 #### Bearer token: User side
@@ -5454,75 +5570,86 @@ ascli node -N --url=... --password="Bearer $(cat bearer.txt)" --root-id=$my_fold
 
 ### Node sample commands
 
-```bash
-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
-node async files 1
-node async list
-node async show 1
-node async show ALL
-node basic_token
-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 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 %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 %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 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
+> **Note:** Add `ascli node` in front of the commands:
+
+```bash
+--url=https://tst.example.com/path --password="Bearer bearer_666" --root-id=root_id access_key do self br /
+access_key create @json:'{"id":"my_username","secret":"my_password_here","storage":{"type":"local","path":"/"}}'
+access_key delete my_username
+access_key do my_ak_name browse /
+access_key do my_ak_name delete /folder2
+access_key do my_ak_name delete testfile1
+access_key do my_ak_name download testfile1 --to-folder=.
+access_key do my_ak_name find my_test_folder
+access_key do my_ak_name find my_test_folder @ruby:'->(f){f["name"].end_with?(".jpg")}'
+access_key do my_ak_name find my_test_folder exec:'f["name"].end_with?(".jpg")'
+access_key do my_ak_name mkdir /folder1
+access_key do my_ak_name node_info /
+access_key do my_ak_name rename /folder1 folder2
+access_key do my_ak_name show %id:1
+access_key do my_ak_name show /testfile1
+access_key do my_ak_name upload 'faux:///testfile1?1k' --default_ports=no
+access_key do self permission %id:root_id create @json:'{"access_type":"user","access_id":"666"}'
+access_key do self show / --fields=id --output=root_id
+access_key list
+access_key set_bearer_key self @file:my_private_key
+access_key show %id:self
+api_details
+asperabrowser
+async bandwidth 1
+async counters 1
+async files 1
+async list
+async show 1
+async show ALL
+basic_token
+bearer_token @file:my_private_key @json:'{"user_id":"666"}' --output=bearer_666
+browse / --log-level=trace2
+central file list
+central file modify --validator=1 --query=@json:'{"files":[]}'
+central session list
+delete @list:,my_upload_folder/a_folder,my_upload_folder/tdlink,my_upload_folder/a_file
+delete my_upload_folder/test_file.bin
+download my_upload_folder/test_file.bin --to-folder=.
+health
+http_node_download my_upload_folder/test_file.bin --to-folder=.
+info --fpac='function FindProxyForURL(url,host){return "DIRECT"}'
+license
+mkdir my_upload_folder/a_folder
+mkfile my_upload_folder/a_file1 "hello world"
+mklink my_upload_folder/a_folder my_upload_folder/tdlink
+rename my_upload_folder a_file1 a_file
+search / --query=@json:'{"sort":"mtime"}'
+service create @json:'{"id":"service1","type":"WATCHD","run_as":{"user":"user1"}}'
+service delete service1
+service list
+slash
+space /
+ssync bandwidth %name:my_node_sync
+ssync counters %name:my_node_sync
+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"}}}'
+ssync delete %name:my_node_sync
+ssync files %name:my_node_sync
+ssync list
+ssync show %name:my_node_sync
+ssync start %name:my_node_sync
+ssync state %name:my_node_sync
+ssync stop %name:my_node_sync
+ssync summary %name:my_node_sync
+stream list
+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"}}'
+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}]}'
+sync start --sync-info=@json:'{"name":"my_node_sync2","reset":true,"direction":"pull","local":{"path":"/data/local_sync"},"remote":{"path":"/aspera-test-dir-tiny"}}'
+sync start --sync-info=@json:'{"sessions":[{"name":"my_node_sync1","direction":"pull","local_dir":"/data/local_sync","remote_dir":"/aspera-test-dir-tiny","reset":true}]}'
+transfer list --query=@json:'{"active_only":true}'
+transfer sessions
+upload --to-folder=my_upload_folder --sources=@ts --ts=@json:'{"paths":[{"source":"/aspera-test-dir-small/10MB.2"}],"precalculate_job_size":true}' --transfer=node --transfer-info=@json:'{"url":"https://node.example.com/path@","username":"my_username","password":"my_password_here"}'
+upload --username=my_ak_name --password=my_ak_secret test_file.bin
+upload test_file.bin --to-folder=my_upload_folder --ts=@json:'{"target_rate_cap_kbps":10000}'
+watch_folder list
+```
+
+## Plugin: `faspex5`: IBM Aspera Faspex v5
 
 IBM Aspera's newer self-managed application.
 
@@ -5537,7 +5664,7 @@ IBM Aspera's newer self-managed application.
 
 > **Note:** If you have a Faspex 5 public link, provide it, unchanged, through the option `url`
 
-For a quick start, one can use the wizard, which will help creating a [option preset](#lprt):
+For a quick start, one can use the wizard, which will help creating a [Option Preset](#option-preset)':
 
 ```bash
 ascli config wizard
@@ -5610,7 +5737,7 @@ Activation is in two steps:
   - Select `Account Settings`
   - on the bottom in the text field: `Public key in PEM format` paste the **public** key corresponding to the private key used by the user.
 
-  **Note:** If you don't have any refer to section [Private Key](#private_key)
+  **Note:** If you don't have any refer to section [Private Key](#private-key)
 
 Then use these options:
 
@@ -5670,7 +5797,60 @@ Use this token as password and use `--auth=boot`.
 ascli config preset update f5boot --url=https://localhost/aspera/faspex --auth=boot --password=_token_here_
 ```
 
-### Faspex 5 sample commands
+### Faspex5 sample commands
+
+> **Note:** Add `ascli faspex5` in front of the commands:
+
+```bash
+admin res accounts list
+admin res contacts list
+admin res jobs list
+admin res metadata_profiles list
+admin res node list
+admin res oauth_clients list
+admin res registrations list
+admin res saml_configs list
+admin res shared_inboxes invite %name:my_shared_box_name johnny@example.com
+admin res shared_inboxes list
+admin res shared_inboxes list --query=@json:'{"all":true}'
+admin res shared_inboxes members %name:my_shared_box_name create %name:john@example.com
+admin res shared_inboxes members %name:my_shared_box_name delete %name:john@example.com
+admin res shared_inboxes members %name:my_shared_box_name delete %name:johnny@example.com
+admin res shared_inboxes members %name:my_shared_box_name list
+admin res workgroups list
+admin smtp show
+admin smtp test my_email_external
+bearer_token
+gateway --pid-file=pid_f5_fxgw https://localhost:12346/aspera/faspex &
+health
+invitation list
+invitations create @json:'{"email_address":"aspera.user1+u@gmail.com"}'
+packages list --box=my_shared_box_name
+packages list --box=my_workgroup --group-type=workgroups
+packages list --query=@json:'{"mailbox":"inbox","status":"completed"}'
+packages receive --box=my_shared_box_name package_box_id1 --to-folder=.
+packages receive --box=my_workgroup --group-type=workgroups workgroup_package_id1 --to-folder=.
+packages receive ALL --once-only=yes --to-folder=.
+packages receive INIT --once-only=yes
+packages receive f5_p31 --to-folder=. --ts=@json:'{"content_protection_password":"my_secret_here"}'
+packages send --shared-folder=%name:my_shared_folder_name @json:'{"title":"test title","recipients":["my_email_internal"]}' my_shared_folder_file
+packages send --url=my_public_link_send_f5_user @json:'{"title":"test title"}' test_file.bin
+packages send --url=my_public_link_send_shared_box @json:'{"title":"test title"}' test_file.bin
+packages send @json:'{"title":"test title","recipients":["my_shared_box_name"],"metadata":{"Options":"Opt1","TextInput":"example text"}}' test_file.bin
+packages send @json:'{"title":"test title","recipients":["my_workgroup"]}' test_file.bin
+packages send @json:'{"title":"test title","recipients":[{"name":"my_username"}]my_meta}' test_file.bin --ts=@json:'{"content_protection_password":"my_secret_here"}'
+packages show --box=my_shared_box_name package_box_id1
+packages show --box=my_workgroup --group-type=workgroups workgroup_package_id1
+packages show f5_p31
+packages status f5_p31
+postprocessing --pid-file=pid_f5_postproc @json:'{"url":"https://localhost:8443/domain","processing":{"script_folder":""}}' &
+shared browse %name:my_src
+shared list
+shared_folders browse %name:my_shared_folder_name
+shared_folders list
+user profile modify @json:'{"preference":{"connect_disabled":false}}'
+user profile show
+```
 
 Most commands are directly REST API calls.
 Parameters to commands are carried through option `query`, as extended value, for `list`, or through positional argument for creation.
@@ -5678,53 +5858,6 @@ 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**.
 
-```bash
-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 oauth_clients list
-faspex5 admin res registrations list
-faspex5 admin res saml_configs list
-faspex5 admin res shared_inboxes invite %name:my_shared_box_name johnny@example.com
-faspex5 admin res shared_inboxes list
-faspex5 admin res shared_inboxes list --query=@json:'{"all":true}'
-faspex5 admin res shared_inboxes members %name:my_shared_box_name create %name:john@example.com
-faspex5 admin res shared_inboxes members %name:my_shared_box_name delete %name:john@example.com
-faspex5 admin res shared_inboxes members %name:my_shared_box_name delete %name:johnny@example.com
-faspex5 admin res shared_inboxes members %name:my_shared_box_name list
-faspex5 admin res workgroups list
-faspex5 admin smtp show
-faspex5 admin smtp test my_email_external
-faspex5 bearer_token
-faspex5 gateway --pid-file=pid_f5_fxgw https://localhost:12346/aspera/faspex &
-faspex5 health
-faspex5 packages list --box=my_shared_box_name
-faspex5 packages list --box=my_workgroup --group-type=workgroups
-faspex5 packages list --query=@json:'{"mailbox":"inbox","state":["released"]}'
-faspex5 packages receive --box=my_shared_box_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 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_box_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_box_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=pid_f5_postproc @json:'{"url":"https://localhost:8443/domain","processing":{"script_folder":""}}' &
-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
 
 By default, package operations (send, receive, list) are done on the user's inbox.
@@ -5829,6 +5962,20 @@ Examples:
   ascli faspex5 packages list @ruby:'->(p){p["state"].eql?("released")}'
   ```
 
+### Faspex 5: Content of a received Package
+
+> **Note:** Listing content also applies to shares folder, nodes, and received packages (using `--box=outbox`).
+
+To list the content of a package, use command `faspex5 packages browse /`.
+
+Option `query` is available.
+
+To list recursively add option `--query=@json:{"recursive":true}`.
+
+> **Note:** Option `recirsive` makes recursive API calls, so it can take a long time on large packages.
+
+To limit the number of items retrieved, use option `--query=@json:{"max":10}`.
+
 ### Faspex 5: Receive a package
 
 To receive one, or several packages at once, use command `faspex5 packages receive`.
@@ -5930,6 +6077,14 @@ To initialize, and skip all current package so that next time `ALL` is used, onl
 ascli faspex5 packages receive INIT --once-only=yes
 ```
 
+### Faspex 5: Invitations
+
+There are two types of invitations of package submission: public or private.
+
+Public invitations are for external users, provide just the email address.
+
+Private invitations are for internal users, provide the user or shared inbox identifier through field `recipient_name`.
+
 ### Faspex 5: Faspex 4-style postprocessing
 
 `ascli` provides command `postprocessing` in plugin `faspex5` to emulate Faspex 4 postprocessing.
@@ -5945,8 +6100,7 @@ The following parameters are supported:
 
 | parameter                  | type    | default                | description                                         |
 |----------------------------|---------|------------------------|-----------------------------------------------------|
-<!-- markdownlint-disable-next-line -->
-| url                        | string  | http://localhost:8080  | Base url on which requests are listened             |
+| url                        | string  | http://localhost:8080  | Base url on which requests are listened             | <!-- markdownlint-disable-line -->
 | certificate                | hash    | nil                    | Certificate information (if HTTPS)                  |
 | certificate.key            | string  | nil                    | Path to private key file                            |
 | certificate.cert           | string  | nil                    | Path to certificate                                 |
@@ -5978,12 +6132,12 @@ Then, the postprocessing script executed will be `script1.sh`.
 
 Environment variables at set to the values provided by the web hook which are the same as Faspex 4 postprocessing.
 
-## <a id="faspex"></a>Plugin: `faspex`: IBM Aspera Faspex v4
+## Plugin: `faspex`: IBM Aspera Faspex v4
 
-Notes:
+> **Note:** For full details on Faspex API, refer to: [Reference on Developer Site](https://developer.ibm.com/apis/catalog/?search=faspex)
 
-- The command `v4` requires the use of APIv4, refer to the Faspex Admin manual on how to activate.
-- For full details on Faspex API, refer to: [Reference on Developer Site](https://developer.ibm.com/apis/catalog/?search=faspex)
+This plugin uses APIs versions 3 Faspex v4.
+The `v4` command requires the use of API v4, refer to the Faspex Admin manual on how to activate.
 
 ### Listing Packages
 
@@ -6130,49 +6284,51 @@ The node configuration name is `my_faspex_node` here.
 ### Automated package download (cargo)
 
 It is possible to tell `ascli` to download newly received packages, much like the official
-cargo client, or drive. Refer to the [same section](#aoccargo) in the Aspera on Cloud plugin:
+cargo client, or drive. Refer to the [same section](#receive-new-packages-only-cargo) in the Aspera on Cloud plugin:
 
 ```bash
 ascli faspex packages recv ALL --once-only=yes --lock-port=12345
 ```
 
-### Faspex 4 sample commands
-
-```bash
-faspex address_book
-faspex dropbox list --recipient="*my_dbx"
-faspex health
-faspex login_methods
-faspex me
-faspex package list --box=sent --query=@json:'{"max":1}' --fields=package_id --display=data --format=csv --output=f4_prs2
-faspex package list --query=@json:'{"max":1}' --fields=package_id --display=data --format=csv --output=f4_prs1
-faspex package list --query=@json:'{"max":5}'
-faspex package list --recipient="*my_dbx" --format=csv --fields=package_id --query=@json:'{"max":1}' --output=f4_db_id1
-faspex package list --recipient="*my_wkg" --format=csv --fields=package_id --query=@json:'{"max":1}' --output=f4_db_id2
-faspex package receive --to-folder=. --link=https://app.example.com/recv_from_user_path
-faspex package receive ALL --once-only=yes --to-folder=. --query=@json:'{"max":10}'
-faspex package receive f4_db_id1 --recipient="*my_dbx" --to-folder=.
-faspex package receive f4_db_id2 --recipient="*my_wkg" --to-folder=.
-faspex package receive f4_pri1 --to-folder=.
-faspex package receive f4_prs2 --to-folder=. --box=sent
-faspex package send --delivery-info=@json:'{"title":"$(notdir test) PACKAGE_TITLE_BASE","recipients":["*my_dbx"]}' test_file.bin
-faspex package send --delivery-info=@json:'{"title":"$(notdir test) PACKAGE_TITLE_BASE","recipients":["*my_wkg"]}' test_file.bin
-faspex package send --delivery-info=@json:'{"title":"$(notdir test) PACKAGE_TITLE_BASE","recipients":["my_email_internal","my_username"]}' test_file.bin
-faspex package send --delivery-info=@json:'{"title":"$(notdir test) PACKAGE_TITLE_BASE","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":"$(notdir test) PACKAGE_TITLE_BASE"}' test_file.bin
-faspex package send --link=https://app.example.com/send_to_user_path --delivery-info=@json:'{"title":"$(notdir test) PACKAGE_TITLE_BASE"}' test_file.bin
-faspex source info %name:my_src --storage=@preset:faspex4_storage
-faspex source list
-faspex source node %name:my_src br / --storage=@preset:faspex4_storage
-faspex v4 dmembership list
-faspex v4 dropbox list
-faspex v4 metadata_profile list
-faspex v4 user list
-faspex v4 wmembership list
-faspex v4 workgroup list
-```
-
-## <a id="shares"></a>Plugin: `shares`: IBM Aspera Shares v1
+### Faspex sample commands
+
+> **Note:** Add `ascli faspex` in front of the commands:
+
+```bash
+address_book
+dropbox list --recipient="*my_dbx"
+health
+login_methods
+me
+package list --box=sent --query=@json:'{"max":1}' --fields=package_id --display=data --format=csv --output=f4_prs2
+package list --query=@json:'{"max":1}' --fields=package_id --display=data --format=csv --output=f4_prs1
+package list --query=@json:'{"max":5}'
+package list --recipient="*my_dbx" --format=csv --fields=package_id --query=@json:'{"max":1}' --output=f4_db_id1
+package list --recipient="*my_wkg" --format=csv --fields=package_id --query=@json:'{"max":1}' --output=f4_db_id2
+package receive --to-folder=. --link=https://app.example.com/recv_from_user_path
+package receive ALL --once-only=yes --to-folder=. --query=@json:'{"max":10}'
+package receive f4_db_id1 --recipient="*my_dbx" --to-folder=.
+package receive f4_db_id2 --recipient="*my_wkg" --to-folder=.
+package receive f4_pri1 --to-folder=.
+package receive f4_prs2 --to-folder=. --box=sent
+package send --delivery-info=@json:'{"title":"$(notdir test) PACKAGE_TITLE_BASE","recipients":["*my_dbx"]}' test_file.bin
+package send --delivery-info=@json:'{"title":"$(notdir test) PACKAGE_TITLE_BASE","recipients":["*my_wkg"]}' test_file.bin
+package send --delivery-info=@json:'{"title":"$(notdir test) PACKAGE_TITLE_BASE","recipients":["my_email_internal","my_username"]}' test_file.bin
+package send --delivery-info=@json:'{"title":"$(notdir test) PACKAGE_TITLE_BASE","recipients":["my_email_internal"]}' --remote_source=%name:my_src sample_source.txt
+package send --link=https://app.example.com/send_to_dropbox_path --delivery-info=@json:'{"title":"$(notdir test) PACKAGE_TITLE_BASE"}' test_file.bin
+package send --link=https://app.example.com/send_to_user_path --delivery-info=@json:'{"title":"$(notdir test) PACKAGE_TITLE_BASE"}' test_file.bin
+source info %name:my_src --storage=@preset:faspex4_storage
+source list
+source node %name:my_src br / --storage=@preset:faspex4_storage
+v4 dmembership list
+v4 dropbox list
+v4 metadata_profile list
+v4 user list
+v4 wmembership list
+v4 workgroup list
+```
+
+## Plugin: `shares`: IBM Aspera Shares v1
 
 Aspera Shares supports the **node API** for the file transfer part.
 
@@ -6192,69 +6348,77 @@ user_id=$(ascli shares admin user list --select=@json:'{"username":"entity1"}' -
 ascli shares admin share user_permissions $share_id create @json:'{"user_id":'$user_id',"browse_permission":true, "download_permission":true, "mkdir_permission":true,"delete_permission":true,"rename_permission":true,"content_availability_permission":true,"manage_permission":true}'
 ```
 
-### Shares 1 sample commands
+To figure out the entities payload, for example for creation, refer to the API documentation above.
+
+### Shares sample commands
+
+> **Note:** Add `ascli shares` in front of the commands:
 
 ```bash
-shares admin group all list
-shares admin node list
-shares admin share list --fields=DEF,-status,status_message
-shares admin share user_permissions 1 list
-shares admin user all app_authorizations 1 modify @json:'{"app_login":true}'
-shares admin user all app_authorizations 1 show
-shares admin user all list
-shares admin user all share_permissions 1 list
-shares admin user all share_permissions 1 show 1
-shares admin user ldap add the_name
-shares admin user local list
-shares admin user saml import @json:'{"id":"the_id","name_id":"the_name"}'
-shares files browse /
-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
+admin group all list
+admin node list
+admin share list --fields=DEF,-status,status_message
+admin share user_permissions 1 list
+admin user all app_authorizations 1 modify @json:'{"app_login":true}'
+admin user all app_authorizations 1 show
+admin user all list
+admin user all share_permissions 1 list
+admin user all share_permissions 1 show 1
+admin user ldap add the_name
+admin user local list
+admin user saml import @json:'{"id":"the_id","name_id":"the_name"}'
+files browse /
+files delete my_share1/test_file.bin
+files download --to-folder=. my_share1/test_file.bin
+files download --to-folder=. my_share1/test_file.bin --transfer=httpgw --transfer-info=@json:'{"url":"https://my_http_gw_fqdn_port/aspera/http-gwy"}'
+files upload --to-folder=my_share1 'faux:///testfile?1m' --transfer=httpgw --transfer-info=@json:'{"url":"https://my_http_gw_fqdn_port/aspera/http-gwy","synchronous":true,"api_version":"v1","upload_chunk_size":100000}'
+files upload --to-folder=my_share1 test_file.bin
+files upload --to-folder=my_share1 test_file.bin --transfer=httpgw --transfer-info=@json:'{"url":"https://my_http_gw_fqdn_port/aspera/http-gwy"}'
+health
 ```
 
-## <a id="console"></a>Plugin: `console`: IBM Aspera Console
+## Plugin: `console`: IBM Aspera Console
 
 ### Console sample commands
 
+> **Note:** Add `ascli console` in front of the commands:
+
 ```bash
-console health
-console transfer current list
-console transfer smart list
-console transfer smart sub my_smart_id @json:'{"source":{"paths":["my_smart_file"]},"source_type":"user_selected"}'
+health
+transfer current list
+transfer smart list
+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
+## Plugin: `orchestrator`:IBM Aspera Orchestrator
 
 ### Orchestrator sample commands
 
+> **Note:** Add `ascli orchestrator` in front of the commands:
+
 ```bash
-orchestrator health
-orchestrator info
-orchestrator plugins
-orchestrator processes
-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_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_workflow_id
+health
+info
+plugins
+processes
+workflow details my_workflow_id
+workflow export my_workflow_id
+workflow inputs my_workflow_id
+workflow list
+workflow start my_workflow_id @json:'{"Param":"world !"}'
+workflow start my_workflow_id @json:'{"Param":"world !"}' --result=ResultStep:Complete_status_message
+workflow status ALL
+workflow status my_workflow_id
 ```
 
-## <a id="cos"></a>Plugin: `cos`: IBM Cloud Object Storage
+## Plugin: `cos`: IBM Cloud Object Storage
 
 The IBM Cloud Object Storage provides the possibility to execute transfers using FASP.
 It uses the same transfer service as Aspera on Cloud, called Aspera Transfer Service (ATS).
 Available ATS regions: [https://status.aspera.io](https://status.aspera.io)
 
 There are two possibilities to provide credentials.
-If you already have the endpoint, API key and CRN, use the first method.
+If you already have the endpoint, API key and Resource Instance ID (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, API key and Resource Instance ID (CRN)
@@ -6322,12 +6486,12 @@ The field `resource_instance_id` is for option `crn`
 
 The field `apikey` is for option `apikey`
 
-(If needed: endpoints for regions can be found by querying the `endpoints` URL.)
+> **Note:** endpoints for regions can be found by querying the `endpoints` URL from file or from the IBM Cloud Console.
 
 The required options for this method are:
 
 - `bucket` bucket name
-- `region` bucket region, e.g. eu-de
+- `region` bucket region, e.g. `eu-de`
 - `service_credentials` see below
 
 For example, let us create a default configuration:
@@ -6339,7 +6503,7 @@ ascli config preset set default cos mycos
 
 ### Operations, transfers
 
-Let's assume you created a default configuration from once of the two previous steps (else specify the access options on command lines).
+Let's assume you created a default configuration from one of the two previous steps (else specify the access options on command lines).
 
 A subset of `node` plugin operations are supported, basically node API:
 
@@ -6348,20 +6512,22 @@ 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:** A dummy file `sample1G` of size 2GB is generated 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
+### Cos sample commands
+
+> **Note:** Add `ascli cos` in front of the commands:
 
 ```bash
-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:my_cos_svc_cred node info
-cos node access_key show self
-cos node download test_file.bin --to-folder=.
-cos node info --log-level=trace2
-cos node upload test_file.bin
+node access_key show self
+node download test_file.bin --to-folder=.
+node info --bucket=my_bucket --endpoint=my_endpoint --apikey=my_api_key --crn=my_resource_instance_id
+node info --bucket=my_bucket --region=my_region --service-credentials=@json:@file:my_cos_svc_cred
+node info --log-level=trace2
+node upload test_file.bin
 ```
 
-## <a id="preview"></a>Plugin: `preview`: Preview generator for AoC
+## Plugin: `preview`: Preview generator for AoC
 
 The `preview` generates thumbnails (office, images, video) and video previews on storage for use primarily in the Aspera on Cloud application.
 It uses the **node API** of Aspera HSTS and requires use of Access Keys and its **storage root**.
@@ -6409,7 +6575,7 @@ If you use a value different than 16777216, then specify it using option `max_si
 
 > **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
+### External tools: Linux
 
 `ascli` requires the following external tools available in the `PATH`:
 
@@ -6476,7 +6642,7 @@ chmod a+x /usr/bin/unoconv
 The preview generator should be executed as a non-user.
 When using object storage, any user can be used, but when using local storage it is usually better to use the user `xfer`, as uploaded files are under this identity: this ensures proper access rights. (we will assume this)
 
-Like any `ascli` commands, parameters can be passed on command line or using a configuration [option preset](#lprt).
+Like any `ascli` commands, parameters can be passed on command line or using a configuration [Option Preset](#option-preset)'.
 The configuration file must be created with the same user used to run so that it is properly used on runtime.
 
 The `xfer` user has a special protected shell: `aspshell`, so in order to update the configuration, and when changing identity, specify an alternate shell.
@@ -6654,23 +6820,26 @@ If the preview generator does not have access to files on the file system (it is
 
 ### Preview sample commands
 
+> **Note:** Add `ascli preview` in front of the commands:
+
 ```bash
-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 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 test --mimemagic=yes --base=test my_dcm
-preview trevents --once-only=yes --skip-types=office --log-level=info
+check --skip-types=office
+scan --scan-id=1 --skip-types=office --log-level=info --file-access=remote --ts=@json:'{"target_rate_kbps":1000000}'
+scan --skip-types=office --log-level=info
+show --base=test my_docx
+show --base=test my_mpg --video-png-conv=animated
+show --base=test my_mpg --video-png-conv=fixed
+show --base=test my_mpg mp4 --video-conversion=clips
+show --base=test my_mpg mp4 --video-conversion=reencode
+show --base=test my_pdf
+test --base=test my_dcm
+test --base=test my_mxf mp4 --video-conversion=blend --query=@json:'{"text":true,"double":true}'
+test --mimemagic=yes --base=test my_dcm
+test --mimemagic=yes --base=test my_jpg_unk
+trevents --once-only=yes --skip-types=office --log-level=info
 ```
 
-## <a id="async"></a>IBM Aspera Sync
+## IBM Aspera Sync
 
 An interface for the `async` utility is provided in the following plugins:
 
@@ -6733,11 +6902,11 @@ Interesting `ascp` features are found in its arguments: (see `ascp` manual):
 - `ascp` has an option to send only files not modified since the last X seconds: `--exclude-newer-than`, `--exclude-older-than` (`exclude_newer_than`,`exclude_older_than`)
 - `--src-base` (`src_base`) if top level folder name shall not be created on destination
 
-> **Note:** `ascli` takes transfer parameters exclusively as a [*transfer-spec*](#transferspec), with `ts` option.
+> **Note:** `ascli` takes transfer parameters exclusively as a [*transfer-spec*](#transfer-specification), with `ts` option.
 >
-> **Note:** Most, but not all, native `ascp` arguments are available as standard [*transfer-spec*](#transferspec) parameters.
+> **Note:** Most, but not all, native `ascp` arguments are available as standard [*transfer-spec*](#transfer-specification) parameters.
 >
-> **Note:** Only for the [`direct`](#agt_direct) transfer agent (not others, like connect or node), native `ascp` arguments can be provided with parameter `ascp_args` of option `transfer_info` .
+> **Note:** Only for the [`direct`](#agent-direct) transfer agent (not others, like connect or node), native `ascp` arguments can be provided with parameter `ascp_args` of option `transfer_info` .
 
 #### Server side and configuration
 
@@ -6745,7 +6914,7 @@ Virtually any transfer on a **repository** on a regular basis might emulate a ho
 
 > **Note:** File detection is not based on events (`inotify`, etc...), but on a simple folder scan on source side.
 >
-> **Note:** Parameters may be saved in a [option preset](#lprt) and used with `-P`.
+> **Note:** Parameters may be saved in a [Option Preset](#option-preset)' and used with `-P`.
 
 #### Scheduling
 
@@ -6912,7 +7081,7 @@ Transfer is: <%=global_transfer_status%>
 
 This gem comes with a second executable tool providing a simplified standardized interface to start a FASP session: `asession`.
 
-It aims at simplifying the startup of a FASP session from a programmatic stand point as formatting a [*transfer-spec*](#transferspec) is:
+It aims at simplifying the startup of a FASP session from a programmatic stand point as formatting a [*transfer-spec*](#transfer-specification) is:
 
 - Common to Aspera Node API (HTTP POST /ops/transfer)
 - Common to Aspera Connect API (browser javascript startTransfer)
@@ -6922,20 +7091,22 @@ Hopefully, IBM integrates this directly in `ascp`, and this tool is made redunda
 
 This makes it easy to integrate with any language provided that one can spawn a sub process, write to its STDIN, read from STDOUT, generate and parse JSON.
 
-`ascli` expect one single argument: a [*transfer-spec*](#transferspec).
+`ascli` expect one single argument: a session specification that contains parameters and a [*transfer-spec*](#transfer-specification).
 
-If no argument is provided, it assumes a value of: `@json:@stdin:`, i.e. a JSON formatted [*transfer-spec*](#transferspec) on stdin.
+If no argument is provided, it assumes a value of: `@json:@stdin:`, i.e. a JSON formatted on stdin.
 
 > **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 `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`
+Top level parameters supported by `asession`:
 
-> **Note:** In addition, many (deprecated) `EX_` [*transfer-spec*](#transferspec) parameters are supported for the [`direct`](#agt_direct) transfer agent (used by `asession`), refer to section [*transfer-spec*](#transferspec).
+| parameter | description |
+|-----------|-------------|
+| `spec` | the [*transfer-spec*](#transfer-specification) |
+| `agent` | same parameters as transfer-info for agent `direct` |
+| `loglevel` | log level of `asession` |
+| `file_list_folder` | the folder used to store (for garbage collection) generated file lists. By default it is `[system tmp folder]/[username]_asession_filelists` |
 
 ### Comparison of interfaces
 
@@ -6965,7 +7136,7 @@ asession < session.json
 
 `asession` also supports asynchronous commands (on the management port). Instead of the traditional text protocol as described in `ascp` manual, the format for commands is: one single line per command, formatted in JSON, where parameters shall be **snake** style, for example: `LongParameter` -&gt; `long_parameter`
 
-This is particularly useful for a persistent session ( with the [*transfer-spec*](#transferspec) parameter: `"keepalive":true` )
+This is particularly useful for a persistent session ( with the [*transfer-spec*](#transfer-specification) parameter: `"keepalive":true` )
 
 ```json
 asession
@@ -6987,23 +7158,24 @@ asession -h
 USAGE
     asession
     asession -h|--help
-    asession <transfer spec extended value>
+    asession <session spec extended value>
     
     If no argument is provided, default will be used: @json:@stdin
     -h, --help display this message
-    <transfer spec extended value> a JSON value for transfer_spec, using the prefix: @json:
+    <session spec extended value> a dictionary value (Hash)
     The value can be either:
        the JSON description itself, e.g. @json:'{"xx":"yy",...}'
        @json:@stdin, if the JSON is provided from stdin
        @json:@file:<path>, if the JSON is provided from a file
+    Parameter spec is mandatory, it contains the transfer spec
     Asynchronous commands can be provided on STDIN, examples:
        {"type":"START","source":"/aspera-test-dir-tiny/200KB.2"}
        {"type":"START","source":"xx","destination":"yy"}
        {"type":"DONE"}
-Note: debug information can be placed on STDERR, using the "EX_loglevel" parameter in transfer spec (debug=0)
+Note: debug information can be placed on STDERR, using the "loglevel" parameter in session spec (debug=0)
 EXAMPLES
-    asession @json:'{"remote_host":"demo.asperasoft.com","remote_user":"asperaweb","ssh_port":33001,"remote_password":"demoaspera","direction":"receive","destination_root":"./test.dir","paths":[{"source":"/aspera-test-dir-tiny/200KB.1"}]}'
-    echo '{"remote_host":...}'|asession @json:@stdin
+    asession @json:'{"spec":{"remote_host":"demo.asperasoft.com","remote_user":"asperaweb","ssh_port":33001,"remote_password":"demoaspera","direction":"receive","destination_root":"./test.dir","paths":[{"source":"/aspera-test-dir-tiny/200KB.1"}]}}'
+    echo '{"spec":{"remote_host":...}}'|asession @json:@stdin
 
 ```
 
@@ -7012,7 +7184,7 @@ EXAMPLES
 Main components:
 
 - `Aspera` generic classes for REST and OAuth
-- `Aspera::Fasp`: starting and monitoring transfers. It can be considered as a FASPManager class for Ruby.
+- `Aspera::Agent::Direct`: starting and monitoring transfers. It can be considered as a FASPManager class for Ruby.
 - `Aspera::Cli`: `ascli`.
 
 Working examples can be found in repo: <https://github.com/laurent-martin/aspera-api-examples> in Ruby examples.
@@ -7033,7 +7205,7 @@ So, it evolved into `ascli`:
 
 - Portable: works on platforms supporting `ruby` (and `ascp`)
 - Easy to install with the `gem` utility
-- Supports transfers with multiple [Transfer Agents](#agents), that&apos;s why transfer parameters moved from `ascp` command line to [*transfer-spec*](#transferspec) (more reliable , more standard)
+- Supports transfers with multiple [Transfer Agents](#transfer-clients-agents), that&apos;s why transfer parameters moved from `ascp` command line to [*transfer-spec*](#transfer-specification) (more reliable , more standard)
 - `ruby` is consistent with other Aspera products
 
 Over the time, a supported command line tool `aspera` was developed in C++, it was later on deprecated.