aspera-cli 4.7.0 → 4.9.0

data/README.md

@@ -2,7 +2,7 @@
 
 [comment1]: # (Do not edit this README.md, edit docs/README.erb.md, for details, read docs/README.md)
 
-Version : 4.7.0
+Version : 4.9.0
 
 Laurent/2016-2022
 
@@ -19,6 +19,16 @@ Minimum required Ruby version: >= 2.4. Deprecation notice: the minimum will be 2
 [Aspera APIs on IBM developer](https://developer.ibm.com/?size=30&q=aspera&DWContentType[0]=APIs)
 [Link 2](https://developer.ibm.com/apis/catalog/?search=aspera)
 
+Release notes: see [CHANGELOG.md](CHANGELOG.md)
+
+[![CII Best Practices](https://bestpractices.coreinfrastructure.org/projects/5861/badge)](https://bestpractices.coreinfrastructure.org/projects/5861)
+
+## BUGS, FEATURES, CONTRIBUTION
+
+Refer to [BUGS.md](BUGS.md) and [CONTRIBUTING.md](CONTRIBUTING.md).
+
+One can also [create one's own plugin](#createownplugin).
+
 ## <a id="when_to_use"></a>When to use and when not to use
 
 `ascli` is designed to be used as a command line tool to:
@@ -48,33 +58,12 @@ Using APIs (application REST API and transfer SDK) will prove to be easier to de
 
 For scripting and ad'hoc command line operations, `ascli` is perfect.
 
-## <a id="parsing"></a>Notations, Shell and Command line parsing
+## Notations, Shell, Examples
 
 In examples, command line operations are shown using a shell such: `bash` or `zsh`.
 
 Command line parameters in examples beginning with `my_`, like `my_param_value` are user-provided value and not fixed value commands.
 
-`ascli` is typically executed in a shell, either interactively or in a script. `ascli` receives its arguments from this shell.
-
-On Linux and Unix environments, this is typically a POSIX shell (bash, zsh, ksh, sh). In this environment shell command line parsing applies before `ascli` (Ruby) is executed, e.g. [bash shell operation](https://www.gnu.org/software/bash/manual/bash.html#Shell-Operation). Ruby receives a list parameters and gives it to `ascli`. So special character handling (quotes, spaces, env vars, ...) is done in the shell.
-
-On Windows, `cmd.exe` is typically used. Windows process creation does not receive the list of arguments but just the whole line. It's up to the program to parse arguments. Ruby follows the Microsoft C/C++ parameter parsing rules.
-
-* [Windows: How Command Line Parameters Are Parsed](https://daviddeley.com/autohotkey/parameters/parameters.htm#RUBY)
-* [Understand Quoting and Escaping of Windows Command Line Arguments](http://www.windowsinspired.com/understanding-the-command-line-string-and-arguments-received-by-a-windows-program/)
-
-In case of doubt of argument values after parsing test like this:
-
-```bash
-ascli conf echo "Hello World" arg2 3
-```
-
-```bash
-"Hello World"
-ERROR: Argument: unprocessed values: ["arg2", "3"]
-```
-
-`echo` displays the value of the first argument using ruby syntax (strings get double quotes) after command line parsing (shell) and extended value parsing (`ascli`), next command line arguments are shown in the error message.
 
 ## Quick Start
 
@@ -89,7 +78,7 @@ ascli --version
 ```
 
 ```bash
-4.7.0
+4.9.0
 ```
 
 ### First use
@@ -196,11 +185,9 @@ An internet connection is required for the installation. If you don't have inter
 
 ### Docker container
 
-Use this method only if you know what you do, else use the standard recommended method as described here above.
+This method installs a docker image that contains: Ruby, `ascli` and the FASP SDK.
 
-This method installs a docker image that contains: Ruby, `ascli` and the FASP sdk.
-
-The image is: [https://hub.docker.com/r/martinlaurent/ascli](https://hub.docker.com/r/martinlaurent/ascli)
+The image is: <https://hub.docker.com/r/martinlaurent/ascli>. It is built from this [Dockerfile](Dockerfile).
 
 Ensure that you have Docker installed.
 
@@ -208,10 +195,16 @@ Ensure that you have Docker installed.
 docker --version
 ```
 
-Download the wrapping script:
+An example of wrapping script is provided: `dascli`. If you have installed `ascli`, the script `dascli` can be found:
+
+```bash
+cp $(ascli conf gem path)/../examples/dascli ascli
+```
+
+Alternatively [download from the GIT repo](https://raw.githubusercontent.com/IBM/aspera-cli/main/examples/dascli) :
 
 ```bash
-curl -o ascli https://raw.githubusercontent.com/IBM/aspera-cli/develop/bin/dascli
+curl -o ascli https://raw.githubusercontent.com/IBM/aspera-cli/main/examples/dascli
 ```
 
 ```bash
@@ -224,14 +217,13 @@ Install the container image:
 ./ascli install
 ```
 
-Start using it !
-
-Note that the tool is run in the container, so transfers are also executed in the container, not calling host.
+Note that ascli is run in the container, so transfers are also executed in the container (not calling host, like for the regular ascli).
 
-The wrapping script maps the container folder `/usr/src/app/config` to configuration folder `$HOME/.aspera/ascli` on host.
+The wrapping script maps the folder `/usr/src/app/config` in the container to configuration folder `$HOME/.aspera/ascli` on host.
+This allows having persistent configuration.
 
 To transfer to/from the native host, you will need to map a volume in docker or use the config folder (already mapped).
-To add local storage as a volume edit the script: `ascli` and add a `--volume` stanza.
+To add local storage as a volume edit the script: `ascli` and add a `--volume` stanza near the existing one.
 
 ### <a id="ruby"></a>Ruby
 
@@ -312,11 +304,13 @@ rvm version
 
 #### Windows: Installer
 
-Install Latest stable Ruby using [https://rubyinstaller.org/](https://rubyinstaller.org/) :
+Install Latest stable Ruby:
 
-* Go to "Downloads".
-* Select the Ruby 2 version "without devkit", x64 corresponding to the one recommended "with devkit". Devkit is not needed.
-* At the end of the installer uncheck the box to skip the installation of "MSys2": not needed.
+* Navigate to [https://rubyinstaller.org/](https://rubyinstaller.org/) &rarr; **Downloads**.
+* Download the latest Ruby installer **with devkit**. (Msys2 is needed to install some native extensions, such as `grpc`)
+* Execute the installer which installs by default in: `RubyVV-x64` (VV is the version number)
+* At the end of the installation procedure execute the Msys2 installer (ridk install) and select option 3 (msys and mingw)
+* Install the "mime info" file as specified in [this section](#mimeinfo).
 
 #### macOS: pre-installed or `brew`
 
@@ -336,20 +330,31 @@ brew install ruby
 
 If your Linux distribution provides a standard ruby package, you can use it provided that the version is compatible (check at beginning of section).
 
-Example:
+Example: Centos 8 Stream
 
 ```bash
-yum install -y ruby rubygems ruby-json
+yum install make automake gcc gcc-c++ kernel-devel
+yum install redhat-rpm-config
+dnf module reset ruby
+dnf module enable ruby:3.0
+dnf module -y install ruby:3.0/common
+gem install aspera-cli
 ```
 
-One can cleanup the whole yum-installed ruby environment like this to uninstall:
+Other examples:
 
 ```bash
-gem uninstall $(ls $(gem env gemdir)/gems/|sed -e 's/-[^-]*$//'|sort -u)
+yum install -y ruby ruby-devel rubygems ruby-json
+```
+
+```bash
+apt install -y ruby ruby-dev rubygems ruby-json
 ```
 
+One can cleanup the whole yum-installed ruby environment like this to uninstall:
+
 ```bash
-yum remove -y ruby ruby-libs
+gem uninstall $(ls $(gem env gemdir)/gems/|sed -e 's/-[^-]*$//'|sort -u)
 ```
 
 #### Other Unixes (AIX)
@@ -531,10 +536,208 @@ Basic usage is displayed by executing:
 ascli -h
 ```
 
-Refer to sections: [Usage](#usage) and [Sample Commands](#commands).
+Refer to sections: [Usage](#usage).
 
 Not all `ascli` features are fully documented here, the user may explore commands on the command line.
 
+### `ascp` command line
+
+If you want to use `ascp` directly as a command line, refer to IBM Aspera documentation of either [Desktop Client](https://www.ibm.com/docs/en/asdc), [Endpoint](https://www.ibm.com/docs/en/ahte) or [Transfer Server](https://www.ibm.com/docs/en/ahts) where [a section on `ascp` can be found](https://www.ibm.com/docs/en/ahts/4.4?topic=linux-ascp-transferring-from-command-line).
+
+Using `ascli` with plugin `server` for command line gives advantages over ascp:
+
+* automatic resume on error
+* configuration file
+* choice of transfer agents
+* integrated support of multi-session
+
+Moreover all `ascp` options are supported either through transfer spec parameters and with the possibility to provide `ascp` arguments directly when the `direct` agent is used (`EX_ascp_args`).
+
+### <a id="parsing"></a>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 Operating System).
+
+#### Shell parsing for Linux, Unix, Macos
+
+On Linux and Unix environments, this is typically a POSIX shell (bash, zsh, ksh, sh).
+In this environment the shell parses the command line, possibly replacing variables, etc...
+see [bash shell operation](https://www.gnu.org/software/bash/manual/bash.html#Shell-Operation).
+Then it builds a list of arguments and then `ascli` (Ruby) is executed.
+Ruby receives a list parameters from shell and gives it to `ascli`.
+So special character handling (quotes, spaces, env vars, ...) is first done in the shell.
+
+#### Shell parsing for Windows
+
+On Windows, `cmd.exe` is typically used.
+Windows process creation does not receive the list of arguments but just the whole line.
+It's up to the program to parse arguments. Ruby follows the Microsoft C/C++ parameter parsing rules.
+
+* [Windows: How Command Line Parameters Are Parsed](https://daviddeley.com/autohotkey/parameters/parameters.htm#RUBY)
+* [Understand Quoting and Escaping of Windows Command Line Arguments](http://www.windowsinspired.com/understanding-the-command-line-string-and-arguments-received-by-a-windows-program/)
+
+#### Extended Values (JSON, Ruby, ...)
+
+Some of the CLI parameters are expected to be [Extended Values](#extended), i.e. not a simple strings, but a complex structure (Hash, Array).
+Typically, the `@json:` modifier is used, it expects a JSON string. JSON itself has some special syntax: for example `"` is used to denote strings.
+
+#### Testing Extended Values
+
+In case of doubt of argument values after parsing, one can test using command `config echo`. `config echo` takes exactly **one** argument which can use the [Extended Value](#extended) syntax. Unprocessed command line arguments are shown in the error message.
+
+Example: The shell parses three arguments (as strings: `1`, `2` and `3`), so the additional two arguments are not processed by the `echo` command.
+
+```bash
+ascli conf echo 1 2 3
+```
+
+```bash
+"1"
+ERROR: Argument: unprocessed values: ["2", "3"]
+```
+
+`config echo` displays the value of the first argument using Ruby syntax: it surrounds a string with `"` and add `\` before special characters.
+Note that 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 sample commands are provided when equivalent.
+For all example, most of special character handling is not specific to `ascli`: It depoends on the underlying syntax: shell , JSON, etc...
+Depending on the case, a different `format` is used to display the actual value.
+
+For example, in the simple string `Hello World`, the space character is special for the shell, so it must be escaped so that a single value is represented.
+
+Double quotes are processed by the shell to create a single string argument.
+For POSIX shells, single quotes can also be used in this case, or protext the special character ` ` (space) with a backslash.
+
+```bash
+ascli conf echo "Hello World" --format=text
+ascli conf echo 'Hello World' --format=text
+ascli conf echo Hello\ World --format=text
+```
+
+```output
+Hello World
+```
+
+#### Using a shell variable, parsed by shell, in an extended value
+
+To be evaluated by shell, the shell variable must not be in single quotes.
+Note we use a simple variable here: the variable is not necessarily an environment variable.
+Even if the variable contains spaces it makes only one argument to `ascli` because word parsing is made before variable expansion by shell. 
+
+```bash
+MYVAR="Hello World"
+ascli conf echo @json:'{"title":"'$MYVAR'"}' --format=json
+ascli conf echo @json:{\"title\":\"$MYVAR\"} --format=json
+```
+
+```json
+{"title":"Hello World"}
+```
+
+#### Double quote in strings in command line
+
+Double quote is a shell special character.
+Like any shell special character, it can be protected either by preceding with a backslash or by enclosing in a single quote.
+
+```bash
+ascli conf echo \"
+ascli conf echo '"'
+```
+
+```output
+"
+```
+
+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 conf echo @json:'"\""' --format=text
+ascli conf echo @json:\"\\\"\" --format=text
+ascli conf echo @ruby:\'\"\' --format=text
+```
+
+```output
+"
+```
+
+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
+
+Construction of values with special characters is done like this:
+
+* First select a syntax to represent the extended value, e.g. JSON or Ruby
+
+* Write the expression using this syntax, for example, using JSON:
+
+```json
+{"title":"Test \" ' & \\"}
+```
+
+or using Ruby:
+
+```ruby
+{"title"=>"Test \" ' & \\"}
+{'title'=>%q{Test " ' & \\}}
+```
+
+Both `"` and `\` are special characters for JSON and Ruby and can be protected with `\` (unless Ruby's extended single quote notation `%q` is used).
+  
+* Then, since the value will be evaluated by shell, any shell special characters must be protected, either using preceding `\` for each character to protect, or by enclosing in single quote:
+
+```bash
+ascli conf echo @json:{\"title\":\"Test\ \\\"\ \'\ \&\ \\\\\"} --format=json
+ascli conf echo @json:'{"title":"Test \" '\'' & \\"}' --format=json
+ascli conf echo @ruby:"{'title'=>%q{Test \" ' & \\\\}}" --format=json
+```
+
+```json
+{"title":"Test \" ' & \\"}
+```
+
+#### Reading special characters interractively
+
+If `ascli` is used interractively (a user typing on terminal), it is easy to require the user to type values:
+
+```bash
+ascli conf echo @ruby:"{'title'=>gets.chomp}" --format=json
+```
+
+`gets` is Ruby's method of terminal input (terminated by `\n`), and `chomp` removes the trailing `\n`.
+
+#### Extended value using special characters read from environmental variables or files
+
+Using a text editor or shell: create a file `title.txt` (and env var) that contains exactly the text required: `Test " ' & \` :
+
+```bash
+export MYTITLE='Test " '\'' & \'
+echo -n $MYTITLE > title.txt
+```
+
+Using those values will not require any escaping of characters since values do not go through shell or JSON parsing.
+
+If the value is to be assigned directly to an option of ascli, then you can directly use the content of the file or env var using the `@file:` or `@env:` readers:
+
+```bash
+ascli conf echo @file:title.txt --format=text
+ascli conf echo @env:MYTITLE --format=text
+```
+
+```output
+Test " ' & \
+```
+
+If the value to be used is in a more complex structure, then the `@ruby:` modifier can be used: it allows any ruby code in expression, including reading from file or env var. In those cases, there is no character to protect because values are not parsed by the shell, or JSON or even Ruby.
+
+```bash
+ascli conf echo @ruby:"{'title'=>File.read('title.txt')}" --format=json
+ascli conf echo @ruby:"{'title'=>ENV['MYTITLE']}" --format=json
+```
+
+```json
+{"title":"Test \" ' & \\"}
+```
+
 ### Arguments : Commands and options
 
 Arguments are the units of command line, as parsed by the shell, typically separated by spaces (and called "argv").
@@ -638,6 +841,7 @@ If transposition of single object is not desired, use option: `transpose_single`
 
 The style of output can be set using the `format` parameter, supporting:
 
+* `text` : Value as String
 * `table` : Text table
 * `ruby` : Ruby code
 * `json` : JSON code
@@ -674,12 +878,12 @@ Output messages are categorized in 3 types:
 
 The option `display` controls the level of output:
 
-* `info` displays all messages
+* `info` displays all messages: `info`, `data`, and `error`
 * `data` display `data` and `error` messages
 * `error` display only error messages.
 
-By default, secrets are shown on output.
-To hide secrets from results, set option `show_secrets` to `no`.
+By default, secrets are removed from output: option `show_secrets` defaults to `no`, unless `display` is `data`, to allows piping results.
+To hide secrets from output, set option `show_secrets` to `no`.
 
 #### Selection of output object properties
 
@@ -778,14 +982,14 @@ Note that `@incps:@json:'{"incps":["config"]}'` or `@incps:@ruby:'{"incps"=>["co
 
 ### <a id="native"></a>Structured Value
 
-Some options and parameters expect a _Structured Value_, i.e. a value more complex than a simple string. This is usually a Hash table or an Array, which could also contain sub structures.
+Some options and parameters expect a [Extended Value](#extended), i.e. a value more complex than a simple string. This is usually a Hash table or an Array, which could also contain sub structures.
 
-For instance, a [*transfer-spec*](#transferspec) is expected to be a _Structured Value_.
+For instance, a [*transfer-spec*](#transferspec) is expected to be a [Extended Value](#extended).
 
 Structured values shall be described using the [Extended Value Syntax](#extended).
-A convenient way to specify a _Structured Value_ is to use the `@json:` decoder, and describe the value in JSON format. The `@ruby:` decoder can also be used. For an array of hash tables, the `@csvt:` decoder can be used.
+A convenient way to specify a [Extended Value](#extended) is to use the `@json:` decoder, and describe the value in JSON format. The `@ruby:` decoder can also be used. For an array of hash tables, the `@csvt:` decoder can be used.
 
-It is also possible to provide a _Structured Value_ in a file using `@json:@file:<path>`
+It is also possible to provide a [Extended Value](#extended) in a file using `@json:@file:<path>`
 
 ### <a id="conffolder"></a>Configuration and Persistency Folder
 
@@ -894,7 +1098,6 @@ ascli config over
 ascli config list
 ```
 
-
 #### <a id="lprtconf"></a>Special Option preset: config
 
 This preset name is reserved and contains a single key: `version`. This is the version of `ascli` which created the file.
@@ -929,6 +1132,49 @@ When `ascli` starts, it looks for the `default` Option preset and if there is a
 
 If no global default is set by the user, the tool will use `global_common_defaults` when setting global parameters (e.g. `conf ascp use`)
 
+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=Tsdk_test_dir
+config ascp install --sdk-folder=Tsdk_test_dir
+config ascp products list
+config ascp show
+config ascp spec
+config check_update
+config detect --url=https://my_aoc_org.ibmaspera.com
+config detect --url=my_faspex_url
+config detect --url=my_node_url
+config doc
+config doc transfer-parameters
+config echo 'hello'
+config echo @base64:SGVsbG8gV29ybGQK
+config echo @csvt:@stdin:
+config echo @env:USER
+config echo @lines:@stdin:
+config echo @list:,1,2,3
+config echo @uri:/etc/hosts
+config echo @uri:file:/etc/hosts
+config echo @uri:http://www.ibm.com
+config echo @uri:https://www.ibm.com
+config echo @val:@file:yo
+config echo @zlib:@stdin:
+config email_test --notif-to=my_recipient_email
+config export
+config flush_tokens
+config genkey mykey
+config plugin create mycommand T
+config plugin list
+config proxy_check --fpac=@file:examples/proxy.pac https://eudemo.asperademo.com
+config wiz --url=https://my_aoc_org.ibmaspera.com --config-file=SAMPLE_CONFIG_FILE --pkeypath= --username=my_aoc_user_email --test-mode=yes
+config wiz --url=https://my_aoc_org.ibmaspera.com --config-file=SAMPLE_CONFIG_FILE --pkeypath= --username=my_aoc_user_email --test-mode=yes --use-generic-client=yes
+```
+
 #### Format of file
 
 The configuration file is a hash in a YAML file. Example:
@@ -1110,6 +1356,8 @@ Secrets must be uniquely identified by `url` and `username`. An optional descrip
 
 #### Legacy config file format
 
+THIS FORMAT WILL BE DEPRECATED
+
 The value provided can be a Hash, where keys are usernames (or access key id), and values are the associated password or secrets in clear.
 
 For example, choose a repository name, for example `my_secrets`, and populate it like this:
@@ -1141,39 +1389,56 @@ ascli conf vault get --username=access_key1
 
 ### <a id="private_key"></a>Private Key
 
-Some applications allow the user to be authenticated using a private key (Server, AoC, Faspex5...).
-It consists in generating a private key, or using a previouly generated key.
+Some applications allow the user to be authenticated using a private key (Server, AoC, Faspex5, ...).
+It consists in using a pair of keys: the private key and its associated public key.
 The same key can be used for multiple applications.
-Technically, a private key contains the public key, which can be extracted.
-Currently, only private key not protected by a passphrase are supported.
-(TODO: add passphrase protection as option for aspera apps).
+Technically, a private key contains the public key, which can be extracted from it.
+The private key can be protected by a passphrase or not.
+If the key is protected by a passphrase, then it will be prompted.
+(some plugins support option `passphrase`)
 
 Several methods can be used to generate a key pair:
 
+The following commands use this variable:
+
+```bash
+PRIVKEYFILE=~/.aspera/ascli/my_private_key
+```
+
 * `ascli`
 
-The generated key is of type RSA 4096 bit. For convenience, the public key is also extracted.
+The generated key is of type RSA, by default: 4096 bit.
+For convenience, the public key is also extracted with extension `.pub`.
+The key is not passphrase protected.
 
 ```bash
-ascli config genkey ~/.aspera/ascli/my_private_key
+ascli config genkey ${PRIVKEYFILE} 4096
 ```
 
 * `ssh-keygen`
 
+Both private and public keys are generated, option `-N` is for passphrase.
+
 ```bash
-ssh-keygen -t rsa -f ~/.aspera/ascli/my_private_key -N ''
+ssh-keygen -t rsa -b 4096 -N '' -f ${PRIVKEYFILE}
 ```
 
 * `openssl`
 
-openssl is sometimes compiled to support option `-nodes` (no DES, i.e. no passphrase, e.g. on macOS). To generate a privatekey pait without passphrase the following shall work on any system:
+openssl is sometimes compiled to support option `-nodes` (no DES, i.e. no passphrase, e.g. on macOS).
+To generate a private key pair without passphrase the following can be used on any system:
+
+```bash
+openssl genrsa -passout pass:dummypassword -out ${PRIVKEYFILE}.protected 4096
+openssl rsa -passin pass:dummypassword -in ${PRIVKEYFILE}.protected -out ${PRIVKEYFILE}
+openssl rsa -pubout -in ${PRIVKEYFILE} -out ${PRIVKEYFILE}.pub
+rm -f ${PRIVKEYFILE}.protected
+```
+
+To change (or add) the passphrase for a key do:
 
 ```bash
-APIKEY=~/.aspera/ascli/my_private_key
-openssl genrsa -passout pass:dummypassword -out ${APIKEY}.protected 2048
-openssl rsa -passin pass:dummypassword -in ${APIKEY}.protected -out ${APIKEY}
-openssl rsa -pubout -in ${APIKEY} -out ${APIKEY}.pub
-rm -f ${APIKEY}.protected
+openssl rsa -des3 -in old_file -out new_file
 ```
 
 ### <a id="certificates"></a>SSL CA certificate bundle
@@ -1250,14 +1515,37 @@ Aspera on Cloud relies on Oauth, refer to the [Aspera on Cloud](#aoc) section.
 
 ### Logging, Debugging
 
-The gem is equipped with traces. By default logging level is `warn`.
-To increase debug level, use parameter `log_level` (e.g. using command line `--log-level=xx`, env var `ASCLI_LOG_LEVEL`, or parameter in con file).
+The gem is equipped with traces, mainly for debugging and learning APIs.
+By default logging level is `warn` and the output channel is `stderr`.
+To increase debug level, use parameter `log_level` (e.g. using command line `--log-level=xx`, env var `ASCLI_LOG_LEVEL`, or a parameter in the configuration file).
 
-It is also possible to activate traces before initialization using env var `AS_LOG_LEVEL`.
+It is also possible to activate traces before log facility initialization using env var `ASCLI_LOG_LEVEL`.
 
 By default passwords and secrets are removed from logs.
 Use option `log_secrets` set to `yes` to reveal secrets in logs.
 
+Available loggers: `stdout`, `stderr`, `syslog`.
+
+Available levels: `debug`, `info`, `warn`, `error`.
+
+Note that when using the `direct` agent (`ascp`), additional transfer logs can be activated using `ascp` option `EX_ascp_args`, see [`direct`](#agt_direct).
+
+Examples:
+
+* display debugging log on `stdout`:
+
+```bash
+ascli conf over --log-level=debug --logger=stdout
+```
+
+* log errors to `syslog`:
+
+```bash
+ascli conf over --log-level=error --logger=syslog
+```
+
+When `ascli` is used interactively in a shell, the shell itself will usually log executed commands in the history file.
+
 ### Learning Aspera Product APIs (REST)
 
 This CLI uses REST APIs.
@@ -1341,7 +1629,7 @@ The PAC file will be used for any HTTP/HTTPS/REST connection, but not other (e.g
 
 The PAC file can be tested with command: `config proxy_check`. Example, using command line option:
 
-```
+```bash
 ascli conf proxy_check --fpac='function FindProxyForURL(url, host) {return "PROXY proxy.example.com:1234;DIRECT";}' http://example.com
 PROXY proxy.example.com:1234;DIRECT
 ```
@@ -1520,12 +1808,12 @@ will effectively push files to the related server from the agent node.
 #### <a id="agt_direct"></a>Direct
 
 The `direct` agent directly executes a local ascp.
-This is the default for `ascli`.
-This is equivalent to specifying `--transfer=direct`.
-`ascli` will detect locally installed Aspera products, including SDK.
+This is the default agent for `ascli`.
+This is equivalent to option `--transfer=direct`.
+`ascli` will detect locally installed Aspera products, including SDK, and use `ascp` from that component.
 Refer to section [FASP](#client).
 
-The `transfer-info` accepts the following optional parameters to control multi-session, WSS
+The `transfer_info` option accepts the following optional parameters to control multi-session, Web Socket Session and Resume policy:
 
 <table>
 <tr><th>Name</th><th>Type</th><th>Description</th></tr>
@@ -1540,7 +1828,7 @@ The `transfer-info` accepts the following optional parameters to control multi-s
 <tr><td>resume.sleep_max</td><td>int</td><td>Resume<br/>Default: 60</td></tr>
 </table>
 
-Resume: In case of transfer interruption, the agent will resume a transfer up to `iter_max` time.
+In case of transfer interruption, the agent will **resume** a transfer up to `iter_max` time.
 Sleep between iterations is:
 
 ```bash
@@ -1548,14 +1836,49 @@ max( sleep_max , sleep_initial * sleep_factor ^ (iter_index-1) )
 ```
 
 Some transfer errors are considered "retryable" (e.g. timeout) and some other not (e.g. wrong password).
+The list of known protocol errors and retry level can be listed:
+
+```bash
+ascli config ascp errors
+```
 
 Examples:
 
 ```javascript
-ascli ... --transfer-info=@json:'{"wss":true,"resume":{"iter_max":10}}'
+ascli ... --transfer-info=@json:'{"wss":true,"resume":{"iter_max":20}}'
 ascli ... --transfer-info=@json:'{"spawn_delay_sec":2.5,"multi_incr_udp":false}'
 ```
 
+Note that the `direct` agent supports additional `transfer_spec` parameters starting with `EX_` (extended).
+In particular the field, `EX_ascp_args` which is a list of additional command line options to `ascp`.
+
+This can be useful to activate logging using option `-L` of ascp.
+For example the option `--ts=@json:'{"EX_ascp_args":["-DDL-"]}'` will activate debug level 2 for `ascp` (`DD`), and display those logs on the terminal (`-`).
+This is useful if the transfer fails.
+To store ascp logs in file `aspera-scp-transfer.log` in a folder, use `--ts=@json:'{"EX_ascp_args":["-L","/path/to/folder"]}'`.
+
+> Implementation 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 in option `ts` in `EX_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`
+
+```javascript
+--sources=@ts --ts=@json:'{"EX_file_list":"filelist.txt"}'
+```
+
+* Using the pseudo [*transfer-spec*](#transferspec) parameter `EX_ascp_args`
+
+```javascript
+--sources=@ts --ts=@json:'{"EX_ascp_args":["--file-list","myfilelist"]}'
+```
+
+> File lists is shown here, there are also similar options for file pair lists.
+
+> 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.
+
+> Those methods have limitations: they apply **only** to the [`direct`](#agt_direct) transfer agent (i.e. local `ascp`) and not for Aspera on Cloud.
+
 #### <a id="agt_connect"></a>IBM Aspera Connect Client GUI
 
 By specifying option: `--transfer=connect`, `ascli` will start transfers using the locally installed Aspera Connect Client. There are no option for `transfer_info`.
@@ -1566,6 +1889,7 @@ By specifying option: `--transfer=node`, the CLI will start transfers in an Aspe
 Transfer Server using the Node API, either on a local or remote node.
 Parameters provided in option `transfer_info` are:
 
+<table>
 <tr><th>Name</th><th>Type</th><th>Description</th></tr>
 <tr><td>url</td><td>string</td><td>URL of the node API</br>Mandatory</td></tr>
 <tr><td>username</td><td>string</td><td>node api user or access key</br>Mandatory</td></tr>
@@ -1579,7 +1903,7 @@ Like any other option, `transfer_info` can get its value from a pre-configured [
 
 If `transfer_info` is not specified and a default node has been configured (name in `node` for section `default`) then this node is used by default.
 
-If the `password` value begins with `Bearer ` then the `username` is expected to be an access key and the parameter `root_id` is mandatory and specifies the root file id on the node. It can be either the access key's root file id, or any authorized file id underneath it.
+If the `password` value begins with `Bearer` then the `username` is expected to be an access key and the parameter `root_id` is mandatory and specifies the root file id on the node. It can be either the access key's root file id, or any authorized file id underneath it.
 
 #### <a id="agt_httpgw"></a>HTTP Gateway
 
@@ -1599,6 +1923,19 @@ Another possibility is to use the Transfer SDK daemon (asperatransferd).
 
 By default it will listen on local port `55002` on `127.0.0.1`.
 
+The gem `grpc` was removed from dependencies, as it requires compilation of a native part. So, to use the Transfer SDK you should install this gem:
+
+```bash
+gem install grpc
+```
+
+On Windows the compilation may fail for various reasons (3.1.1):
+
+* `cannot find -lx64-ucrt-ruby310`
+   &rarr; copy the file `[Ruby main dir]\lib\libx64-ucrt-ruby310.dll.a` to `[Ruby main dir]\lib\libx64-ucrt-ruby310.a` (remove the dll extension)
+* `conflicting types for 'gettimeofday'`
+  &rarr; edit the file `[Ruby main dir]/include/ruby-[version]/ruby/win32.h` and change the signature of `gettimeofday` to `gettimeofday(struct timeval *, void *)` ,i.e. change `struct timezone` to `void`
+
 ### <a id="transferspec"></a>Transfer Specification
 
 Some commands lead to file transfer (upload/download), all parameters necessary for this transfer
@@ -1651,7 +1988,91 @@ Columns:
 
 Fields with EX_ prefix are extensions to transfer agent [`direct`](#agt_direct). (only in `ascli`).
 
-<table><tr><th>Field</th><th>Type</th><th>D</th><th>N</th><th>C</th><th>Description</th></tr><tr><td>cipher</td><td>string</td><td>Y</td><td>Y</td><td>Y</td><td>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)</td></tr><tr><td>content_protection</td><td>string</td><td>Y</td><td>Y</td><td>Y</td><td>Enable client-side encryption at rest. (CSEAR, content protection)<br/>Allowed values: encrypt, decrypt<br/>(--file-crypt)</td></tr><tr><td>content_protection_password</td><td>string</td><td>Y</td><td>Y</td><td>Y</td><td>Specifies CSEAR password. (content protection)<br/>(env:ASPERA_SCP_FILEPASS)</td></tr><tr><td>cookie</td><td>string</td><td>Y</td><td>Y</td><td>Y</td><td>Metadata for transfer specified by application<br/>(env:ASPERA_SCP_COOKIE)</td></tr><tr><td>create_dir</td><td>bool</td><td>Y</td><td>Y</td><td>Y</td><td>Specifies whether to create new directories.<br/>(-d)</td></tr><tr><td>delete_before_transfer</td><td>bool</td><td>Y</td><td>Y</td><td>Y</td><td>Before transfer, delete files that exist at the destination but not at the source. The source and destination arguments must be directories that have matching names. Objects on the destination that have the same name but different type or size as objects on the source are not deleted.<br/>(--delete-before-transfer)</td></tr><tr><td>delete_source</td><td>bool</td><td>Y</td><td>Y</td><td>&nbsp;</td><td>Remove SRC files after transfer success<br/>(--remove-after-transfer)</td></tr><tr><td>destination_root</td><td>string</td><td>Y</td><td>Y</td><td>Y</td><td>Destination root directory.</td></tr><tr><td>direction</td><td>string</td><td>Y</td><td>Y</td><td>Y</td><td>Direction of transfer (on client side)<br/>Allowed values: send, receive<br/>(--mode)</td></tr><tr><td>exclude_newer_than</td><td>int</td><td>Y</td><td>&nbsp;</td><td>&nbsp;</td><td>skip src files with mtime > arg<br/>(--exclude-newer-than)</td></tr><tr><td>exclude_older_than</td><td>int</td><td>Y</td><td>&nbsp;</td><td>&nbsp;</td><td>skip src files with mtime < arg<br/>(--exclude-older-than)</td></tr><tr><td>fasp_port</td><td>int</td><td>Y</td><td>Y</td><td>Y</td><td>Specifies fasp (UDP) port.<br/>(-O)</td></tr><tr><td>file_checksum</td><td>string</td><td>Y</td><td>Y</td><td>&nbsp;</td><td>Enable checksum reporting for transferred files by specifying the hash to use.<br/>Allowed values: sha-512, sha-384, sha-256, sha1, md5, none</td></tr><tr><td>http_fallback</td><td>bool<br/>string</td><td>Y</td><td>Y</td><td>Y</td><td>When true(1), attempts to perform an HTTP transfer if a FASP transfer cannot be performed.<br/>(-y)</td></tr><tr><td>http_fallback_port</td><td>int</td><td>Y</td><td>&nbsp;</td><td>&nbsp;</td><td>Specifies http port when no cipher is used<br/>(-t)</td></tr><tr><td>https_fallback_port</td><td>int</td><td>Y</td><td>Y</td><td>Y</td><td>Specifies https port when cipher is used<br/>(-t)</td></tr><tr><td>move_after_transfer</td><td>string</td><td>Y</td><td>Y</td><td>Y</td><td>(--move-after-transfer)</td></tr><tr><td>multi_session</td><td>int</td><td>Y</td><td>Y</td><td>Y</td><td>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.</td></tr><tr><td>multi_session_threshold</td><td>int</td><td>Y</td><td>Y</td><td>&nbsp;</td><td>Split files across multiple ascp sessions if their size in bytes is greater than or equal to the specified value. (0=no file is split)<br/>(--multi-session-threshold)</td></tr><tr><td>overwrite</td><td>string</td><td>Y</td><td>Y</td><td>Y</td><td>Overwrite destination files with the source files of the same name.<br/>Allowed values: never, always, diff, older, diff+older<br/>(--overwrite)</td></tr><tr><td>paths</td><td>array</td><td>Y</td><td>Y</td><td>Y</td><td>Array of path to the source (required) and a path to the destination (optional).</td></tr><tr><td>precalculate_job_size</td><td>bool</td><td>Y</td><td>Y</td><td>Y</td><td>Specifies whether to precalculate the job size.<br/>(--precalculate-job-size)</td></tr><tr><td>preserve_access_time</td><td>bool</td><td>Y</td><td>Y</td><td>Y</td><td>(--preserve-access-time)</td></tr><tr><td>preserve_creation_time</td><td>bool</td><td>Y</td><td>Y</td><td>Y</td><td>(--preserve-creation-time)</td></tr><tr><td>preserve_modification_time</td><td>bool</td><td>Y</td><td>Y</td><td>Y</td><td>(--preserve-modification-time)</td></tr><tr><td>preserve_times</td><td>bool</td><td>Y</td><td>Y</td><td>Y</td><td>(--preserve-times)</td></tr><tr><td>rate_policy</td><td>string</td><td>Y</td><td>Y</td><td>Y</td><td>The transfer rate policy to use when sharing bandwidth.<br/>Allowed values: low, fair, high, fixed<br/>(--policy)</td></tr><tr><td>remote_host</td><td>string</td><td>Y</td><td>Y</td><td>Y</td><td>IP or fully qualified domain name of the remote server<br/>(--host)</td></tr><tr><td>remote_user</td><td>string</td><td>Y</td><td>Y</td><td>Y</td><td>Remote user. Default value is "xfer" on node or connect.<br/>(--user)</td></tr><tr><td>remote_password</td><td>string</td><td>Y</td><td>Y</td><td>Y</td><td>SSH session password<br/>(env:ASPERA_SCP_PASS)</td></tr><tr><td>remove_after_transfer</td><td>bool</td><td>Y</td><td>Y</td><td>&nbsp;</td><td>Remove SRC files after transfer success<br/>(--remove-after-transfer)</td></tr><tr><td>remove_empty_directories</td><td>bool</td><td>Y</td><td>Y</td><td>&nbsp;</td><td>Specifies whether to remove empty directories.<br/>(--remove-empty-directories)</td></tr><tr><td>remove_skipped</td><td>bool</td><td>Y</td><td>Y</td><td>Y</td><td>Must also have remove_after_transfer set to true, Defaults to false, if true, skipped files will be removed as well.<br/>(--remove-skipped)</td></tr><tr><td>proxy</td><td>string</td><td>Y</td><td>&nbsp;</td><td>&nbsp;</td><td>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)</td></tr><tr><td>resume_policy</td><td>string</td><td>Y</td><td>Y</td><td>Y</td><td>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)</td></tr><tr><td>retry_duration</td><td>string<br/>int</td><td>&nbsp;</td><td>Y</td><td>Y</td><td>Specifies how long to wait before retrying transfer. (e.g. "5min")</td></tr><tr><td>source_root_id</td><td>string</td><td>&nbsp;</td><td>Y</td><td>&nbsp;</td><td>The file ID of the source root directory. Required when using Bearer token auth for the source node.</td></tr><tr><td>ssh_port</td><td>int</td><td>Y</td><td>Y</td><td>Y</td><td>Specifies SSH (TCP) port. Default: local:22, other:33001<br/>(-P)</td></tr><tr><td>ssh_private_key</td><td>string</td><td>Y</td><td>&nbsp;</td><td>&nbsp;</td><td>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)</td></tr><tr><td>ssh_private_key_passphrase</td><td>string</td><td>Y</td><td>&nbsp;</td><td>&nbsp;</td><td>The passphrase associated with the transfer user's SSH private key. Available as of 3.7.2.<br/>(env:ASPERA_SCP_PASS)</td></tr><tr><td>symlink_policy</td><td>string</td><td>Y</td><td>Y</td><td>Y</td><td>Handle source side symbolic links<br/>Allowed values: follow, copy, copy+force, skip<br/>(--symbolic-links)</td></tr><tr><td>tags</td><td>hash</td><td>Y</td><td>Y</td><td>Y</td><td>Metadata for transfer as JSON<br/>(--tags64)</td></tr><tr><td>target_rate_cap_kbps</td><td>int</td><td>&nbsp;</td><td>&nbsp;</td><td>Y</td><td>Returned by upload/download_setup node API.</td></tr><tr><td>target_rate_kbps</td><td>int</td><td>Y</td><td>Y</td><td>Y</td><td>Specifies desired speed for the transfer.<br/>(-l)</td></tr><tr><td>title</td><td>string</td><td>&nbsp;</td><td>Y</td><td>Y</td><td>Title of the transfer</td></tr><tr><td>token</td><td>string</td><td>Y</td><td>Y</td><td>Y</td><td>Authorization token: Bearer, Basic or ATM (Also arg -W)<br/>(env:ASPERA_SCP_TOKEN)</td></tr><tr><td>use_ascp4</td><td>bool</td><td>Y</td><td>Y</td><td>&nbsp;</td><td>specify version of protocol</td></tr><tr><td>source_root</td><td>string</td><td>Y</td><td>Y</td><td>Y</td><td>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)</td></tr><tr><td>min_rate_cap_kbps</td><td>int</td><td>Y</td><td>Y</td><td>Y</td><td>&nbsp;</td></tr><tr><td>lock_rate_policy</td><td>bool</td><td>Y</td><td>Y</td><td>Y</td><td>&nbsp;</td></tr><tr><td>lock_target_rate_kbps</td><td>bool</td><td>Y</td><td>Y</td><td>Y</td><td>&nbsp;</td></tr><tr><td>lock_min_rate_kbps</td><td>bool</td><td>Y</td><td>Y</td><td>Y</td><td>&nbsp;</td></tr><tr><td>apply_local_docroot</td><td>bool</td><td>Y</td><td>&nbsp;</td><td>&nbsp;</td><td>(--apply-local-docroot)</td></tr><tr><td>preserve_acls</td><td>string</td><td>Y</td><td>&nbsp;</td><td>&nbsp;</td><td>Preserve access control lists.<br/>Allowed values: none, native, metafile<br/>(--preserve-acls)</td></tr><tr><td>preserve_remote_acls</td><td>string</td><td>Y</td><td>&nbsp;</td><td>&nbsp;</td><td>Preserve remote access control lists.<br/>Allowed values: none, native, metafile<br/>(--remote-preserve-acls)</td></tr><tr><td>preserve_file_owner_uid</td><td>bool</td><td>Y</td><td>&nbsp;</td><td>&nbsp;</td><td>Preserve the user ID for a file owner<br/>(--preserve-file-owner-uid)</td></tr><tr><td>preserve_file_owner_gid</td><td>bool</td><td>Y</td><td>&nbsp;</td><td>&nbsp;</td><td>Preserve the group ID for a file owner<br/>(--preserve-file-owner-gid)</td></tr><tr><td>preserve_source_access_time</td><td>bool</td><td>Y</td><td>&nbsp;</td><td>&nbsp;</td><td>Preserve the time logged for when the source file was accessed<br/>(--preserve-source-access-time)</td></tr><tr><td>remove_empty_source_directory</td><td>bool</td><td>Y</td><td>&nbsp;</td><td>&nbsp;</td><td>Remove empty source subdirectories and remove the source directory itself, if empty<br/>(--remove-empty-source-directory)</td></tr><tr><td>EX_at_rest_password</td><td>string</td><td>Y</td><td>&nbsp;</td><td>&nbsp;</td><td>Passphrase used for at rest encryption or decryption. Prefer to use standard: content_protection_password<br/>(env:ASPERA_SCP_FILEPASS)</td></tr><tr><td>EX_proxy_password</td><td>string</td><td>Y</td><td>&nbsp;</td><td>&nbsp;</td><td>Password used for Aspera proxy server authentication.<br/> May be overridden by password in URL EX_fasp_proxy_url.<br/>(env:ASPERA_PROXY_PASS)</td></tr><tr><td>EX_license_text</td><td>string</td><td>Y</td><td>&nbsp;</td><td>&nbsp;</td><td>License file text override.<br/>By default ascp looks for license file near executable.<br/>(env:ASPERA_SCP_LICENSE)</td></tr><tr><td>dgram_size</td><td>int</td><td>Y</td><td>Y</td><td>Y</td><td>UDP datagram size in bytes<br/>(-Z)</td></tr><tr><td>min_rate_kbps</td><td>int</td><td>Y</td><td>Y</td><td>Y</td><td>Set the minimum transfer rate in kilobits per second.<br/>(-m)</td></tr><tr><td>sshfp</td><td>string</td><td>Y</td><td>Y</td><td>Y</td><td>Check it against server SSH host key fingerprint<br/>(--check-sshfp)</td></tr><tr><td>EX_http_proxy_url</td><td>string</td><td>Y</td><td>&nbsp;</td><td>&nbsp;</td><td>Specify the proxy server address used by HTTP Fallback<br/>(-x)</td></tr><tr><td>EX_ssh_key_paths</td><td>array</td><td>Y</td><td>&nbsp;</td><td>&nbsp;</td><td>Use public key authentication for SSH and specify the private key file paths<br/>(-i)</td></tr><tr><td>EX_http_transfer_jpeg</td><td>int</td><td>Y</td><td>&nbsp;</td><td>&nbsp;</td><td>HTTP transfers as JPEG file<br/>(-j)</td></tr><tr><td>EX_no_read</td><td>bool</td><td>Y</td><td>&nbsp;</td><td>&nbsp;</td><td>no read source<br/>(--no-read)</td></tr><tr><td>EX_no_write</td><td>bool</td><td>Y</td><td>&nbsp;</td><td>&nbsp;</td><td>no write on destination<br/>(--no-write)</td></tr><tr><td>target_rate_percentage</td><td>string</td><td>Y</td><td>Y</td><td>Y</td><td>&nbsp;</td></tr><tr><td>rate_policy_allowed</td><td>string</td><td>&nbsp;</td><td>&nbsp;</td><td>Y</td><td>Specifies most aggressive rate policy that is allowed.<br/>Returned by node API.<br/>Allowed values: low, fair, high, fixed</td></tr><tr><td>lock_min_rate</td><td>bool</td><td>Y</td><td>Y</td><td>Y</td><td>&nbsp;</td></tr><tr><td>lock_target_rate</td><td>bool</td><td>Y</td><td>Y</td><td>Y</td><td>&nbsp;</td></tr><tr><td>authentication</td><td>string</td><td>&nbsp;</td><td>&nbsp;</td><td>Y</td><td>value=token for SSH bypass keys, else password asked if not provided.</td></tr><tr><td>cipher_allowed</td><td>string</td><td>Y</td><td>Y</td><td>Y</td><td>returned by node API. Valid literals include "aes-128" and "none".</td></tr><tr><td>EX_file_list</td><td>string</td><td>Y</td><td>&nbsp;</td><td>&nbsp;</td><td>source file list</td></tr><tr><td>EX_file_pair_list</td><td>string</td><td>Y</td><td>&nbsp;</td><td>&nbsp;</td><td>source file pair list</td></tr><tr><td>EX_ascp_args</td><td>array</td><td>Y</td><td>&nbsp;</td><td>&nbsp;</td><td>Add native command line arguments to ascp</td></tr><tr><td>wss_enabled</td><td>bool</td><td>Y</td><td>Y</td><td>Y</td><td>&nbsp;</td></tr><tr><td>wss_port</td><td>int</td><td>Y</td><td>Y</td><td>Y</td><td>TCP port used for websocket service feed.</td></tr></table>
+<table><tr><th>Field</th><th>Type</th><th>D</th><th>N</th><th>C</th><th>Description</th></tr>
+<tr><td>EX_ascp_args</td><td>array</td><td>Y</td><td>&nbsp;</td><td>&nbsp;</td><td>Add native command line arguments to ascp</td></tr>
+<tr><td>EX_at_rest_password</td><td>string</td><td>Y</td><td>&nbsp;</td><td>&nbsp;</td><td>DEPRECATED: Prefer to use standard parameter: content_protection_password<br/>(env:ASPERA_SCP_FILEPASS)</td></tr>
+<tr><td>EX_file_list</td><td>string</td><td>Y</td><td>&nbsp;</td><td>&nbsp;</td><td>source file list</td></tr>
+<tr><td>EX_file_pair_list</td><td>string</td><td>Y</td><td>&nbsp;</td><td>&nbsp;</td><td>source file pair list</td></tr>
+<tr><td>EX_http_proxy_url</td><td>string</td><td>Y</td><td>&nbsp;</td><td>&nbsp;</td><td>Specify the proxy server address used by HTTP Fallback<br/>(-x)</td></tr>
+<tr><td>EX_http_transfer_jpeg</td><td>int</td><td>Y</td><td>&nbsp;</td><td>&nbsp;</td><td>HTTP transfers as JPEG file<br/>(-j)</td></tr>
+<tr><td>EX_license_text</td><td>string</td><td>Y</td><td>&nbsp;</td><td>&nbsp;</td><td>License file text override.<br/>By default ascp looks for license file near executable.<br/>(env:ASPERA_SCP_LICENSE)</td></tr>
+<tr><td>EX_no_read</td><td>bool</td><td>Y</td><td>&nbsp;</td><td>&nbsp;</td><td>no read source<br/>(--no-read)</td></tr>
+<tr><td>EX_no_write</td><td>bool</td><td>Y</td><td>&nbsp;</td><td>&nbsp;</td><td>no write on destination<br/>(--no-write)</td></tr>
+<tr><td>EX_proxy_password</td><td>string</td><td>Y</td><td>&nbsp;</td><td>&nbsp;</td><td>Password used for Aspera proxy server authentication.<br/>May be overridden by password in URL EX_fasp_proxy_url.<br/>(env:ASPERA_PROXY_PASS)</td></tr>
+<tr><td>EX_ssh_key_paths</td><td>array</td><td>Y</td><td>&nbsp;</td><td>&nbsp;</td><td>Use public key authentication for SSH and specify the private key file paths<br/>(-i)</td></tr>
+<tr><td>apply_local_docroot</td><td>bool</td><td>Y</td><td>&nbsp;</td><td>&nbsp;</td><td>(--apply-local-docroot)</td></tr>
+<tr><td>authentication</td><td>string</td><td>&nbsp;</td><td>&nbsp;</td><td>Y</td><td>value=token for SSH bypass keys, else password asked if not provided.</td></tr>
+<tr><td>cipher</td><td>string</td><td>Y</td><td>Y</td><td>Y</td><td>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)</td></tr>
+<tr><td>cipher_allowed</td><td>string</td><td>Y</td><td>Y</td><td>Y</td><td>returned by node API. Valid literals include "aes-128" and "none".</td></tr>
+<tr><td>content_protection</td><td>string</td><td>Y</td><td>Y</td><td>Y</td><td>Enable client-side encryption at rest. (CSEAR, content protection)<br/>Allowed values: encrypt, decrypt<br/>(--file-crypt)</td></tr>
+<tr><td>content_protection_password</td><td>string</td><td>Y</td><td>Y</td><td>Y</td><td>Specifies CSEAR password. (content protection)<br/>(env:ASPERA_SCP_FILEPASS)</td></tr>
+<tr><td>cookie</td><td>string</td><td>Y</td><td>Y</td><td>Y</td><td>Metadata for transfer specified by application<br/>(env:ASPERA_SCP_COOKIE)</td></tr>
+<tr><td>create_dir</td><td>bool</td><td>Y</td><td>Y</td><td>Y</td><td>Specifies whether to create new directories.<br/>(-d)</td></tr>
+<tr><td>delete_before_transfer</td><td>bool</td><td>Y</td><td>Y</td><td>Y</td><td>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)</td></tr>
+<tr><td>delete_source</td><td>bool</td><td>Y</td><td>Y</td><td>&nbsp;</td><td>Remove SRC files after transfer success<br/>(--remove-after-transfer)</td></tr>
+<tr><td>destination_root</td><td>string</td><td>Y</td><td>Y</td><td>Y</td><td>Destination root directory.</td></tr>
+<tr><td>dgram_size</td><td>int</td><td>Y</td><td>Y</td><td>Y</td><td>UDP datagram size in bytes<br/>(-Z)</td></tr>
+<tr><td>direction</td><td>string</td><td>Y</td><td>Y</td><td>Y</td><td>Direction of transfer (on client side)<br/>Allowed values: send, receive<br/>(--mode)</td></tr>
+<tr><td>exclude_newer_than</td><td>int</td><td>Y</td><td>&nbsp;</td><td>&nbsp;</td><td>skip src files with mtime > arg<br/>(--exclude-newer-than)</td></tr>
+<tr><td>exclude_older_than</td><td>int</td><td>Y</td><td>&nbsp;</td><td>&nbsp;</td><td>skip src files with mtime < arg<br/>(--exclude-older-than)</td></tr>
+<tr><td>fasp_port</td><td>int</td><td>Y</td><td>Y</td><td>Y</td><td>Specifies fasp (UDP) port.<br/>(-O)</td></tr>
+<tr><td>file_checksum</td><td>string</td><td>Y</td><td>Y</td><td>&nbsp;</td><td>Enable checksum reporting for transferred files by specifying the hash to use.<br/>Allowed values: sha-512, sha-384, sha-256, sha1, md5, none</td></tr>
+<tr><td>http_fallback</td><td>bool<br/>string</td><td>Y</td><td>Y</td><td>Y</td><td>When true(1), attempts to perform an HTTP transfer if a FASP transfer cannot be performed.<br/>(-y)</td></tr>
+<tr><td>http_fallback_port</td><td>int</td><td>Y</td><td>&nbsp;</td><td>&nbsp;</td><td>Specifies http port when no cipher is used<br/>(-t)</td></tr>
+<tr><td>https_fallback_port</td><td>int</td><td>Y</td><td>Y</td><td>Y</td><td>Specifies https port when cipher is used<br/>(-t)</td></tr>
+<tr><td>lock_min_rate</td><td>bool</td><td>Y</td><td>Y</td><td>Y</td><td>&nbsp;</td></tr>
+<tr><td>lock_min_rate_kbps</td><td>bool</td><td>Y</td><td>Y</td><td>Y</td><td>&nbsp;</td></tr>
+<tr><td>lock_rate_policy</td><td>bool</td><td>Y</td><td>Y</td><td>Y</td><td>&nbsp;</td></tr>
+<tr><td>lock_target_rate</td><td>bool</td><td>Y</td><td>Y</td><td>Y</td><td>&nbsp;</td></tr>
+<tr><td>lock_target_rate_kbps</td><td>bool</td><td>Y</td><td>Y</td><td>Y</td><td>&nbsp;</td></tr>
+<tr><td>min_rate_cap_kbps</td><td>int</td><td>Y</td><td>Y</td><td>Y</td><td>&nbsp;</td></tr>
+<tr><td>min_rate_kbps</td><td>int</td><td>Y</td><td>Y</td><td>Y</td><td>Set the minimum transfer rate in kilobits per second.<br/>(-m)</td></tr>
+<tr><td>move_after_transfer</td><td>string</td><td>Y</td><td>Y</td><td>Y</td><td>The relative path to which the files will be moved after the transfer at the source side.<br/>(--move-after-transfer)</td></tr>
+<tr><td>multi_session</td><td>int</td><td>Y</td><td>Y</td><td>Y</td><td>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/></td></tr>
+<tr><td>multi_session_threshold</td><td>int</td><td>Y</td><td>Y</td><td>&nbsp;</td><td>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)</td></tr>
+<tr><td>overwrite</td><td>string</td><td>Y</td><td>Y</td><td>Y</td><td>Overwrite destination files with the source files of the same name.<br/>Allowed values: never, always, diff, older, diff+older<br/>(--overwrite)</td></tr>
+<tr><td>password</td><td>string</td><td>&nbsp;</td><td>Y</td><td>&nbsp;</td><td>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.</td></tr>
+<tr><td>paths</td><td>array</td><td>Y</td><td>Y</td><td>Y</td><td>Array of path to the source (required) and a path to the destination (optional).</td></tr>
+<tr><td>precalculate_job_size</td><td>bool</td><td>Y</td><td>Y</td><td>Y</td><td>Specifies whether to precalculate the job size.<br/>(--precalculate-job-size)</td></tr>
+<tr><td>preserve_access_time</td><td>bool</td><td>Y</td><td>Y</td><td>Y</td><td>(--preserve-access-time)</td></tr>
+<tr><td>preserve_acls</td><td>string</td><td>Y</td><td>&nbsp;</td><td>&nbsp;</td><td>Preserve access control lists.<br/>Allowed values: none, native, metafile<br/>(--preserve-acls)</td></tr>
+<tr><td>preserve_creation_time</td><td>bool</td><td>Y</td><td>Y</td><td>Y</td><td>(--preserve-creation-time)</td></tr>
+<tr><td>preserve_file_owner_gid</td><td>bool</td><td>Y</td><td>&nbsp;</td><td>&nbsp;</td><td>Preserve the group ID for a file owner<br/>(--preserve-file-owner-gid)</td></tr>
+<tr><td>preserve_file_owner_uid</td><td>bool</td><td>Y</td><td>&nbsp;</td><td>&nbsp;</td><td>Preserve the user ID for a file owner<br/>(--preserve-file-owner-uid)</td></tr>
+<tr><td>preserve_modification_time</td><td>bool</td><td>Y</td><td>Y</td><td>Y</td><td>(--preserve-modification-time)</td></tr>
+<tr><td>preserve_remote_acls</td><td>string</td><td>Y</td><td>&nbsp;</td><td>&nbsp;</td><td>Preserve remote access control lists.<br/>Allowed values: none, native, metafile<br/>(--remote-preserve-acls)</td></tr>
+<tr><td>preserve_source_access_time</td><td>bool</td><td>Y</td><td>&nbsp;</td><td>&nbsp;</td><td>Preserve the time logged for when the source file was accessed<br/>(--preserve-source-access-time)</td></tr>
+<tr><td>preserve_times</td><td>bool</td><td>Y</td><td>Y</td><td>Y</td><td>(--preserve-times)</td></tr>
+<tr><td>proxy</td><td>string</td><td>Y</td><td>&nbsp;</td><td>&nbsp;</td><td>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)</td></tr>
+<tr><td>rate_policy</td><td>string</td><td>Y</td><td>Y</td><td>Y</td><td>The transfer rate policy to use when sharing bandwidth.<br/>Allowed values: low, fair, high, fixed<br/>(--policy)</td></tr>
+<tr><td>rate_policy_allowed</td><td>string</td><td>&nbsp;</td><td>&nbsp;</td><td>Y</td><td>Specifies most aggressive rate policy that is allowed.<br/>Returned by node API.<br/>Allowed values: low, fair, high, fixed</td></tr>
+<tr><td>remote_host</td><td>string</td><td>Y</td><td>Y</td><td>Y</td><td>IP or fully qualified domain name of the remote server<br/>(--host)</td></tr>
+<tr><td>remote_password</td><td>string</td><td>Y</td><td>Y</td><td>Y</td><td>SSH session password<br/>(env:ASPERA_SCP_PASS)</td></tr>
+<tr><td>remote_user</td><td>string</td><td>Y</td><td>Y</td><td>Y</td><td>Remote user. Default value is "xfer" on node or connect.<br/>(--user)</td></tr>
+<tr><td>remove_after_transfer</td><td>bool</td><td>Y</td><td>Y</td><td>&nbsp;</td><td>Remove SRC files after transfer success<br/>(--remove-after-transfer)</td></tr>
+<tr><td>remove_empty_directories</td><td>bool</td><td>Y</td><td>Y</td><td>&nbsp;</td><td>Specifies whether to remove empty directories.<br/>(--remove-empty-directories)</td></tr>
+<tr><td>remove_empty_source_directory</td><td>bool</td><td>Y</td><td>&nbsp;</td><td>&nbsp;</td><td>Remove empty source subdirectories and remove the source directory itself, if empty<br/>(--remove-empty-source-directory)</td></tr>
+<tr><td>remove_skipped</td><td>bool</td><td>Y</td><td>Y</td><td>Y</td><td>Must also have remove_after_transfer set to true, Defaults to false, if true, skipped files will be removed as well.<br/>(--remove-skipped)</td></tr>
+<tr><td>resume_policy</td><td>string</td><td>Y</td><td>Y</td><td>Y</td><td>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)</td></tr>
+<tr><td>retry_duration</td><td>string<br/>int</td><td>&nbsp;</td><td>Y</td><td>Y</td><td>Specifies how long to wait before retrying transfer. (e.g. "5min")</td></tr>
+<tr><td>source_root</td><td>string</td><td>Y</td><td>Y</td><td>Y</td><td>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)</td></tr>
+<tr><td>source_root_id</td><td>string</td><td>&nbsp;</td><td>Y</td><td>&nbsp;</td><td>The file ID of the source root directory. Required when using Bearer token auth for the source node.</td></tr>
+<tr><td>src_base</td><td>string</td><td>Y</td><td>Y</td><td>&nbsp;</td><td>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)</td></tr>
+<tr><td>ssh_port</td><td>int</td><td>Y</td><td>Y</td><td>Y</td><td>Specifies SSH (TCP) port. Default: local:22, other:33001<br/>(-P)</td></tr>
+<tr><td>ssh_private_key</td><td>string</td><td>Y</td><td>&nbsp;</td><td>&nbsp;</td><td>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)</td></tr>
+<tr><td>ssh_private_key_passphrase</td><td>string</td><td>Y</td><td>&nbsp;</td><td>&nbsp;</td><td>The passphrase associated with the transfer user's SSH private key. Available as of 3.7.2.<br/>(env:ASPERA_SCP_PASS)</td></tr>
+<tr><td>sshfp</td><td>string</td><td>Y</td><td>Y</td><td>Y</td><td>Check it against server SSH host key fingerprint<br/>(--check-sshfp)</td></tr>
+<tr><td>symlink_policy</td><td>string</td><td>Y</td><td>Y</td><td>Y</td><td>Handle source side symbolic links<br/>Allowed values: follow, copy, copy+force, skip<br/>(--symbolic-links)</td></tr>
+<tr><td>tags</td><td>hash</td><td>Y</td><td>Y</td><td>Y</td><td>Metadata for transfer as JSON<br/>(--tags64)</td></tr>
+<tr><td>target_rate_cap_kbps</td><td>int</td><td>&nbsp;</td><td>&nbsp;</td><td>Y</td><td>Returned by upload/download_setup node API.</td></tr>
+<tr><td>target_rate_kbps</td><td>int</td><td>Y</td><td>Y</td><td>Y</td><td>Specifies desired speed for the transfer.<br/>(-l)</td></tr>
+<tr><td>target_rate_percentage</td><td>string</td><td>Y</td><td>Y</td><td>Y</td><td>&nbsp;</td></tr>
+<tr><td>title</td><td>string</td><td>&nbsp;</td><td>Y</td><td>Y</td><td>Title of the transfer</td></tr>
+<tr><td>token</td><td>string</td><td>Y</td><td>Y</td><td>Y</td><td>Authorization token: Bearer, Basic or ATM (Also arg -W)<br/>(env:ASPERA_SCP_TOKEN)</td></tr>
+<tr><td>use_ascp4</td><td>bool</td><td>Y</td><td>Y</td><td>&nbsp;</td><td>specify version of protocol</td></tr>
+<tr><td>wss_enabled</td><td>bool</td><td>Y</td><td>Y</td><td>Y</td><td>&nbsp;</td></tr>
+<tr><td>wss_port</td><td>int</td><td>Y</td><td>Y</td><td>Y</td><td>TCP port used for websocket service feed.</td></tr>
+</table>
 
 #### Destination folder for transfers
 
@@ -1665,87 +2086,98 @@ 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>` .
 
-#### List of files for transfers
+#### <a id="file_list"></a>List of files for transfers
 
-When uploading, downloading or sending files, the user must specify the list of files to transfer. The option to specify the list of files is `sources`, the default value is `@args`, which means: take remain non used arguments (not starting with `-` as list of files.
-So, by default, the list of files to transfer will be simply specified on the command line:
+When uploading, downloading or sending files, the user must specify the list of files to transfer.
 
-```bash
-ascli server upload ~/mysample.file secondfile
-```
+By default the list of files to transfer is simply provided on the command line.
 
-This is equivalent to:
+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`).
 
-```bash
-ascli server upload --sources=@args ~/mysample.file secondfile
-```
+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).
+The `sources` and `src_type` options provide convenient ways to populate the transfer spec with the source file list.
 
-More advanced options are provided to adapt to various cases. In fact, list of files to transfer are normally conveyed using the [*transfer-spec*](#transferspec) using the field: "paths" which is a list (array) of pairs of "source" (mandatory) and "destination" (optional).
+Possible values for option `sources` are:
 
-Note that this is different from the "ascp" command line. The paradigm used by `ascli` is:
-all transfer parameters are kept in [*transfer-spec*](#transferspec) so that execution of a transfer is independent of the transfer agent. Note that other IBM Aspera interfaces use this: connect, node, transfer sdk.
+* `@args` : (default) the list of files (or file pair) is directly provided on the command line (after commands): unused arguments (not starting with `-`) are considered as source files.
+So, by default, the list of files to transfer will be simply specified on the command line. Example:
 
-For ease of use and flexibility, the list of files to transfer is specified by the option `sources`. Accepted values are:
+  ```bash
+  ascli server upload ~/first.file secondfile
+  ```
 
-* `@args` : (default value) the list of files is directly provided at the end of the command line (see at the beginning of this section).
+  This is the same as (with default values):
 
-* an [Extended Value](#extended) holding an *Array of String*. Examples:
+  ```bash
+  ascli server upload --sources=@args --src-type=list ~/mysample.file secondfile
+  ```
 
-```javascript
---sources=@json:'["file1","file2"]'
-```
+* an [Extended Value](#extended) with type **Array of String**
 
-```bash
---sources=@lines:@stdin:
-```
+  > Note: extended values can be tested with the command `conf echo`
 
-```ruby
---sources=@ruby:'File.read("myfilelist").split("\n")'
-```
+  Examples:
 
-* `@ts` : the user provides the list of files directly in the `ts` option, in its `paths` field. Example:
+  * Using extended value
 
-```javascript
---sources=@ts --ts=@json:'{"paths":[{"source":"file1"},{"source":"file2"}]}'
-```
+    Create the file list:
 
-providing a file list directly to ascp:
+    ```bash
+    echo ~/mysample.file > myfilelist.txt
+    echo secondfile >> myfilelist.txt
+    ```
 
-```javascript
-... --sources=@ts --ts=@json:'{"paths":[],"EX_file_list":"filelist.txt"}'
-```
+    Use the file list: one path per line:
 
-* Not recommended: It is possible to specify bare ascp arguments using the pseudo [*transfer-spec*](#transferspec) parameter `EX_ascp_args`.
+    ```ruby
+    --sources=@lines:@file:myfilelist.txt
+    ```
 
-```javascript
---sources=@ts --ts=@json:'{"paths":[{"source":"dummy"}],"EX_ascp_args":["--file-list","myfilelist"]}'
-```
+  * Using JSON array
 
-This method avoids creating a copy of the file list, but has drawbacks: it applies *only* to the [`direct`](#agt_direct) transfer agent (i.e. bare ascp) and not for Aspera on Cloud. One must specify a dummy list in the [*transfer-spec*](#transferspec), which will be overridden by the bare ascp command line provided. (TODO) In next version, dummy source paths can be removed.
+    ```javascript
+    --sources=@json:'["file1","file2"]'
+    ```
 
-In case the file list is provided on the command line i.e. using `--sources=@args` or `--sources=<Array>` (but not `--sources=@ts`), then the list of files will be used either as a simple file list or a file pair list depending on the value of the option: `src_type`:
+  * Using STDIN, one path per line
 
-* `list` : (default) the path of destination is the same as source
-* `pair` : in that case, the first element is the first source, the second element is the first destination, and so on.
+    ```bash
+    --sources=@lines:@stdin:
+    ```
 
-Example:
+  * Using ruby code (one path per line in file)
 
-```bash
-ascli server upload --src-type=pair ~/Documents/Samples/200KB.1 /Upload/sample1
-```
+    ```ruby
+    --sources=@ruby:'File.read("myfilelist.txt").split("\n")'
+    ```
 
-Internally, when transfer agent [`direct`](#agt_direct) is used, a temporary file list (or pair) file is generated and provided to ascp, unless `--file-list` or `--file-pair-list` is provided in `ts` in `EX_ascp_args`.
+* `@ts` : the user provides the list of files directly in the `paths` field of transfer spec (option `ts`).
+Examples:
 
-Note the special case when the source files are located on "Aspera on Cloud", i.e. using access keys and the `file id` API:
+  * Using transfer spec
 
-* All files must be in the same source folder.
-* If there is a single file : specify the full path
-* For multiple files, specify the source folder as first item in the list followed by the list of file names.
+  ```javascript
+  --sources=@ts --ts=@json:'{"paths":[{"source":"file1"},{"source":"file2"}]}'
+  ```
 
-Source files are located on "Aspera on cloud", when :
+The option `src_type` allows specifying if the list specified in option `sources` is a simple file list or if it is a file pair list.
+
+> Note: Option `src_type` is not used if option `sources` is set to `@ts`
+
+Supported values for `src_type` are:
+
+* `list` : (default) the path of destination is the same as source and each entry is a source file path
+* `pair` : the first element is the first source, the second element is the first destination, and so on.
+
+Example: Source file `200KB.1` is renamed `sample1` on destination:
+
+```bash
+ascli server upload --src-type=pair ~/Documents/Samples/200KB.1 /Upload/sample1
+```
 
-* the server is Aspera on Cloud, and making a download / recv
-* the agent is Aspera on Cloud, and making an upload / send
+> Note there are some specific rules to specify file list when using "Aspera on Cloud", refer to the AoC plugin section.
 
 #### <a id="multisession"></a>Support of multi-session
 
@@ -1785,13 +2217,13 @@ activating CSEAR consists in using transfer spec parameters:
 
 Example: parameter to download a faspex package and decrypt on the fly
 
-```json
+```javascript
 --ts=@json:'{"content_protection":"decrypt","content_protection_password":"_pass_here_"}'
 ```
 
 Note that up to version 4.6.0, the following parameters should be used for agent `direct`:
 
-```json
+```javascript
 --ts=@json:'{"EX_ascp_args":["--file-crypt=decrypt"],"EX_at_rest_password":"_secret_here_"}'
 ```
 
@@ -1978,318 +2410,51 @@ 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="commands"></a>Sample Commands
-
-A non complete list of commands used in unit tests:
-
-```bash
-ascli
-ascli -h
-ascli aoc -N remind --username=my_aoc_user_email
-ascli aoc -N servers
-ascli aoc admin analytics transfers --query=@json:'{"status":"completed","direction":"receive"}' --notif-to=my_recipient_email --notif-template=@ruby:'%Q{From: <%=from_name%> <<%=from_email%>>\nTo: <<%=to%>>\nSubject: <%=ev["files_completed"]%> files received\n\n<%=ev.to_yaml%>}'
-ascli aoc admin ats access_key create --cloud=aws --region=my_aws_bucket_region --params=@json:'{"id":"ak_aws","name":"my test key AWS","storage":{"type":"aws_s3","bucket":"my_aws_bucket_name","credentials":{"access_key_id":"my_aws_bucket_key","secret_access_key":"my_aws_bucket_secret"},"path":"/"}}'
-ascli aoc admin ats access_key create --cloud=softlayer --region=my_icos_bucket_region --params=@json:'{"id":"akibmcloud","secret":"somesecret","name":"my test key","storage":{"type":"ibm-s3","bucket":"my_icos_bucket_name","credentials":{"access_key_id":"my_icos_bucket_key","secret_access_key":"my_icos_bucket_secret"},"path":"/"}}'
-ascli aoc admin ats access_key delete akibmcloud
-ascli aoc admin ats access_key list --fields=name,id
-ascli aoc admin ats access_key node akibmcloud --secret=somesecret browse /
-ascli aoc admin ats cluster clouds
-ascli aoc admin ats cluster list
-ascli aoc admin ats cluster show --cloud=aws --region=eu-west-1
-ascli aoc admin ats cluster show 1f412ae7-869a-445c-9c05-02ad16813be2
-ascli aoc admin res application list
-ascli aoc admin res client list
-ascli aoc admin res client_access_key list
-ascli aoc admin res client_registration_token create @json:'{"data":{"name":"test_client_reg1","client_subject_scopes":["alee","aejd"],"client_subject_enabled":true}}'
-ascli aoc admin res client_registration_token delete my_clt_reg_id
-ascli aoc admin res client_registration_token list
-ascli aoc admin res contact list
-ascli aoc admin res dropbox list
-ascli aoc admin res dropbox_membership list
-ascli aoc admin res group list
-ascli aoc admin res kms_profile list
-ascli aoc admin res node list
-ascli aoc admin res operation list
-ascli aoc admin res organization show
-ascli aoc admin res package list --http-options=@json:'{"read_timeout":120.0}'
-ascli aoc admin res saml_configuration list
-ascli aoc admin res self show
-ascli aoc admin res short_link list
-ascli aoc admin res user list
-ascli aoc admin res workspace_membership list
-ascli aoc admin resource node --name=my_aoc_node1_name --secret=my_aoc_node1_secret v3 access_key create --value=@json:'{"id":"testsub1","storage":{"path":"/folder1"}}'
-ascli aoc admin resource node --name=my_aoc_node1_name --secret=my_aoc_node1_secret v3 events
-ascli aoc admin resource node --name=my_aoc_node1_name --secret=my_aoc_node1_secret v4 browse /
-ascli aoc admin resource node --name=my_aoc_node1_name --secret=my_aoc_node1_secret v4 delete /folder1
-ascli aoc admin resource node --name=my_aoc_node1_name --secret=my_aoc_node1_secret v4 mkdir /folder1
-ascli aoc admin resource node v3 name my_aoc_node1_name --secret=my_aoc_node1_secret access_key delete testsub1
-ascli aoc admin resource workspace list
-ascli aoc admin resource workspace_membership list --fields=ALL --query=@json:'{"page":1,"per_page":50,"embed":"member","inherited":false,"workspace_id":11363,"sort":"name"}'
-ascli aoc automation workflow action my_wf_id create --value=@json:'{"name":"toto"}'
-ascli aoc automation workflow create --value=@json:'{"name":"test_workflow"}'
-ascli aoc automation workflow delete my_wf_id
-ascli aoc automation workflow list
-ascli aoc automation workflow list --select=@json:'{"name":"test_workflow"}' --fields=id --format=csv --display=data
-ascli aoc automation workflow list --value=@json:'{"show_org_workflows":"true"}' --scope=admin:all
-ascli aoc bearer_token --display=data --scope=user:all
-ascli aoc faspex
-ascli aoc files bearer /
-ascli aoc files bearer_token_node / --cache-tokens=no
-ascli aoc files browse /
-ascli aoc files browse / -N --link=my_aoc_publink_folder
-ascli aoc files delete /testsrc
-ascli aoc files download --transfer=connect /200KB.1
-ascli aoc files file show my_file_id
-ascli aoc files find / --value='\.partial$'
-ascli aoc files http_node_download --to-folder=. /200KB.1
-ascli aoc files mkdir /testsrc
-ascli aoc files rename /somefolder testdst
-ascli aoc files short_link create --to-folder=/testdst --value=private
-ascli aoc files short_link create --to-folder=/testdst --value=public
-ascli aoc files short_link list --value=@json:'{"purpose":"shared_folder_auth_link"}'
-ascli aoc files transfer --from-folder=/testsrc --to-folder=/testdst testfile.bin
-ascli aoc files upload --to-folder=/testsrc testfile.bin
-ascli aoc files upload -N --to-folder=/ testfile.bin --link=my_aoc_publink_folder
-ascli aoc files upload Test.pdf --transfer=node --transfer-info=@json:@stdin:
-ascli aoc files v3 info
-ascli aoc org -N --link=my_aoc_publink_recv_from_aocuser
-ascli aoc organization
-ascli aoc packages list
-ascli aoc packages list --query=@json:'{"dropbox_name":"my_aoc_shbx_name","sort":"-received_at","archived":false,"received":true,"has_content":true,"exclude_dropbox_packages":false}'
-ascli aoc packages recv "my_package_id" --to-folder=.
-ascli aoc packages recv ALL --to-folder=. --once-only=yes --lock-port=12345
-ascli aoc packages send --value=@json:'{"name":"Important files delivery","recipients":["my_email_external_user"]}' --new-user-option=@json:'{"package_contact":true}' testfile.bin
-ascli aoc packages send --value=@json:'{"name":"Important files delivery","recipients":["my_email_internal_user"],"note":"my note"}' testfile.bin
-ascli aoc packages send --workspace="my_aoc_shbx_ws" --value=@json:'{"name":"Important files delivery","recipients":["my_aoc_shbx_name"],"metadata":[{"input_type":"single-text","name":"Project Id","values":["123"]},{"input_type":"single-dropdown","name":"Type","values":["Opt2"]},{"input_type":"multiple-checkbox","name":"CheckThose","values":["Check1","Check2"]},{"input_type":"date","name":"Optional Date","values":["2021-01-13T15:02:00.000Z"]}]}' testfile.bin
-ascli aoc packages send --workspace="my_aoc_shbx_ws" --value=@json:'{"name":"Important files delivery","recipients":["my_aoc_shbx_name"],"metadata":{"Project Id":"456","Type":"Opt2","CheckThose":["Check1","Check2"],"Optional Date":"2021-01-13T15:02:00.000Z"}}' testfile.bin
-ascli aoc packages send --workspace="my_aoc_shbx_ws" --value=@json:'{"name":"Important files delivery","recipients":["my_aoc_shbx_name"]}' testfile.bin
-ascli aoc packages send -N --value=@json:'{"name":"Important files delivery"}' testfile.bin --link=my_aoc_publink_send_aoc_user --password=my_aoc_publink_send_use_pass
-ascli aoc packages send -N --value=@json:'{"name":"Important files delivery"}' testfile.bin --link=my_aoc_publink_send_shd_inbox
-ascli aoc packages shared_inboxes list
-ascli aoc user profile modify @json:'{"name":"dummy change"}'
-ascli aoc user profile show
-ascli aoc user workspaces current
-ascli aoc user workspaces list
-ascli ats access_key cluster akibmcloud --secret=somesecret
-ascli ats access_key create --cloud=aws --region=my_aws_bucket_region --params=@json:'{"id":"ak_aws","name":"my test key AWS","storage":{"type":"aws_s3","bucket":"my_aws_bucket_name","credentials":{"access_key_id":"my_aws_bucket_key","secret_access_key":"my_aws_bucket_secret"},"path":"/"}}'
-ascli ats access_key create --cloud=softlayer --region=my_icos_bucket_region --params=@json:'{"id":"akibmcloud","secret":"somesecret","name":"my test key","storage":{"type":"ibm-s3","bucket":"my_icos_bucket_name","credentials":{"access_key_id":"my_icos_bucket_key","secret_access_key":"my_icos_bucket_secret"},"path":"/"}}'
-ascli ats access_key delete ak_aws
-ascli ats access_key delete akibmcloud
-ascli ats access_key list --fields=name,id
-ascli ats access_key node akibmcloud browse / --secret=somesecret
-ascli ats api_key create
-ascli ats api_key instances
-ascli ats api_key list
-ascli ats cluster clouds
-ascli ats cluster list
-ascli ats cluster show --cloud=aws --region=eu-west-1
-ascli ats cluster show 1f412ae7-869a-445c-9c05-02ad16813be2
-ascli conf flush_tokens
-ascli conf wiz --url=https://my_aoc_org.ibmaspera.com --config-file=SAMPLE_CONFIG_FILE --pkeypath= --username=my_aoc_user_email --test-mode=yes
-ascli conf wiz --url=https://my_aoc_org.ibmaspera.com --config-file=SAMPLE_CONFIG_FILE --pkeypath= --username=my_aoc_user_email --test-mode=yes --use-generic-client=yes
-ascli config ascp connect info 'Aspera Connect for Windows'
-ascli config ascp connect list
-ascli config ascp connect version 'Aspera Connect for Windows' download 'Windows Installer' --to-folder=.
-ascli config ascp connect version 'Aspera Connect for Windows' list
-ascli config ascp connect version 'Aspera Connect for Windows' open documentation
-ascli config ascp errors
-ascli config ascp info
-ascli config ascp install
-ascli config ascp products list
-ascli config ascp show
-ascli config ascp spec
-ascli config check_update
-ascli config detect --url=https://my_aoc_org.ibmaspera.com
-ascli config detect --url=my_faspex_url
-ascli config doc
-ascli config doc transfer-parameters
-ascli config email_test --notif-to=my_recipient_email
-ascli config export
-ascli config genkey mykey
-ascli config plugin create mycommand T
-ascli config plugin list
-ascli config proxy_check --fpac=@file:examples/proxy.pac https://eudemo.asperademo.com
-ascli console transfer current list 
-ascli console transfer smart list 
-ascli console transfer smart sub my_job_id @json:'{"source":{"paths":["my_file_name"]},"source_type":"user_selected"}'
-ascli cos -N --bucket=my_icos_bucket_name --endpoint=my_icos_bucket_endpoint --apikey=my_icos_bucket_apikey --crn=my_icos_resource_instance_id node info
-ascli cos -N --bucket=my_icos_bucket_name --region=my_icos_bucket_region --service-credentials=@json:@file:service_creds.json node info
-ascli cos node access_key show self
-ascli cos node download testfile.bin --to-folder=.
-ascli cos node info
-ascli cos node upload testfile.bin
-ascli faspex dropbox list --recipient="*my_faspex_dbx"
-ascli faspex dropbox list --recipient="*my_faspex_wkg"
-ascli faspex health
-ascli faspex package list
-ascli faspex package list --box=sent --fields=package_id --format=csv --display=data --query=@json:'{"max":1}'
-ascli faspex package list --fields=package_id --format=csv --display=data --query=@json:'{"max":1}'
-ascli faspex package list --recipient="*my_faspex_dbx" --format=csv --fields=package_id --query=@json:'{"max":1}'
-ascli faspex package list --recipient="*my_faspex_wkg" --format=csv --fields=package_id --query=@json:'{"max":1}'
-ascli faspex package recv "my_package_id" --to-folder=.
-ascli faspex package recv "my_package_id" --to-folder=. --box=sent
-ascli faspex package recv --to-folder=. --link="my_faspex_publink_recv_from_fxuser"
-ascli faspex package recv ALL --to-folder=. --once-only=yes
-ascli faspex package recv my_pkgid --recipient="*my_faspex_dbx" --to-folder=.
-ascli faspex package recv my_pkgid --recipient="*my_faspex_wkg" --to-folder=.
-ascli faspex package send --delivery-info=@json:'{"title":"Important files delivery","recipients":["*my_faspex_dbx"]}' testfile.bin
-ascli faspex package send --delivery-info=@json:'{"title":"Important files delivery","recipients":["*my_faspex_wkg"]}' testfile.bin
-ascli faspex package send --delivery-info=@json:'{"title":"Important files delivery","recipients":["my_email_internal_user","my_faspex_username"]}' testfile.bin
-ascli faspex package send --link="my_faspex_publink_send_to_dropbox" --delivery-info=@json:'{"title":"Important files delivery"}' testfile.bin
-ascli faspex package send --link="my_faspex_publink_send_to_fxuser" --delivery-info=@json:'{"title":"Important files delivery"}' testfile.bin
-ascli faspex source name "Server Files" node br /
-ascli faspex v4 dmembership list
-ascli faspex v4 dropbox list
-ascli faspex v4 metadata_profile list
-ascli faspex v4 user list
-ascli faspex v4 wmembership list
-ascli faspex v4 workgroup list
-ascli faspex5 admin res accounts list
-ascli faspex5 admin res contacts list
-ascli faspex5 admin res jobs list
-ascli faspex5 admin res node list --value=@json:'{"type":"received","subtype":"mypackages"}'
-ascli faspex5 admin res oauth_clients list
-ascli faspex5 admin res registrations list
-ascli faspex5 admin res saml_configs list
-ascli faspex5 admin res shared_inboxes list
-ascli faspex5 admin res workgroups list
-ascli faspex5 package list --value=@json:'{"mailbox":"inbox","state":["released"]}'
-ascli faspex5 package receive "my_package_id" --to-folder=.
-ascli faspex5 package send --value=@json:'{"title":"test title","recipients":[{"name":"my_f5_user"}]}' testfile.bin
-ascli mycommand --plugin-folder=T
-ascli node -N -Ptst_node_preview access_key create --value=@json:'{"id":"aoc_1","storage":{"type":"local","path":"/"}}'
-ascli node -N -Ptst_node_preview access_key delete aoc_1
-ascli node async bandwidth 1
-ascli node async counters 1
-ascli node async files 1
-ascli node async list
-ascli node async show 1
-ascli node async show ALL
-ascli node basic_token
-ascli node browse / -r
-ascli node delete folder_1/10MB.1
-ascli node delete testfile.bin
-ascli node download testfile.bin --to-folder=.
-ascli node download testfile.bin --to-folder=. --token-type=hybrid
-ascli node health
-ascli node info --fpac='function FindProxyForURL(url,host){return "DIRECT"}'
-ascli node search / --value=@json:'{"sort":"mtime"}'
-ascli node service create @json:'{"id":"service1","type":"WATCHD","run_as":{"user":"user1"}}'
-ascli node service delete service1
-ascli node service list
-ascli node transfer list --value=@json:'{"active_only":true}'
-ascli node upload --to-folder="folder_1" --sources=@ts --ts=@json:'{"paths":[{"source":"/aspera-test-dir-small/10MB.1"}],"precalculate_job_size":true}' --transfer=node --transfer-info=@json:'{"url":"my_node_url","username":"my_node_user","password":"my_node_pass"}'
-ascli node upload testfile.bin --to-folder=folder_1 --ts=@json:'{"target_rate_cap_kbps":10000}'
-ascli node upload testfile.bin --to-folder=folder_1 --ts=@json:'{"target_rate_cap_kbps":10000}' --token-type=hybrid
-ascli orchestrator info
-ascli orchestrator plugins
-ascli orchestrator processes
-ascli orchestrator workflow inputs my_orch_workflow_id
-ascli orchestrator workflow list
-ascli orchestrator workflow start my_orch_workflow_id --params=@json:'{"Param":"world !"}'
-ascli orchestrator workflow start my_orch_workflow_id --params=@json:'{"Param":"world !"}' --result=ResultStep:Complete_status_message
-ascli orchestrator workflow status ALL
-ascli orchestrator workflow status my_orch_workflow_id
-ascli preview check --skip-types=office
-ascli preview folder 1 --skip-types=office --log-level=info --file-access=remote --ts=@json:'{"target_rate_kbps":1000000}'
-ascli preview scan --skip-types=office --log-level=info
-ascli preview test --case=test mp4 my_file_mxf --video-conversion=blend --log-level=debug
-ascli preview test --case=test mp4 my_file_mxf --video-conversion=clips --log-level=debug
-ascli preview test --case=test mp4 my_file_mxf --video-conversion=reencode --log-level=debug
-ascli preview test --case=test png my_file_dcm --log-level=debug
-ascli preview test --case=test png my_file_docx --log-level=debug
-ascli preview test --case=test png my_file_mxf --video-png-conv=animated --log-level=debug
-ascli preview test --case=test png my_file_mxf --video-png-conv=fixed --log-level=debug
-ascli preview test --case=test png my_file_pdf --log-level=debug
-ascli preview trevents --once-only=yes --skip-types=office --log-level=info
-ascli server -N -Ptst_hstsfaspex_ssh -Plocal_user ctl all:status
-ascli server -N -Ptst_hstsfaspex_ssh -Plocal_user health app_services --format=nagios
-ascli server -N -Ptst_hstsfaspex_ssh -Plocal_user health asctlstatus --format=nagios --cmd-prefix='sudo '
-ascli server -N -Ptst_hstsfaspex_ssh -Plocal_user nodeadmin -- -l
-ascli server -N -Ptst_server_bykey -Plocal_user br /
-ascli server browse /
-ascli server browse folder_1/target_hot
-ascli server cp NEW_SERVER_FOLDER/testfile.bin folder_1/200KB.2
-ascli server delete NEW_SERVER_FOLDER
-ascli server delete folder_1/target_hot
-ascli server delete folder_1/to.delete
-ascli server df
-ascli server download NEW_SERVER_FOLDER/testfile.bin --to-folder=. --transfer-info=@json:'{"wss":false,"resume":{"iter_max":1}}'
-ascli server download NEW_SERVER_FOLDER/testfile.bin --to-folder=folder_1 --transfer=node
-ascli server du /
-ascli server health transfer --to-folder=folder_1 --format=nagios 
-ascli server info
-ascli server md5sum NEW_SERVER_FOLDER/testfile.bin
-ascli server mkdir NEW_SERVER_FOLDER --logger=stdout
-ascli server mkdir folder_1/target_hot
-ascli server mv folder_1/200KB.2 folder_1/to.delete
-ascli server upload --sources=@ts --ts=@json:'{"paths":[{"source":"testfile.bin","destination":"NEW_SERVER_FOLDER/othername"}]}'
-ascli server upload --src-type=pair --sources=@json:'["testfile.bin","NEW_SERVER_FOLDER/othername"]'
-ascli server upload --src-type=pair testfile.bin NEW_SERVER_FOLDER/othername --notif-to=my_recipient_email
-ascli server upload --src-type=pair testfile.bin folder_1/with_options --ts=@json:'{"cipher":"aes-192-gcm","content_protection":"encrypt","content_protection_password":"_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"}'
-ascli server upload --to-folder=folder_1/target_hot --lock-port=12345 --ts=@json:'{"EX_ascp_args":["--remove-after-transfer","--remove-empty-directories","--exclude-newer-than=-8","--src-base","source_hot"]}' source_hot
-ascli server upload testfile.bin --to-folder=NEW_SERVER_FOLDER --ts=@json:'{"multi_session":3,"multi_session_threshold":1,"resume_policy":"none","target_rate_kbps":1500}' --transfer-info=@json:'{"spawn_delay_sec":2.5}' --progress=multi
-ascli shares admin share list
-ascli shares repository browse /
-ascli shares repository delete my_shares_upload/testfile.bin
-ascli shares repository download --to-folder=. my_shares_upload/testfile.bin
-ascli shares repository download --to-folder=. my_shares_upload/testfile.bin --transfer=httpgw --transfer-info=@json:'{"url":"https://my_http_gw_fqdn/aspera/http-gwy/v1"}'
-ascli shares repository upload --to-folder=my_shares_upload testfile.bin
-ascli shares repository upload --to-folder=my_shares_upload testfile.bin --transfer=httpgw --transfer-info=@json:'{"url":"https://my_http_gw_fqdn/aspera/http-gwy/v1"}'
-ascli shares2 appinfo
-ascli shares2 organization list
-ascli shares2 project list --organization=Sport
-ascli shares2 repository browse /
-ascli shares2 userinfo
-ascli sync start --parameters=@json:'{"sessions":[{"name":"test","reset":true,"remote_dir":"/sync_test","local_dir":"contents","host":"my_remote_host","tcp_port":33001,"user":"my_remote_user","private_key_path":"my_local_user_key"}]}'
-...and more
-```
-
 ### <a id="usage"></a>Usage
 
-```bash
+```text
 ascli -h
 NAME
-	ascli -- a command line tool for Aspera Applications (v4.7.0)
+        ascli -- a command line tool for Aspera Applications (v4.9.0)
 
 SYNOPSIS
-	ascli COMMANDS [OPTIONS] [ARGS]
+        ascli COMMANDS [OPTIONS] [ARGS]
 
 DESCRIPTION
-	Use Aspera application to perform operations on command line.
-	Documentation and examples: https://rubygems.org/gems/aspera-cli
-	execute: ascli conf doc
-	or visit: https://www.rubydoc.info/gems/aspera-cli
-	source repo: https://github.com/IBM/aspera-cli
+        Use Aspera application to perform operations on command line.
+        Documentation and examples: https://rubygems.org/gems/aspera-cli
+        execute: ascli conf doc
+        or visit: https://www.rubydoc.info/gems/aspera-cli
+        source repo: https://github.com/IBM/aspera-cli
 
 ENVIRONMENT VARIABLES
-	ASCLI_HOME config folder, default: $HOME/.aspera/ascli
-	Any option can be set as an environment variable, refer to the manual
+        ASCLI_HOME config folder, default: $HOME/.aspera/ascli
+        Any option can be set as an environment variable, refer to the manual
 
 COMMANDS
-	To list first level commands, execute: ascli
-	Note that commands can be written shortened (provided it is unique).
+        To list first level commands, execute: ascli
+        Note that commands can be written shortened (provided it is unique).
 
 OPTIONS
-	Options begin with a '-' (minus), and value is provided on command line.
-	Special values are supported beginning with special prefix @pfx:, where pfx is one of:
-	base64, json, zlib, ruby, csvt, lines, list, incps, val, file, path, env, uri, stdin, preset
-	Dates format is 'DD-MM-YY HH:MM:SS', or 'now' or '-<num>h'
+        Options begin with a '-' (minus), and value is provided on command line.
+        Special values are supported beginning with special prefix @pfx:, where pfx is one of:
+        base64, json, zlib, ruby, csvt, lines, list, incps, val, file, path, env, uri, stdin, preset
+        Dates format is 'DD-MM-YY HH:MM:SS', or 'now' or '-<num>h'
 
 ARGS
-	Some commands require mandatory arguments, e.g. a path.
+        Some commands require mandatory arguments, e.g. a path.
 
 OPTIONS: global
         --interactive=ENUM           use interactive input of missing params: yes, [no]
         --ask-options=ENUM           ask even optional options: yes, [no]
-        --format=ENUM                output format: [table], ruby, json, jsonpp, yaml, csv, nagios
+        --format=ENUM                output format: text, nagios, ruby, json, jsonpp, yaml, [table], csv
         --display=ENUM               output only some information: [info], data, error
         --fields=VALUE               comma separated list of fields, or ALL, or DEF
         --select=VALUE               select only some items in lists, extended value: hash (column, value)
         --table-style=VALUE          table display style
         --flat-hash=ENUM             display hash values as additional keys: [yes], no
         --transpose-single=ENUM      single object fields output vertically: [yes], no
-        --show-secrets=ENUM          show secrets on command output: [yes], no
+        --show-secrets=ENUM          show secrets on command output: yes, [no]
     -h, --help                       Show this message.
         --bash-comp                  generate bash completion for command
         --show-config                Display parameters used for the provided action.
@@ -2313,6 +2478,7 @@ OPTIONS:
         --value=VALUE                extended value for create, update, list filter
         --property=VALUE             name of property to set
         --id=VALUE                   resource identifier (modify,delete,show)
+        --bulk=ENUM                  Bulk operation (only some): yes, [no]
         --config-file=VALUE          read parameters from file in YAML format, current=/usershome/.aspera/ascli/config.yaml
     -N, --no-default                 do not load default configuration for plugin
         --override=ENUM              Wizard: override existing value: yes, [no]
@@ -2335,16 +2501,16 @@ OPTIONS:
         --plugin-folder=VALUE        folder where to find additional plugins
         --ts=VALUE                   override transfer spec values (Hash, use @json: prefix), current={"create_dir"=>true}
         --local-resume=VALUE         set resume policy (Hash, use @json: prefix), current=
-        --to-folder=VALUE            destination folder for downloaded files
-        --sources=VALUE              list of source files (see doc)
-        --transfer-info=VALUE        parameters for transfer agent
+        --to-folder=VALUE            destination folder for transfered files
+        --sources=VALUE              how list of transfered files is provided (@args,@ts,Array)
         --src-type=ENUM              type of file list: list, pair
         --transfer=ENUM              type of transfer agent: direct, node, connect, httpgw, trsdk
+        --transfer-info=VALUE        parameters for transfer agent
         --progress=ENUM              type of progress bar: none, native, multi
 
 
 COMMAND: shares
-SUBCOMMANDS: repository admin
+SUBCOMMANDS: health repository admin
 OPTIONS:
         --url=VALUE                  URL of application, e.g. https://org.asperafiles.com
         --username=VALUE             username to log in
@@ -2364,7 +2530,7 @@ OPTIONS:
 
 
 COMMAND: orchestrator
-SUBCOMMANDS: info workflow plugins processes
+SUBCOMMANDS: health info workflow plugins processes
 OPTIONS:
         --url=VALUE                  URL of application, e.g. https://org.asperafiles.com
         --username=VALUE             username to log in
@@ -2405,27 +2571,29 @@ OPTIONS:
 
 
 COMMAND: faspex5
-SUBCOMMANDS: package admin
+SUBCOMMANDS: health package admin user
 OPTIONS:
         --url=VALUE                  URL of application, e.g. https://org.asperafiles.com
         --username=VALUE             username to log in
         --password=VALUE             user's password
         --client-id=VALUE            OAuth client identifier
         --client-secret=VALUE        OAuth client secret
-        --redirect-uri=VALUE         OAuth redirect URI
+        --redirect-uri=VALUE         OAuth redirect URI for web authentication
         --auth=ENUM                  OAuth type of authentication: web, jwt, boot
-        --private-key=VALUE          Oauth RSA private key PEM value for JWT (prefix file path with @val:@file:)
+        --private-key=VALUE          OAuth JWT RSA private key PEM value (prefix file path with @file:)
+        --passphrase=VALUE           RSA private key passphrase
 
 
 COMMAND: cos
 SUBCOMMANDS: node
 OPTIONS:
-        --bucket=VALUE               IBM Cloud Object Storage bucket name
-        --endpoint=VALUE             storage endpoint url
-        --apikey=VALUE               storage API key
-        --crn=VALUE                  ressource instance id
+        --bucket=VALUE               Bucket name
+        --endpoint=VALUE             Storage endpoint url
+        --apikey=VALUE               Storage API key
+        --crn=VALUE                  Ressource instance id
         --service-credentials=VALUE  IBM Cloud service credentials (Hash)
-        --region=VALUE               IBM Cloud Object storage region
+        --region=VALUE               Storage region
+        --identity=VALUE             Authentication url (https://iam.cloud.ibm.com/identity)
 
 
 COMMAND: faspex
@@ -2462,9 +2630,9 @@ OPTIONS:
         --file-access=ENUM           how to read and write files in repository: [local], remote
         --max-size=VALUE             maximum size (in bytes) of preview file
         --thumb-vid-scale=VALUE      png: video: size (ffmpeg scale argument)
-        --thumb-vid-fraction=VALUE   png: video: position of snapshot
+        --thumb-vid-fraction=VALUE   png: video: time percent position of snapshot
         --thumb-img-size=VALUE       png: non-video: height (and width)
-        --thumb-text-font=VALUE      png: plaintext: font to render text with image magick convert, list with: identify -list font
+        --thumb-text-font=VALUE      png: plaintext: font to render text with imagemagick convert (identify -list font)
         --video-conversion=ENUM      mp4: method for preview generation: [reencode], blend, clips
         --video-png-conv=ENUM        mp4: method for thumbnail generation: [fixed], animated
         --video-start-sec=VALUE      mp4: start offset (seconds) of video preview
@@ -2495,27 +2663,27 @@ OPTIONS:
         --client-id=VALUE            OAuth API client identifier in application
         --client-secret=VALUE        OAuth API client passcode
         --redirect-uri=VALUE         OAuth API client redirect URI
-        --private-key=VALUE          OAuth JWT RSA private key PEM value (prefix file path with @val:@file:)
+        --private-key=VALUE          OAuth JWT RSA private key PEM value (prefix file path with @file:)
+        --passphrase=VALUE           RSA private key passphrase
         --workspace=VALUE            name of workspace
         --name=VALUE                 resource name
         --path=VALUE                 file or folder path
         --link=VALUE                 public link to shared resource
-        --new-user-option=VALUE      new user creation option
+        --new-user-option=VALUE      new user creation option for unknown package recipients
         --from-folder=VALUE          share to share source folder
         --scope=VALUE                OAuth scope for AoC API calls
-        --bulk=ENUM                  bulk operation: yes, [no]
         --default-ports=ENUM         use standard FASP ports or get from node api: yes, [no]
+        --validate-metadata=ENUM     validate shared inbox metadata: yes, [no]
 
 
 COMMAND: server
-SUBCOMMANDS: health nodeadmin userdata configurator ctl download upload browse delete rename ls rm mv du info mkdir cp df md5sum
+SUBCOMMANDS: health download upload browse delete rename ls rm mv du info mkdir cp df md5sum
 OPTIONS:
         --url=VALUE                  URL of application, e.g. https://org.asperafiles.com
         --username=VALUE             username to log in
         --password=VALUE             user's password
-        --ssh-keys=VALUE             ssh key path list (Array or single)
-        --ssh-options=VALUE          ssh options (Hash)
-        --cmd-prefix=VALUE           prefix to add for as cmd execution, e.g. sudo or /opt/aspera/bin 
+        --ssh-keys=VALUE             SSH key path list (Array or single)
+        --ssh-options=VALUE          SSH options (Hash)
 
 
 COMMAND: console
@@ -2532,9 +2700,15 @@ OPTIONS:
 
 Note that actions and parameter values can be written in short form.
 
-## <a id="aoc"></a>Plugin: Aspera on Cloud
+### Bulk creation and deletion of resources
 
-Aspera on Cloud uses the more advanced Oauth v2 mechanism for authentication (HTTP Basic authentication is not supported).
+Bulk creation and deletion of resources are possible using option `bulk` (yes,no(default)).
+In that case, the operation expects an Array of Hash instead of a simple Hash using the [Extended Value Syntax](#extended).
+This option is available only for some of the resources: if you need it: try and see if the entities you try to create or delete support this option.
+
+## <a id="aoc"></a>Plugin: Aspera on Cloud
+
+Aspera on Cloud uses the more advanced Oauth v2 mechanism for authentication (HTTP Basic authentication is not supported).
 
 It is recommended to use the wizard to set it up, but manual configuration is also possible.
 
@@ -2542,7 +2716,7 @@ It is recommended to use the wizard to set it up, but manual configuration is al
 
 `ascli` provides a configuration wizard. Here is a sample invocation :
 
-```bash
+```text
 ascli config wizard
 option: url> https://myorg.ibmaspera.com
 Detected: Aspera on Cloud
@@ -2575,7 +2749,7 @@ ascli config wizard --value=aoc
 
 ### <a id="aocmanual"></a>Configuration: using manual setup
 
-If you used the wizard (recommended): skip this section.
+> If you used the wizard (recommended): skip this section.
 
 #### Configuration details
 
@@ -2646,7 +2820,7 @@ Note: Default `auth` method is `web` and default `redirect_uri` is `http://local
 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 (without passphrase)
+a [private/public key pair](#private_key) must be used.
 
 ##### API Client JWT activation
 
@@ -2654,7 +2828,7 @@ If you are not using the built-in client_id and secret, JWT needs to be authoriz
 
 * Graphically
 
-  * Open a web browser, log to your instance: https://myorg.ibmaspera.com/
+  * Open a web browser, log to your instance: `https://myorg.ibmaspera.com/`
   * Go to Apps&rarr;Admin&rarr;Organization&rarr;Integrations
   * Click on the previously created application
   * select tab : "JSON Web Token Auth"
@@ -2691,7 +2865,7 @@ The public key must be assigned to your user. This can be done in two manners:
 
 Open the previously generated public key located here: `$HOME/.aspera/ascli/my_private_key.pub`
 
-* Open a web browser, log to your instance: https://myorg.ibmaspera.com/
+* Open a web browser, log to your instance: `https://myorg.ibmaspera.com/`
 * Click on the user's icon (top right)
 * Select "Account Settings"
 * Paste the *Public Key* in the "Public Key" section
@@ -2736,7 +2910,7 @@ Execute:
 ascli config preset update my_aoc_org --auth=jwt --private-key=@val:@file:~/.aspera/ascli/my_private_key --username=laurent.martin.aspera@fr.ibm.com
 ```
 
-Note: the private key argument represents the actual PEM string. In order to read the content from a file, use the @file: prefix. But if the @file: argument is used as is, it will read the file and set in the config file. So to keep the "@file" tag in the configuration file, the @val: prefix is added.
+Note: the private key argument represents the actual PEM string. In order to read the content from a file, use the `@file:` prefix. But if the @file: argument is used as is, it will read the file and set in the config file. So to keep the "@file" tag in the configuration file, the `@val:` prefix is added.
 
 After this last step, commands do not require web login anymore.
 
@@ -2753,17 +2927,33 @@ Current Workspace: Default Workspace (default)
 empty
 ```
 
+### Calling AoC APIs from command line
+
+The command `ascli aoc bearer` can be used to generate an OAuth token suitable to call any AoC API (use the `scope` option to change the scope, default is `user:all`).
+This can be useful when a command is not yet available.
+
+Example:
+
+```bash
+curl -s -H "Authorization: $(ascli aoc bearer_token)" 'https://api.ibmaspera.com/api/v1/group_memberships?embed[]=dropbox&embed[]=workspace'|jq -r '.[]|(.workspace.name + " -> " + .dropbox.name)'
+```
+
+It is also possible to get the bearer token for node, as user or as admin using:
+
+```bash
+ascli aoc files bearer_token_node /
+```
+
+```bash
+ascli aoc admin res node v4 1234 --secret=_ak_secret_here_ bearer_token_node /
+```
+
 ### Administration
 
 The `admin` command allows several administrative tasks (and require admin privilege).
 
 It allows actions (create, update, delete) on "resources": users, group, nodes, workspace, etc... with the `admin resource` command.
 
-#### Bulk creation and deletion of resource
-
-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).
-
 #### Listing resources
 
 The command `aoc admin res <type> list` lists all entities of given type. It uses paging and multiple requests if necessary.
@@ -2825,6 +3015,50 @@ To execute an action on a specific resource, select it using one of those method
 * provide option `id` : `aoc admin res node show --id=123`
 * provide option `name` : `aoc admin res node show --name=abc`
 
+#### <a id="res_create"></a>Creating a resource
+
+New resources (users, groups, workspaces, etc..) can be created using a command like:
+
+```bash
+ascli aoc admin res create <resource type> @json:'{<...parameters...>}'
+```
+
+Some of the API endpoints are described [here](https://developer.ibm.com/apis/catalog?search=%22aspera%20on%20cloud%20api%22). Sadly, not all.
+
+Nevertheless, it is possible to guess the structure of the creation value by simply dumping an existing resource, and use the same parameters for the creation.
+
+```bash
+ascli aoc admin res group show 12345 --format=json
+```
+
+```json
+{"created_at":"2018-07-24T21:46:39.000Z","description":null,"id":"12345","manager":false,"name":"A8Demo WS1","owner":false,"queued_operation_count":0,"running_operation_count":0,"stopped_operation_count":0,"updated_at":"2018-07-24T21:46:39.000Z","saml_group":false,"saml_group_dn":null,"system_group":true,"system_group_type":"workspace_members"}
+```
+
+Remove the parameters that are either obviously added by the system: `id`, `created_at`, `updated_at` or optional.
+
+And then craft your command:
+
+```bash
+ascli aoc admin res group create @json:'{"description":"test to delete","name":"test 1 to delete","saml_group":false}'
+```
+
+If the command returns an error, example:
+
+```output
++----+-----------------------------------------------------------------------------------+
+| id | status                                                                            |
++----+-----------------------------------------------------------------------------------+
+|    | found unpermitted parameters: :manager, :owner, :system_group, :system_group_type |
+|    | code: unpermitted_parameters                                                      |
+|    | request_id: b0f45d5b-c00a-4711-acef-72b633f8a6ea                                  |
+|    | api.ibmaspera.com 422 Unprocessable Entity                                        |
++----+-----------------------------------------------------------------------------------+```
+
+Well, remove the offending parameters and try again.
+
+Note that some properties that are shown in the web UI, such as membership, are not listed directly in the resource, but instead another resource is created to link a user and its group: `group_membership`
+
 #### Access Key secrets
 
 In order to access some administrative actions on "nodes" (in fact, access keys), the associated secret is required.
@@ -3018,7 +3252,7 @@ ascli aoc admin res workspace_membership list --fields=member_type,manager,membe
 :.............:.........:..................................:
 ```
 
-other query parameters:
+Other query parameters:
 
 ```javascript
 {"workspace_membership_through":true,"include_indirect":true}
@@ -3085,6 +3319,44 @@ ascli aoc admin res user list --fields=email --query=@json:'{"q":"last_login_at:
 ascli aoc admin res user list --fields=email --select=@json:'{"member_of_any_workspace":false}'
 ```
 
+#### Example: create a group, add to workspace and add user to group
+
+* Create the group and take note of `id`
+
+```bash
+ascli aoc admin res group create @json:'{"name":"group 1","description":"my super group"}'
+```
+
+Group: `11111`
+
+* Get the workspace id
+
+```bash
+ascli aoc admin res workspace list --query=@json:'{"q":"myworkspace"}' --fields=id --format=csv --display=data
+```
+
+Workspace: 22222
+
+* Add group to workspace
+
+```bash
+ascli aoc admin res workspace_membership create @json:'{"workspace_id":22222,"member_type":"user","member_id":11111}'
+```
+
+* Get a user's id
+
+```bash
+ascli aoc admin res user list --query=@json:'{"q":"manu.macron@example.com"}' --fields=id --format=csv --display=data
+```
+
+User: 33333
+
+* Add user to group
+
+```bash
+ascli aoc admin res group_membership create @json:'{"group_id":11111,"member_type":"user","member_id":33333}'
+```
+
 #### Example: Perform a multi Gbps transfer between two remote shared folders
 
 In this example, a user has access to a workspace where two shared folders are located on different sites, e.g. different cloud regions.
@@ -3154,40 +3426,64 @@ ascli aoc admin res client list --fields=id --format=csv|ascli aoc admin res cli
 +-----+---------+
 ```
 
-#### Example: Create a node
+#### Example: Create a Node
 
 AoC nodes as actually composed with two related entities:
 
 * An access key created on the Transfer Server (HSTS/ATS)
 * a `node` resource in the AoC application.
 
-The web UI allows creation of both entities in one shot but not the CLI for more flexibility.
-Note that when selecting "Use existing access key" in the web UI, this actually skips access key creation.
+The web UI allows creation of both entities in one shot.
+For more flexibility, `ascli` allows this in two separate steps.
+Note that when selecting "Use existing access key" in the web UI, this actually skips access key creation (first step).
 
 So, for example, the creation of a node using ATS in IBM Cloud looks like (see other example in this manual):
 
-* create the access key on ATS
+* Create the access key on ATS
 
-```javascript
-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":"/"}}'
-```
+  The creation options are the ones of ATS API, refer to the [section on ATS](#ats_params) for more details and examples.
 
-Take a note of the randomly generated `id` and `secret`.
+  ```javascript
+  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":"/"}}'
+  ```
 
-* Retrieve the ATS node address
+  Once executed, the access key `id` and `secret`, randomly generated by the node api, is displayed: take note of it as the secrets will not be disclosed again.
 
-```bash
-ascli aoc admin ats cluster show --cloud=softlayer --region=eu-de --fields=transfer_setup_url --format=csv --transpose-single=no
-```
+* Create the AoC node entity
 
-* Create the node entity
+  First, Retrieve the ATS node address
 
-```javascript
-ascli aoc admin res node create @json:'{"name":"myname","access_key":"*accesskeyid*","ats_access_key":true,"ats_storage_type":"ibm-s3","url":"https://ats-sl-fra-all.aspera.io"}'
-```
+  ```bash
+  ascli aoc admin ats cluster show --cloud=softlayer --region=eu-de --fields=transfer_setup_url --format=csv --transpose-single=no
+  ```
+
+  Then use the returned address for the `url` key to actually create the AoC Node entity:
+
+  ```javascript
+  ascli aoc admin res node create @json:'{"name":"myname","access_key":"*accesskeyid*","ats_access_key":true,"ats_storage_type":"ibm-s3","url":"https://ats-sl-fra-all.aspera.io"}'
+  ```
 
 Creation of a node with a self-managed node is similar, but the command `aoc admin ats access_key create` is replaced with `node access_key create` on the private node itself.
 
+### List of files to transfer
+
+Source files are provided as a list with the `sources` option. Refer to section [File list](#file_list)
+
+Note the special case when the source files are located on "Aspera on Cloud" (i.e. using access keys and the `file id` API).
+
+Source files are located on "Aspera on cloud", when :
+
+* the server is Aspera on Cloud, and executing a download or recv
+* the agent is Aspera on Cloud, and executing an upload or send
+
+In this case:
+
+* If there is a single file : specify the full path
+* Else, if there are multiple files:
+  * All source files must be in the same source folder
+  * Specify the source folder as first item in the list
+  * followed by the list of file names.
+
 ### Packages
 
 The webmail-like application.
@@ -3255,6 +3551,31 @@ shbxid=$(ascli aoc packages shared_inboxes show name 'My Shared Inbox' --format=
 ascli aoc packages list --query=@json:'{"dropbox_id":"'$shbxid'","archived":false,"received":true,"has_content":true,"exclude_dropbox_packages":false,"include_draft":false,"sort":"-received_at"}'
 ```
 
+#### Example: Send a package with files from the Files app
+
+Find files in Files app:
+
+```bash
+ascli aoc files browse /src_folder
+```
+
+```bash
++------------------------------+--------+----------------+--------------+----------------------+--------------+
+| name                         | type   | recursive_size | size         | modified_time        | access_level |
++------------------------------+--------+----------------+--------------+----------------------+--------------+
+| sample_video                 | link   |                |              | 2020-11-29T22:49:09Z | edit         |
+| 100G                         | file   |                | 107374182400 | 2021-04-21T18:19:25Z | edit         |
+| 10M.dat                      | file   |                | 10485760     | 2021-05-18T08:22:39Z | edit         |
+| Test.pdf                     | file   |                | 1265103      | 2022-06-16T12:49:55Z | edit         |
++------------------------------+--------+----------------+--------------+----------------------+--------------+
+```
+
+Let's send a package with the file `10M.dat` from subfolder /src_folder in a package:
+
+```bash
+ascli aoc files node_info /src_folder --format=json --display=data | ascli aoc package send --value=@json:'{"name":"test","recipients":["laurent.martin.aspera@fr.ibm.com"]}' 10M.dat --transfer=node --transfer-info=@json:@stdin:
+```
+
 #### <a id="aoccargo"></a>Receive new packages only (Cargo)
 
 It is possible to automatically download new packages, like using Aspera Cargo:
@@ -3279,26 +3600,47 @@ Folder sharing app.
 
 #### Download Files
 
-Download of files is straightforward with a specific syntax for the `aoc files download` action: Like other commands the source file list is provided as  a list with the `sources` option. Nevertheless, consider this:
-
-* if only one source is provided, it is downloaded
-* if multiple sources must be downloaded, then the first in list is the path of the source folder, and the remaining items are the file names in this folder (without path).
+Download of files is straightforward using command: `aoc files download`
 
 #### Shared folders
 
-* list shared folders in node
+Shared folder by users are managed through **permissions**.
+For creation, parameters are the same as for node api [permissions](https://developer.ibm.com/apis/catalog/aspera--aspera-node-api/api/API--aspera--node-api#post960739960).
+`ascli` expects the same payload for creation, but it will automatically populated required tags if needed.
+Also, the pseudo key `with` is added: it will lookup the name in the contacts and fill the proper type and id.
+The pseudo parameter `link_name` allows changing default "shared as" name.
+
+* List permissions on a shared folder as user
+
+```bash
+ascli aoc files file --path=/shared_folder_test1 perm list
+```
+
+* Share a personal folder with other users
+
+```bash
+ascli aoc files file --path=/shared_folder_test1 perm create @json:'{"with":"laurent"}'
+```
+
+* Revoke shared access
+
+```bash
+ascli aoc files file --path=/shared_folder_test1 perm delete 6161
+```
+
+* List shared folders in node
 
 ```bash
 ascli aoc admin res node --id=8669 shared_folders
 ```
 
-* list shared folders in workspace
+* List shared folders in workspace
 
 ```bash
 ascli aoc admin res workspace --id=10818 shared_folders
 ```
 
-* list members of shared folder
+* List members of shared folder
 
 ```bash
 ascli aoc admin res node --id=8669 v4 perm 82 show
@@ -3373,6 +3715,99 @@ cat my_file_list.txt|while read path;do echo ascli aoc admin res node --name='my
 cat my_file_list.txt | ascli aoc admin res node --name='my node name' --secret='_secret_here_' v3 delete @lines:@stdin:
 ```
 
+### AoC sample commands
+
+```bash
+aoc -N remind --username=my_aoc_user_email
+aoc -N servers
+aoc admin analytics transfers --query=@json:'{"status":"completed","direction":"receive"}' --notif-to=my_recipient_email --notif-template=@ruby:'%Q{From: <%=from_name%> <<%=from_email%>>\nTo: <<%=to%>>\nSubject: <%=ev["files_completed"]%> files received\n\n<%=ev.to_yaml%>}'
+aoc admin ats access_key create --cloud=aws --region=my_aws_bucket_region --params=@json:'{"id":"ak_aws","name":"my test key AWS","storage":{"type":"aws_s3","bucket":"my_aws_bucket_name","credentials":{"access_key_id":"my_aws_bucket_key","secret_access_key":"my_aws_bucket_secret"},"path":"/"}}'
+aoc admin ats access_key create --cloud=softlayer --region=my_icos_bucket_region --params=@json:'{"id":"akibmcloud","secret":"somesecret","name":"my test key","storage":{"type":"ibm-s3","bucket":"my_icos_bucket_name","credentials":{"access_key_id":"my_icos_bucket_key","secret_access_key":"my_icos_bucket_secret"},"path":"/"}}'
+aoc admin ats access_key delete akibmcloud
+aoc admin ats access_key list --fields=name,id
+aoc admin ats access_key node akibmcloud --secret=somesecret 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 res application list
+aoc admin res client list
+aoc admin res client_access_key list
+aoc admin res client_registration_token create @json:'{"data":{"name":"test_client_reg1","client_subject_scopes":["alee","aejd"],"client_subject_enabled":true}}'
+aoc admin res client_registration_token delete my_clt_reg_id
+aoc admin res client_registration_token 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 workspace_membership list
+aoc admin resource node --name=my_aoc_ak_name --secret=my_aoc_ak_secret v3 access_key create --value=@json:'{"id":"testsub1","storage":{"path":"/folder1"}}'
+aoc admin resource node --name=my_aoc_ak_name --secret=my_aoc_ak_secret v3 events
+aoc admin resource node --name=my_aoc_ak_name --secret=my_aoc_ak_secret v4 browse /
+aoc admin resource node --name=my_aoc_ak_name --secret=my_aoc_ak_secret v4 delete /folder1
+aoc admin resource node --name=my_aoc_ak_name --secret=my_aoc_ak_secret v4 mkdir /folder1
+aoc admin resource node v3 name my_aoc_ak_name --secret=my_aoc_ak_secret access_key delete testsub1
+aoc admin resource workspace list
+aoc admin resource workspace_membership list --fields=ALL --query=@json:'{"page":1,"per_page":50,"embed":"member","inherited":false,"workspace_id":11363,"sort":"name"}'
+aoc automation workflow action my_wf_id create --value=@json:'{"name":"toto"}'
+aoc automation workflow create --value=@json:'{"name":"test_workflow"}'
+aoc automation workflow delete my_wf_id
+aoc automation workflow list
+aoc automation workflow list --select=@json:'{"name":"test_workflow"}' --fields=id --format=csv --display=data
+aoc automation workflow list --value=@json:'{"show_org_workflows":"true"}' --scope=admin:all
+aoc bearer_token --display=data --scope=user:all
+aoc faspex
+aoc files bearer /
+aoc files bearer_token_node / --cache-tokens=no
+aoc files browse /
+aoc files browse / -N --link=my_aoc_publink_folder
+aoc files delete /testsrc
+aoc files download --transfer=connect /200KB.1
+aoc files file permission --path=/ascli_test list
+aoc files file show --path=/200KB.1
+aoc files file show my_file_id
+aoc files find / --value='\.partial$'
+aoc files http_node_download --to-folder=. /200KB.1
+aoc files mkdir /testsrc
+aoc files rename /somefolder testdst
+aoc files short_link create --to-folder=/testdst --value=private
+aoc files short_link create --to-folder=/testdst --value=public
+aoc files short_link list --value=@json:'{"purpose":"shared_folder_auth_link"}'
+aoc files transfer --from-folder=/testsrc --to-folder=/testdst testfile.bin
+aoc files upload --to-folder=/testsrc testfile.bin
+aoc files upload -N --to-folder=/ testfile.bin --link=my_aoc_publink_folder
+aoc files upload Test.pdf --transfer=node --transfer-info=@json:@stdin:
+aoc files v3 info
+aoc org -N --link=my_aoc_publink_recv_from_aocuser
+aoc organization
+aoc packages browse "my_package_id" /contents
+aoc packages list
+aoc packages list --query=@json:'{"dropbox_name":"my_aoc_shbx_name","sort":"-received_at","archived":false,"received":true,"has_content":true,"exclude_dropbox_packages":false}'
+aoc packages recv "my_package_id" --to-folder=.
+aoc packages recv ALL --to-folder=. --once-only=yes --lock-port=12345
+aoc packages send --value=@json:'{"name":"Important files delivery","recipients":["my_email_external_user"]}' --new-user-option=@json:'{"package_contact":true}' testfile.bin
+aoc packages send --value=@json:'{"name":"Important files delivery","recipients":["my_email_internal_user"],"note":"my note"}' testfile.bin
+aoc packages send --workspace="my_aoc_shbx_ws" --value=@json:'{"name":"Important files delivery","recipients":["my_aoc_shbx_name"],"metadata":[{"input_type":"single-text","name":"Project Id","values":["123"]},{"input_type":"single-dropdown","name":"Type","values":["Opt2"]},{"input_type":"multiple-checkbox","name":"CheckThose","values":["Check1","Check2"]},{"input_type":"date","name":"Optional Date","values":["2021-01-13T15:02:00.000Z"]}]}' testfile.bin
+aoc packages send --workspace="my_aoc_shbx_ws" --value=@json:'{"name":"Important files delivery","recipients":["my_aoc_shbx_name"],"metadata":{"Project Id":"456","Type":"Opt2","CheckThose":["Check1","Check2"],"Optional Date":"2021-01-13T15:02:00.000Z"}}' testfile.bin
+aoc packages send --workspace="my_aoc_shbx_ws" --value=@json:'{"name":"Important files delivery","recipients":["my_aoc_shbx_name"]}' testfile.bin
+aoc packages send -N --value=@json:'{"name":"Important files delivery"}' testfile.bin --link=my_aoc_publink_send_aoc_user --password=my_aoc_publink_send_use_pass
+aoc packages send -N --value=@json:'{"name":"Important files delivery"}' testfile.bin --link=my_aoc_publink_send_shd_inbox
+aoc packages shared_inboxes list
+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: Aspera Transfer Service
 
 ATS is usable either :
@@ -3451,6 +3886,10 @@ 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
+
+When creating an ATS access key, the option `params` must contain an extended value with the creation parameters. Those asre directly the parameters expected by the [ATS API](https://developer.ibm.com/apis/catalog?search=%22Aspera%20ATS%20API%22).
+
 ### Misc. Examples
 
 Example: create access key on IBM Cloud (softlayer):
@@ -3487,27 +3926,82 @@ for k in $(ascli ats access_key list --field=id --format=csv);do ascli ats acces
 
 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
+
+```bash
+ats access_key cluster akibmcloud --secret=somesecret
+ats access_key create --cloud=aws --region=my_aws_bucket_region --params=@json:'{"id":"ak_aws","name":"my test key AWS","storage":{"type":"aws_s3","bucket":"my_aws_bucket_name","credentials":{"access_key_id":"my_aws_bucket_key","secret_access_key":"my_aws_bucket_secret"},"path":"/"}}'
+ats access_key create --cloud=softlayer --region=my_icos_bucket_region --params=@json:'{"id":"akibmcloud","secret":"somesecret","name":"my test key","storage":{"type":"ibm-s3","bucket":"my_icos_bucket_name","credentials":{"access_key_id":"my_icos_bucket_key","secret_access_key":"my_icos_bucket_secret"},"path":"/"}}'
+ats access_key delete ak_aws
+ats access_key delete akibmcloud
+ats access_key list --fields=name,id
+ats access_key node akibmcloud browse / --secret=somesecret
+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
+```
+
 ## Plugin: IBM Aspera High Speed Transfer Server (transfer)
 
 This plugin uses SSH as a session protocol (using commands `ascp` and `ascmd`) and does not use the node API.
 It is the legacy way of accessing an Aspera Server, often used for server to server transfers.
 Modern mode is to use the node API and transfer tokens.
 
-### Authentication
-
-Both password and SSH keys auth are supported.
+### Server sample commands
+
+```bash
+server -N -Ptst_server_bykey -Plocal_user br /
+server browse /
+server browse folder_1/target_hot
+server cp NEW_SERVER_FOLDER/testfile.bin folder_1/200KB.2
+server delete NEW_SERVER_FOLDER
+server delete folder_1/target_hot
+server delete folder_1/to.delete
+server df
+server download NEW_SERVER_FOLDER/testfile.bin --to-folder=. --transfer-info=@json:'{"wss":false,"resume":{"iter_max":1}}'
+server download NEW_SERVER_FOLDER/testfile.bin --to-folder=folder_1 --transfer=node
+server du /
+server health transfer --to-folder=folder_1 --format=nagios 
+server info
+server md5sum NEW_SERVER_FOLDER/testfile.bin
+server mkdir NEW_SERVER_FOLDER --logger=stdout
+server mkdir folder_1/target_hot
+server mv folder_1/200KB.2 folder_1/to.delete
+server upload --sources=@ts --ts=@json:'{"EX_ascp_args":["--file-list","'"filelist.txt"'"]}' --to-folder=NEW_SERVER_FOLDER 
+server upload --sources=@ts --ts=@json:'{"EX_ascp_args":["--file-pair-list","'"filepairlist.txt"'"]}'
+server upload --sources=@ts --ts=@json:'{"EX_file_list":"'"filelist.txt"'"}' --to-folder=NEW_SERVER_FOLDER
+server upload --sources=@ts --ts=@json:'{"EX_file_pair_list":"'"filepairlist.txt"'"}'
+server upload --sources=@ts --ts=@json:'{"paths":[{"source":"testfile.bin","destination":"NEW_SERVER_FOLDER/othername"}]}'
+server upload --src-type=pair --sources=@json:'["testfile.bin","NEW_SERVER_FOLDER/othername"]'
+server upload --src-type=pair testfile.bin NEW_SERVER_FOLDER/othername --notif-to=my_recipient_email
+server upload --src-type=pair testfile.bin folder_1/with_options --ts=@json:'{"cipher":"aes-192-gcm","content_protection":"encrypt","content_protection_password":"_secret_here_","cookie":"biscuit","create_dir":true,"delete_before_transfer":false,"delete_source":false,"exclude_newer_than":1,"exclude_older_than":10000,"fasp_port":33001,"http_fallback":false,"multi_session":0,"overwrite":"diff+older","precalculate_job_size":true,"preserve_access_time":true,"preserve_creation_time":true,"rate_policy":"fair","resume_policy":"sparse_csum","symlink_policy":"follow"}'
+server upload --to-folder=folder_1/target_hot --lock-port=12345 --ts=@json:'{"EX_ascp_args":["--remove-after-transfer","--remove-empty-directories","--exclude-newer-than=-8","--src-base","source_hot"]}' source_hot
+server upload testfile.bin --to-folder=NEW_SERVER_FOLDER --ts=@json:'{"multi_session":3,"multi_session_threshold":1,"resume_policy":"none","target_rate_kbps":1500}' --transfer-info=@json:'{"spawn_delay_sec":2.5}' --progress=multi
+```
+
+### Authentication on Server with SSH session
+
+If SSH is the session control protocol (i.e. not WSS), then following session authentication methods are supported:
+
+* SSH password
+* SSH keys (Multiple SSH key paths can be provided.)
 
 If username is not provided, the default transfer user `xfer` is used.
 
-If no SSH password or key is provided, and a token is provided in transfer spec, then standard bypass keys are used:
+If no SSH password or key is provided and a transfer token is provided in transfer spec (option `ts`), then standard SSH bypass keys are used. Example:
 
 ```javascript
 ascli server --url=ssh://... --ts=@json:'{"token":"Basic abc123"}'
 ```
 
-Multiple SSH key paths can be provided.
-The value of the parameter `ssh_keys` can be a single value or an array.
-Each value is a path to a private key and is expanded (`~` is replaced with the user's home folder).
+> Note: If you need to use the Aspera public keys, then specify an empty token: `--ts=@json:'{"token":""}'` : Aspera public SSH keys will be used, but the protocol will ignore the empty token.
+
+The value of the `ssh_keys` option can be a single value or an array.
+Each value is a **path** to a private key and is expanded (`~` is replaced with the user's home folder).
 
 Examples:
 
@@ -3517,8 +4011,10 @@ ascli server --ssh-keys=@list:,~/.ssh/id_rsa
 ascli server --ssh-keys=@json:'["~/.ssh/id_rsa"]'
 ```
 
-The underlying ssh library `net::ssh` provides several options that may be used depending on environment.
-By default the ssh library expect that an ssh-agent is running.
+For non-transfer related command (browse, delete), the ruby SSH client library `Net::SSH` is used and provides several options settable using option `ssh_options`.
+For a list of SSH client options, refer to the ruby documentation of [Net::SSH](http://net-ssh.github.io/net-ssh/Net/SSH.html).
+
+By default the SSH library expect that a local ssh-agent is running.
 
 On Linux, if you get an error message such as:
 
@@ -3532,12 +4028,12 @@ or on Windows:
 ERROR -- net.ssh.authentication.agent: could not connect to ssh-agent: pageant process not running
 ```
 
-This means that you don't have such an ssh agent running, then:
+This means that you don't have such an SSH agent running, then:
 
 * check env var: `SSH_AGENT_SOCK`
-* check if the ssh key is protected with a passphrase
+* check if the SSH key is protected with a passphrase (then, use the `passphrase` SSH option)
 * [check the manual](https://net-ssh.github.io/ssh/v1/chapter-2.html#s2)
-* To disable use of `ssh-agent`, use the option `ssh_option` like this:
+* To disable the use of `ssh-agent`, use the option `ssh_options` like this:
 
 ```bash
 ascli server --ssh-options=@ruby:'{use_agent: false}' ...
@@ -3652,7 +4148,7 @@ updated
 
 Scenario: Access to a "Shares on Demand" (SHOD) server on AWS is provided by a partner.
 We need to transfer files from this third party SHOD instance into our Azure BLOB storage.
-Simply create an "Aspera Transfer Service" instance (https://ts.asperasoft.com), which provides access to the node API.
+Simply create an "Aspera Transfer Service" instance, which provides access to the node API.
 Then create a configuration for the "SHOD" instance in the configuration file: in section "shares", a configuration named: awsshod.
 Create another configuration for the Azure ATS instance: in section "node", named azureats.
 Then execute the following command:
@@ -3669,6 +4165,47 @@ This will get transfer information from the SHOD instance and tell the Azure ATS
 ascli node access_key create --value=@json:'{"id":"eudemo-sedemo","secret":"mystrongsecret","storage":{"type":"local","path":"/data/asperafiles"}}'
 ```
 
+### Node sample commands
+
+```bash
+node -N -Ptst_node_preview access_key create --value=@json:'{"id":"aoc_1","storage":{"type":"local","path":"/"}}'
+node -N -Ptst_node_preview access_key delete aoc_1
+node access_key do my_aoc_ak_name br /
+node access_key list
+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 browse / -r
+node delete /todelete
+node delete @list:,/todelete,/tdlink,/delfile
+node delete folder_1/10MB.1
+node delete testfile.bin
+node download testfile.bin --to-folder=.
+node download testfile.bin --to-folder=. --token-type=hybrid
+node health
+node info --fpac='function FindProxyForURL(url,host){return "DIRECT"}'
+node license
+node mkdir /todelete
+node mkfile /delfile1 "hello world"
+node mklink /todelete /tdlink
+node rename / delfile1 delfile
+node search / --value=@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 transfer list --value=@json:'{"active_only":true}'
+node upload --to-folder="folder_1" --sources=@ts --ts=@json:'{"paths":[{"source":"/aspera-test-dir-small/10MB.1"}],"precalculate_job_size":true}' --transfer=node --transfer-info=@json:'{"url":"my_node_url","username":"my_node_user","password":"my_node_pass"}'
+node upload --username=my_aoc_ak_name --password=my_aoc_ak_secret testfile.bin --token-type=basic
+node upload testfile.bin --to-folder=folder_1 --ts=@json:'{"target_rate_cap_kbps":10000}'
+node upload testfile.bin --to-folder=folder_1 --ts=@json:'{"target_rate_cap_kbps":10000}' --token-type=hybrid
+```
+
 ## Plugin: IBM Aspera Faspex5
 
 This is currently in beta, limited operations are supported.
@@ -3689,47 +4226,47 @@ The API is listed in [Faspex 5 API Reference](https://developer.ibm.com/apis/cat
 
 This is the preferred method to use.
 
-For JWT, create an API client in Faspex with JWT support:
+For `jwt`, create an API client in Faspex with JWT support:
 
-* Identify a private key, if you don't have any refer to section [Private Key](#private_key)
+* Select a private key file: if you don't have any refer to section [Private Key](#private_key)
 * Navigate to the web UI: Admin &rarr; Configurations &rarr; API Clients &rarr; Create
 * Activate JWT
 * Paste public key in the appropriate section
 * Click on Create Button
-* Take note of Client Id and Secret
+* Take note of Client Id (and Client Secret, but not used in current version)
 
-Then use options:
+Then use these options:
 
 ```text
 --auth=jwt
 --client-id=xxx
 --client-secret=xxx
 --username=xxx
---password=xxx
---private-key=@file:../path/to/key.pem
+--private-key=@file:.../path/to/key.pem
 ```
 
 #### Faspex 5 using web browser
 
-For web method, create an API client in Faspex without JWT:
+For `web` method, create an API client in Faspex without JWT:
 
 * Navigate to the web UI: Admin &rarr; Configurations &rarr; API Clients &rarr; Create
 * Do not Activate JWT
-* enter https://127.0.0.1:8888 in the redirect URI
+* enter `https://127.0.0.1:8888` in the redirect URI
 * Click on Create Button
-* Take note of Client Id
+* Take note of Client Id (and Client Secret, but not used in current version)
 
 Then use options:
 
 ```text
 --auth=web
 --client-id=xxx
+--client-secret=xxx
 --redirect-uri=https://127.0.0.1:8888
 ```
 
 #### Faspex 5 using bootstrap
 
-For boot method: (will be removed in future)
+For `boot` method: (will be removed in future)
 
 * open a browser
 * start developer mode
@@ -3742,6 +4279,44 @@ Use it as password and use `--auth=boot`.
 ascli conf id f5boot update --url=https://localhost/aspera/faspex --auth=boot --password=ABC.DEF.GHI...
 ```
 
+### Faspex 5 sample commands
+
+```bash
+faspex5 admin res accounts list
+faspex5 admin res contacts list
+faspex5 admin res jobs list
+faspex5 admin res node list --value=@json:'{"type":"received","subtype":"mypackages"}'
+faspex5 admin res oauth_clients list
+faspex5 admin res registrations list
+faspex5 admin res saml_configs list
+faspex5 admin res shared_inboxes list
+faspex5 admin res workgroups list
+faspex5 health
+faspex5 package list --value=@json:'{"mailbox":"inbox","state":["released"]}'
+faspex5 package receive "my_package_id" --to-folder=.  --ts=@json:'{"content_protection_password":"abc123_yo"}'
+faspex5 package send --value=@json:'{"title":"test title","recipients":[{"name":"my_f5_user"}]}' testfile.bin --ts=@json:'{"content_protection_password":"_content_prot_here_"}'
+```
+
+### Faspex 5 other examples
+
+* List all shared inboxes
+
+```javascript
+ascli faspex5 admin res shared list --value=@json:'{"all":true}' --fields=id,name
+```
+
+* Create Metadata profile
+
+```javascript
+ascli faspex5 admin res metadata_profiles create --value=@json:'{"name":"the profile","default":false,"title":{"max_length":200,"illegal_chars":[]},"note":{"max_length":400,"illegal_chars":[],"enabled":false},"fields":[{"ordering":0,"name":"field1","type":"text_area","require":true,"illegal_chars":[],"max_length":100},{"ordering":1,"name":"fff2","type":"option_list","require":false,"choices":["opt1","opt2"]}]}'
+```
+
+* Create a Shared inbox with specific metadata profile
+
+```javascript
+ascli faspex5 admin res shared create --value=@json:'{"name":"the shared inbox","metadata_profile_id":1}'
+```
+
 ## Plugin: IBM Aspera Faspex (4.x)
 
 Notes:
@@ -3812,7 +4387,8 @@ if `id` is set to `ALL`, then all packages are downloaded, and if option `once_o
 
 ### Sending a Package
 
-The command is `faspex package send`. Package information (title, note, metadata, options) is provided in option `delivery_info`. (Refer to Faspex API).
+The command is `faspex package send`. Package information (title, note, metadata, options) is provided in option `delivery_info`.
+The contents of `delivery_info` is directly the contents of the `send` v3 [API of Faspex 4](https://developer.ibm.com/apis/catalog/aspera--aspera-faspex-client-sdk/API%20v.3:%20Send%20Packages), consult it for extended supported parameters.
 
 Example:
 
@@ -3888,10 +4464,90 @@ cargo client, or drive. Refer to the [same section](#aoccargo) in the Aspera on
 ascli faspex packages recv --id=ALL --once-only=yes --lock-port=12345
 ```
 
+### Faspex 4 sample commands
+
+```bash
+faspex address_book
+faspex dropbox list --recipient="*my_faspex_dbx"
+faspex dropbox list --recipient="*my_faspex_wkg"
+faspex health
+faspex login_methods
+faspex me
+faspex package list
+faspex package list --box=sent --fields=package_id --format=csv --display=data --query=@json:'{"max":1}'
+faspex package list --fields=package_id --format=csv --display=data --query=@json:'{"max":1}'
+faspex package list --recipient="*my_faspex_dbx" --format=csv --fields=package_id --query=@json:'{"max":1}'
+faspex package list --recipient="*my_faspex_wkg" --format=csv --fields=package_id --query=@json:'{"max":1}'
+faspex package recv "my_package_id" --to-folder=.
+faspex package recv "my_package_id" --to-folder=. --box=sent
+faspex package recv --to-folder=. --link="my_faspex_publink_recv_from_fxuser"
+faspex package recv ALL --to-folder=. --once-only=yes
+faspex package recv my_pkgid --recipient="*my_faspex_dbx" --to-folder=.
+faspex package recv my_pkgid --recipient="*my_faspex_wkg" --to-folder=.
+faspex package send --delivery-info=@json:'{"title":"Important files delivery","recipients":["*my_faspex_dbx"]}' testfile.bin
+faspex package send --delivery-info=@json:'{"title":"Important files delivery","recipients":["*my_faspex_wkg"]}' testfile.bin
+faspex package send --delivery-info=@json:'{"title":"Important files delivery","recipients":["my_email_internal_user","my_faspex_username"]}' testfile.bin
+faspex package send --link="my_faspex_publink_send_to_dropbox" --delivery-info=@json:'{"title":"Important files delivery"}' testfile.bin
+faspex package send --link="my_faspex_publink_send_to_fxuser" --delivery-info=@json:'{"title":"Important files delivery"}' testfile.bin
+faspex source list
+faspex source name "my_source_name" info
+faspex source name "my_source_name" node br /
+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
+```
+
 ## Plugin: IBM Aspera Shares
 
 Aspera Shares supports the "node API" for the file transfer part. (Shares 1 and 2)
 
+### Shares 1 sample commands
+
+```bash
+shares admin share list
+shares admin share user_permissions 9
+shares admin user app_authorizations 1
+shares admin user list
+shares admin user share_permissions 1
+shares repository browse /
+shares repository delete my_shares_upload/testfile.bin
+shares repository download --to-folder=. my_shares_upload/testfile.bin
+shares repository download --to-folder=. my_shares_upload/testfile.bin --transfer=httpgw --transfer-info=@json:'{"url":"https://my_http_gw_fqdn/aspera/http-gwy/v1"}'
+shares repository upload --to-folder=my_shares_upload testfile.bin
+shares repository upload --to-folder=my_shares_upload testfile.bin --transfer=httpgw --transfer-info=@json:'{"url":"https://my_http_gw_fqdn/aspera/http-gwy/v1"}'
+```
+
+## Plugin: Console
+
+### Console sample commands
+
+```bash
+console transfer current list 
+console transfer smart list 
+console transfer smart sub my_job_id @json:'{"source":{"paths":["my_file_name"]},"source_type":"user_selected"}'
+```
+
+## Plugin: Orchestrator
+
+### Orchestrator sample commands
+
+```bash
+orchestrator info
+orchestrator plugins
+orchestrator processes
+orchestrator workflow details my_orch_workflow_id
+orchestrator workflow export my_orch_workflow_id
+orchestrator workflow inputs my_orch_workflow_id
+orchestrator workflow list
+orchestrator workflow start my_orch_workflow_id --params=@json:'{"Param":"world !"}'
+orchestrator workflow start my_orch_workflow_id --params=@json:'{"Param":"world !"}' --result=ResultStep:Complete_status_message
+orchestrator workflow status ALL
+orchestrator workflow status my_orch_workflow_id
+```
+
 ## Plugin: IBM Cloud Object Storage
 
 The IBM Cloud Object Storage provides the possibility to execute transfers using FASP.
@@ -3905,7 +4561,7 @@ There are two possibilities to provide credentials. If you already have the endp
 If you have those parameters already, then following options shall be provided:
 
 * `bucket` bucket name
-* `endpoint` storage endpoint url, e.g. https://s3.hkg02.cloud-object-storage.appdomain.cloud
+* `endpoint` storage endpoint url, e.g. `https://s3.hkg02.cloud-object-storage.appdomain.cloud`
 * `apikey` API Key
 * `crn` resource instance id
 
@@ -3985,20 +4641,37 @@ 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.
 
+### COS sample commands
+
+```bash
+cos -N --bucket=my_icos_bucket_name --endpoint=my_icos_bucket_endpoint --apikey=my_icos_bucket_apikey --crn=my_icos_resource_instance_id node info
+cos -N --bucket=my_icos_bucket_name --region=my_icos_bucket_region --service-credentials=@json:@file:service_creds.json node info
+cos node access_key show self
+cos node download testfile.bin --to-folder=.
+cos node info
+cos node upload testfile.bin
+```
+
 ## Plugin: IBM Aspera Sync
 
 A basic plugin to start an "async" using `ascli`.
 The main advantage is the possibility to start from ma configuration file, using `ascli` standard options.
 
+### Sync sample commands
+
+```bash
+sync start --parameters=@json:'{"sessions":[{"name":"test","reset":true,"remote_dir":"/sync_test","local_dir":"contents","host":"my_remote_host","tcp_port":33001,"user":"my_remote_user","private_key_path":"my_local_user_key"}]}'
+```
+
 ## Plugin: Preview
 
-The `preview` generates "previews" of graphical files, i.e. thumbnails (office, images, video) and video previews on storage for use primarily in the Aspera on Cloud application.
-This is based on the "node API" of Aspera HSTS when using Access Keys only inside it's "storage root".
+The `preview` generates thumbnails (office, images, video) and video previews on storage for use primarily in the Aspera on Cloud application.
+It uses the **node API** of Aspera HSTS and requires use of Access Keys and it's **storage root**.
 Several parameters can be used to tune several aspects:
 
-* methods for detection of new files needing generation
-* methods for generation of video preview
-* parameters for video handling
+* Methods for detection of new files needing generation
+* Methods for generation of video preview
+* Parameters for video handling
 
 ### Aspera Server configuration
 
@@ -4237,13 +4910,48 @@ The mp4 video preview file is only for category `video`
 
 File type is primarily based on file extension detected by the node API and translated info a mime type returned by the node API.
 
-The tool can also locally detect the mime type using option `mimemagic`.
+### mimemagic
+
+By default, the Mime type used for conversion is the one returned by the node API, based on file name extension.
 
-To use it, set option `mimemagic` to `yes`: `--mimemagic=yes`
+It is also possible to detect the mime type using option `mimemagic`.
+To use it, set option `mimemagic` to `yes`: `--mimemagic=yes`.
 
-If not used, Mime type used for conversion is the one provided by the node API.
+This requires to manually install the mimemagic gem: `gem install mimemagic`.
 
-If used, the `preview` command will first analyze the file content using mimemagic, and if no match, will try by extension.
+In this case the `preview` command will first analyze the file content using mimemagic, and if no match, will try by extension.
+
+If the `mimemagic` gem complains about missing mime info file:
+
+* any OS:
+
+  * Examine the error message
+  * Download the file: <https://gitlab.freedesktop.org/xdg/shared-mime-info/-/raw/master/data/freedesktop.org.xml.in>
+  * move and rename this file to one of the locations expected by mimemagic as specified in the error message
+
+* Windows:
+
+  * Download the file: <https://gitlab.freedesktop.org/xdg/shared-mime-info/-/raw/master/data/freedesktop.org.xml.in>
+  * Place this file in the root of Ruby (or elsewhere): `C:\RubyVV-x64\freedesktop.org.xml.in`
+  * Set a global variable using `SystemPropertiesAdvanced.exe` or using `cmd` (replace `VV` with version) to the exact path of this file:
+
+  ```cmd
+  SETX FREEDESKTOP_MIME_TYPES_PATH C:\RubyVV-x64\freedesktop.org.xml.in
+  ```
+
+  * Close the `cmd` and restart a new one if needed to get refreshed env vars
+
+* Linux:
+
+```bash
+yum install shared-mime-info
+```
+
+* macOS:
+
+```bash
+brew install shared-mime-info
+```
 
 ### Access to original files and preview creation
 
@@ -4256,6 +4964,23 @@ are directly written to the storage.
 
 If the preview generator does not have access to files on the file system (it is remote, no mount, or is an object storage), then the original file is first downloaded, then the result is uploaded, use method `remote`.
 
+### Preview sample commands
+
+```bash
+preview check --skip-types=office
+preview folder 1 --skip-types=office --log-level=info --file-access=remote --ts=@json:'{"target_rate_kbps":1000000}'
+preview scan --skip-types=office --log-level=info
+preview test --case=test mp4 my_file_mxf --video-conversion=blend --log-level=debug
+preview test --case=test mp4 my_file_mxf --video-conversion=clips --log-level=debug
+preview test --case=test mp4 my_file_mxf --video-conversion=reencode --log-level=debug
+preview test --case=test png my_file_dcm --log-level=debug
+preview test --case=test png my_file_docx --log-level=debug
+preview test --case=test png my_file_mxf --video-png-conv=animated --log-level=debug
+preview test --case=test png my_file_mxf --video-png-conv=fixed --log-level=debug
+preview test --case=test png my_file_pdf --log-level=debug
+preview trevents --once-only=yes --skip-types=office --log-level=info
+```
+
 ## SMTP for email notifications
 
 Aspera CLI can send email, for that setup SMTP configuration. This is done with option `smtp`.
@@ -4273,7 +4998,7 @@ The `smtp` option is a hash table (extended value) with the following fields:
 <tr><td>`from_name`</td><td>same as email</td><td>John Wayne</td><td>display name of sender</td></tr>
 </table>
 
-### Example of configuration:
+### Example of configuration
 
 ```bash
 ascli config preset set smtp_google server smtp.google.com
@@ -4350,8 +5075,7 @@ Transfer is: <%=global_transfer_status%>
 
 ## Tool: `asession`
 
-This gem comes with a second executable tool providing a simplified standardized interface
-to start a FASP session: `asession`.
+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:
 
@@ -4365,7 +5089,7 @@ This makes it easy to integrate with any language provided that one can spawn a
 
 The tool expect one single argument: a [*transfer-spec*](#transferspec).
 
-If not 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 [*transfer-spec*](#transferspec) on stdin.
 
 Note that if JSON is the format, one has to specify `@json:` to tell the tool to decode the hash using JSON.
 
@@ -4382,18 +5106,24 @@ Note that in addition, many "EX_" [*transfer-spec*](#transferspec) parameters ar
 
 <table>
 <tr><th>feature/tool</th><th>asession</th><th>ascp</th><th>FaspManager</th><th>Transfer SDK</th></tr>
-<tr><td>language integration</td><td>any</td><td>any</td><td>C/C++<br/>C#/.net<br/>Go<br/>Python<br/>java<br/></td><td>any</td></tr>
-<tr><td>additional components to ascp</td><td>Ruby<br/>Aspera</td><td>-</td><td>library<br/>(headers)</td><td>daemon</td></tr>
+<tr><td>language integration</td><td>any</td><td>any</td><td>C/C++<br/>C#/.net<br/>Go<br/>Python<br/>java<br/></td><td>many</td></tr>
+<tr><td>required additional components to ascp</td><td>Ruby<br/>Aspera</td><td>-</td><td>library<br/>(headers)</td><td>daemon</td></tr>
 <tr><td>startup</td><td>JSON on stdin<br/>(standard APIs:<br/>JSON.generate<br/>Process.spawn)</td><td>command line arguments</td><td>API</td><td>daemon</td></tr>
 <tr><td>events</td><td>JSON on stdout</td><td>none by default<br/>or need to open management port<br/>and proprietary text syntax</td><td>callback</td><td>callback</td></tr>
-<tr><td>platforms</td><td>any with ruby and ascp</td><td>any with ascp</td><td>any with ascp</td><td>any with ascp and transferdaemon</td></tr></table>
+<tr><td>platforms</td><td>any with ruby and ascp</td><td>any with ascp (and SDK if compiled)</td><td>any with ascp</td><td>any with ascp and transfer daemon</td></tr></table>
 
 ### Simple session
 
-```javascript
-MY_TSPEC='{"remote_host":"demo.asperasoft.com","remote_user":"asperaweb","ssh_port":33001,"remote_password":"_pass_here_","direction":"receive","destination_root":"./test.dir","paths":[{"source":"/aspera-test-dir-tiny/200KB.1"}],"resume_level":"none"}'
+Create a file `session.json` with:
+
+```json
+{"remote_host":"demo.asperasoft.com","remote_user":"asperaweb","ssh_port":33001,"remote_password":"_pass_here_","direction":"receive","destination_root":"./test.dir","paths":[{"source":"/aspera-test-dir-tiny/200KB.1"}],"resume_level":"none"}
+````
 
-echo "${MY_TSPEC}"|asession
+Then start the session:
+
+```
+asession < session.json
 ```
 
 ### Asynchronous commands and Persistent session
@@ -4487,7 +5217,7 @@ Note: parameters may be saved in a [option preset](#lprt) and used with `-P`.
 
 #### Scheduling
 
-Once `ascli` parameters are defined, run the command using the OS native scheduler, e.g. every minutes, or 5 minutes, etc... Refer to section [_Scheduling_](#_scheduling_).
+Once `ascli` parameters are defined, run the command using the OS native scheduler, e.g. every minutes, or 5 minutes, etc... Refer to section [Scheduling](#scheduling).
 
 ### Example: upload folder
 
@@ -4570,6 +5300,10 @@ aoc.read('self')
 
 <https://github.com/IBM/aspera-cli/blob/main/examples/aoc.rb>
 
+## Changes (Release notes)
+
+See <CHANGELOG.md>
+
 ## History
 
 When I joined Aspera, there was only one CLI: `ascp`, which is the implementation of the FASP protocol, but there was no CLI to access the various existing products (Server, Faspex, Shares). Once, Serban (founder) provided a shell script able to create a Faspex Package using Faspex REST API. Since all products relate to file transfers using FASP (ascp), I thought it would be interesting to have a unified CLI for transfers using FASP. Also, because there was already the `ascp` tool, I thought of an extended tool : `eascp.pl` which was accepting all `ascp` options for transfer but was also able to transfer to Faspex and Shares (destination was a kind of URI for the applications).
@@ -4586,472 +5320,15 @@ So, it evolved into `ascli`:
 * 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)
 * `ruby` is consistent with other Aspera products
 
-## Changes (Release notes)
-
-* 4.7.0
-
-  * new: option to specify font used to generate image of text file in `preview`
-  * new: #66 improvement for content protection (support standard transfer spec options for direct agent)
-  * new: option `fpac` is now applicable to all ruby based HTTP connections, i.e. API calls
-  * new: option `show_secrets` to reveal secrets in command output
-  * new: added and updated commands for Faspex 5
-  * new: option `cache_tokens`
-  * new: Faspex4 dropbox packages can now be received by id
-  * change: (break) command `conf gem path` replaces `conf gem_path`
-  * change: (break) option `fpac` expects a value instead of URL
-  * change: (break) option `cipher` in transfer spec must have hyphen
-  * change: (break) renamed option `log_passwords` to `log_secrets`
-  * change: (break) removed plugin `shares2` as products is now EOL
-  * fix: After AoC version update, wizard did not detect AoC properly
-
-* 4.6.0
-
-  * new: command `conf plugin create`
-  * new: global option `plugin_folder`
-  * new: global option `transpose_single`
-  * new: simplified metadata passing for shared inbox package creation in AoC
-  * change: (break) command `aoc packages shared_inboxes list` replaces `aoc user shared_inboxes`
-  * change: (break) command `aoc user profile` replaces `aoc user info`
-  * change: (break) command `aoc user workspaces list` replaces `aoc user workspaces`
-  * change: (break) command `aoc user workspaces current` replaces `aoc workspace`
-  * change: (break) command `conf plugin list` replaces `conf plugins`
-  * change: (break) command `conf connect` simplified
-  * fix: #60 ascli executable was not installed by default in 4.5.0
-  * fix: add password hiding case in logs
-
-* 4.5.0
-
-  * new: support transfer agent: [Transfer SDK](#agt_trsdk)
-  * new: support [http socket options](#http_options)
-  * new: logs hide passwords and secrets, option `log_passwords` to enable logging secrets
-  * new: `config vault` supports encrypted passwords, also macos keychain
-  * new: `config preset` command for consistency with id
-  * new: identifier can be provided using either option `id` or directly after the command, e.g. `delete 123` is the same as `delete --id=123`
-  * change: when using wss, use [ruby's CA certs](#certificates)
-  * change: unexpected parameter makes exit code not zero
-  * change: (break) options `id` and `name` cannot be specified at the same time anymore, use [positional identifer or name selection](#res_select)
-  * change: (break) `aoc admin res node` does not take workspace main node as default node if no `id` specified.
-  * change: (break): `orchestrator workflow status` requires id, and supports special id `ALL`
-  * fix: various smaller fixes and renaming of some internal classes (transfer agents and few other)
-
-* 4.4.0
-
-  * new: `aoc packages list` add possibility to add filter with option `query`
-  * new: `aoc admin res xxx list` now get all items by default #50
-  * new: `preset` option can specify name or hash value
-  * new: `node` plugin accepts bearer token and access key as credential
-  * new: `node` option `token_type` allows using basic token in addition to aspera type.
-  * change: `server`: option `username` not mandatory anymore: xfer user is by default. If transfer spec token is provided, password or keys are optional, and bypass keys are used by default.
-  * change: (break) resource `apps_new` of `aoc` replaced with `application` (more clear)
-
-* 4.3.0
-
-  * new: parameter `multi_incr_udp` for option `transfer_info`: control if UDP port is incremented when multi-session is used on [`direct`](#agt_direct) transfer agent.
-  * new: command `aoc files node_info` to get node information for a given folder in the Files application of AoC. Allows cross-org or cross-workspace transfers.
-
-* 4.2.2
-
-  * new: `faspex package list` retrieves the whole list, not just first page
-  * new: support web based auth to aoc and faspex 5 using HTTPS, new dependency on gem `webrick`
-  * new: the error "Remote host is not who we expected" displays a special remediation message
-  * new: `conf ascp spec` displays supported transfer spec
-  * new: options `notif_to` and `notif_template` to send email notifications on transfer (and other events)
-  * fix: space character in `faspe:` url are precent encoded if needed
-  * fix: `preview scan`: if file_id is unknown, ignore and continue scan
-  * change: for commands that potentially execute several transfers (`package recv --id=ALL`), if one transfer fails then `ascli` exits with code 1 (instead of zero=success)
-  * change: (break) option `notify` or `aoc` replaced with `notif_to` and `notif_template`
-
-* 4.2.1
-
-  * new: command `faspex package recv` supports link of type: `faspe:`
-  * new: command `faspex package recv` supports option `recipient` to specify dropbox with leading `*`
-
-* 4.2.0
-
-  * new: command `aoc remind` to receive organization membership by email
-  * new: in `preview` option `value` to filter out on file name
-  * new: `initdemo` to initialize for demo server
-  * new: [`direct`](#agt_direct) transfer agent options: `spawn_timeout_sec` and `spawn_delay_sec`
-  * fix: on Windows `conf ascp use` expects ascp.exe
-  * fix: (break) multi_session_threshold is Integer, not String
-  * fix: `conf ascp install` renames sdk folder if it already exists (leftover shared lib may make fail)
-  * fix: removed replace_illegal_chars from default aspera.conf causing "Error creating illegal char conversion table"
-  * change: (break) `aoc apiinfo` is removed, use `aoc servers` to provide the list of cloud systems
-  * change: (break) parameters for resume in `transfer-info` for [`direct`](#agt_direct) are now in sub-key `"resume"`
-
-* 4.1.0
-
-  * fix: remove keys from transfer spec and command line when not needed 	* fix: default to create_dir:true so that sending single file to a folder does not rename file if folder does not exist
-  * new: update documentation with regard to offline and docker installation
-  * new: renamed command `nagios_check` to `health`
-  * new: agent `http_gw` now supports upload
-  * new: added option `sdk_url` to install SDK from local file for offline install
-  * new: check new gem version periodically
-  * new: the --fields= option, support -_fieldname_ to remove a field from default fields
-  * new: Oauth tokens are discarded automatically after 30 minutes (useful for COS delegated refresh tokens)
-  * new: mimemagic is now optional, needs manual install for `preview`, compatible with version 0.4.x
-  * new: AoC a password can be provided for a public link
-  * new: `conf doc` take an optional parameter to go to a section
-  * new: initial support for Faspex 5 Beta 1
-
-* 4.0.0
-
-  * now available as open source at [https://github.com/IBM/aspera-cli](https://github.com/IBM/aspera-cli) with general cleanup
-  * changed default tool name from `mlia` to `ascli`
-  * changed `aspera` command to `aoc`
-  * changed gem name from `asperalm` to `aspera-cli`
-  * changed module name from `Asperalm` to `Aspera`
-  * removed command `folder` in `preview`, merged to `scan`
-  * persistency files go to sub folder instead of main folder
-  * added possibility to install SDK: `config ascp install`
-
-* 0.11.8
-
-  * Simplified to use `unoconv` instead of bare `libreoffice` for office conversion, as `unoconv` does not require a X server (previously using Xvfb
-
-* 0.11.7
-
-  * rework on rest call error handling
-  * use option `display` with value `data` to remove out of extraneous information
-  * fixed option `lock_port` not working
-  * generate special icon if preview failed
-  * possibility to choose transfer progress bar type with option `progress`
-  * AoC package creation now output package id
-
-* 0.11.6
-
-  * orchestrator : added more choice in auth type
-  * preview: cleanup in generator (removed and renamed parameters)
-  * preview: better documentation
-  * preview: animated thumbnails for video (option: `video_png_conv=animated`)
-  * preview: new event trigger: `trevents` (`events` seems broken)
-  * preview: unique tmp folder to avoid clash of multiple instances
-  * repo: added template for secrets used for testing
-
-* 0.11.5
-
-  * added option `default_ports` for AoC (see manual)
-  * allow bulk delete in `aspera files` with option `bulk=yes`
-  * fix getting connect versions
-  * added section for Aix
-  * support all ciphers for [`direct`](#agt_direct) agent (including gcm, etc..)
-  * added transfer spec param `apply_local_docroot` for [`direct`](#agt_direct)
-
-* 0.11.4
-
-  * possibility to give shared inbox name when sending a package (else use id and type)
-
-* 0.11.3
-
-  * minor fixes on multi-session: avoid exception on progress bar
-
-* 0.11.2
-
-  * fixes on multi-session: progress bat and transfer spec param for "direct"
-
-* 0.11.1
-
-  * enhanced short_link creation commands (see examples)
-
-* 0.11
-
-  * add transfer spec option (agent `direct` only) to provide file list directly to ascp: `EX_file_list`.
-
-* 0.10.18
-
-  * new option in. `server` : `ssh_options`
-
-* 0.10.17
-
-  * fixed problem on `server` for option `ssh_keys`, now accepts both single value and list.
-  * new modifier: `@list:<separator>val1<separator>...`
-
-* 0.10.16
-
-  * added list of shared inboxes in workspace (or global), use `--query=@json:'{}'`
-
-* 0.10.15
-
-  * in case of command line error, display the error cause first, and non-parsed argument second
-  * AoC : Activity / Analytics
-
-* 0.10.14
-
-  * added missing bss plugin
-
-* 0.10.13
-
-  * added Faspex5 (use option `value` to give API arguments)
-
-* 0.10.12
-
-  * added support for AoC node registration keys
-  * replaced option : `local_resume` with `transfer_info` for agent [`direct`](#agt_direct)
-  * Transfer agent is no more a Singleton instance, but only one is used in CLI
-  * `@incps` : new extended value modifier
-  * ATS: no more provides access keys secrets: now user must provide it
-  * begin work on "aoc" transfer agent
-
-* 0.10.11
-
-  * minor refactor and fixes
-
-* 0.10.10
-
-  * fix on documentation
-
-* 0.10.9.1
-
-  * add total number of items for AoC resource list
-  * better gem version dependency (and fixes to support Ruby 2.0.0)
-  * removed aoc search_nodes
-
-* 0.10.8
-
-  * removed option: `fasp_proxy`, use pseudo transfer spec parameter: `EX_fasp_proxy_url`
-  * removed option: `http_proxy`, use pseudo transfer spec parameter: `EX_http_proxy_url`
-  * several other changes..
-
-* 0.10.7
-
-  * fix: ascli fails when username cannot be computed on Linux.
-
-* 0.10.6
-
-  * FaspManager: transfer spec `authentication` no more needed for local transfer to use Aspera public keys. public keys will be used if there is a token and no key or password is provided.
-  * gem version requirements made more open
-
-* 0.10.5
-
-  * fix faspex package receive command not working
-
-* 0.10.4
-
- 	* new options for AoC : `secrets`
- 	* ACLI-533 temp file list folder to use file lists is set by default, and used by asession
-
-* 0.10.3
-
-  * included user name in oauth bearer token cache for AoC when JWT is used.
-
-* 0.10.2
-
-  * updated `search_nodes` to be more generic, so it can search not only on access key, but also other queries.
-  * added doc for "cargo" like actions
-  * added doc for multi-session
-
-* 0.10.1
-
-  * AoC and node v4 "browse" works now on non-folder items: file, link
-  * initial support for AoC automation (do not use yet)
-
-* 0.10
-
-  * support for transfer using IBM Cloud Object Storage
-  * improved `find` action using arbitrary expressions
-
-* 0.9.36
-
-  * added option to specify file pair lists
-
-* 0.9.35
-
-  * updated plugin `preview` , changed parameter names, added documentation
-  * fix in `ats` plugin : instance id needed in request header
-
-* 0.9.34
-
-  * parser "@preset" can be used again in option "transfer_info"
-  * some documentation re-organizing
-
-* 0.9.33
-
-  * new command to display basic token of node
-  * new command to display bearer token of node in AoC
-  * the --fields= option, support +_fieldname_ to add a field to default fields
-  * many small changes
-
-* 0.9.32
-
-  * all Faspex public links are now supported
-  * removed faspex operation recv_publink
-  * replaced with option `link` (consistent with AoC)
-
-* 0.9.31
-
-  * added more support for public link: receive and send package, to user or dropbox and files view.
-  * delete expired file lists
-  * changed text table gem from text-table to terminal-table because it supports multiline values
-
-* 0.9.27
-
-  * basic email support with SMTP
-  * basic proxy auto config support
-
-* 0.9.26
-
-  * table display with --fields=ALL now includes all column names from all lines, not only first one
-  * unprocessed argument shows error even if there is an error beforehand
-
-* 0.9.25
-
-  * the option `value` of command `find`, to filter on name, is not optional
-  * `find` now also reports all types (file, folder, link)
-  * `find` now is able to report all fields (type, size, etc...)
-
-* 0.9.24
-
-  * fix bug where AoC node to node transfer did not work
-  * fix bug on error if ED25519 private key is defined in .ssh
-
-* 0.9.23
-
-  * defined REST error handlers, more error conditions detected
-  * commands to select specific ascp location
-
-* 0.9.21
-
-  * supports simplified wizard using global client
-  * only ascp binary is required, other SDK (keys) files are now generated
-
-* 0.9.20
-
-  * improved wizard (prepare for AoC global client id)
-  * preview generator: addedoption : --skip-format=&lt;png,mp4&gt;
-  * removed outdated pictures from this doc
-
-* 0.9.19
-
-  * added command aspera bearer --scope=xx
-
-* 0.9.18
-
-  * enhanced aspera admin events to support query
-
-* 0.9.16
-
-  * AoC transfers are now reported in activity app
-  * new interface for Rest class authentication (keep backward compatibility)
-
-* 0.9.15
-
-  * new feature: "find" command in aspera files
-  * sample code for transfer API
-
-* 0.9.12
-
-  * add nagios commands
-  * support of ATS for IBM Cloud, removed old version based on aspera id
-
-* 0.9.11
-
-  * Breaking change: @stdin is now @stdin:
-  * support of ATS for IBM Cloud, removed old version based on aspera id
-
-
-* 0.9.10
-
-  * Breaking change: parameter transfer-node becomes more generic: transfer-info
-  * Display SaaS storage usage with command: aspera admin res node --id=nn info
-  * cleaner way of specifying source file list for transfers
-  * Breaking change: replaced download_mode option with http_download action
-
-* 0.9.9
-
-  * Breaking change: "aspera package send" parameter deprecated, use the --value option instead with "recipients" value. See example.
-  * Now supports "cargo" for Aspera on Cloud (automatic package download)
-
-* 0.9.8
-
-  * Faspex: use option once_only set to yes to enable cargo like function. id=NEW deprecated.
-  * AoC: share to share transfer with command "transfer"
-
-* 0.9.7
-
-  * homogeneous [*transfer-spec*](#transferspec) for `node` and [`direct`](#agt_direct) transfer agents
-  * preview persistency goes to unique file by default
-  * catch mxf extension in preview as video
-  * Faspex: possibility to download all packages by specifying id=ALL
-  * Faspex: to come: cargo-like function to download only new packages with id=NEW
-
-* 0.9.6
-
-  * Breaking change: `@param:`is now `@preset:` and is generic
-  * AoC: added command to display current workspace information
-
-* 0.9.5
-
-  * new parameter: new_user_option used to choose between public_link and invite of external users.
-  * fixed bug in wizard, and wizard uses now product detection
-
-* 0.9.4
-
-  * Breaking change: onCloud file list follow --source convention as well (plus specific case for download when first path is source folder, and other are source file names).
-  * AoC Package send supports external users
-  * new command to export AoC config to Aspera CLI config
-
-* 0.9.3
-
-  * REST error message show host and code
-  * option for quiet display
-  * modified transfer interface and allow token re-generation on error
-  * async add admin command
-  * async add db parameters
-  * Breaking change: new option "sources" to specify files to transfer
-
-* 0.9.2
-
-  * Breaking change: changed AoC package creation to match API, see AoC section
-
-* 0.9.1
-
-  * Breaking change: changed faspex package creation to match API, see Faspex section
-
-* 0.9
-
-  * Renamed the CLI from aslmcli to `ascli`
-  * Automatic rename and conversion of former config folder from aslmcli to `ascli`
-
-* 0.7.6
-
-  * add "sync" plugin
-
-* 0.7
-
-  * Breaking change: AoC package recv take option if for package instead of argument.
-  * Breaking change: Rest class and Oauth class changed init parameters
-  * AoC: receive package from public link
-  * select by col value on output
-  * added rename (AoC, node)
-
-* 0.6.19
-
-  * change: (break) ats server list provisioned &rarr; ats cluster list
-  * change: (break) ats server list clouds &rarr; ats cluster clouds
-  * change: (break) ats server list instance --cloud=x --region=y &rarr; ats cluster show --cloud=x --region=y
-  * change: (break) ats server id xxx &rarr; ats cluster show --id=xxx
-  * change: (break) ats subscriptions &rarr; ats credential subscriptions
-  * change: (break) ats api_key repository list &rarr; ats credential cache list
-  * change: (break) ats api_key list &rarr; ats credential list
-  * change: (break) ats access_key id xxx &rarr; ats access_key --id=xxx
-
-* 0.6.18
-
-  * some commands take now --id option instead of id command.
-
-* 0.6.15
-
-  * Breaking change: "files" application renamed to "aspera" (for "Aspera on Cloud"). "repository" renamed to "files". Default is automatically reset, e.g. in config files and change key "files" to "aspera" in [option preset](#lprt) "default".
-
 ## Common problems
 
-### Error "Remote host is not who we expected"
+### Error: "Remote host is not who we expected"
 
 Cause: `ascp` >= 4.x checks fingerprint of highest server host key, including ECDSA. `ascp` < 4.0 (3.9.6 and earlier) support only to RSA level (and ignore ECDSA presented by server). `aspera.conf` supports a single fingerprint.
 
 Workaround on client side: To ignore the certificate (SSH fingerprint) add option on client side (this option can also be added permanently to the config file):
 
-```json
+```javascript
 --ts=@json:'{"sshfp":null}'
 ```
 
@@ -5059,6 +5336,13 @@ Workaround on server side: Either remove the fingerprint from `aspera.conf`, or
 
 References: ES-1944 in release notes of 4.1 and to [HSTS admin manual section "Configuring Transfer Server Authentication With a Host-Key Fingerprint"](https://www.ibm.com/docs/en/ahts/4.2?topic=upgrades-configuring-ssh-server).
 
+### Error "can't find header files for ruby"
+
+Some Ruby gems dependencies require compilation of native parts (C).
+This also requires Ruby header files.
+If Ruby was installed as a Linux Packages, then also install ruby dev elopment package:
+`ruby-dev` ir `ruby-devel`, depending on distribution.
+
 ### ED255519 key not supported
 
 ED25519 keys are deactivated since version 0.9.24 so this type of key will just be ignored.
@@ -5071,19 +5355,3 @@ OpenSSH keys only supported if ED25519 is available
 
 Which meant that you do not have ruby support for ED25519 SSH keys.
 You may either install the suggested Gems, or remove your ed25519 key from your `.ssh` folder to solve the issue.
-
-## BUGS, FEATURES, CONTRIBUTION
-
-For issues reports or feature requests use the Github repository and issues.
-
-You can also contribute to this open source project.
-
-One can also [create one's own plugin](#createownplugin).
-
-## Miscellaneous
-
-* replace rest and oauth classes with ruby standard gems:
-  * <https://github.com/rest-client/rest-client>
-  * <https://github.com/oauth-xx/oauth2>
-* use gem Thor <http://whatisthor.com/> (or other standard Ruby CLI manager)
-* Package with <https://github.com/pmq20/ruby-packer> (rubyc)