aspera-cli 4.4.0 → 4.5.0

data/README.md

@@ -1,7 +1,7 @@
 [comment1]: # (Do not edit this README.md, edit docs/README.erb.md, for details, read docs/README.md)
 <font size="+12"><center>`ascli` : Command Line Interface for IBM Aspera products</center></font>
 
-Version : 4.4.0
+Version : 4.5.0
 
 _Laurent/2016-2021_
 
@@ -15,7 +15,9 @@ Ruby Doc: [https://www.rubydoc.info/gems/aspera-cli](https://www.rubydoc.info/ge
 
 Required Ruby version: > 2.4
 
-# <a name="when_to_use"></a>When to use and when not to use
+[Aspera APIs](https://developer.ibm.com/?size=30&q=aspera&DWContentType[0]=APIs)
+
+# <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:
 
@@ -38,21 +40,18 @@ One might be tempted to use it as an integration element, e.g. by building a com
 For such integration cases, e.g. performing operations and transfer to aspera products, it is preferred to use [Aspera APIs](https://ibm.biz/aspera_api):
 
 * Product APIs (REST) : e.g. AoC, Faspex, node
-* Transfer SDK : with gRPC interface and laguage stubs (C, C++, Python, .NET/C#, java, ruby, etc...)
+* Transfer SDK : with gRPC interface and language stubs (C, C++, Python, .NET/C#, java, ruby, etc...)
 
 Using APIs (application REST API and transfer SDK) will prove to be easier to develop and maintain.
 
 For scripting and ad'hoc command line operations, `ascli` is perfect.
 
-# Notations
+# <a id="parsing"></a>Notations, Shell and Command line parsing
 
-In examples, command line operations (starting with `$`) are shown using a standard shell: `bash` or `zsh`.
-Prompt `# ` refers to user `root`, prompt `xfer$ ` refer to user `xfer`.
+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.
 
-# <a name="parsing"></a>Shell and Command line parsing
-
 `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.
@@ -65,12 +64,15 @@ On Windows, `cmd.exe` is typically used. Windows process creation does not recei
 In case of doubt of argument values after parsing test like this:
 
 ```
-$ ascli conf echo "Hello World" arg2 3
+ascli conf echo "Hello World" arg2 3
+```
+
+```
 "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.
+`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
 
@@ -81,8 +83,11 @@ First, follow the section: [Installation](#installation) (Ruby, Gem, FASP) to st
 Once the gem is installed, `ascli` shall be accessible:
 
 ```
-$ ascli --version
-4.4.0
+ascli --version
+```
+
+```
+4.5.0
 ```
 
 ## First use
@@ -94,8 +99,14 @@ If you want to test with Aspera on Cloud, jump to section: [Wizard](#aocwizard)
 To test with Aspera demo transfer server, setup the environment and then test:
 
 ```
-$ ascli config initdemo
-$ ascli server browse /
+ascli config initdemo
+```
+
+```
+ascli server browse /
+```
+
+```
 :............:...........:......:........:...........................:.......................:
 :   zmode    :   zuid    : zgid :  size  :           mtime           :         name          :
 :............:...........:......:........:...........................:.......................:
@@ -114,11 +125,26 @@ If you want to use `ascli` with another server, and in order to make further cal
 * download a file
 
 ```
-$ ascli config id myserver update --url=ssh://demo.asperasoft.com:33001 --username=asperaweb --password=_demo_pass_
+ascli config preset update myserver --url=ssh://demo.asperasoft.com:33001 --username=asperaweb --password=_demo_pass_
+```
+
+```
 updated: myserver
-$ ascli config id default set server myserver
+```
+
+```
+ascli config preset set default server myserver
+```
+
+```
 updated: default&rarr;server to myserver
-$ ascli server browse /aspera-test-dir-large
+```
+
+```
+ascli server browse /aspera-test-dir-large
+```
+
+```
 :............:...........:......:..............:...........................:............................:
 :   zmode    :   zuid    : zgid :     size     :           mtime           :            name            :
 :............:...........:......:..............:...........................:............................:
@@ -135,7 +161,13 @@ $ ascli server browse /aspera-test-dir-large
 : -rw-r--r-- : asperaweb : fasp : 104857600    : 2014-04-10 19:49:29 +0200 : 100MB                      :
 : -rw-r--r-- : asperaweb : fasp : 10737418240  : 2014-04-10 19:49:04 +0200 : 10GB                       :
 :............:...........:......:..............:...........................:............................:
-$ ascli server download /aspera-test-dir-large/200MB
+```
+
+```
+ascli server download /aspera-test-dir-large/200MB
+```
+
+```
 Time: 00:00:02 ========================================================================================================== 100% 100 Mbps Time: 00:00:00
 complete
 ```
@@ -146,9 +178,9 @@ Get familiar with configuration, options, commands : [Command Line Interface](#c
 
 Then, follow the section relative to the product you want to interact with ( Aspera on Cloud, Faspex, ...) : [Application Plugins](plugins)
 
-# <a name="installation"></a>Installation
+# <a id="installation"></a>Installation
 
-It is possible to install *either* directly on the host operating system (Linux, Windows, Macos) or as a docker container.
+It is possible to install *either* directly on the host operating system (Linux, Windows, macOS) or as a docker container.
 
 The direct installation is recommended and consists in installing:
 
@@ -158,33 +190,36 @@ The direct installation is recommended and consists in installing:
 
 The following sections provide information on the various installation methods.
 
-An internet connection is required for the installation. If you dont have internet for the installation, refer to section [Installation without internet access](#offline_install).
+An internet connection is required for the installation. If you don't have internet for the installation, refer to section [Installation without internet access](#offline_install).
 
 ## Docker container
 
 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)
 
 Ensure that you have Docker installed.
 
 ```
-$ docker --version
+docker --version
 ```
 
 Download the wrapping script:
 
 ```
-$ curl -o ascli https://raw.githubusercontent.com/IBM/aspera-cli/develop/bin/dascli
-$ chmod a+x ascli
+curl -o ascli https://raw.githubusercontent.com/IBM/aspera-cli/develop/bin/dascli
+```
+
+```
+chmod a+x ascli
 ```
 
 Install the container image:
 
 ```
-$ ./ascli install
+./ascli install
 ```
 
 Start using it !
@@ -194,9 +229,9 @@ Note that the tool is run in the container, so transfers are also executed in th
 The wrapping script maps the container folder `/usr/src/app/config` to configuration folder `$HOME/.aspera/ascli` on host.
 
 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.
 
-## <a name="ruby"></a>Ruby
+## <a id="ruby"></a>Ruby
 
 Use this method to install on the native host.
 
@@ -208,7 +243,7 @@ Required Ruby version: > 2.4. Ruby version 3 is also supported.
 
 Refer to the following sections for a proposed method for specific operating systems.
 
-The recommended installation method is `rvm` for systems with "bash-like" shell (Linux, Macos, Windows with cygwin, etc...).
+The recommended installation method is `rvm` for systems with "bash-like" shell (Linux, macOS, Windows with cygwin, etc...).
 If the generic install is not suitable (e.g. Windows, no cygwin), you can use one of OS-specific install method.
 If you have a simpler better way to install Ruby version > 2.4 : use it !
 
@@ -221,31 +256,31 @@ Install "rvm": follow [https://rvm.io/](https://rvm.io/) :
 Install the 2 keys
 
 ```
-$ gpg2 --keyserver hkp://pool.sks-keyservers.net --recv-keys 409B6B1796C275462A1703113804BB82D39DC0E3 7D2BAF1CF37B13E2069D6956105BD0E739499BDB
+gpg2 --keyserver hkp://pool.sks-keyservers.net --recv-keys 409B6B1796C275462A1703113804BB82D39DC0E3 7D2BAF1CF37B13E2069D6956105BD0E739499BDB
 ```
 
 Execute the shell/curl command. As regular user, it install in the user's home: `~/.rvm` .
 
 ```
-$ \curl -sSL https://get.rvm.io | bash -s stable
+\curl -sSL https://get.rvm.io | bash -s stable
 ```
 
-If you keep the same terminal (ont needed if re-login):
+If you keep the same terminal (not needed if re-login):
 
 ```
-$ source ~/.rvm/scripts/rvm
+source ~/.rvm/scripts/rvm
 ```
 
 It is advised to get one of the pre-compiled ruby version, you can list with:
 
 ```
-$ rvm list --remote
+rvm list --remote
 ```
 
 Install the chosen pre-compiled Ruby version:
 
 ```
-$ rvm install 2.7.2 --binary
+rvm install 2.7.2 --binary
 ```
 
 Ruby is now installed for the user, go on to Gem installation.
@@ -258,7 +293,7 @@ As root, it installs by default in /usr/local/rvm for all users and creates `/et
 One can install in another location with :
 
 ```
-# curl -sSL https://get.rvm.io | bash -s -- --path /usr/local
+curl -sSL https://get.rvm.io | bash -s -- --path /usr/local
 ```
 
 As root, make sure this will not collide with other application using Ruby (e.g. Faspex).
@@ -266,8 +301,11 @@ If so, one can rename the login script: `mv /etc/profile.d/rvm.sh /etc/profile.d
 To activate ruby (and ascli) later, source it:
 
 ```
-# source /etc/profile.d/rvm.sh.ok
-# rvm version
+source /etc/profile.d/rvm.sh.ok
+```
+
+```
+rvm version
 ```
 
 ### Windows: Installer
@@ -280,16 +318,16 @@ Install Latest stable Ruby using [https://rubyinstaller.org/](https://rubyinstal
 
 ### macOS: pre-installed or `brew`
 
-MacOS 10.13+ (High Sierra) comes with a recent Ruby. So you can use it directly. You will need to install aspera-cli using `sudo` :
+macOS 10.13+ (High Sierra) comes with a recent Ruby. So you can use it directly. You will need to install aspera-cli using `sudo` :
 
 ```
-$ sudo gem install aspera-cli
+sudo gem install aspera-cli
 ```
 
 Alternatively, if you use [Homebrew](https://brew.sh/) already you can install Ruby with it:
 
 ```
-$ brew install ruby
+brew install ruby
 ```
 
 ### Linux: package
@@ -299,90 +337,56 @@ If your Linux distribution provides a standard ruby package, you can use it prov
 Example:
 
 ```
-# yum install -y ruby rubygems ruby-json
+yum install -y ruby rubygems ruby-json
 ```
 
 One can cleanup the whole yum-installed ruby environment like this to uninstall:
 
 ```
 gem uninstall $(ls $(gem env gemdir)/gems/|sed -e 's/-[^-]*$//'|sort -u)
+```
+
+```
 yum remove -y ruby ruby-libs
 ```
 
 ### Other Unixes: Aix, etc...
 
-If your unix do not provide a pre-built ruby, you can get it using one of those
+If your Unix does not provide a pre-built ruby, you can get it using one of those
 [methods](https://www.ruby-lang.org/en/documentation/installation/)
 
 For instance to build from source, and install in `/opt/ruby` :
 
 ```
-# wget https://cache.ruby-lang.org/pub/ruby/2.7/ruby-2.7.2.tar.gz
-# gzip -d ruby-2.7.2.tar.gz
-# tar xvf ruby-2.7.2.tar
-# cd ruby-2.7.2
-# ./configure --prefix=/opt/ruby
-# make ruby.imp
-# make
-# make install
-```
-
-### <a name="offline_install"></a>Installation without internet access
-
-Note that currently no pre-packaged version exist yet.
-A method to build one provided here:
-
-On a server with the same OS version and with internet access follow the "Generic single user installation" method.
-
-Then create an archive:
-
-```
-$ cd
-$ tar zcvf rvm-ascli.tgz .rvm
-```
-
-Get the Aspera SDK. Execute:
-
-```
-$ ascli conf --show-config|grep sdk_url
-```
-
-Then download the SDK archive from that URL.
+wget https://cache.ruby-lang.org/pub/ruby/2.7/ruby-2.7.2.tar.gz
 
-Another method for the SDK is to install the SDK (`ascli conf ascp install`) on the first system, and archive `$HOME/.aspera`.
+gzip -d ruby-2.7.2.tar.gz
 
-Transfer those 2 archives to the target system without internet access.
+tar xvf ruby-2.7.2.tar
 
-On the target system:
+cd ruby-2.7.2
 
-* Extract the RVM archive either in a global location, or in a user's home folder : `path_to_rvm_root`
-* in the user's `.profile` add this line: (replace `path_to_rvm_root` with the actual location)
+./configure --prefix=/opt/ruby
 
-```
-source path_to_rvm_root/scripts/rvm
-rvm use 2.7.2
-```
+make ruby.imp
 
-For the SDK, either install from archive:
+make
 
+make install
 ```
-$ ascli conf ascp install --sdk-url=file:///SDK.zip
-```
-
-or restore the `$HOME/.aspera` folder for the user.
 
-## <a name="the_gem"></a>`aspera-cli` gem
+## <a id="the_gem"></a>`aspera-cli` gem
 
 Once you have Ruby and rights to install gems: Install the gem and its dependencies:
 
 ```
-# gem install aspera-cli
+gem install aspera-cli
 ```
 
 To upgrade to the latest version:
 
 ```
-# gem update aspera-cli
+gem update aspera-cli
 ```
 
 `ascli` checks every week if a new version is available and notify the user in a WARN log. To de-activate this feature set the option `version_check_days` to `0`, or specify a different period in days.
@@ -390,12 +394,10 @@ To upgrade to the latest version:
 To check manually:
 
 ```
-# ascli conf check_update
+ascli conf check_update
 ```
 
-
-
-## <a name="fasp_prot"></a>FASP Protocol
+## <a id="fasp_prot"></a>FASP Protocol
 
 Most file transfers will be done using the FASP protocol, using `ascp`.
 Only two additional files are required to perform an Aspera Transfer, which are part of Aspera SDK:
@@ -403,17 +405,20 @@ Only two additional files are required to perform an Aspera Transfer, which are
 * ascp
 * aspera-license (in same folder, or ../etc)
 
-This can be installed either be installing an Aspera transfer sofware, or using an embedded command:
+This can be installed either be installing an Aspera transfer software, or using an embedded command:
 
 ```
-$ ascli conf ascp install
+ascli conf ascp install
 ```
 
-If a local SDK installation is prefered instead of fetching from internet: one can specify the location of the SDK file:
+If a local SDK installation is preferred instead of fetching from internet: one can specify the location of the SDK file:
 
 ```
-$ curl -Lso SDK.zip https://ibm.biz/aspera_sdk
-$ ascli conf ascp install --sdk-url=file:///SDK.zip
+curl -Lso SDK.zip https://ibm.biz/aspera_sdk
+```
+
+```
+ascli conf ascp install --sdk-url=file:///SDK.zip
 ```
 
 The format is: `file:///<path>`, where `<path>` can be either a relative path (not starting with `/`), or an absolute path.
@@ -433,36 +438,55 @@ by visiting the page: [https://www.ibm.com/aspera/connect/](https://www.ibm.com/
 Refer to section [FASP](#client) for details on how to select a client or set path to the FASP protocol.
 
 Several methods are provided to start a transfer.
-Use of a local client ([`direct`](#direct) transfer agent) is one of them, but other methods are available. Refer to section: [Transfer Agents](#agents)
+Use of a local client ([`direct`](#agt_direct) transfer agent) is one of them, but other methods are available. Refer to section: [Transfer Agents](#agents)
 
-## <a name="offline_install"></a>Offline Installation (without internet)
+## <a id="offline_install"></a>Installation in air gapped environment
 
-The procedure consists in:
+Note that currently no pre-packaged version exist yet.
+A method to build one is provided here:
+
+The procedure:
 
 * Follow the non-root installation procedure with RVM, including gem
-* archive (zip, tar) the main RVM folder (includes ascli):
+* Archive (zip, tar) the main RVM folder (includes ascli):
 
 ```
-$ cd ~
-$ tar zcvf rvm_ascli.tgz .rvm
+cd $HOME && tar zcvf rvm-ascli.tgz .rvm
 ```
 
-* retrieve the SDK:
+* Get the Aspera SDK.
 
 ```
-$ curl -Lso SDK.zip https://ibm.biz/aspera_sdk
+ascli conf --show-config --fields=sdk_url
 ```
 
-* on the system without internet access:
+* Download the SDK archive from that URL.
 
 ```
-$ cd ~
-$ tar zxvf rvm_ascli.tgz
-$ source ~/.rvm/scripts/rvm
-$ ascli conf ascp install --sdk-url=file:///SDK.zip
+curl -Lso SDK.zip https://ibm.biz/aspera_sdk
 ```
 
-# <a name="cli"></a>Command Line Interface: `ascli`
+* Transfer those 2 files to the target system
+
+* On target system
+
+```
+cd $HOME
+
+tar zxvf rvm-ascli.tgz
+
+source ~/.rvm/scripts/rvm
+
+ascli conf ascp install --sdk-url=file:///SDK.zip
+```
+
+* Add those lines to shell init (`.profile`)
+
+```
+source ~/.rvm/scripts/rvm
+```
+
+# <a id="cli"></a>Command Line Interface: `ascli`
 
 The `aspera-cli` Gem provides a command line interface (CLI) which interacts with Aspera Products (mostly using REST APIs):
 
@@ -491,7 +515,7 @@ The `aspera-cli` Gem provides a command line interface (CLI) which interacts wit
 Basic usage is displayed by executing:
 
 ```
-$ ascli -h
+ascli -h
 ```
 
 Refer to sections: [Usage](#usage) and [Sample Commands](#commands).
@@ -505,7 +529,7 @@ Arguments are the units of command line, as parsed by the shell, typically separ
 There are two types of arguments: Commands and Options. Example :
 
 ```
-$ ascli command --option-name=VAL1 VAL2
+ascli command --option-name=VAL1 VAL2
 ```
 
 * executes _command_: `command`
@@ -533,13 +557,16 @@ Exceptions:
 * the special option `--` stops option processing and is ignored, following command line arguments are taken as arguments, including the ones starting with a `-`. Example:
 
 ```
-$ ascli config echo -- --sample
+ascli config echo -- --sample
+```
+
+```
 "--sample"
 ```
 
 Note that `--sample` is taken as an argument, and not option.
 
-Options can be optional or mandatory, with or without (hardcoded) default value. Options can be placed anywhere on comand line and evaluated in order.
+Options can be optional or mandatory, with or without (hardcoded) default value. Options can be placed anywhere on command line and evaluated in order.
 
 The value for _any_ options can come from the following locations (in this order, last value evaluated overrides previous value):
 
@@ -560,7 +587,7 @@ Command line arguments that are not options are either commands or arguments. If
 
 Some options and parameters are mandatory and other optional. By default, the tool will ask for missing mandatory options or parameters for interactive execution.
 
-The behaviour can be controlled with:
+The behavior can be controlled with:
 
 * --interactive=&lt;yes|no&gt; (default=yes if STDIN is a terminal, else no)
    * yes : missing mandatory parameters/options are asked to the user
@@ -577,8 +604,8 @@ The information displayed depends on the action.
 
 Depending on action, the output will contain:
 
-* `single_object` : displayed as a 2 dimensional table: one line per attribute, first column is attribute name, and second is atteribute value. Nested hashes are collapsed.
-* `object_list` : displayed as a 2 dimensional table: one line per item, one colum per attribute.
+* `single_object` : displayed as a 2 dimensional table: one line per attribute, first column is attribute name, and second is attribute value. Nested hashes are collapsed.
+* `object_list` : displayed as a 2 dimensional table: one line per item, one column per attribute.
 * `value_list` : a table with one column.
 * `empty` : nothing
 * `status` : a message
@@ -603,12 +630,15 @@ The style of output can be set using the `format` parameter, supporting:
 * `yaml` : YAML
 * `csv` : Comma Separated Values
 
-### <a name="option_select"></a>Option: `select`: Filter on columns values for `object_list`
+### <a id="option_select"></a>Option: `select`: Filter on columns values for `object_list`
 
 Table output can be filtered using the `select` parameter. Example:
 
 ```
-$ ascli aoc admin res user list --fields=name,email,ats_admin --query=@json:'{"sort":"name"}' --select=@json:'{"ats_admin":true}'
+ascli aoc admin res user list --fields=name,email,ats_admin --query=@json:'{"sort":"name"}' --select=@json:'{"ats_admin":true}'
+```
+
+```
 :...............................:..................................:...........:
 :             name              :              email               : ats_admin :
 :...............................:..................................:...........:
@@ -621,7 +651,7 @@ Note that `select` filters selected elements from the result of API calls, while
 
 ### Verbosity of output
 
-Outpout messages are categorized in 3 types:
+Output messages are categorized in 3 types:
 
 * `info` output contain additional information, such as number of elements in a table
 * `data` output contain the actual output of the command (object, or list of objects)
@@ -635,7 +665,7 @@ The option `display` controls the level of output:
 
 ### Selection of output object properties
 
-By default, a table output will display one line per entry, and columns for each entries. Depending on the command, columns may include by default all properties, or only some selected properties. It is possible to define specific colums to be displayed, by setting the `fields` option to one of the following value:
+By default, a table output will display one line per entry, and columns for each entries. Depending on the command, columns may include by default all properties, or only some selected properties. It is possible to define specific columns to be displayed, by setting the `fields` option to one of the following value:
 
 * DEF : default display of columns (that's the default, when not set)
 * ALL : all columns available
@@ -644,7 +674,7 @@ By default, a table output will display one line per entry, and columns for each
 * +a,b,c : add selected properties to the default selection.
 * -a,b,c : remove selected properties from the default selection.
 
-## <a name="extended"></a>Extended Value Syntax
+## <a id="extended"></a>Extended Value Syntax
 
 Usually, values of options and arguments are specified by a simple string. But sometime it is convenient to read a value from a file, or decode it, or have a value more complex than a string (e.g. Hash table).
 
@@ -681,23 +711,32 @@ To display the result of an extended value, use the `config echo` command.
 Example: read the content of the specified file, then, base64 decode, then unzip:
 
 ```
-$ ascli config echo @zlib:@base64:@file:myfile.dat
+ascli config echo @zlib:@base64:@file:myfile.dat
 ```
 
 Example: create a value as a hash, with one key and the value is read from a file:
 
 ```
-$ ascli config echo @ruby:'{"token_verification_key"=>File.read("pubkey.txt")}'
+ascli config echo @ruby:'{"token_verification_key"=>File.read("pubkey.txt")}'
 ```
 
 Example: read a csv file and create a list of hash for bulk provisioning:
 
 ```
-$ cat test.csv
+cat test.csv
+```
+
+```
 name,email
 lolo,laurent@example.com
 toto,titi@tutu.tata
-$ ascli config echo @csvt:@file:test.csv
+```
+
+```
+ascli config echo @csvt:@file:test.csv
+```
+
+```
 :......:.....................:
 : name :        email        :
 :......:.....................:
@@ -709,13 +748,16 @@ $ ascli config echo @csvt:@file:test.csv
 Example: create a hash and include values from preset named "config" of config file in this hash
 
 ```
-$ ascli config echo @incps:@json:'{"hello":true,"incps":["config"]}'
+ascli config echo @incps:@json:'{"hello":true,"incps":["config"]}'
+```
+
+```
 {"version"=>"0.9", "hello"=>true}
 ```
 
 Note that `@incps:@json:'{"incps":["config"]}'` or `@incps:@ruby:'{"incps"=>["config"]}'` is equivalent to: `@preset:config`
 
-## <a name="native"></a>Structured Value
+## <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.
 
@@ -726,7 +768,7 @@ A convenient way to specify a _Structured Value_ is to use the `@json:` decoder,
 
 It is also possible to provide a _Structured Value_ in a file using `@json:@file:<path>`
 
-## <a name="conffolder"></a>Configuration and Persistency Folder
+## <a id="conffolder"></a>Configuration and Persistency Folder
 
 `ascli` configuration and other runtime files (token cache, file lists, persistency files, SDK) are stored in folder `[User's home folder]/.aspera/ascli`.
 
@@ -736,49 +778,52 @@ It uses the `HOME` env var primarily, and on MS Windows it also looks at `%HOMED
 The main folder can be displayed using :
 
 ```
-$ ascli config folder
+ascli config folder
+```
+
+```
 /Users/kenji/.aspera/ascli
 ```
 
-It can be overriden using the envinonment variable `ASCLI_HOME`.
+It can be overridden using the environment variable `ASCLI_HOME`.
 
 Example (Windows):
 
 ```
-$ set ASCLI_HOME=C:\Users\Kenji\.aspera\ascli
-$ ascli config folder
+set ASCLI_HOME=C:\Users\Kenji\.aspera\ascli
+ascli config folder
 C:\Users\Kenji\.aspera\ascli
 ```
 
-## <a name="configfile"></a>Configuration file
+## <a id="configfile"></a>Configuration file
 
 On the first execution of `ascli`, an empty configuration file is created in the configuration folder.
 Nevertheless, there is no mandatory information required in this file, the use of it is optional as any option can be provided on the command line.
 
 Although the file is a standard YAML file, `ascli` provides commands to read and modify it using the `config` command.
 
-All options for `ascli` can be set on command line, or by env vars, or using [option presets](#lprt) in the configuratin file.
+All options for `ascli` can be set on command line, or by env vars, or using [option presets](#lprt) in the configuration file.
 
 A configuration file provides a way to define default values, especially for authentication parameters, thus avoiding to always having to specify those parameters on the command line.
 
-The default configuration file is: `$HOME/.aspera/ascli/config.yaml` (this can be overriden with option `--config-file=path` or equivalent env var).
+The default configuration file is: `$HOME/.aspera/ascli/config.yaml` (this can be overridden with option `--config-file=path` or equivalent env var).
 
 The configuration file is simply a catalog of pre-defined lists of options, called: [option presets](#lprt). Then, instead of specifying some common options on the command line (e.g. address, credentials), it is possible to invoke the ones of a [option preset](#lprt) (e.g. `mypreset`) using the option: `-Pmypreset` or `--preset=mypreset`.
 
-### <a name="lprt"></a>Option preset
+### <a id="lprt"></a>Option preset
 
 A [option preset](#lprt) is simply a collection of parameters and their associated values in a named section in the configuration file.
 
 A named [option preset](#lprt) can be modified directly using `ascli`, which will update the configuration file :
 
 ```
-$ ascli config id <option preset> set|delete|show|initialize|update
+ascli config preset set|delete|show|initialize|update <option preset>
 ```
 
 The command `update` allows the easy creation of [option preset](#lprt) by simply providing the options in their command line format, e.g. :
 
 ```
-$ ascli config id demo_server update --url=ssh://demo.asperasoft.com:33001 --username=asperaweb --password=_demo_pass_ --ts=@json:'{"precalculate_job_size":true}'
+ascli config preset update demo_server --url=ssh://demo.asperasoft.com:33001 --username=asperaweb --password=_demo_pass_ --ts=@json:'{"precalculate_job_size":true}'
 ```
 
 * This creates a [option preset](#lprt) `demo_server` with all provided options.
@@ -786,39 +831,48 @@ $ ascli config id demo_server update --url=ssh://demo.asperasoft.com:33001 --use
 The command `set` allows setting individual options in a [option preset](#lprt).
 
 ```
-$ ascli config id demo_server set password _demo_pass_
+ascli config preset set demo_server password _demo_pass_
 ```
 
 The command `initialize`, like `update` allows to set several parameters at once, but it deletes an existing configuration instead of updating it, and expects a _[Structured Value](#native)_.
 
 ```
-$ ascli config id demo_server initialize @json:'{"url":"ssh://demo.asperasoft.com:33001","username":"asperaweb","password":"_demo_pass_","ts":{"precalculate_job_size":true}}'
+ascli config preset initialize demo_server @json:'{"url":"ssh://demo.asperasoft.com:33001","username":"asperaweb","password":"_demo_pass_","ts":{"precalculate_job_size":true}}'
 ```
 
-A good practice is to not manually edit the configuration file and use modification commands instead.
-If necessary, the configuration file can be edited (or simply consulted) with:
+A full terminal based overview of the configuration can be displayed using:
 
 ```
-$ ascli config open
+ascli config preset over
 ```
 
-A full terminal based overview of the configuration can be displayed using:
+A list of [option preset](#lprt) can be displayed using:
 
 ```
-$ ascli config over
+ascli config preset list
 ```
 
-A list of [option preset](#lprt) can be displayed using:
+A good practice is to not manually edit the configuration file and use modification commands instead.
+If necessary, the configuration file can opened in a text editor with:
+
+```
+ascli config open
+```
+
+Older format for commands are still supported:
 
 ```
-$ ascli config list
+ascli config id <name> set|delete|show|initialize|update
+ascli config over
+ascli config list
 ```
 
-### <a name="lprtconf"></a>Special Option preset: config
+
+### <a id="lprtconf"></a>Special Option preset: config
 
 This preset name is reserved and contains a single key: `version`. This is the version of `ascli` which created the file.
 
-### <a name="lprtdef"></a>Special Option preset: default
+### <a id="lprtdef"></a>Special Option preset: default
 
 This preset name is reserved and contains an array of key-value , where the key is the name of a plugin, and the value is the name of another preset.
 
@@ -829,16 +883,16 @@ Note that special plugin name: `config` can be associated with a preset that is
 Operations on this preset are done using regular `config` operations:
 
 ```
-$ ascli config id default set _plugin_name_ _default_preset_for_plugin_
-$ ascli config id default get _plugin_name_
+ascli config preset set default _plugin_name_ _default_preset_for_plugin_
+ascli config preset get default _plugin_name_
 "_default_preset_for_plugin_"
 ```
 
-### <a name="lprtdef"></a>Special Plugin: config
+### <a id="lplugconf"></a>Special Plugin: config
 
 Plugin `config` (not to be confused with Option preset config) is used to configure `ascli` but it also contains global options.
 
-When `ascli` starts, it lookjs for the `default` Option preset and if there is a value for `config`, if so, it loads the option values for any plugin used.
+When `ascli` starts, it looks for the `default` Option preset and if there is a value for `config`, if so, it loads the option values for any plugin used.
 
 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`)
 
@@ -877,10 +931,10 @@ The user may create as many [option presets](#lprt) as needed. For instance, a p
 
 Values in the configuration also follow the [Extended Value Syntax](#extended).
 
-Note: if the user wants to use the [Extended Value Syntax](#extended) inside the configuration file, using the `config id update` command, the user shall use the `@val:` prefix. Example:
+Note: if the user wants to use the [Extended Value Syntax](#extended) inside the configuration file, using the `config preset update` command, the user shall use the `@val:` prefix. Example:
 
 ```
-$ ascli config id my_aoc_org set private_key @val:@file:"$HOME/.aspera/ascli/aocapikey"
+ascli config preset set my_aoc_org private_key @val:@file:"$HOME/.aspera/ascli/aocapikey"
 ```
 
 This creates the [option preset](#lprt):
@@ -916,26 +970,29 @@ is an underscore. E.g. --xxx-yyy  on command line gives xxx_yyy in configuration
 The main plugin name is `config`, so it is possible to define a default [option preset](#lprt) for the main plugin with:
 
 ```
-$ ascli config id cli_default set interactive no
-$ ascli config id default set config cli_default
+ascli config preset set cli_default interactive no
+```
+
+```
+ascli config preset set default config cli_default
 ```
 
 A [option preset](#lprt) value can be removed with `unset`:
 
 ```
-$ ascli config id cli_default unset interactive
+ascli config preset unset cli_default interactive
 ```
 
 Example: Define options using command line:
 
 ```
-$ ascli -N --url=x --password=y --username=y node --show-config
+ascli -N --url=x --password=y --username=y node --show-config
 ```
 
 Example: Define options using a hash:
 
 ```
-$ ascli -N --preset=@json:'{"url":"x","password":"y","username":"y"}' node --show-config
+ascli -N --preset=@json:'{"url":"x","password":"y","username":"y"}' node --show-config
 ```
 
 ### Examples
@@ -945,44 +1002,120 @@ only username/password and url are required (either on command line, or from con
 Those can usually be provided on the command line:
 
 ```
-$ ascli shares repo browse / --url=https://10.25.0.6 --username=john --password=4sp3ra
+ascli shares repo browse / --url=https://10.25.0.6 --username=john --password=4sp3ra
 ```
 
 This can also be provisioned in a config file:
 
+* Build [option preset](#lprt)
+
 ```
-1$ ascli config id shares06 set url https://10.25.0.6
-2$ ascli config id shares06 set username john
-3$ ascli config id shares06 set password 4sp3ra
-4$ ascli config id default set shares shares06
-5$ ascli config overview
-6$ ascli shares repo browse /
+ascli config preset set shares06 url https://10.25.0.6
+ascli config preset set shares06 username john
+ascli config preset set shares06 password 4sp3ra
 ```
 
-The three first commands build a [option preset](#lprt).
 Note that this can also be done with one single command:
 
 ```
-$ ascli config id shares06 init @json:'{"url":"https://10.25.0.6","username":"john","password":"4sp3ra"}'
+ascli config preset init shares06 @json:'{"url":"https://10.25.0.6","username":"john","password":"4sp3ra"}'
 ```
 
-The fourth command defines this [option preset](#lprt) as the default [option preset](#lprt) for the
-specified application ("shares"). The 5th command displays the content of configuration file in table format.
-Alternative [option presets](#lprt) can be used with option "-P&lt;[option preset](#lprt)&gt;"
-(or --preset=&lt;[option preset](#lprt)&gt;)
+or
+
+```
+ascli config preset update shares06 --url=https://10.25.0.6 --username=john --password=4sp3ra
+```
+
+* Define this [option preset](#lprt) as the default [option preset](#lprt) for the specified plugin (`shares`)
+
+```
+ascli config preset set default shares shares06
+```
+
+* Display the content of configuration file in table format
+
+```
+ascli config overview
+```
+
+* Execute a command on the shares application using default parameters
+
+```
+ascli shares repo browse /
+```
+
+## <a id="vault"></a>Secret Vault
+
+When a secret or password is needed, it is possible to store in the secret vault.
+
+By default the vault is defined using option `secrets`.
+
+### Using system keychain
+
+Only on macOS.
+
+It is possible to store secrets in macOS keychain (only read supported currently).
+
+Set option `secrets` to value `system` to use the default keychain or use value `system:[name]` to use a custom keychain.
+
+### Modern config file format: encrypted in config file
 
-Eventually, the last command shows a call to the shares application using default parameters.
+It is possible to store and use secrets encrypted.
+For this use the `config vault` command.
 
+The vault can be initialized with `config vault init`
+
+Then secrets can be manipulated using commands:
+
+* `set`
+* `get`
+* `list`
+* `delete`
+
+Secrets must be uniquely identified by `url` and `username`. An optional description can be provided using option `value`.
+
+### Legacy config file format
+
+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:
+
+```
+ascli conf id my_secrets set 'access_key1' 'secret1'
+
+ascli conf id my_secrets set 'access_key2' 'secret2'
+
+ascli conf id default get config
+
+cli_default
+```
+
+Here above, one has already set a `config` global preset to preset `cli_default` (refer to earlier in documentation).
+So the repository can be read by default like this (note the prefix `@val:` to avoid the evaluation of prefix `@preset:`):
+
+```
+ascli conf id cli_default set secrets @val:@preset:my_secrets
+```
+
+A secret repository can always be selected at runtime using `--secrets=@preset:xxxx`, or `--secrets=@json:'{"accesskey1":"secret1"}'`
+
+To test if a secret can be found use:
+
+```
+ascli conf vault get --username=access_key1
+```
 
 ## Plugins
 
 The CLI tool uses a plugin mechanism. The first level command (just after `ascli` on the command line) is the name of the concerned plugin which will execute the command. Each plugin usually represent commands sent to a specific application.
 For instance, the plugin "faspex" allows operations on the application "Aspera Faspex".
 
-### Create your own plugin
+### <a id="createownplugin"></a>Create your own plugin
+
 ```
-$ mkdir -p ~/.aspera/ascli/plugins
-$ cat<<EOF>~/.aspera/ascli/plugins/test.rb
+mkdir -p ~/.aspera/ascli/plugins
+cat<<EOF>~/.aspera/ascli/plugins/test.rb
 require 'aspera/cli/plugin'
 module Aspera
   module Cli
@@ -997,39 +1130,78 @@ end # Aspera
 EOF
 ```
 
-## Debugging
+### <a id="plugins"></a>Plugins: Application URL and Authentication
 
-The gem is equipped with traces. By default logging level is "warn". To increase debug level, use parameter `log_level`, so either command line `--log-level=xx` or env var `ASCLI_LOG_LEVEL`.
+`ascli` comes with several Aspera application plugins.
 
-It is also possible to activate traces before initialisation using env var `AS_LOG_LEVEL`.
+REST APIs of Aspera legacy applications (Aspera Node, Faspex, Shares, Console, Orchestrator, Server) use simple username/password authentication: HTTP Basic Authentication.
+
+Those are using options:
+
+* url
+* username
+* password
+
+Those can be provided using command line, parameter set, env var, see section above.
+
+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).
+
+It is also possible to activate traces before initialization using env var `AS_LOG_LEVEL`.
+
+By default passwords and secrets are removed from logs.
+Use option `log_passwords` to change this behaviour.
 
 ## Learning Aspera Product APIs (REST)
 
 This CLI uses REST APIs.
-To display HTTP calls, use argument `-r` or `--rest-debug`, this is useful to display
-exact content or HTTP requests and responses.
+To display HTTP calls, use argument `-r` or `--rest-debug`, this is useful to display exact content of HTTP requests and responses.
 
 In order to get traces of execution, use argument : `--log-level=debug`
 
-## <a name="graphical"></a>Graphical Interactions: Browser and Text Editor
+## <a id="http_options"></a>HTTP socket parameters
+
+If the server does not provide a valid certificate, use parameter: `--insecure=yes`.
+
+Some of HTTP socket parameters can be adjusted, those are the parameters of Ruby [`Net::HTTP`](https://ruby-doc.org/stdlib/libdoc/net/http/rdoc/Net/HTTP.html), for example:
+
+* `read_timeout` 60 sec
+* `write_timeout` 60 sec
+
+Default values are the ones of Ruby.
+
+Example:
+
+```
+ascli aoc admin res package list --http-options=@json:'{"read_timeout":10.0}'
+```
+
+## <a id="graphical"></a>Graphical Interactions: Browser and Text Editor
 
 Some actions may require the use of a graphical tool:
 
 * a browser for Aspera on Cloud authentication (web auth method)
 * a text editor for configuration file edition
 
-By default the CLI will assume that a graphical environment is available on windows,
-and on other systems, rely on the presence of the "DISPLAY" environment variable.
+By default the CLI will assume that a graphical environment is available on windows, and on other systems, rely on the presence of the "DISPLAY" environment variable.
 It is also possible to force the graphical mode with option --ui :
 
-* `--ui=graphical` forces a graphical environment, a browser will be opened for URLs or
-a text editor for file edition.
-* `--ui=text` forces a text environment, the URL or file path to open is displayed on
-terminal.
+* `--ui=graphical` forces a graphical environment, a browser will be opened for URLs or a text editor for file edition.
+* `--ui=text` forces a text environment, the URL or file path to open is displayed on terminal.
 
 ## HTTP proxy for REST
 
-To specify a HTTP proxy, set the HTTP_PROXY environment variable (or HTTPS_PROXY), those are honoured by Ruby when calling REST APIs.
+To specify a HTTP proxy, set the HTTP_PROXY environment variable (or HTTPS_PROXY), those are honored by Ruby when calling REST APIs.
+
+## <a id="certificates"></a>SSL CA certificate bundle
+
+`ascli` uses ruby `openssl` gem, which uses the `openssl` library, so certificates are checked against the ruby default certificates [OpenSSL::X509::DEFAULT_CERT_FILE](https://ruby-doc.org/stdlib-3.0.3/libdoc/openssl/rdoc/OpenSSL/X509/Store.html), which are typically the ones of `openssl` on Unix systems (Linux, macOS, etc..). The environment variables `SSL_CERT_FILE` and `SSL_CERT_DIR` are used if defined.
+
+`ascp` also needs to validate certificates when using WSS. By default, `ascp` uses primarily certificates from hard coded path (e.g. on macOS: `/Library/Aspera/ssl`). `ascli` overrides and sets the default ruby certificate path as well for `ascp` using `-i` switch. So to update certificates, update ruby's `openssl` gem, or use env vars `SSL_CERT_*`.
 
 ## Proxy auto config
 
@@ -1038,13 +1210,13 @@ The `fpac` option allows specification of a Proxy Auto Configuration (PAC) file,
 The PAC file can be tested with command: `config proxy_check` , example:
 
 ```
-$ ascli config proxy_check --fpac=file:///./proxy.pac http://www.example.com
+ascli config proxy_check --fpac=file:///./proxy.pac http://www.example.com
 PROXY proxy.example.com:8080
 ```
 
 This is not yet implemented to specify http proxy, so use `http_proxy` env vars.
 
-## <a name="client"></a>FASP configuration
+## <a id="client"></a>FASP configuration
 
 The `config` plugin also allows specification for the use of a local FASP client. It provides the following commands for `ascp` subcommand:
 
@@ -1056,9 +1228,9 @@ The `config` plugin also allows specification for the use of a local FASP client
 ### Show path of currently used `ascp`
 
 ```
-$ ascli config ascp show
+ascli config ascp show
 /Users/laurent/.aspera/ascli/sdk/ascp
-$ ascli config ascp info
+ascli config ascp info
 +--------------------+-----------------------------------------------------------+
 | key                | value                                                     |
 +--------------------+-----------------------------------------------------------+
@@ -1066,7 +1238,7 @@ $ ascli config ascp info
 ...
 ```
 
-### Selection of `ascp` location for [`direct`](#direct) agent
+### Selection of `ascp` location for [`direct`](#agt_direct) agent
 
 By default, `ascli` uses any found local product with ascp, including SDK.
 
@@ -1077,7 +1249,7 @@ For a permanent change, the command `config ascp use` sets the same parameter fo
 Using a POSIX shell:
 
 ```
-$ ascli config ascp use '/Users/laurent/Applications/Aspera CLI/bin/ascp'
+ascli config ascp use '/Users/laurent/Applications/Aspera CLI/bin/ascp'
 ascp version: 4.0.0.182279
 Updated: global_common_defaults: ascp_path <- /Users/laurent/Applications/Aspera CLI/bin/ascp
 Saved to default global preset global_common_defaults
@@ -1086,7 +1258,7 @@ Saved to default global preset global_common_defaults
 Windows:
 
 ```
-$ ascli config ascp use C:\Users\admin\.aspera\ascli\sdk\ascp.exe
+ascli config ascp use C:\Users\admin\.aspera\ascli\sdk\ascp.exe
 ascp version: 4.0.0.182279
 Updated: global_common_defaults: ascp_path <- C:\Users\admin\.aspera\ascli\sdk\ascp.exe
 Saved to default global preset global_common_defaults
@@ -1099,7 +1271,7 @@ If the path has spaces, read section: [Shell and Command line parsing](#parsing)
 Locally installed Aspera products can be listed with:
 
 ```
-$ ascli config ascp products list
+ascli config ascp products list
 :.........................................:................................................:
 :                  name                   :                    app_root                    :
 :.........................................:................................................:
@@ -1110,7 +1282,7 @@ $ ascli config ascp products list
 :.........................................:................................................:
 ```
 
-### Selection of local client for `ascp` for [`direct`](#direct) agent
+### Selection of local client for `ascp` for [`direct`](#agt_direct) agent
 
 If no ascp is selected, this is equivalent to using option: `--use-product=FIRST`.
 
@@ -1119,14 +1291,14 @@ Using the option use_product finds the ascp binary of the selected product.
 To permanently use the ascp of a product:
 
 ```
-$ ascli config ascp products use 'Aspera Connect'
+ascli config ascp products use 'Aspera Connect'
 saved to default global preset /Users/laurent/Applications/Aspera Connect.app/Contents/Resources/ascp
 ```
 
 ### Installation of Connect Client on command line
 
 ```
-$ ascli config ascp connect list
+ascli config ascp connect list
 :...............................................:......................................:..............:
 :                      id                       :                title                 :   version    :
 :...............................................:......................................:..............:
@@ -1139,7 +1311,7 @@ $ ascli config ascp connect list
 : urn:uuid:213C9370-22B1-11E2-81C1-0800200C9A66 : Aspera Connect for Linux 32          : 3.6.2.117442 :
 : urn:uuid:97F94DF0-22B1-11E2-81C1-0800200C9A66 : Aspera Connect for Linux 64          : 3.7.2.141527 :
 :...............................................:......................................:..............:
-$ ascli config ascp connect id 'Aspera Connect for Mac Intel 10.6' links list
+ascli config ascp connect id 'Aspera Connect for Mac Intel 10.6' links list
 :.............................................:..........................:.......................................................................:..........:...............:
 :                    title                    :           type           :                                 href                                  : hreflang :      rel      :
 :.............................................:..........................:.......................................................................:..........:...............:
@@ -1152,11 +1324,11 @@ $ ascli config ascp connect id 'Aspera Connect for Mac Intel 10.6' links list
 : Aspera Connect PDF Documentation for Mac OS : application/pdf          : docs/user/osx/zh-cn/pdf/Connect_User_3.7.0_OSX_zh-cn.pdf              : zh-cn    : documentation :
 : Aspera Connect for Mac Release Notes        : text/html                : http://www.asperasoft.com/en/release_notes/default_1/release_notes_54 : en       : release-notes :
 :.............................................:..........................:.......................................................................:..........:...............:
-$ ascli config ascp connect id 'Aspera Connect for Mac Intel 10.6' links id 'Mac Intel Installer' download --to-folder=.
+ascli config ascp connect id 'Aspera Connect for Mac Intel 10.6' links id 'Mac Intel Installer' download --to-folder=.
 downloaded: AsperaConnect-3.6.1.111259-mac-intel-10.6.dmg
 ```
 
-## <a name="agents"></a>Transfer Agents
+## <a id="agents"></a>Transfer Agents
 
 Some of the actions on Aspera Applications lead to file transfers (upload and download) using the FASP protocol (`ascp`).
 
@@ -1165,102 +1337,109 @@ This [_transfer-spec_](#transferspec) will be executed by a transfer client, her
 
 There are currently 3 agents:
 
-* [`direct`](#direct) : a local execution of `ascp`
-* `connect` : use of a local Connect Client
-* `node` : use of an Aspera Transfer Node (potentially _remote_).
-* `httpgw` : use of an Aspera HTTP Gateway
+* [`direct`](#agt_direct) : a local execution of `ascp`
+* [`connect`](#agt_connect) : use of a local Connect Client
+* [`node`](#agt_node) : use of an Aspera Transfer Node (potentially _remote_).
+* [`httpgw`](#agt_httpgw) : use of an Aspera HTTP Gateway
+* [`trsdk`](#agt_trsdk) : use of Aspera Transfer SDK
 
 Note that all transfer operation are seen from the point of view of the agent.
 For instance, a node agent making an "upload", or "package send" operation,
 will effectively push files to the related server from the agent node.
 
-`ascli` standadizes on the use of a [_transfer-spec_](#transferspec) instead of _raw_ ascp options to provide parameters for a transfer session, as a common method for those three Transfer Agents.
+`ascli` standardizes on the use of a [_transfer-spec_](#transferspec) instead of _raw_ ascp options to provide parameters for a transfer session, as a common method for those three Transfer Agents.
 
 
-### <a name="direct"></a>Direct (local ascp execution)
+### <a id="agt_direct"></a>Direct
 
-By default `ascli` uses a local ascp, equivalent to specifying `--transfer=direct`.
-`ascli` will detect locally installed Aspera products.
+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.
 Refer to section [FASP](#client).
 
-To specify a FASP proxy (only supported with the `direct` agent), set the appropriate [_transfer-spec_](#transferspec) parameter:
-
-* `EX_fasp_proxy_url`
-* `EX_http_proxy_url` (proxy for legacy http fallback)
-* `EX_ascp_args`
-
-The `transfer-info` accepts the following optional parameters:
+The `transfer-info` accepts the following optional parameters to control multi-session, WSS
 
 <table>
-<tr><th>Name</th><th>Type</th><th>Default</th><th>Feature</th><th>Description</th></tr>
-<tr><td>spawn_timeout_sec</td><td>Float</td><td>3</td><td>Multi session</td><td>Verification time that ascp is running</td></tr>
-<tr><td>spawn_delay_sec</td><td>Float</td><td>2</td><td>Multi session</td><td>Delay between startup of sessions</td></tr>
-<tr><td>wss</td><td>Bool</td><td>false</td><td>Web Socket Session</td><td>Enable use of web socket session in case it is available</td></tr>
-<tr><td>multi_incr_udp</td><td>Bool</td><td>true</td><td>Multi Session</td><td>Increment UDP port on multi-session<br/>If true, each session will have a different UDP port starting at `fasp_port` (or default 33001)<br/>Else, each session will use `fasp_port` (or `ascp` default)</td></tr>
-<tr><td>resume</td><td>Hash</td><td>nil</td><td>Resumer parameters</td><td>See below</td></tr>
+<tr><th>Name</th><th>Type</th><th>Description</th></tr>
+<tr><td>wss</td><td>Bool</td><td>Web Socket Session<br/>Enable use of web socket session in case it is available<br/>Default: false</td></tr>
+<tr><td>spawn_timeout_sec</td><td>Float</td><td>Multi session<br/>Verification time that ascp is running<br/>Default: 3</td></tr>
+<tr><td>spawn_delay_sec</td><td>Float</td><td>Multi session<br/>Delay between startup of sessions<br/>Default: 2</td></tr>
+<tr><td>multi_incr_udp</td><td>Bool</td><td>Multi Session<br/>Increment UDP port on multi-session<br/>If true, each session will have a different UDP port starting at `fasp_port` (or default 33001)<br/>Else, each session will use `fasp_port` (or `ascp` default)<br/>Default: true</td></tr>
+<tr><td>resume</td><td>Hash</td><td>Resume<br/>parameters<br/>See below</td></tr>
+<tr><td>resume.iter_max</td><td>int</td><td>Resume<br/>Max number of retry on error<br/>Default: 7</td></tr>
+<tr><td>resume.sleep_initial</td><td>int</td><td>Resume<br/>First Sleep before retry<br/>Default: 2</td></tr>
+<tr><td>resume.sleep_factor</td><td>int</td><td>Resume<br/>Multiplier of sleep period between attempts<br/>Default: 2</td></tr>
+<tr><td>resume.sleep_max</td><td>int</td><td>Resume<br/>Default: 60</td></tr>
 </table>
 
-Resume parameters:
-
-In case of transfer interruption, the agent will resume a transfer up to `iter_max` time.
-Sleep between iteration is:
+Resume: In case of transfer interruption, the agent will resume a transfer up to `iter_max` time.
+Sleep between iterations is:
 
 ```
 max( sleep_max , sleep_initial * sleep_factor ^ (iter_index-1) )
 ```
 
-<table>
-<tr><th>Name</th><th>Type</th><th>Default</th><th>Feature</th><th>Description</th></tr>
-<tr><td>iter_max</td><td>int</td><td>7</td><td>Resume</td><td>Max number of retry on error</td></tr>
-<tr><td>sleep_initial</td><td>int</td><td>2</td><td>Resume</td><td>First Sleep before retry</td></tr>
-<tr><td>sleep_factor</td><td>int</td><td>2</td><td>Resume</td><td>Multiplier of Sleep</td></tr>
-<tr><td>sleep_max</td><td>int</td><td>60</td><td>Resume</td><td>Maximum sleep</td></tr>
-</table>
+Some transfer errors are considered "retryable" (e.g. timeout) and some other not (e.g. wrong password).
 
 Examples:
 
 ```
-$ ascli ... --transfer-info=@json:'{"wss":true,"resume":{"iter_max":10}}'
-$ ascli ... --transfer-info=@json:'{"spawn_delay_sec":2.5,"multi_incr_udp":false}'
+ascli ... --transfer-info=@json:'{"wss":true,"resume":{"iter_max":10}}'
+ascli ... --transfer-info=@json:'{"spawn_delay_sec":2.5,"multi_incr_udp":false}'
 ```
 
-### IBM Aspera Connect Client GUI
+To specify a FASP proxy (only supported with the `direct` agent), set the appropriate [_transfer-spec_](#transferspec) parameter:
+
+* `EX_fasp_proxy_url`
+* `EX_http_proxy_url` (proxy for legacy http fallback)
+* `EX_ascp_args`
+
+### <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.
+By specifying option: `--transfer=connect`, `ascli` will start transfers using the locally installed Aspera Connect Client. There are no option for `transfer_info`.
 
-### Aspera Node API : Node to node transfers
+### <a id="agt_node"></a>Aspera Node API : Node to node transfers
 
 By specifying option: `--transfer=node`, the CLI will start transfers in an Aspera
 Transfer Server using the Node API, either on a local or remote node.
+Parameters provided in option `transfer_info` are:
 
-If a default node has been configured
-in the configuration file, then this node is used by default else the parameter
-`--transfer-info` is required. The node specification shall be a hash table with
-three keys: url, username and password, corresponding to the URL of the node API
-and associated credentials (node user or access key).
+<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>
+<tr><td>password</td><td>string</td><td>password, secret or bearer token</br>Mandatory</td></tr>
+<tr><td>root_id</td><td>string</td><td>password or secret</br>Mandatory only for bearer token</td></tr>
+</table>
 
-The `--transfer-info` parameter can directly specify a pre-configured [option preset](#lprt) :
-`--transfer-info=@preset:<psetname>` or specified using the option syntax :
+Like any other option, `transfer_info` can get its value from a pre-configured [option preset](#lprt) :
+`--transfer-info=@preset:<psetname>` or be specified using the extended value syntax :
 `--transfer-info=@json:'{"url":"https://...","username":"theuser","password":"thepass"}'`
 
-### <a name="trinfoaoc"></a>Aspera on cloud
+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.
 
-By specifying option: `--transfer=aoc`, WORK IN PROGRESS
+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 name="httpgw"></a>HTTP Gateway
+### <a id="agt_httpgw"></a>HTTP Gateway
 
-If it possible to send using a HTTP gateway, in case FASP is not allowed.
+If it possible to send using a HTTP gateway, in case FASP is not allowed. `transfer_info` shall have a single mandatory parameter: `url`.
 
 Example:
 
 ```
-$ ascli faspex package recv --id=323 --transfer=httpgw --transfer-info=@json:'{"url":"https://asperagw.example.com:9443/aspera/http-gwy/v1"}'
+ascli faspex package recv --id=323 --transfer=httpgw --transfer-info=@json:'{"url":"https://asperagw.example.com:9443/aspera/http-gwy/v1"}'
 ```
 
 Note that the gateway only supports transfers authorized with a token.
 
-## <a name="transferspec"></a>Transfer Specification
+### <a id="agt_trsdk"></a>Transfer SDK
+
+Another possibility is to use the Transfer SDK daemon (asperatransferd).
+
+By default it will listen on local port `55002` on `127.0.0.1`.
+
+## <a id="transferspec"></a>Transfer Specification
 
 Some commands lead to file transfer (upload/download), all parameters necessary for this transfer
 is described in a _transfer-spec_ (Transfer Specification), such as:
@@ -1273,9 +1452,9 @@ is described in a _transfer-spec_ (Transfer Specification), such as:
 
 `ascli` builds a default _transfer-spec_ internally, so it is not necessary to provide additional parameters on the command line for this transfer.
 
-If needed, it is possible to modify or add any of the supported _transfer-spec_ parameter using the `ts` option. The `ts` option accepts a [Structured Value](#native) containing one or several _transfer-spec_ parameters. Multiple `ts` options on command line are cummulative.
+If needed, it is possible to modify or add any of the supported _transfer-spec_ parameter using the `ts` option. The `ts` option accepts a [Structured Value](#native) containing one or several _transfer-spec_ parameters. Multiple `ts` options on command line are cumulative.
 
-It is possible to specify ascp options when the `transfer` option is set to [`direct`](#direct) using the special [_transfer-spec_](#transferspec) parameter: `EX_ascp_args`. Example: `--ts=@json:'{"EX_ascp_args":["-l","100m"]}'`. This is espacially useful for ascp command line parameters not supported yet in the transfer spec.
+It is possible to specify ascp options when the `transfer` option is set to [`direct`](#agt_direct) using the special [_transfer-spec_](#transferspec) parameter: `EX_ascp_args`. Example: `--ts=@json:'{"EX_ascp_args":["-l","100m"]}'`. This is especially useful for ascp command line parameters not supported yet in the transfer spec.
 
 The use of a _transfer-spec_ instead of `ascp` parameters has the advantage of:
 
@@ -1284,21 +1463,22 @@ The use of a _transfer-spec_ instead of `ascp` parameters has the advantage of:
 
 A [_transfer-spec_](#transferspec) is a Hash table, so it is described on the command line with the [Extended Value Syntax](#extended).
 
-## <a name="transferparams"></a>Transfer Parameters
+## <a id="transferparams"></a>Transfer Parameters
 
-All standard _transfer-spec_ parameters can be speficied.
+All standard _transfer-spec_ parameters can be specified.
 [_transfer-spec_](#transferspec) can also be saved/overridden in the config file.
 
 References:
 
 * [Aspera Node API Documentation](https://developer.ibm.com/apis/catalog?search=%22aspera%20node%20api%22)&rarr;/opt/transfers
 * [Aspera Transfer SDK Documentation](https://developer.ibm.com/apis/catalog?search=%22aspera%20transfer%20sdk%22)&rarr;Guides&rarr;API Ref&rarr;Transfer Spec V1
+* [Aspera Connect SDK](https://d3gcli72yxqn2z.cloudfront.net/connect/v4/asperaweb-4.js) &rarr; search `The parameters for starting a transfer.`
 
 Parameters can be displayed with commands:
 
 ```
-$ ascli config ascp spec
-$ ascli config ascp spec --select=@json:'{"f":"Y"}' --fields=-f,n,c
+ascli config ascp spec
+ascli config ascp spec --select=@json:'{"d":"Y"}' --fields=-d,n,c
 ```
 
 Columns:
@@ -1306,9 +1486,10 @@ Columns:
 * D=Direct (local `ascp` execution)
 * N=Node API
 * C=Connect Client
-* arg=`ascp` argument or environment variable
 
-Fields with EX_ prefix are extensions to transfer agent [`direct`](#direct). (only in `ascli`).
+`ascp` argument or environment variable is provided in description.
+
+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/>none, aes-128, aes-256<br/>Allowed values: aes128, aes192, aes256, aes128cfb, aes192cfb, aes256cfb, aes128gcm, aes192gcm, aes256gcm<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 content protection. (encryption at rest)<br/>Allowed values: encrypt, decrypt</td></tr><tr><td>content_protection_password</td><td>string</td><td>Y</td><td>Y</td><td>Y</td><td>Specifies CSEAR password.</td></tr><tr><td>cookie</td><td>string</td><td>Y</td><td>Y</td><td>Y</td><td>Metadata for transfer (older,string)<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>(--delete-before-transfer)</td></tr><tr><td>delete_source</td><td>bool</td><td>&nbsp;</td><td>Y</td><td>&nbsp;</td><td>Remove SRC files after transfer success</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>http_fallback</td><td>string<br/>bool</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.<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.</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>in bytes<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>Required. Contains a path to the source (required) and a path to the destination.</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_access_key</td><td>string</td><td>Y</td><td>Y</td><td>Y</td><td>Node only?</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>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>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 PRIVATE KEY-----\nMII...<br/> Note the JSON encoding: \n for newlines.<br/>(env:ASPERA_SCP_KEY)</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 by:<br/> following the link (follow),<br/> copying the link itself (copy),<br/> skipping (skip),<br/> or forcibly copying the link itself (copy+force).<br/> Default: follow<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<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>destination_root</td><td>string</td><td>Y</td><td>Y</td><td>Y</td><td>Destination root directory.</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/>Allowable values: none, native, metafile<br/>(--preserve-acls)</td></tr><tr><td>remove_empty_source_directory</td><td>bool</td><td>Y</td><td>&nbsp;</td><td>&nbsp;</td><td>TODO: check node, sdk<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<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>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 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>&nbsp;</td></tr></table>
 
@@ -1326,17 +1507,17 @@ The option `to_folder` provides an equivalent and convenient way to change this
 
 ### 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 (Extensed value) is `sources`, the default value is `@args`, which means: take remain non used arguments (not starting with `-` as list of files.
+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:
 
 ```
-$ ascli server upload ~/mysample.file secondfile
+ascli server upload ~/mysample.file secondfile
 ```
 
 This is equivalent to:
 
 ```
-$ ascli server upload --sources=@args ~/mysample.file secondfile
+ascli server upload --sources=@args ~/mysample.file secondfile
 ```
 
 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).
@@ -1362,13 +1543,19 @@ For ease of use and flexibility, the list of files to transfer is specified by t
 --sources=@ts --ts=@json:'{"paths":[{"source":"file1"},{"source":"file2"}]}'
 ```
 
+providing a file list directly to ascp:
+
+```
+... --sources=@ts --ts=@json:'{"paths":[],"EX_file_list":"filelist.txt"}'
+```
+
 * Not recommended: It is possible to specify bare ascp arguments using the pseudo [_transfer-spec_](#transferspec) parameter `EX_ascp_args`.
 
 ```
 --sources=@ts --ts=@json:'{"paths":[{"source":"dummy"}],"EX_ascp_args":["--file-list","myfilelist"]}'
 ```
 
-This method avoids creating a copy of the file list, but has drawbacks: it applies *only* to the [`direct`](#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 overriden by the bare ascp command line provided. (TODO) In next version, dummy source paths can be removed.
+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.
 
 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`:
 
@@ -1378,10 +1565,10 @@ In case the file list is provided on the command line i.e. using `--sources=@arg
 Example:
 
 ```
-$ ascli server upload --src-type=pair ~/Documents/Samples/200KB.1 /Upload/sample1
+ascli server upload --src-type=pair ~/Documents/Samples/200KB.1 /Upload/sample1
 ```
 
-Internally, when transfer agent [`direct`](#direct) is used, a temporary file list (or pair) file is generated and provided to ascp, unless `--file-list` or `--file-pait-list` is provided in `ts` in `EX_ascp_args`.
+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`.
 
 Note the special case when the source files are located on "Aspera on Cloud", i.e. using access keys and the `file id` API:
 
@@ -1394,7 +1581,7 @@ Source files are located on "Aspera on cloud", when :
 * the server is Aspera on Cloud, and making a download / recv
 * the agent is Aspera on Cloud, and making an upload / send
 
-### <a name="multisession"></a>Support of multi-session
+### <a id="multisession"></a>Support of multi-session
 
 Multi session, i.e. starting a transfer of a file set using multiple sessions (one ascp process per session) is supported on "direct" and "node" agents, not yet on connect.
 
@@ -1445,16 +1632,14 @@ When multi-session is used, one separate UDP port is used per session (refer to
 --ts=@json:'{"precalculate_job_size":true}'
 ```
 
-
-
-## <a name="scheduling"></a>Lock for exclusive execution
+## <a id="scheduling"></a>Lock for exclusive execution
 
 In some conditions, it may be desirable to ensure that `ascli` is not executed several times in parallel.
 
 For instance when `ascli` is executed automatically on a schedule basis, one generally desire that a new execution is not started if a previous execution is still running because an on-going operation may last longer than the scheduling period:
 
 * Executing instances may pile-up and kill the system
-* The same file may be transfered by multiple instances at the same time.
+* The same file may be transferred by multiple instances at the same time.
 * `preview` may generate the same files in multiple instances.
 
 Usually the OS native scheduler already provides some sort of protection against parallel execution:
@@ -1488,14 +1673,14 @@ WARN -- : Another instance is already running (Address already in use - bind(2)
 `ascp`, the underlying executable implementing Aspera file transfer using FASP, has a capability to not only access the local file system (using system's `open`,`read`,`write`,`close` primitives), but also to do the same operations on other data storage such as S3, Hadoop and others. This mechanism is call *PVCL*. Several *PVCL* adapters are available, some are embedded in `ascp`
 , some are provided om shared libraries and must be activated. (e.g. using `trapd`)
 
-The list of supported *PVCL* adapters can be retried with command:
+The list of supported *PVCL* adapters can be retrieved with command:
 
 ```
-$ ascli conf ascp info
+ascli conf ascp info
 +--------------------+-----------------------------------------------------------+
 | key                | value                                                     |
 +--------------------+-----------------------------------------------------------+
------8<----snip---------
+-----8<-----snip-----8<-----
 | product_name       | IBM Aspera SDK                                            |
 | product_version    | 4.0.1.182389                                              |
 | process            | pvcl                                                      |
@@ -1520,20 +1705,26 @@ The simplified format is:
 
 One of the adapters, used in this manual, for testing, is `faux`. It is a pseudo file system allowing generation of file data without actual storage (on source or destination).
 
-## <a name="faux_testing"></a>`faux:` for testing
+## <a id="faux_testing"></a>`faux:` for testing
 
-This is an extract of the man page of `ascp`. This feature is a feature of `ascp`, not `ascli`
+This is an extract of the man page of `ascp`. This feature is a feature of `ascp`, not `ascli`.
 
 This adapter can be used to simulate a file or a directory.
 
-To send uninitialized data in place of an actual source file, the source file is replaced with an argument of the form `faux:///fname?fsize` where:
+To send uninitialized data in place of an actual source file, the source file is replaced with an argument of the form:
 
-* `fname` is the name that will be assigned to the file on the destination
-* `fsize` is the number of bytes that will be sent (in decimal).
+```
+faux:///filename?filesize
+```
+
+where:
+
+* `filename` is the name that will be assigned to the file on the destination
+* `filesize` is the number of bytes that will be sent (in decimal).
 
-Note that the character `?` is a special shell character (wildcard), so `faux` file specification on command line shall be protected (using `\?` and `\&` or using quotes). If not, the shell may give error: `no matches found` or equivalent.
+Note: characters `?` and `&` are shell special characters (wildcard and backround), so `faux` file specification on command line should be protected (using quotes or `\`). If not, the shell may give error: `no matches found` or equivalent.
 
-For all sizes, a suffix can be added (case insensitive) to the size: k,m,g,t,p,e (values are power of 2, e.g. 1M is 2^20, i.e. 1 mebibyte, not megabyte). The maximum allowed value is 8*2^60. Very large `faux` file sizes (petabyte range and above) will likely fail due to lack of system memory unless `faux://`.
+For all sizes, a suffix can be added (case insensitive) to the size: k,m,g,t,p,e (values are power of 2, e.g. 1M is 2<sup>20</sup>, i.e. 1 mebibyte, not megabyte). The maximum allowed value is 8*2<sup>60</sup>. Very large `faux` file sizes (petabyte range and above) will likely fail due to lack of destination storage unless destination is `faux://`.
 
 To send uninitialized data in place of a source directory, the source argument is replaced with an argument of the form:
 
@@ -1541,21 +1732,21 @@ To send uninitialized data in place of a source directory, the source argument i
 faux:///dirname?<arg1>=<val1>&...
 ```
 
-`dirname` is the folder name and can contain `/` to specify a subfolder.
+where:
 
-Supported arguments are:
+* `dirname` is the folder name and can contain `/` to specify a subfolder.
+* supported arguments are:
 
 <table>
 <tr><th>name</th><th>type</th><th>default</th><th>description</th></tr>
-<tr><td>count</td><td>int</td><td>mandatory</td><td>number of files</td></tr>
-<tr><td>file</td><td>string</td><td>file</td><td>basename for files</td></tr>
-<tr><td>size</td><td>int</td><td>0</td><td>size of first file.</td></tr>
-<tr><td>inc</td><td>int</td><td>0</td><td>increment applied to determine next file size</td></tr>
-<tr><td>seq</td><td>sequential<br/>random</td><td>sequential</td><td>sequence in determining next file size</td></tr>
-<tr><td>buf_init</td><td>none<br/>zero<br/>random</td><td>zero</td><td>how source data initialized.<br/>Option 'none' is not allowed for downloads.</td></tr>
+<tr><td>count</td><td>int</td><td>mandatory</td><td>Number of files</td></tr>
+<tr><td>file</td><td>string</td><td>file</td><td>Basename for files</td></tr>
+<tr><td>size</td><td>int</td><td>0</td><td>Size of first file.</td></tr>
+<tr><td>inc</td><td>int</td><td>0</td><td>Increment applied to determine next file size</td></tr>
+<tr><td>seq</td><td>sequential<br/>random</td><td>sequential</td><td>Sequence in determining next file size</td></tr>
+<tr><td>buf_init</td><td>none<br/>zero<br/>random</td><td>zero</td><td>How source data is initialized<br/>Option 'none' is not allowed for downloads.</td></tr>
 </table>
 
-
 The sequence parameter is applied as follows:
 
 * If `seq` is `random` then each file size is:
@@ -1563,40 +1754,40 @@ The sequence parameter is applied as follows:
   * size +/- (inc * rand())
   * Where rand is a random number between 0 and 1
   * Note that file size must not be negative, inc will be set to size if it is greater than size
-  * Similarly, overall file size must be less than 8 * 2^60. If size + inc is greater, inc will be reduced to limit size + inc to 7 * 2^60.
+  * Similarly, overall file size must be less than 8*2<sup>60</sup>. If size + inc is greater, inc will be reduced to limit size + inc to 7*2<sup>60</sup>.
 
 * If `seq` is `sequential` then each file size is:
 
-  * size + ((fileindex - 1) * inc)
+  * `size + ((fileindex - 1) * inc)`
   * Where first file is index 1
-  * So file1 is size bytes, file2 is size + inc bytes, file3 is size + inc * 2 bytes, etc.
-  * As with random, inc will be adjusted if size + (count * inc) is not less then 8 ^ 2^60.
+  * So file1 is `size` bytes, file2 is `size + inc` bytes, file3 is `size + inc * 2` bytes, etc.
+  * As with `random`, `inc` will be adjusted if `size + (count * inc)` is not less then 8*2<sup>60</sup>.
 
-Filenames generated are of the form: `<file>_<00000 . . . count>_<filesize>`
+Filenames generated are of the form: `<file>_<00000 ... count>_<filesize>`
 
 To discard data at the destination, the destination argument is set to `faux://` .
 
 Examples:
 
-* Upload 20 gigabytes of random data to file myfile to directory /Upload
+* Upload 20 gibibytes of random data to file myfile to directory /Upload
 
 ```
-$ ascli server upload faux:///myfile\?20g --to-folder=/Upload
+ascli server upload faux:///myfile\?20g --to-folder=/Upload
 ```
 
 * Upload a file /tmp/sample but do not save results to disk (no docroot on destination)
 
 ```
-$ ascli server upload /tmp/sample --to-folder=faux://
+ascli server upload /tmp/sample --to-folder=faux://
 ```
 
-* Upload a faux directory `mydir` containing 1 million files, sequentially with sizes ranging from 0 to 2 M - 2 bytes, with the basename of each file being `testfile` to /Upload
+* Upload a faux directory `mydir` containing 1 million files, sequentially with sizes ranging from 0 to 2 Mebibyte - 2 bytes, with the basename of each file being `testfile` to /Upload
 
 ```
-$ ascli server upload "faux:///mydir?file=testfile&count=1m&size=0&inc=2&seq=sequential" --to-folder=/Upload
+ascli server upload "faux:///mydir?file=testfile&count=1m&size=0&inc=2&seq=sequential" --to-folder=/Upload
 ```
 
-## <a name="commands"></a>Sample Commands
+## <a id="commands"></a>Sample Commands
 
 A non complete list of commands used in unit tests:
 
@@ -1606,20 +1797,20 @@ 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 --id=akibmcloud --secret=somesecret node browse /
-ascli aoc admin ats access_key --id=akibmcloud delete
 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 --id=1f412ae7-869a-445c-9c05-02ad16813be2
+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 --id=my_clt_reg_id delete
 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
@@ -1629,23 +1820,23 @@ 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
+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=AOC_NODE1_NAME --secret=AOC_NODE1_SECRET v3 access_key create --value=@json:'{"id":"testsub1","storage":{"path":"/folder1"}}'
-ascli aoc admin resource node --name=AOC_NODE1_NAME --secret=AOC_NODE1_SECRET v3 access_key delete --id=testsub1
 ascli aoc admin resource node --name=AOC_NODE1_NAME --secret=AOC_NODE1_SECRET v3 events
 ascli aoc admin resource node --name=AOC_NODE1_NAME --secret=AOC_NODE1_SECRET v4 browse /
 ascli aoc admin resource node --name=AOC_NODE1_NAME --secret=AOC_NODE1_SECRET v4 delete /folder1
 ascli aoc admin resource node --name=AOC_NODE1_NAME --secret=AOC_NODE1_SECRET v4 mkdir /folder1
+ascli aoc admin resource node v3 name AOC_NODE1_NAME --secret=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 --id="my_wf_id" action create --value=@json:'{"name":"toto"}' | tee action.info
+ascli aoc automation workflow "my_wf_id" action create --value=@json:'{"name":"toto"}' | tee action.info
 ascli aoc automation workflow create --value=@json:'{"name":"test_workflow"}'
-ascli aoc automation workflow delete --id="my_wf_id"
+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 > test
 ascli aoc automation workflow list --value=@json:'{"show_org_workflows":"true"}' --scope=admin:all
@@ -1657,7 +1848,7 @@ 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 --id=my_file_id show
+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
@@ -1674,8 +1865,8 @@ 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_id":"my_shbxid","sort":"-received_at","archived":false,"received":true,"has_content":true,"exclude_dropbox_packages":false}'
-ascli aoc packages recv --id="my_package_id" --to-folder=.
-ascli aoc packages recv --id=ALL --to-folder=. --once-only=yes --lock-port=12345
+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":["external.user@example.com"]}' --new-user-option=@json:'{"package_contact":true}' testfile.bin
 ascli aoc packages send --value=@json:'{"name":"Important files delivery","recipients":["internal.user@example.com"],"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"]}' testfile.bin
@@ -1686,20 +1877,20 @@ ascli aoc user info show
 ascli aoc user shared_inboxes
 ascli aoc user workspaces
 ascli aoc workspace
-ascli ats access_key --id=ak_aws delete
-ascli ats access_key --id=akibmcloud --secret=somesecret cluster
-ascli ats access_key --id=akibmcloud --secret=somesecret node browse /
-ascli ats access_key --id=akibmcloud delete
+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 --id=1f412ae7-869a-445c-9c05-02ad16813be2
+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
@@ -1713,6 +1904,8 @@ 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
@@ -1725,34 +1918,35 @@ 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 --id=self show
+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 health
 ascli faspex package list
-ascli faspex package list --box=sent --fields=package_id --format=csv --display=data|tail -n 1);\
-ascli faspex package list --fields=package_id --format=csv --display=data|tail -n 1);\
-ascli faspex package recv --to-folder=. --box=sent --id="my_package_id"
-ascli faspex package recv --to-folder=. --id="my_package_id"
-ascli faspex package recv --to-folder=. --id=ALL --once-only=yes
+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 recv "my_package_id" --to-folder=.
+ascli faspex package recv "my_package_id" --to-folder=. --box=sent
+ascli faspex package recv --to-folder=. "my_package_id"
 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 send --delivery-info=@json:'{"title":"Important files delivery","recipients":["internal.user@example.com","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 faspex5 node list --value=@json:'{"type":"received","subtype":"mypackages"}'
 ascli faspex5 package list --value=@json:'{"mailbox":"inbox","state":["released"]}'
-ascli faspex5 package receive --id="my_package_id" --to-folder=.
+ascli faspex5 package receive "my_package_id" --to-folder=.
 ascli faspex5 package send --value=@json:'{"title":"test title","recipients":[{"name":"${f5_user}"}]}' testfile.bin
 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 --id=aoc_1
-ascli node async --id=1 bandwidth 
-ascli node async --id=1 counters 
-ascli node async --id=1 files 
+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 --id=1
-ascli node async show --id=ALL
+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
@@ -1761,8 +1955,8 @@ ascli node download --to-folder=. folder_1/testfile.bin
 ascli node health
 ascli node info
 ascli node search / --value=@json:'{"sort":"mtime"}'
-ascli node service --id=service1 delete
 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"}'
@@ -1770,12 +1964,12 @@ ascli node upload --to-folder=folder_1 --ts=@json:'{"target_rate_cap_kbps":10000
 ascli orchestrator info
 ascli orchestrator plugins
 ascli orchestrator processes
-ascli orchestrator workflow --id=ORCH_WORKFLOW_ID inputs
-ascli orchestrator workflow --id=ORCH_WORKFLOW_ID start --params=@json:'{"Param":"world !"}'
-ascli orchestrator workflow --id=ORCH_WORKFLOW_ID start --params=@json:'{"Param":"world !"}' --result=ResultStep:Complete_status_message
-ascli orchestrator workflow --id=ORCH_WORKFLOW_ID status
+ascli orchestrator workflow inputs ORCH_WORKFLOW_ID
 ascli orchestrator workflow list
-ascli orchestrator workflow status
+ascli orchestrator workflow start ORCH_WORKFLOW_ID --params=@json:'{"Param":"world !"}'
+ascli orchestrator workflow start ORCH_WORKFLOW_ID --params=@json:'{"Param":"world !"}' --result=ResultStep:Complete_status_message
+ascli orchestrator workflow status ALL
+ascli orchestrator workflow status 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
@@ -1831,12 +2025,12 @@ ascli sync start --parameters=@json:'{"sessions":[{"name":"test","reset":true,"r
 ...and more
 ```
 
-## <a name="usage"></a>Usage
+## <a id="usage"></a>Usage
 
 ```
-$ ascli -h
+ascli -h
 NAME
-	ascli -- a command line tool for Aspera Applications (v4.4.0)
+	ascli -- a command line tool for Aspera Applications (v4.5.0)
 
 SYNOPSIS
 	ascli COMMANDS [OPTIONS] [ARGS]
@@ -1846,10 +2040,11 @@ DESCRIPTION
 	Documentation and examples: https://rubygems.org/gems/aspera-cli
 	execute: ascli conf doc
 	or visit: http://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
+	any option can be set as an environment variable, refer to the manual
 
 COMMANDS
 	To list first level commands, execute: ascli
@@ -1857,7 +2052,8 @@ COMMANDS
 
 OPTIONS
 	Options begin with a '-' (minus), and value is provided on command line.
-	Special values are supported beginning with special prefix, like: @base64: @json: @zlib: @ruby: @csvt: @lines: @list: @val: @file: @path: @env: @stdin:.
+	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, stdin, preset
 	Dates format is 'DD-MM-YY HH:MM:SS', or 'now' or '-<num>h'
 
 ARGS
@@ -1883,11 +2079,13 @@ OPTIONS: global
         --logger=ENUM                log method: stderr, stdout, syslog
         --lock-port=VALUE            prevent dual execution of a command, e.g. in cron
         --query=VALUE                additional filter for API calls (extended value) (some commands)
+        --http-options=VALUE         options for http socket (extended value)
         --insecure=ENUM              do not validate HTTPS certificate: yes, no
         --once-only=ENUM             process only new items (some commands): yes, no
+        --log-passwords=ENUM         show passwords in logs: yes, no
 
 COMMAND: config
-SUBCOMMANDS: gem_path genkey plugins flush_tokens list overview open echo id documentation wizard export_to_cli detect coffee ascp email_test smtp_settings proxy_check folder file check_update initdemo
+SUBCOMMANDS: list overview id preset open documentation genkey gem_path plugins flush_tokens echo wizard export_to_cli detect coffee ascp email_test smtp_settings proxy_check folder file check_update initdemo vault
 OPTIONS:
         --value=VALUE                extended value for create, update, list filter
         --property=VALUE             name of property to set
@@ -1898,14 +2096,14 @@ OPTIONS:
         --use-generic-client=ENUM    Wizard: AoC: use global or org specific jwt client id: yes, no
         --default=ENUM               Wizard: set as default configuration for specified plugin (also: update): yes, no
         --test-mode=ENUM             Wizard: skip private key check step: yes, no
+    -P, --presetVALUE                load the named option preset from current config file
         --pkeypath=VALUE             Wizard: path to private key for JWT
         --ascp-path=VALUE            path to ascp
         --use-product=VALUE          use ascp from specified product
         --smtp=VALUE                 smtp configuration (extended value: hash)
         --fpac=VALUE                 proxy auto configuration URL
-    -P, --presetVALUE                load the named option preset from current config file
         --secret=VALUE               default secret
-        --secrets=VALUE              secret repository (Hash)
+        --secrets=VALUE              secret vault
         --sdk-url=VALUE              URL to get SDK
         --sdk-folder=VALUE           SDK folder path
         --notif-to=VALUE             email recipient for notification of transfers
@@ -1917,7 +2115,7 @@ OPTIONS:
         --sources=VALUE              list of source files (see doc)
         --transfer-info=VALUE        parameters for transfer agent
         --src-type=ENUM              type of file list: list, pair
-        --transfer=ENUM              type of transfer agent: direct, httpgw, connect, node
+        --transfer=ENUM              type of transfer agent: direct, node, connect, httpgw, trsdk
         --progress=ENUM              type of progress bar: none, native, multi
 
 
@@ -1988,11 +2186,11 @@ 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            API client identifier in application
-        --client-secret=VALUE        API client secret in application
-        --redirect-uri=VALUE         API client redirect URI
-        --auth=ENUM                  type of Oauth authentication: body_userpass, header_userpass, web, jwt, url_token, ibm_apikey, boot
-        --private-key=VALUE          RSA private key PEM value for JWT (prefix file path with @val:@file:)
+        --client-id=VALUE            OAuth client identifier
+        --client-secret=VALUE        OAuth client secret
+        --redirect-uri=VALUE         OAuth redirect URI
+        --auth=ENUM                  OAuth type of authentication: body_userpass, header_userpass, web, jwt, url_token, ibm_apikey, boot
+        --private-key=VALUE          Oauth RSA private key PEM value for JWT (prefix file path with @val:@file:)
 
 
 COMMAND: cos
@@ -2120,34 +2318,18 @@ OPTIONS:
 
 Note that actions and parameter values can be written in short form.
 
-# <a name="plugins"></a>Plugins: Application URL and Authentication
-
-`ascli` comes with several Aspera application plugins.
-
-REST APIs of Aspera legacy applications (Aspera Node, Faspex, Shares, Console, Orchestrator, Server) use simple username/password authentication: HTTP Basic Authentication.
-
-Those are using options:
-
-* url
-* username
-* password
-
-Those can be provided using command line, parameter set, env var, see section above.
-
-Aspera on Cloud relies on Oauth, refer to the [Aspera on Cloud](#aoc) section.
-
-# <a name="aoc"></a>Plugin: Aspera on Cloud
+# <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.
 
-## <a name="aocwizard"></a>Configuration: using Wizard
+## <a id="aocwizard"></a>Configuration: using Wizard
 
 `ascli` provides a configuration wizard. Here is a sample invocation :
 
 ```
-$ ascli config wizard
+ascli config wizard
 option: url> https://myorg.ibmaspera.com
 Detected: Aspera on Cloud
 Preparing preset: aoc_myorg
@@ -2163,7 +2345,7 @@ Setting config preset as default for aspera
 saving config file
 Done.
 You can test with:
-$ ascli aoc user info show
+ascli aoc user info show
 ```
 
 Optionally, it is possible to create a new organization-specific "integration".
@@ -2171,7 +2353,7 @@ For this, specify the option: `--use-generic-client=no`.
 
 This will guide you through the steps to create.
 
-## <a name="aocmanual"></a>Configuration: using manual setup
+## <a id="aocmanual"></a>Configuration: using manual setup
 
 If you used the wizard (recommended): skip this section.
 
@@ -2183,7 +2365,7 @@ Several types of OAuth authentication are supported:
 * Web based authentication : authentication is made by user using a browser
 * URL Token : external users authentication with url tokens (public links)
 
-The authentication method is controled by option `auth`.
+The authentication method is controlled by option `auth`.
 
 For a _quick start_, follow the mandatory and sufficient section: [API Client Registration](#clientreg) (auth=web) as well as [[option preset](#lprt) for Aspera on Cloud](#aocpreset).
 
@@ -2191,7 +2373,7 @@ For a more convenient, browser-less, experience follow the [JWT](#jwt) section (
 
 In Oauth, a "Bearer" token are generated to authenticate REST calls. Bearer tokens are valid for a period of time.`ascli` saves generated tokens in its configuration folder, tries to re-use them or regenerates them when they have expired.
 
-### <a name="clientreg"></a>Optional: API Client Registration
+### <a id="clientreg"></a>Optional: API Client Registration
 
 If you use the built-in client_id and client_secret, skip this and do not set them in next section.
 
@@ -2215,31 +2397,31 @@ Note: for web based authentication, `ascli` listens on a local port (e.g. specif
 
 Once the client is registered, a "Client ID" and "Secret" are created, these values will be used in the next step.
 
-### <a name="aocpreset"></a>[option preset](#lprt) for Aspera on Cloud
+### <a id="aocpreset"></a>[option preset](#lprt) for Aspera on Cloud
 
 If you did not use the wizard, you can also manually create a [option preset](#lprt) for `ascli` in its configuration file.
 
 Lets create an [option preset](#lprt) called: `my_aoc_org` using `ask` interactive input (client info from previous step):
 
 ```
-$ ascli config id my_aoc_org ask url client_id client_secret
+ascli config preset ask my_aoc_org url client_id client_secret
 option: url> https://myorg.ibmaspera.com/
 option: client_id> BJLPObQiFw
 option: client_secret> yFS1mu-crbKuQhGFtfhYuoRW...
 updated: my_aoc_org
 ```
 
-(This can also be done in one line using the command `config id my_aoc_org update --url=...`)
+(This can also be done in one line using the command `config preset update my_aoc_org --url=...`)
 
 Define this [option preset](#lprt) as default configuration for the `aspera` plugin:
 
 ```
-$ ascli config id default set aoc my_aoc_org
+ascli config preset set default aoc my_aoc_org
 ```
 
 Note: Default `auth` method is `web` and default `redirect_uri` is `http://localhost:12345`. Leave those default values.
 
-### <a name="jwt"></a>Activation of JSON Web Token (JWT) for direct authentication
+### <a id="jwt"></a>Activation of JSON Web Token (JWT) for direct authentication
 
 For a Browser-less, Private Key-based authentication, use the following steps.
 
@@ -2254,13 +2436,13 @@ This can be done using any of the following method:
 * using the CLI:
 
 ```
-$ ascli config genkey ~/.aspera/ascli/aocapikey
+ascli config genkey ~/.aspera/ascli/aocapikey
 ```
 
 * `ssh-keygen`:
 
 ```
-$ ssh-keygen -t rsa -f ~/.aspera/ascli/aocapikey -N ''
+ssh-keygen -t rsa -f ~/.aspera/ascli/aocapikey -N ''
 ```
 
 * `openssl`
@@ -2268,11 +2450,11 @@ $ ssh-keygen -t rsa -f ~/.aspera/ascli/aocapikey -N ''
 (on some openssl implementation (mac) there is option: -nodes (no DES))
 
 ```
-$ APIKEY=~/.aspera/ascli/aocapikey
-$ 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
+APIKEY=~/.aspera/ascli/aocapikey
+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
 ```
 
 #### API Client JWT activation
@@ -2291,13 +2473,13 @@ If you are not using the built-in client_id and secret, JWT needs to be authoriz
 * Using command line
 
 ```
-$ ascli aoc admin res client list
+ascli aoc admin res client list
 :............:.........:
 :     id     :  name   :
 :............:.........:
 : BJLPObQiFw : ascli :
 :............:.........:
-$ ascli aoc admin res client --id=BJLPObQiFw modify @json:'{"jwt_grant_enabled":true,"explicit_authorization_required":false}'
+ascli aoc admin res client modify --id=BJLPObQiFw @json:'{"jwt_grant_enabled":true,"explicit_authorization_required":false}'
 modified
 ```
 
@@ -2318,14 +2500,14 @@ open the previously generated public key located here: `$HOME/.aspera/ascli/aoca
 * Using command line
 
 ```
-$ ascli aoc admin res user list
+ascli aoc admin res user list
 :........:................:
 :   id   :      name      :
 :........:................:
 : 109952 : Tech Support   :
 : 109951 : LAURENT MARTIN :
 :........:................:
-$ ascli aoc user info modify @ruby:'{"public_key"=>File.read(File.expand_path("~/.aspera/ascli/aocapikey.pub"))}'
+ascli aoc user info modify @ruby:'{"public_key"=>File.read(File.expand_path("~/.aspera/ascli/aocapikey.pub"))}'
 modified
 ```
 
@@ -2333,7 +2515,7 @@ Note: the `aspera user info show` command can be used to verify modifications.
 
 ### [option preset](#lprt) modification for JWT
 
-To activate default use of JWT authentication for `ascli` using the [option preset](#lprt), do the folowing:
+To activate default use of JWT authentication for `ascli` using the [option preset](#lprt), do the following:
 
 * change auth method to JWT
 * provide location of private key
@@ -2342,7 +2524,7 @@ To activate default use of JWT authentication for `ascli` using the [option pres
 Execute:
 
 ```
-$ ascli config id my_aoc_org update --auth=jwt --private-key=@val:@file:~/.aspera/ascli/aocapikey --username=laurent.martin.aspera@fr.ibm.com
+ascli config preset update my_aoc_org --auth=jwt --private-key=@val:@file:~/.aspera/ascli/aocapikey --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.
@@ -2350,26 +2532,29 @@ Note: the private key argument represents the actual PEM string. In order to rea
 After this last step, commands do not require web login anymore.
 
 
-### <a name="aocfirst"></a>First Use
+### <a id="aocfirst"></a>First Use
 
 Once client has been registered and [option preset](#lprt) created: `ascli` can be used:
 
 ```
-$ ascli aoc files br /
+ascli aoc files br /
 Current Workspace: Default Workspace (default)
 empty
 ```
 
 
-### Administration
+## 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 operations are possible using option `bulk` (yes,no(default)): currently: create only. In that case, the operation expects an Array of Hash instead of a simple Hash using the [Extended Value Syntax](#extended).
+### Bulk creation and deletion of resource 
 
-#### Listing resources
+Bulk creation and deletion of resources are possible using option `bulk` (yes,no(default)).
+In that case, the operation expects an Array of Hash instead of a simple Hash using the [Extended Value Syntax](#extended).
+
+### Listing resources
 
 The command `aoc admin res <type> list` lists all entities of given type. It uses paging and multiple requests if necessary.
 
@@ -2391,7 +2576,7 @@ Other parameters are directly sent as parameters to the GET request on API.
 
 `page` and `per_page` are normally added by `ascli` to build successive API calls to get all values if there are more than 1000. (AoC allows a maximum page size of 1000).
 
-`q` and `sort` are available on most resrouce types.
+`q` and `sort` are available on most resource types.
 
 Other parameters depend on the type of entity (refer to AoC API).
 
@@ -2403,7 +2588,7 @@ Examples:
 ascli aoc admin res user list --query=--query=@json:'{"q":"laurent"}'
 ```
 
-* List users who logded-in before a date:
+* List users who logged-in before a date:
 
 ```
 ascli aoc admin res user list --query=@json:'{"q":"last_login_at:<2018-05-28"}'
@@ -2419,40 +2604,85 @@ Refer to the AoC API for full list of query parameters, or use the browser in de
 
 Note the option `select` can also be used to further refine selection, refer to [section earlier](#option_select).
 
-#### Access Key secrets
+### <a id="res_select"></a>Selecting a resource
+
+Resources are identified by a unique `id`, as well as a unique `name` (case insensitive).
+
+To execute an action on a specific resource, select it using one of those methods:
 
-In order to access some administrative actions on "nodes" (in fact, access keys), the associated
-secret is required, it is usually provided using the `secret` option. For example in a command like:
+* *recommended:* give id directly on command line *after the action*: `aoc admin res node show 123`
+* give name on command line *after the action*: `aoc admin res node show name abc`
+* provide option `id` : `aoc admin res node show --id=123`
+* provide option `name` : `aoc admin res node show --name=abc`
+
+### Access Key secrets
+
+In order to access some administrative actions on "nodes" (in fact, access keys), the associated secret is required.
+It is usually provided using the `secret` option.
+For example in a command like:
 
 ```
-$ ascli aoc admin res node --id="access_key1" --secret="secret1" v3 info
+ascli aoc admin res node --id=123 --secret="secret1" v3 info
 ```
 
-It is also possible to provide a set of secrets used on a regular basis. This can be done using the `secrets` option. The value provided shall be a Hash, where keys are access key ids, and values are the associated secrets.
+It is also possible to provide a set of secrets used on a regular basis using the [secret vault](#vault).
 
-First choose a repository name, for example `my_secrets`, and populate it like this:
+### Activity
+
+The activity app can be queried with:
 
 ```
-$ ascli conf id my_secrets set 'access_key1' 'secret1'
-$ ascli conf id my_secrets set 'access_key2' 'secret2'
-$ ascli conf id default get config
-"cli_default"
+ascli aoc admin analytics transfers
 ```
 
-Here above, one already has set a `config` global preset to preset `cli_default` (refer to earlier in documentation), then the repository can be read by default like this (note the prefix `@val:` to avoid the evaluation of prefix `@preset:`):
+It can also support filters and send notification using option `notif_to`. a template is defined using option `notif_template` :
+
+`mytemplate.erb`:
 
 ```
-$ ascli conf id cli_default set secrets @val:@preset:my_secrets
+From: <%=from_name%> <<%=from_email%>>
+To: <<%=ev['user_email']%>>
+Subject: <%=ev['files_completed']%> files received
+
+Dear <%=ev[:user_email.to_s]%>,
+We received <%=ev['files_completed']%> files for a total of <%=ev['transferred_bytes']%> bytes, starting with file:
+<%=ev['content']%>
+
+Thank you.
 ```
+The environment provided contains the following additional variable:
 
-A secret repository can always be selected at runtime using `--secrets=@preset:xxxx`, or `--secrets=@json:'{"accesskey1":"secret1"}'`
+* ev : all details on the transfer event
+
+Example:
 
-#### Examples
+```
+ascli aoc admin analytics transfers --once-only=yes --lock-port=12345 \
+--query=@json:'{"status":"completed","direction":"receive"}' \
+--notif-to=active --notif-template=@file:mytemplate.erb
+```
 
-* Bulk creation
+Options:
+
+* `once_only` keep track of last date it was called, so next call will get only new events
+* `query` filter (on API call)
+* `notify` send an email as specified by template, this could be places in a file with the `@file` modifier.
+
+Note this must not be executed in less than 5 minutes because the analytics interface accepts only a period of time between 5 minutes and 6 months. The period is [date of previous execution]..[now].
+
+### Transfer: Using specific transfer ports
+
+By default transfer nodes are expected to use ports TCP/UDP 33001. The web UI enforces that.
+The option `default_ports` ([yes]/no) allows ascli to retrieve the server ports from an API call (download_setup) which reads the information from `aspera.conf` on the server.
+
+### Using ATS
+
+Refer to section "Examples" of [ATS](#ats) and substitute command `ats` with `aoc admin ats`.
+
+### Example: Bulk creation of users
 
 ```
-$ ascli aoc admin res user create --bulk=yes @json:'[{"email":"dummyuser1@example.com"},{"email":"dummyuser2@example.com"}]'
+ascli aoc admin res user create --bulk=yes @json:'[{"email":"dummyuser1@example.com"},{"email":"dummyuser2@example.com"}]'
 :.......:.........:
 :  id   : status  :
 :.......:.........:
@@ -2461,20 +2691,20 @@ $ ascli aoc admin res user create --bulk=yes @json:'[{"email":"dummyuser1@exampl
 :.......:.........:
 ```
 
-* Find with filter and delete
+### Example: Find with filter and delete
 
 ```
-$ ascli aoc admin res user list --query='@json:{"q":"dummyuser"}' --fields=id,email
+ascli aoc admin res user list --query='@json:{"q":"dummyuser"}' --fields=id,email
 :.......:........................:
 :  id   :         email          :
 :.......:........................:
 : 98398 : dummyuser1@example.com :
 : 98399 : dummyuser2@example.com :
 :.......:........................:
-$ thelist=$(ascli aoc admin res user list --query='@json:{"q":"dummyuser"}' --fields=id --format=json --display=data|jq -cr 'map(.id)')
-$ echo $thelist
+thelist=$(ascli aoc admin res user list --query='@json:{"q":"dummyuser"}' --fields=id --format=json --display=data|jq -cr 'map(.id)')
+echo $thelist
 ["113501","354061"]
-$ ascli aoc admin res user --bulk=yes --id=@json:"$thelist" delete
+ascli aoc admin res user --bulk=yes --id=@json:"$thelist" delete
 :.......:.........:
 :  id   : status  :
 :.......:.........:
@@ -2483,7 +2713,7 @@ $ ascli aoc admin res user --bulk=yes --id=@json:"$thelist" delete
 :.......:.........:
 ```
 
-* <a name="deactuser"></a>Find deactivated users since more than 2 years
+### Example: <a id="deactuser"></a>Find deactivated users since more than 2 years
 
 ```
 ascli aoc admin res user list --query=@ruby:'{"deactivated"=>true,"q"=>"last_login_at:<#{(DateTime.now.to_time.utc-2*365*86400).iso8601}"}'
@@ -2491,10 +2721,10 @@ ascli aoc admin res user list --query=@ruby:'{"deactivated"=>true,"q"=>"last_log
 
 To delete them use the same method as before
 
-* Display current user's workspaces
+### Example: Display current user's workspaces
 
 ```
-$ ascli aoc user workspaces
+ascli aoc user workspaces
 :......:............................:
 :  id  :            name            :
 :......:............................:
@@ -2504,18 +2734,18 @@ $ ascli aoc user workspaces
 :......:............................:
 ```
 
-* Create a sub access key in a "node"
+### Example: Create a sub access key in a "node"
 
 Creation of a sub-access key is like creation of access key with the following difference: authentication to node API is made with accesskey (master access key) and only the path parameter is provided: it is relative to the storage root of the master key. (id and secret are optional)
 
 ```
-$ ascli aoc admin resource node --name=_node_name_ --secret=_secret_ v4 access_key create --value=@json:'{"storage":{"path":"/folder1"}}'
+ascli aoc admin resource node --name=_node_name_ --secret=_secret_ v4 access_key create --value=@json:'{"storage":{"path":"/folder1"}}'
 ```
 
-* Display transfer events (ops/transfer)
+### Example: Display transfer events (ops/transfer)
 
 ```
-$ ascli aoc admin res node --secret=_secret_ v3 transfer list --value=@json:'[["q","*"],["count",5]]'
+ascli aoc admin res node --secret=_secret_ v3 transfer list --value=@json:'[["q","*"],["count",5]]'
 ```
 
 Examples of query (TODO: cleanup):
@@ -2533,16 +2763,16 @@ Examples of query (TODO: cleanup):
               # active_only=true|false
 ```
 
-* Display node events (events)
+### Example: Display node events (events)
 
 ```
-$ ascli aoc admin res node --secret=_secret_ v3 events
+ascli aoc admin res node --secret=_secret_ v3 events
 ```
 
-* display members of a workspace
+### Example: Display members of a workspace
 
 ```
-$ ascli aoc admin res workspace_membership list --fields=member_type,manager,member.email --query=@json:'{"embed":"member","inherited":false,"workspace_id":11363,"sort":"name"}'
+ascli aoc admin res workspace_membership list --fields=member_type,manager,member.email --query=@json:'{"embed":"member","inherited":false,"workspace_id":11363,"sort":"name"}'
 :.............:.........:..................................:
 : member_type : manager :           member.email           :
 :.............:.........:..................................:
@@ -2561,7 +2791,7 @@ other query parameters:
 {"workspace_membership_through":true,"include_indirect":true}
 ```
 
-* <a name="aoc_sample_member"></a>add all members of a workspace to another workspace
+### Example: <a id="aoc_sample_member"></a>add all members of a workspace to another workspace
 
 a- Get id of first workspace
 
@@ -2580,7 +2810,7 @@ WS2ID=$(ascli aoc admin res workspace list --query=@json:'{"q":"'"$WS2"'"}' --se
 c- Extract membership information
 
 ```
-$ ascli aoc admin res workspace_membership list --fields=manager,member_id,member_type,workspace_id --query=@json:'{"workspace_id":'"$WS1ID"'}' --format=jsonpp > ws1_members.json
+ascli aoc admin res workspace_membership list --fields=manager,member_id,member_type,workspace_id --query=@json:'{"workspace_id":'"$WS1ID"'}' --format=jsonpp > ws1_members.json
 ```
 
 d- Convert to creation data for second workspace:
@@ -2598,13 +2828,13 @@ jq '[.[] | {member_type,member_id,workspace_id,manager,workspace_id:"'"$WS2ID"'"
 e- Add members to second workspace
 
 ```
-$ ascli aoc admin res workspace_membership create --bulk=yes @json:@file:ws2_members.json
+ascli aoc admin res workspace_membership create --bulk=yes @json:@file:ws2_members.json
 ```
 
-* Get users who did not log since a date
+### Example: Get users who did not log since a date
 
 ```
-$ ascli aoc admin res user list --fields=email --query=@json:'{"q":"last_login_at:<2018-05-28"}'
+ascli aoc admin res user list --fields=email --query=@json:'{"q":"last_login_at:<2018-05-28"}'
 :...............................:
 :             email             :
 :...............................:
@@ -2613,20 +2843,20 @@ $ ascli aoc admin res user list --fields=email --query=@json:'{"q":"last_login_a
 :...............................:
 ```
 
-* List "Limited" users
+### Example: List "Limited" users
 
 ```
-$ ascli aoc admin res user list --fields=email --select=@json:'{"member_of_any_workspace":false}'
+ascli aoc admin res user list --fields=email --select=@json:'{"member_of_any_workspace":false}'
 ```
 
-* Perform a multi Gbps transfer between two remote shared folders
+### 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 differente sites, e.g. different cloud regions.
+In this example, a user has access to a workspace where two shared folders are located on different sites, e.g. different cloud regions.
 
 First, setup the environment (skip if already done)
 
 ```
-$ ascli conf wizard --url=https://sedemo.ibmaspera.com --username=laurent.martin.aspera@fr.ibm.com
+ascli conf wizard --url=https://sedemo.ibmaspera.com --username=laurent.martin.aspera@fr.ibm.com
 Detected: Aspera on Cloud
 Preparing preset: aoc_sedemo
 Using existing key:
@@ -2645,7 +2875,7 @@ Setting config preset as default for aspera
 saving config file
 Done.
 You can test with:
-$ ascli aoc user info show
+ascli aoc user info show
 ```
 
 This creates the option preset "aoc_&lt;org name&gt;" to allow seamless command line access and sets it as default for aspera on cloud.
@@ -2655,20 +2885,20 @@ Then, create two shared folders located in two regions, in your files home, in a
 Then, transfer between those:
 
 ```
-$ ascli -Paoc_show aoc files transfer --from-folder='IBM Cloud SJ' --to-folder='AWS Singapore' 100GB.file --ts=@json:'{"target_rate_kbps":"1000000","multi_session":10,"multi_session_threshold":1}'
+ascli -Paoc_show aoc files transfer --from-folder='IBM Cloud SJ' --to-folder='AWS Singapore' 100GB.file --ts=@json:'{"target_rate_kbps":"1000000","multi_session":10,"multi_session_threshold":1}'
 ```
 
-* create registration key to register a node
+### Example: create registration key to register a node
 
 ```
-$ ascli aoc admin res admin/client create @json:'{"data":{"name":"laurentnode","client_subject_scopes":["alee","aejd"],"client_subject_enabled":true}}' --fields=token --format=csv
+ascli aoc admin res client create @json:'{"data":{"name":"laurentnode","client_subject_scopes":["alee","aejd"],"client_subject_enabled":true}}' --fields=token --format=csv
 jfqslfdjlfdjfhdjklqfhdkl
 ```
 
-* delete all registration keys
+### Example: delete all registration keys
 
 ```
-$ ascli aoc admin res admin/client list --fields=id --format=csv|ascli aoc admin res admin/client delete --bulk=yes --id=@lines:@stdin:
+ascli aoc admin res client list --fields=id --format=csv|ascli aoc admin res client delete --bulk=yes --id=@lines:@stdin:
 +-----+---------+
 | id  | status  |
 +-----+---------+
@@ -2679,81 +2909,107 @@ $ ascli aoc admin res admin/client list --fields=id --format=csv|ascli aoc admin
 +-----+---------+
 ```
 
-* List packages in a given shared inbox
+### Example: Create a node
 
-First retrieve the id of the shared inbox, and then list packages with the appropriate filter.
-(To find out available filters, consult the API definition, or use the web interface in developer mode).
+AoC nodes as actually composed with two related entities:
 
-Note that when no query is provided, the query used by default is: `{"archived":false,"exclude_dropbox_packages":true,"has_content":true,"received":true}`. The workspace id is added if not already present in the query.
+* An access key created on the Transfer Server (HSTS/ATS)
+* a `node` resource in the AoC application.
 
-```
-shbxid=$(ascli aoc user shared_inboxes --select=@json:'{"dropbox.name":"My Shared Inbox"}' --format=csv --fields=dropbox_id --display=data)
+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.
 
-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"}'
+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
+
+```
+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":"/"}}'
 ```
 
-## Shared folders
+Take a note of the randomly generated `id` and `secret`.
 
-* list shared folders in node
+* Retrieve the ATS node address
 
 ```
-$ ascli aoc admin res node --id=8669 shared_folders
+ascli aoc admin ats cluster show --cloud=softlayer --region=eu-de --fields=transfer_setup_url --format=csv|cut -f2 -d,
 ```
 
-* list shared folders in workspace
+* Create the node entity
 
 ```
-$ ascli aoc admin res workspace --id=10818 shared_folders
+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"}'
 ```
 
-* list members of shared folder
+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.
+
+### Example: List packages in a given shared inbox
+
+First retrieve the id of the shared inbox, and then list packages with the appropriate filter.
+(To find out available filters, consult the API definition, or use the web interface in developer mode).
+
+Note that when no query is provided, the query used by default is: `{"archived":false,"exclude_dropbox_packages":true,"has_content":true,"received":true}`. The workspace id is added if not already present in the query.
 
 ```
-$ ascli aoc admin res node --id=8669 v4 perm 82 show
+shbxid=$(ascli aoc user shared_inboxes --select=@json:'{"dropbox.name":"My Shared Inbox"}' --format=csv --fields=dropbox_id --display=data)
+
+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"}'
 ```
 
-## Send a Package
+## Packages
+
+The webmail-like application.
+
+### Send a Package
 
 Send a package:
 
 ```
-$ ascli aoc packages send --value=[package extended value] [other parameters such as file list and transfer parameters]
+ascli aoc packages send --value=[package extended value] [other parameters such as file list and transfer parameters]
 ```
 
 Notes:
 
-* the `value` parameter can contain any supported package creation parameter. Refer to the AoC package creation API, or display an existing package to find attributes.
-* to provide the list of recipients, use fields: "recipients" and/or "bcc_recipients". ascli will resolve the list of email addresses to expected user ids.
-* a recipient can be a shared inbox, in this case just use the name of the shared inbox as recipient.
-* If a recipient is not already registered and the workspace allows external users, then the package is sent to an external user, and
-  * if the option `new_user_option` is `@json:{"package_contact":true}` (default), then a public link is sent and the external user does not need to create an account.
+* The `value` option can contain any supported package creation parameter. Refer to the AoC package creation API, or display an existing package in JSON to list attributes.
+* List allowed shared inbox destinations with: `ascli aoc user shared_inboxes`
+* Use fields: `recipients` and/or `bcc_recipients` to provide the list of recipients: user or shared inbox. 
+  * Provide either ids as expected by API: `"recipients":[{"type":"dropbox","id":"1234"}]`
+  * or just names: `"recipients":[{"The Dest"}]` . ascli will resolve the list of email addresses and dropbox names to the expected type/id list, based on case insensitive partial match.
+* If a user recipient (email) is not already registered and the workspace allows external users, then the package is sent to an external user, and
+  * if the option `new_user_option` is `@json:{"package_contact":true}` (default), then a public link is sent and the external user does not need to create an account
   * if the option `new_user_option` is `@json:{}`, then external users are invited to join the workspace
 
 Examples:
 
+* Send a package with one file to two users, using their email
+
 ```
-$ ascli aoc package send --value=@json:'{"name":"my title","note":"my note","recipients":["laurent.martin.aspera@fr.ibm.com","other@example.com"]}' --sources=@args my_file.dat
+ascli aoc package send --value=@json:'{"name":"my title","note":"my note","recipients":["laurent.martin.aspera@fr.ibm.com","other@example.com"]}' my_file.dat
 ```
 
+* Send a package with one file to a shared inbox, using internal identifier, with specific transfer parameters
+
 ```
-$ ascli aoc package send --value=@json:'{"name":"my file in shared inbox","recipients":["The Shared Inbox"]}' my_file.dat --ts=@json:'{"target_rate_kbps":100000}'
+ascli aoc package send --value=@json:'{"name":"my delivery","recipients":[{"type":"dropbox","id":"12345"}]}' --ts=@json:'{"target_rate_kbps":100000}'  my_file.dat
 ```
 
+* Send a package with one file to a shared inbox (by name) with metadata
+
 ```
-$ ascli aoc package send --workspace=eudemo --value=@json:'{"name":"my pack title","recipients":["Shared Inbox Name"],"metadata":[{"input_type":"single-text","name":"Project Id","values":["123"]},{"input_type":"single-dropdown","name":"Type","values":["Opt2"]},{"input_type":"multiple-checkbox","name":"CheckThose","values":["Check1","Check2"]},{"input_type":"date","name":"Optional Date","values":["2021-01-13T15:02:00.000Z"]}]}' ~/Documents/Samples/200KB.1
+ascli aoc package send --workspace=eudemo --value=@json:'{"name":"my pack title","recipients":["Shared Inbox Name"],"metadata":[{"input_type":"single-text","name":"Project Id","values":["123"]},{"input_type":"single-dropdown","name":"Type","values":["Opt2"]},{"input_type":"multiple-checkbox","name":"CheckThose","values":["Check1","Check2"]},{"input_type":"date","name":"Optional Date","values":["2021-01-13T15:02:00.000Z"]}]}' ~/Documents/Samples/200KB.1
 ```
 
-## <a name="aoccargo"></a>Receive new packages only
+### <a id="aoccargo"></a>Receive new packages only (Cargo)
 
 It is possible to automatically download new packages, like using Aspera Cargo:
 
 ```
-$ ascli aoc packages recv --id=ALL --once-only=yes --lock-port=12345
+ascli aoc packages recv --id=ALL --once-only=yes --lock-port=12345
 ```
 
 * `--id=ALL` (case sensitive) will download all packages
-* `--once-only=yes` keeps memory of any downloaded package in persistency files located in the configuration folder.
-* `--lock-port=12345` ensures that only one instance is started at the same time, to avoid collisions
+* `--once-only=yes` keeps memory of any downloaded package in persistency files located in the configuration folder
+* `--lock-port=12345` ensures that only one instance is started at the same time, to avoid running two downloads in parallel
 
 Typically, one would execute this command on a regular basis, using the method of your choice:
 
@@ -2761,101 +3017,107 @@ Typically, one would execute this command on a regular basis, using the method o
 * Linux/Unix: [cron](https://www.man7.org/linux/man-pages/man5/crontab.5.html)
 * etc...
 
-## Download Files
+## Files
+
+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).
 
-## Find Files
-
-The command `aoc files find [--value=expression]` will recursively scan storage to find files matching the expression criteria. It works also on node resource using the v4 command. (see examples)
-
-The expression can be of 3 formats:
-
-* empty (default) : all files, equivalent to value: `exec:true`
-* not starting with `exec:` : the expression is a regular expression, using [Ruby Regex](https://ruby-doc.org/core/Regexp.html) syntax. equivalent to value: `exec:f['name'].match(/expression/)`
-
-For instance, to find files with a special extension, use `--value='\.myext$'`
-
-* starting with `exec:` : the Ruby code after the prefix is executed for each entry found. The entry variable name is `f`. The file is displayed if the result of the expression is true;
-
-Examples of expressions: (using like this: `--value=exec:'<expression>'`)
+### Shared folders
 
-* Find files more recent than 100 days
+* list shared folders in node
 
 ```
-f["type"].eql?("file") and (DateTime.now-DateTime.parse(f["modified_time"]))<100
+ascli aoc admin res node --id=8669 shared_folders
 ```
 
-* Find files older than 1 year on a given node and store in file list
+* list shared folders in workspace
 
 ```
-$ ascli aoc admin res node --name='my node name' --secret='my secret' v4 find / --fields=path --value='exec:f["type"].eql?("file") and (DateTime.now-DateTime.parse(f["modified_time"]))<100' --format=csv > my_file_list.txt
+ascli aoc admin res workspace --id=10818 shared_folders
 ```
 
-* Delete the files, one by one
+* list members of shared folder
 
 ```
-$ cat my_file_list.txt|while read path;do echo ascli aoc admin res node --name='my node name' --secret='my secret' v4 delete "$path" ;done
+ascli aoc admin res node --id=8669 v4 perm 82 show
 ```
 
-* Delete the files in bulk
+### Cross Organization transfers
 
-```
-cat my_file_list.txt | ascli aoc admin res node --name='my node name' --secret='my secret' v3 delete @lines:@stdin:
-```
+It is possible to transfer files directly between organizations without having to first download locally and then upload...
 
-## Activity
+Although optional, the creation of [option preset](#lprt) is recommended to avoid placing all parameters in the command line.
 
-The activity app can be queried with:
+Procedure to send a file from org1 to org2:
+
+* Get access to Organization 1 and create a [option preset](#lprt): e.g. `org1`, for instance, use the [Wizard](#aocwizard)
+* Check that access works and locate the source file e.g. `mysourcefile`, e.g. using command `files browse`
+* Get access to Organization 2 and create a [option preset](#lprt): e.g. `org2`
+* Check that access works and locate the destination folder `mydestfolder`
+* execute the following:
 
 ```
-$ ascli aoc admin analytics transfers
+ascli -Porg1 aoc files node_info /mydestfolder --format=json --display=data | ascli -Porg2 aoc files upload mysourcefile --transfer=node --transfer-info=@json:@stdin:
 ```
 
-It can also support filters and send notification using option `notif_to`. a template is defined using option `notif_template` :
+Explanation:
 
-`mytemplate.erb`:
+* `-Porg1 aoc` use Aspera on Cloud plugin and load credentials for `org1`
+* `files node_info /mydestfolder` generate transfer information including node api credential and root id, suitable for the next command
+* `--format=json` format the output in JSON (instead of default text table)
+* `--display=data` display only the result, and remove other information, such as workspace name
+* `|` the standard output of the first command is fed into the second one
+* `-Porg2 aoc` use Aspera on Cloud plugin and load credentials for `org2`
+* `files upload mysourcefile` upload the file named `mysourcefile` (located in `org1`)
+* `--transfer=node` use transfer agent type `node` instead of default [`direct`](#agt_direct)
+* `--transfer-info=@json:@stdin:` provide `node` transfer agent information, i.e. node API credentials, those are expected in JSON format and read from standard input
 
-```
-From: <%=from_name%> <<%=from_email%>>
-To: <<%=ev['user_email']%>>
-Subject: <%=ev['files_completed']%> files received
+### Find Files
 
-Dear <%=ev[:user_email.to_s]%>,
-We received <%=ev['files_completed']%> files for a total of <%=ev['transferred_bytes']%> bytes, starting with file:
-<%=ev['content']%>
+The command `aoc files find [--value=expression]` will recursively scan storage to find files matching the expression criteria. It works also on node resource using the v4 command. (see examples)
 
-Thank you.
-```
-The environment provided contains the following additional variable:
+The expression can be of 3 formats:
 
-* ev : all details on the transfer event
+* empty (default) : all files, equivalent to value: `exec:true`
+* not starting with `exec:` : the expression is a regular expression, using [Ruby Regex](https://ruby-doc.org/core/Regexp.html) syntax. equivalent to value: `exec:f['name'].match(/expression/)`
 
-Example:
+For instance, to find files with a special extension, use `--value='\.myext$'`
+
+* starting with `exec:` : the Ruby code after the prefix is executed for each entry found. The entry variable name is `f`. The file is displayed if the result of the expression is true;
+
+Examples of expressions: (using like this: `--value=exec:'<expression>'`)
+
+* Find files more recent than 100 days
 
 ```
-$ ascli aoc admin analytics transfers --once-only=yes --lock-port=12345 \
---query=@json:'{"status":"completed","direction":"receive"}' \
---notif-to=active --notif-template=@file:mytemplate.erb
+f["type"].eql?("file") and (DateTime.now-DateTime.parse(f["modified_time"]))<100
 ```
 
-Options:
+* Find files older than 1 year on a given node and store in file list
 
-* `once_only` keep track of last date it was called, so next call will get only new events
-* `query` filter (on API call)
-* `notify` send an email as specified by template, this could be places in a file with the `@file` modifier.
+```
+ascli aoc admin res node --name='my node name' --secret='my secret' v4 find / --fields=path --value='exec:f["type"].eql?("file") and (DateTime.now-DateTime.parse(f["modified_time"]))<100' --format=csv > my_file_list.txt
+```
 
-Note this must not be executed in less than 5 minutes because the analytics interface accepts only a period of time between 5 minutes and 6 months. The period is [date of previous execution]..[now].
+* Delete the files, one by one
 
-## Using specific transfer ports
+```
+cat my_file_list.txt|while read path;do echo ascli aoc admin res node --name='my node name' --secret='my secret' v4 delete "$path" ;done
+```
 
-By default transfer nodes are expected to use ports TCP/UDP 33001. The web UI enforces that. The option `default_ports` ([yes]/no) allows ascli to retrieve the server ports from an API call (download_setup) which reads the information from `aspera.conf` on the server.
+* Delete the files in bulk
 
+```
+cat my_file_list.txt | ascli aoc admin res node --name='my node name' --secret='my secret' v3 delete @lines:@stdin:
+```
 
-# Plugin: Aspera Transfer Service
+# <a id="ats"></a>Plugin: Aspera Transfer Service
 
 ATS is usable either :
 
@@ -2865,10 +3127,13 @@ ATS is usable either :
 
 ## IBM Cloud ATS : creation of api key
 
+This section is about using ATS with an IBM cloud subscription.
+If you are using ATS as part of AoC, then authentication is thropugh AoC, not IBM Cloud.
+
 First get your IBM Cloud APIkey. For instance, it can be created using the IBM Cloud web interface, or using command line:
 
 ```
-$ ibmcloud iam api-key-create mykeyname -d 'my sample key'
+ibmcloud iam api-key-create mykeyname -d 'my sample key'
 OK
 API key mykeyname was created
 
@@ -2887,78 +3152,47 @@ References:
   * [https://console.bluemix.net/docs/iam/userid_keys.html#userapikey](https://console.bluemix.net/docs/iam/userid_keys.html#userapikey)
   * [https://ibm.ibmaspera.com/helpcenter/transfer-service](https://ibm.ibmaspera.com/helpcenter/transfer-service)
 
-
 Then, to register the key by default for the ats plugin, create a preset. Execute:
 
 ```
-$ ascli config id my_ibm_ats update --ibm-api-key=my_secret_api_key_here_8f8d9fdakjhfsashjk678
-$ ascli config id default set ats my_ibm_ats
-$ ascli ats api_key instances
+ascli config preset update my_ibm_ats --ibm-api-key=my_secret_api_key_here_8f8d9fdakjhfsashjk678
+ascli config preset set default ats my_ibm_ats
+ascli ats api_key instances
 +--------------------------------------+
 | instance                             |
 +--------------------------------------+
 | aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee |
 +--------------------------------------+
-$ ascli config id my_ibm_ats update --instance=aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee
-$ ascli ats api_key create
+ascli config preset update my_ibm_ats --instance=aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee
+ascli ats api_key create
 +--------+----------------------------------------------+
 | key    | value                                        |
 +--------+----------------------------------------------+
 | id     | ats_XXXXXXXXXXXXXXXXXXXXXXXX                 |
 | secret | YYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYY |
 +--------+----------------------------------------------+
-$ ascli config id my_ibm_ats update --ats-key=ats_XXXXXXXXXXXXXXXXXXXXXXXX --ats-secret=YYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYY
-```
-## Cross Organization transfers
-
-It is possible to transfer files directly between organizations without having to first download locally and then upload...
-
-Although optional, the creation of [option preset](#lprt) is recommended to avoid placing all parameters in the command line.
-
-Procedure to send a file from org1 to org2:
-
-* Get access to Organization 1 and create a [option preset](#lprt): e.g. `org1`, for instance, use the [Wizard](#aocwizard)
-* Check that access works and locate the source file e.g. `mysourcefile`, e.g. using command `files browse`
-* Get access to Organization 2 and create a [option preset](#lprt): e.g. `org2`
-* Check that access works and locate the destination folder `mydestfolder`
-* execute the following:
-
+ascli config preset update my_ibm_ats --ats-key=ats_XXXXXXXXXXXXXXXXXXXXXXXX --ats-secret=YYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYY
 ```
-$ ascli -Porg1 aoc files node_info /mydestfolder --format=json --display=data | ascli -Porg2 aoc files upload mysourcefile --transfer=node --transfer-info=@json:@stdin:
-```
-
-Explanation:
-
-* `-Porg1 aoc` use Aspera on Cloud plugin and load credentials for `org1`
-* `files node_info /mydestfolder` generate transfer information including node api credential and root id, suitable for the next command
-* `--format=json` format the output in JSON (instead of default text table)
-* `--display=data` display only the result, and remove other information, such as workspace name
-* `|` the standard output of the first command is fed into the second one
-* `-Porg2 aoc` use Aspera on Cloud plugin and load credentials for `org2`
-* `files upload mysourcefile` upload the file named `mysourcefile` (located in `org1`)
-* `--transfer=node` use transfer agent type `node` instead of default [`direct`](#direct)
-* `--transfer-info=@json:@stdin:` provide `node` transfer agent information, i.e. node API credentials, those are expected in JSON format and read from standard input
 
-Note that when using a POSIX shell, another possibility to write `cmd1 | cmd2 --transfer-info=@json:stdin:` is `cmd2 --transfer-info=@json:$(cmd1)` instead of ``
 ## Examples
 
-Example: create access key on softlayer:
+Example: create access key on IBM Cloud (softlayer):
 
 ```
-$ ascli ats access_key create --cloud=softlayer --region=ams --params=@json:'{"storage":{"type":"softlayer_swift","container":"_container_name_","credentials":{"api_key":"value","username":"_name_:_usr_name_"},"path":"/"},"id":"_optional_id_","name":"_optional_name_"}'
+ascli ats access_key create --cloud=softlayer --region=ams --params=@json:'{"storage":{"type":"softlayer_swift","container":"_container_name_","credentials":{"api_key":"value","username":"_name_:_usr_name_"},"path":"/"},"id":"_optional_id_","name":"_optional_name_"}'
 ```
 
 Example: create access key on AWS:
 
 ```
-$ ascli ats access_key create --cloud=aws --region=eu-west-1 --params=@json:'{"id":"testkey3","name":"laurent key AWS","storage":{"type":"aws_s3","bucket":"my-bucket","credentials":{"access_key_id":"AKIA_MY_API_KEY","secret_access_key":"my/secret/here"},"path":"/laurent"}}'
+ascli ats access_key create --cloud=aws --region=eu-west-1 --params=@json:'{"id":"testkey3","name":"laurent key AWS","storage":{"type":"aws_s3","bucket":"my-bucket","credentials":{"access_key_id":"AKIA_MY_API_KEY","secret_access_key":"my/secret/here"},"path":"/laurent"}}'
 
 ```
 
 Example: create access key on Azure SAS:
 
 ```
-$ ascli ats access_key create --cloud=azure --region=eastus --params=@json:'{"id":"testkeyazure","name":"laurent key azure","storage":{"type":"azure_sas","credentials":{"shared_access_signature":"https://containername.blob.core.windows.net/blobname?sr=c&..."},"path":"/"}}'
+ascli ats access_key create --cloud=azure --region=eastus --params=@json:'{"id":"testkeyazure","name":"laurent key azure","storage":{"type":"azure_sas","credentials":{"shared_access_signature":"https://containername.blob.core.windows.net/blobname?sr=c&..."},"path":"/"}}'
 
 ```
 
@@ -2967,7 +3201,7 @@ $ ascli ats access_key create --cloud=azure --region=eastus --params=@json:'{"id
 Example: create access key on Azure:
 
 ```
-$ ascli ats access_key create --cloud=azure --region=eastus --params=@json:'{"id":"testkeyazure","name":"laurent key azure","storage":{"type":"azure","credentials":{"account":"myaccount","key":"myaccesskey","storage_endpoint":"myblob"},"path":"/"}}'
+ascli ats access_key create --cloud=azure --region=eastus --params=@json:'{"id":"testkeyazure","name":"laurent key azure","storage":{"type":"azure","credentials":{"account":"myaccount","key":"myaccesskey","storage_endpoint":"myblob"},"path":"/"}}'
 
 ```
 
@@ -2977,74 +3211,77 @@ delete all my access keys:
 for k in $(ascli ats access_key list --field=id --format=csv);do ascli ats access_key id $k delete;done
 ```
 
+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.
+
 # Plugin: IBM Aspera High Speed Transfer Server (transfer)
 
-This plugin works at FASP level (SSH/ascp/ascmd) and does not use the node API.
+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.
 
-If not username is provided, the default transfer user `xfer` is used.
+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 token is provided in transfer spec, then standard bypass keys are used:
 
 ```
-$ ascli server --url=ssh://... --ts=@json:'{"token":"Basic abc123"}'
+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).
+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).
 
 Examples:
 
 ```
-$ ascli server --ssh-keys=~/.ssh/id_rsa
-$ ascli server --ssh-keys=@list:,~/.ssh/id_rsa
-$ ascli server --ssh-keys=@json:'["~/.ssh/id_rsa"]'
+ascli server --ssh-keys=~/.ssh/id_rsa
+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.
+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.
 
-If you get an error message such as:
+On Linux, if you get an error message such as:
 
 ```
-[Linux]
 ERROR -- net.ssh.authentication.agent: could not connect to ssh-agent: Agent not configured
 ```
 
-or
+or on Windows:
 
 ```
-[Windows]
 ERROR -- net.ssh.authentication.agent: could not connect to ssh-agent: pageant process not running
 ```
 
-This means that you dont have such an ssh agent running:
+This means that you don't have such an ssh agent running, then:
 
 * check env var: `SSH_AGENT_SOCK`
-* check if the key is protected with a passphrase
+* check if the ssh key is protected with a passphrase
 * [check the manual](https://net-ssh.github.io/ssh/v1/chapter-2.html#s2)
-* To diable use of `ssh-agent`, use the option `ssh_option` like this (or set in preset):
+* To disable use of `ssh-agent`, use the option `ssh_option` like this:
 
 ```
-$ ascli server --ssh-options=@ruby:'{use_agent: false}' ...
+ascli server --ssh-options=@ruby:'{use_agent: false}' ...
 ```
 
-This can also be set as default using a preset.
+This can also be set as default using a global preset.
 
 ## Example
 
-One can test the "server" application using the well known demo server:
+One can test the `server` application using the well known demo server:
 
 ```
-$ ascli config id aspera_demo_server update --url=ssh://demo.asperasoft.com:33001 --username=asperaweb --password=_demo_pass_
-$ ascli config id default set server aspera_demo_server
-$ ascli server browse /aspera-test-dir-large
-$ ascli server download /aspera-test-dir-large/200MB
+ascli config initdemo
+ascli server browse /aspera-test-dir-large
+ascli server download /aspera-test-dir-large/200MB
 ```
 
-This creates a [option preset](#lprt) "aspera_demo_server" and set it as default for application "server"
-
+`initdemo` creates a [option preset](#lprt) `demoserver` and set it as default for plugin `server`.
 
 # Plugin: IBM Aspera High Speed Transfer Server (node)
 
@@ -3076,12 +3313,12 @@ For transfers, it is possible to control how transfer is authorized using option
 
 ## Central
 
-The central subcommand uses the "reliable query" API (session and file). It allows listing transfer sessions and transfered files.
+The central subcommand uses the "reliable query" API (session and file). It allows listing transfer sessions and transferred files.
 
 Filtering can be applied:
 
 ```
-$ ascli node central file list
+ascli node central file list
 ```
 
 by providing the `validator` option, offline transfer validation can be done.
@@ -3093,7 +3330,7 @@ It is possible to start a FASPStream session using the node API:
 Use the "node stream create" command, then arguments are provided as a [_transfer-spec_](#transferspec).
 
 ```
-$ ascli node stream create --ts=@json:'{"direction":"send","source":"udp://233.3.3.4:3000?loopback=1&ttl=2","destination":"udp://233.3.3.3:3001/","remote_host":"localhost","remote_user":"stream","remote_password":"XXXX"}' --preset=stream
+ascli node stream create --ts=@json:'{"direction":"send","source":"udp://233.3.3.4:3000?loopback=1&ttl=2","destination":"udp://233.3.3.3:3001/","remote_host":"localhost","remote_user":"stream","remote_password":"XXXX"}' --preset=stream
 ```
 
 ## Watchfolder
@@ -3106,9 +3343,9 @@ Refer to [Aspera documentation](https://download.asperasoft.com/download/docs/en
 * configure a watchfolder to define automated transfers
 
 ```
-$ ascli node service create @json:'{"id":"mywatchd","type":"WATCHD","run_as":{"user":"user1"}}'
-$ ascli node service create @json:'{"id":"mywatchfolderd","type":"WATCHFOLDERD","run_as":{"user":"user1"}}'
-$ ascli node watch_folder create @json:'{"id":"mywfolder","source_dir":"/watch1","target_dir":"/","transport":{"host":"10.25.0.4","user":"user1","pass":"mypassword"}}'
+ascli node service create @json:'{"id":"mywatchd","type":"WATCHD","run_as":{"user":"user1"}}'
+ascli node service create @json:'{"id":"mywatchfolderd","type":"WATCHFOLDERD","run_as":{"user":"user1"}}'
+ascli node watch_folder create @json:'{"id":"mywfolder","source_dir":"/watch1","target_dir":"/","transport":{"host":"10.25.0.4","user":"user1","pass":"mypassword"}}'
 ```
 
 ## Out of Transfer File Validation
@@ -3116,13 +3353,13 @@ $ ascli node watch_folder create @json:'{"id":"mywfolder","source_dir":"/watch1"
 Follow the Aspera Transfer Server configuration to activate this feature.
 
 ```
-$ ascli node central file list --validator=ascli --data=@json:'{"file_transfer_filter":{"max_result":1}}'
+ascli node central file list --validator=ascli --data=@json:'{"file_transfer_filter":{"max_result":1}}'
 :..............:..............:............:......................................:
 : session_uuid :    file_id   :   status   :              path                    :
 :..............:..............:............:......................................:
 : 1a74444c-... : 084fb181-... : validating : /home/xfer.../PKG - my title/200KB.1 :
 :..............:..............:............:......................................:
-$ ascli node central file update --validator=ascli --data=@json:'{"files":[{"session_uuid": "1a74444c-...","file_id": "084fb181-...","status": "completed"}]}'
+ascli node central file update --validator=ascli --data=@json:'{"files":[{"session_uuid": "1a74444c-...","file_id": "084fb181-...","status": "completed"}]}'
 updated
 ```
 
@@ -3138,7 +3375,7 @@ Create another configuration for the Azure ATS instance: in section "node", name
 Then execute the following command:
 
 ```
-$ ascli node download /share/sourcefile --to-folder=/destinationfolder --preset=awsshod --transfer=node --transfer-info=@preset:azureats
+ascli node download /share/sourcefile --to-folder=/destinationfolder --preset=awsshod --transfer=node --transfer-info=@preset:azureats
 ```
 
 This will get transfer information from the SHOD instance and tell the Azure ATS instance
@@ -3147,7 +3384,7 @@ to download files.
 ## Create access key
 
 ```
-$ ascli node access_key create --value=@json:'{"id":"eudemo-sedemo","secret":"mystrongsecret","storage":{"type":"local","path":"/data/asperafiles"}}'
+ascli node access_key create --value=@json:'{"id":"eudemo-sedemo","secret":"mystrongsecret","storage":{"type":"local","path":"/data/asperafiles"}}'
 ```
 
 # Plugin: IBM Aspera Faspex5
@@ -3172,7 +3409,7 @@ For boot method: (will be removed in future)
 Use it as password and use `--auth=boot`.
 
 ```
-$ ascli conf id f5boot update --url=https://localhost/aspera/faspex --auth=boot --password=ABC.DEF.GHI...
+ascli conf id f5boot update --url=https://localhost/aspera/faspex --auth=boot --password=ABC.DEF.GHI...
 ```
 
 Ready to use Faspex5 with CLI.
@@ -3218,7 +3455,7 @@ If no parameter `max` or `pmax` is provided, then all packages will be listed in
 ### Example
 
 ```
-$ ascli faspex package list --box=inbox --recipient='*my_dropbox' --query=@json:'{"max":20,"pmax":2,"count":20}'
+ascli faspex package list --box=inbox --recipient='*my_dropbox' --query=@json:'{"max":20,"pmax":2,"count":20}'
 ```
 
 List a maximum of 20 items grouped by pages of 20, with maximum 2 pages in received box (inbox) when received in dropbox `*my_dropbox`.
@@ -3232,14 +3469,14 @@ The command is `package recv`, possible methods are:
 * provide a `faspe:` URI with option `link`
 
 ```
-$ ascli faspex package recv --id=12345
-$ ascli faspex package recv --link=faspe://...
+ascli faspex package recv --id=12345
+ascli faspex package recv --link=faspe://...
 ```
 
 If the package is in a specific dropbox, add option `recipient` for both the `list` and `recv` commands.
 
 ```
-$ ascli faspex package list --recipient='*thedropboxname'
+ascli faspex package list --recipient='*thedropboxname'
 ```
 
 if `id` is set to `ALL`, then all packages are downloaded, and if option `once_only`is used, then a persistency file is created to keep track of already downloaded packages.
@@ -3251,7 +3488,7 @@ The command is `faspex package send`. Package information (title, note, metadata
 Example:
 
 ```
-$ ascli faspex package send --delivery-info=@json:'{"title":"my title","recipients":["laurent.martin.aspera@fr.ibm.com"]}' --url=https://faspex.corp.com/aspera/faspex --username=foo --password=bar /tmp/file1 /home/bar/file2
+ascli faspex package send --delivery-info=@json:'{"title":"my title","recipients":["laurent.martin.aspera@fr.ibm.com"]}' --url=https://faspex.corp.com/aspera/faspex --username=foo --password=bar /tmp/file1 /home/bar/file2
 ```
 
 If the recipient is a dropbox, just provide the name of the dropbox in `recipients`: `"recipients":["My Dropbox Name"]`
@@ -3268,7 +3505,7 @@ Like for any transfer, a notification can be sent by email using parameters: `no
 Example:
 
 ```
-$ ascli faspex package send --delivery-info=@json:'{"title":"test pkg 1","recipients":["aspera.user1@gmail.com"]}' ~/Documents/Samples/200KB.1 --notif-to=aspera.user1@gmail.com --notif-template=@ruby:'%Q{From: <%=from_name%> <<%=from_email%>>\nTo: <<%=to%>>\nSubject: Package sent: <%=ts["tags"]["aspera"]["faspex"]["metadata"]["_pkg_name"]%> files received\n\nTo user: <%=ts["tags"]["aspera"]["faspex"]["recipients"].first["email"]%>}'
+ascli faspex package send --delivery-info=@json:'{"title":"test pkg 1","recipients":["aspera.user1@gmail.com"]}' ~/Documents/Samples/200KB.1 --notif-to=aspera.user1@gmail.com --notif-template=@ruby:'%Q{From: <%=from_name%> <<%=from_email%>>\nTo: <<%=to%>>\nSubject: Package sent: <%=ts["tags"]["aspera"]["faspex"]["metadata"]["_pkg_name"]%> files received\n\nTo user: <%=ts["tags"]["aspera"]["faspex"]["recipients"].first["email"]%>}'
 ```
 
 In this example the notification template is directly provided on command line. Package information placed in the message are directly taken from the tags in transfer spec. The template can be placed in a file using modifier: `@file:`
@@ -3278,9 +3515,9 @@ In this example the notification template is directly provided on command line.
 Example:
 
 ```
-$ ascli faspex v4 dropbox create --value=@json:'{"dropbox":{"e_wg_name":"test1","e_wg_desc":"test1"}}'
-$ ascli faspex v4 dropbox list
-$ ascli faspex v4 dropbox delete --id=36
+ascli faspex v4 dropbox create --value=@json:'{"dropbox":{"e_wg_name":"test1","e_wg_desc":"test1"}}'
+ascli faspex v4 dropbox list
+ascli faspex v4 dropbox delete --id=36
 ```
 
 ## Remote sources
@@ -3318,7 +3555,7 @@ It is possible to tell `ascli` to download newly received packages, much like th
 cargo client, or drive. Refer to the [same section](#aoccargo) in the Aspera on Cloud plugin:
 
 ```
-$ ascli faspex packages recv --id=ALL --once-only=yes --lock-port=12345
+ascli faspex packages recv --id=ALL --once-only=yes --lock-port=12345
 ```
 
 # Plugin: IBM Aspera Shares
@@ -3328,7 +3565,7 @@ Aspera Shares supports the "node API" for the file transfer part. (Shares 1 and
 In Shares2, users, groups listing are paged, to display sequential pages:
 
 ```
-$ for p in 1 2 3;do ascli shares2 admin users list --value=@json:'{"page":'$p'}';done
+for p in 1 2 3;do ascli shares2 admin users list --value=@json:'{"page":'$p'}';done
 ```
 
 # Plugin: IBM Cloud Object Storage
@@ -3337,9 +3574,9 @@ The IBM Cloud Object Storage provides the possibility to execute transfers using
 It uses the same transfer service as Aspera on Cloud, called Aspera Transfer Service (ATS).
 Available ATS regions: [https://status.aspera.io](https://status.aspera.io)
 
-There are two possibilities to provide credentials. If you already have the endpoint, apikey and CRN, use the forst method. If you dont have credentials but have access to the IBM Cloud console, then use the second method.
+There are two possibilities to provide credentials. If you already have the endpoint, apikey and CRN, use the first method. If you don't have credentials but have access to the IBM Cloud console, then use the second method.
 
-## Using endpoint, apikey and Ressource Instance ID (CRN)
+## Using endpoint, apikey and Resource Instance ID (CRN)
 
 If you have those parameters already, then following options shall be provided:
 
@@ -3351,15 +3588,15 @@ If you have those parameters already, then following options shall be provided:
 For example, let us create a default configuration:
 
 ```
-$ ascli conf id mycos update --bucket=mybucket --endpoint=https://s3.us-east.cloud-object-storage.appdomain.cloud --apikey=abcdefgh --crn=crn:v1:bluemix:public:iam-identity::a/xxxxxxx
-$ ascli conf id default set cos mycos
+ascli conf id mycos update --bucket=mybucket --endpoint=https://s3.us-east.cloud-object-storage.appdomain.cloud --apikey=abcdefgh --crn=crn:v1:bluemix:public:iam-identity::a/xxxxxxx
+ascli conf id default set cos mycos
 ```
 
 Then, jump to the transfer example.
 
 ## Using service credential file
 
-If you are the COS administrator and dont have yet the credential: Service credentials are directly created using the IBM cloud web ui. Navigate to:
+If you are the COS administrator and don't have yet the credential: Service credentials are directly created using the IBM cloud web ui. Navigate to:
 
 Navigation Menu &rarr; Resource List &rarr; Storage &rarr; Cloud Object Storage &rarr; Service Credentials &rarr; &lt;select or create credentials&gt; &rarr; view credentials &rarr; copy
 
@@ -3368,11 +3605,11 @@ Then save the copied value to a file, e.g. : `$HOME/cos_service_creds.json`
 or using the IBM Cloud CLI:
 
 ```
-$ ibmcloud resource service-keys
-$ ibmcloud resource service-key aoclaurent --output JSON|jq '.[0].credentials'>$HOME/service_creds.json
+ibmcloud resource service-keys
+ibmcloud resource service-key aoclaurent --output JSON|jq '.[0].credentials'>$HOME/service_creds.json
 ```
 
-(if you dont have `jq` installed, extract the structure as follows)
+(if you don't have `jq` installed, extract the structure as follows)
 
 It consists in the following structure:
 
@@ -3407,8 +3644,8 @@ The required options for this method are:
 For example, let us create a default configuration:
 
 ```
-$ ascli conf id mycos update --bucket=laurent --service-credentials=@val:@json:@file:~/service_creds.json --region=us-south
-$ ascli conf id default set cos mycos
+ascli conf id mycos update --bucket=laurent --service-credentials=@val:@json:@file:~/service_creds.json --region=us-south
+ascli conf id default set cos mycos
 ```
 
 ## Operations, transfers
@@ -3418,8 +3655,8 @@ Let's assume you created a default configuration from once of the two previous s
 A subset of `node` plugin operations are supported, basically node API:
 
 ```
-$ ascli cos node info
-$ ascli cos node upload 'faux:///sample1G?1g'
+ascli cos node info
+ascli cos node upload 'faux:///sample1G?1g'
 ```
 
 Note: we generate a dummy file `sample1G` of size 2GB using the `faux` PVCL (man ascp and section above), but you can of course send a real file by specifying a real file instead.
@@ -3448,8 +3685,10 @@ Specify the previews folder as shown in:
 By default, the `preview` plugin expects previews to be generated in a folder named `previews` located in the storage root. On the transfer server execute:
 
 ```
-# /opt/aspera/bin/asconfigurator -x "server;preview_dir,previews"
-# /opt/aspera/bin/asnodeadmin --reload
+PATH=/opt/aspera/bin:$PATH
+
+asconfigurator -x "server;preview_dir,previews"
+asnodeadmin --reload
 ```
 
 Note: the configuration `preview_dir` is *relative* to the storage root, no need leading or trailing `/`. In general just set the value to `previews`
@@ -3462,16 +3701,18 @@ This size is internally capped to `1<<24` Bytes (16777216) , i.e. 16384 KBytes.
 To change this parameter in `aspera.conf`, use `asconfigurator`. To display the value, use `asuserdata`:
 
 ```
-# /opt/aspera/bin/asuserdata -a | grep max_request_file_create_size_kb
+asuserdata -a | grep max_request_file_create_size_kb
+
   max_request_file_create_size_kb: "1024"
-# /opt/aspera/bin/asconfigurator -x "server; max_request_file_create_size_kb,16384"
+
+asconfigurator -x "server; max_request_file_create_size_kb,16384"
 ```
 
 If you use a value different than 16777216, then specify it using option `max_size`.
 
 Note: the HSTS parameter (max_request_file_create_size_kb) is in *kiloBytes* while the generator parameter is in *Bytes* (factor of 1024).
 
-## <a name="prev_ext"></a>External tools: Linux
+## <a id="prev_ext"></a>External tools: Linux
 
 The tool requires the following external tools available in the `PATH`:
 
@@ -3488,7 +3729,7 @@ Other OSes should work as well, but are note tested.
 To check if all tools are found properly, execute:
 
 ```
-$ ascli preview check
+ascli preview check
 ```
 
 ### mimemagic
@@ -3496,22 +3737,22 @@ $ ascli preview check
 To benefit from extra mime type detection install gem mimemagic:
 
 ```
-# gem install mimemagic
+gem install mimemagic
 ```
 
 or to install an earlier version if any problem:
 
 ```
-# gem install mimemagic -v '~> 0.3.0'
+gem install mimemagic -v '~> 0.3.0'
 ```
 
 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.
 
-If used, it the `preview` command will first analyse the file content using mimemagic, and if no match, will try by extension.
+If used, it the `preview` command will first analyze the file content using mimemagic, and if no match, will try by extension.
 
-### Image: Imagemagick and optipng
+### Image: ImageMagick and optipng
 
 ```
 yum install -y ImageMagick optipng
@@ -3527,25 +3768,25 @@ curl -s https://johnvansickle.com/ffmpeg/releases/ffmpeg-release-amd64-static.ta
 
 ### Office: Unoconv and Libreoffice
 
-If you dont want to have preview for office dpcuments or if it is too complex you can skip office document preview generation by using option: `--skip-types=office`
+If you don't want to have preview for office documents or if it is too complex you can skip office document preview generation by using option: `--skip-types=office`
 
 The generation of preview in based on the use of `unoconv` and `libreoffice`
 
-* Centos 8
+* CentOS 8
 
 ```
-# dnf install unoconv
+dnf install unoconv
 ```
 
 * Amazon Linux
 
 ```
-# amazon-linux-extras enable libreoffice
-# yum clean metadata
-# yum install libreoffice-core libreoffice-calc libreoffice-opensymbol-fonts libreoffice-ure libreoffice-writer libreoffice-pyuno libreoffice-impress
-# wget https://raw.githubusercontent.com/unoconv/unoconv/master/unoconv
-# mv unoconv /usr/bin
-# chmod a+x /usr/bin/unoconv
+amazon-linux-extras enable libreoffice
+yum clean metadata
+yum install libreoffice-core libreoffice-calc libreoffice-opensymbol-fonts libreoffice-ure libreoffice-writer libreoffice-pyuno libreoffice-impress
+wget https://raw.githubusercontent.com/unoconv/unoconv/master/unoconv
+mv unoconv /usr/bin
+chmod a+x /usr/bin/unoconv
 ```
 
 ## Configuration
@@ -3557,9 +3798,11 @@ Like any `ascli` commands, parameters can be passed on command line or using a c
 Note that the `xfer` user has a special protected shell: `aspshell`, so changing identity requires specification of alternate shell:
 
 ```
-# su -s /bin/bash - xfer
-$ ascli config id previewconf update --url=https://localhost:9092 --username=my_access_key --password=my_secret --skip-types=office --lock-port=12346
-$ ascli config id default set preview previewconf
+su -s /bin/bash - xfer
+
+ascli config preset update previewconf --url=https://localhost:9092 --username=my_access_key --password=my_secret --skip-types=office --lock-port=12346
+
+ascli config preset set default preview previewconf
 ```
 
 Here we assume that Office file generation is disabled, else remove this option.
@@ -3568,7 +3811,7 @@ Here we assume that Office file generation is disabled, else remove this option.
 One can check if the access key is well configured using:
 
 ```
-$ ascli -Ppreviewconf node browse /
+ascli -Ppreviewconf node browse /
 ```
 
 This shall list the contents of the storage root of the access key.
@@ -3584,8 +3827,9 @@ Typically, for "Access key" access, the system/transfer is `xfer`. So, in order
 Lets do a one shot test, using the configuration previously created:
 
 ```
-# su -s /bin/bash - xfer
-xfer$ ascli preview scan --overwrite=always
+su -s /bin/bash - xfer
+
+ascli preview scan --overwrite=always
 ```
 
 When the preview generator is first executed it will create a file: `.aspera_access_key`
@@ -3599,13 +3843,13 @@ Adapt the scripts to your own preference.
 
 We assume here that a configuration preset was created as shown previously.
 
-Lets first setup a script that will be used in the sceduler and sets up the environment.
+Lets first setup a script that will be used in the scheduler and sets up the environment.
 
 Example of startup script `cron_ascli`, which sets the Ruby environment and adds some timeout protection:
 
 ```
-#!/bin/bash
-# set a timeout protection, just in case
+ #!/bin/bash
+ # set a timeout protection, just in case
 case "$*" in *trev*) tmout=10m ;; *) tmout=30m ;; esac
 . /etc/profile.d/rvm.sh
 rvm use 2.6 --quiet
@@ -3615,13 +3859,13 @@ exec timeout ${tmout} ascli "${@}"
 Here the cronjob is created for user `xfer`.
 
 ```
-xfer$ crontab<<EOF
+crontab<<EOF
 0    * * * *  /home/xfer/cron_ascli preview scan --logger=syslog --display=error
 2-59 * * * *  /home/xfer/cron_ascli preview trev --logger=syslog --display=error
 EOF
 ```
 
-Note that the loging options are kept in the cronfile instead of conf file to allow execution on command line with output on command line.
+Note that the logging options are kept in the cronfile instead of conf file to allow execution on command line with output on command line.
 
 ## Candidate detection for creation or update (or deletion)
 
@@ -3646,12 +3890,12 @@ Deletion of preview for deleted source files: not implemented yet (TODO).
 If the `scan` or `events` detection method is used, then the option : `skip_folders` can be used to skip some folders. It expects a list of path relative to the storage root (docroot) starting with slash, use the `@json:` notation, example:
 
 ```
-$ ascli preview scan --skip-folders=@json:'["/not_here"]'
+ascli preview scan --skip-folders=@json:'["/not_here"]'
 ```
 
 The option `folder_reset_cache` forces the node service to refresh folder contents using various methods.
 
-When scanning the option `value` has the same behaviour as for the `node find` command.
+When scanning the option `value` has the same behavior as for the `node find` command.
 
 For instance to filter out files beginning with `._` do:
 
@@ -3670,7 +3914,7 @@ Use option `skip_format` to skip generation of a format.
 
 ## Supported input Files types
 
-The preview generator supports redering of those file categories:
+The preview generator supports rendering of those file categories:
 
 * image
 * pdf
@@ -3690,7 +3934,7 @@ The tool can also locally detect the mime type using gem `mimemagic`.
 
 ## Access to original files and preview creation
 
-Standard open source tools are used to create thumnails and video previews.
+Standard open source tools are used to create thumbnails and video previews.
 Those tools require that original files are accessible in the local file system and also write generated files on the local file system.
 The tool provides 2 ways to read and write files with the option: `file_access`
 
@@ -3720,28 +3964,28 @@ The `smtp` option is a hash table (extended value) with the following fields:
 ## Example of configuration:
 
 ```
-$ ascli config id smtp_google set server smtp.google.com
-$ ascli config id smtp_google set username john@gmail.com
-$ ascli config id smtp_google set password P@ssw0rd
+ascli config preset set smtp_google server smtp.google.com
+ascli config preset set smtp_google username john@gmail.com
+ascli config preset set smtp_google password P@ssw0rd
 ```
 
 or
 
 ```
-$ ascli config id smtp_google init @json:'{"server":"smtp.google.com","username":"john@gmail.com","password":"P@ssw0rd"}'
+ascli config preset init smtp_google @json:'{"server":"smtp.google.com","username":"john@gmail.com","password":"P@ssw0rd"}'
 ```
 
 or
 
 ```
-$ ascli config id smtp_google update --server=smtp.google.com --username=john@gmail.com --password=P@ssw0rd
+ascli config preset update smtp_google --server=smtp.google.com --username=john@gmail.com --password=P@ssw0rd
 ```
 
-Set this configation as global default, for instance:
+Set this configuration as global default, for instance:
 
 ```
-$ ascli config id cli_default set smtp @val:@preset:smtp_google
-$ ascli config id default set config cli_default
+ascli config preset set cli_default smtp @val:@preset:smtp_google
+ascli config preset set default config cli_default
 ```
 
 ## Email templates
@@ -3763,8 +4007,8 @@ Other variables are defined depending on context.
 Check settings with `smtp_settings` command. Send test email with `email_test`.
 
 ```
-$ ascli config --smtp=@preset:smtp_google smtp
-$ ascli config --smtp=@preset:smtp_google email --notif-to=sample.dest@example.com
+ascli config --smtp=@preset:smtp_google smtp
+ascli config --smtp=@preset:smtp_google email --notif-to=sample.dest@example.com
 ```
 
 ## Notifications for transfer status
@@ -3773,7 +4017,7 @@ An e-mail notification can be sent upon transfer success and failure (one email
 
 To activate, use option `notif_to`.
 
-A default e-mail template is used, but it can be overriden with option `notif_template`.
+A default e-mail template is used, but it can be overridden with option `notif_template`.
 
 The environment provided contains the following additional variables:
 
@@ -3797,7 +4041,7 @@ Transfer is: <%=global_transfer_status%>
 This gem comes with a second executable tool providing a simplified standardized interface
 to start a FASP session: `asession`.
 
-It aims at simplifying the startup of a FASP session from a programmatic stand point as formating a [_transfer-spec_](#transferspec) is:
+It aims at simplifying the startup of a FASP session from a programmatic stand point as formatting a [_transfer-spec_](#transferspec) is:
 
 * common to Aspera Node API (HTTP POST /ops/transfer)
 * common to Aspera Connect API (browser javascript startTransfer)
@@ -3809,7 +4053,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 formated [_transfer-spec_](#transferspec) on stdin.
+If not 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.
 
@@ -3820,7 +4064,7 @@ Note that there are special "extended" [_transfer-spec_](#transferspec) paramete
   * `EX_loglevel` to change log level of the tool
   * `EX_file_list_folder` to set the folder used to store (exclusively, because of garbage collection) generated file lists. By default it is `[system tmp folder]/[username]_asession_filelists`
 
-Note that in addition, many "EX_" [_transfer-spec_](#transferspec) parameters are supported for the [`direct`](#direct) transfer agent (used by `asession`), refer to section [_transfer-spec_](#transferspec).
+Note that in addition, many "EX_" [_transfer-spec_](#transferspec) parameters are supported for the [`direct`](#agt_direct) transfer agent (used by `asession`), refer to section [_transfer-spec_](#transferspec).
 
 ## Comparison of interfaces
 
@@ -3847,7 +4091,7 @@ echo "${MY_TSPEC}"|asession
 This is particularly useful for a persistent session ( with the [_transfer-spec_](#transferspec) parameter: `"keepalive":true` )
 
 ```
-$ asession
+asession
 {"remote_host":"demo.asperasoft.com","ssh_port":33001,"remote_user":"asperaweb","remote_password":"_demo_pass_","direction":"receive","destination_root":".","keepalive":true,"resume_level":"none"}
 {"type":"START","source":"/aspera-test-dir-tiny/200KB.2"}
 {"type":"DONE"}
@@ -3862,7 +4106,7 @@ Nodejs: [https://www.npmjs.com/package/aspera](https://www.npmjs.com/package/asp
 ## Help
 
 ```
-$ asession -h
+asession -h
 USAGE
     asession
     asession -h|--help
@@ -3921,7 +4165,7 @@ Note that:
 
 * `ascli` takes transfer parameters exclusively as a transfer_spec, with `--ts` parameter.
 * most, but not all native ascp arguments are available as standard transfer_spec parameters
-* native ascp arguments can be provided with the [_transfer-spec_](#transferspec) parameter: EX_ascp_args (array), only for the [`direct`](#direct) transfer agent (not connect or node)
+* native ascp arguments can be provided with the [_transfer-spec_](#transferspec) parameter: EX_ascp_args (array), only for the [`direct`](#agt_direct) transfer agent (not connect or node)
 
 ### server side and configuration
 
@@ -3936,18 +4180,18 @@ Once `ascli` parameters are defined, run the command using the OS native schedul
 ## Example
 
 ```
-$ ascli server upload source_hot --to-folder=/Upload/target_hot --lock-port=12345 --ts=@json:'{"EX_ascp_args":["--remove-after-transfer","--remove-empty-directories","--exclude-newer-than=-8","--src-base","source_hot"]}'
+ascli server upload source_hot --to-folder=/Upload/target_hot --lock-port=12345 --ts=@json:'{"EX_ascp_args":["--remove-after-transfer","--remove-empty-directories","--exclude-newer-than=-8","--src-base","source_hot"]}'
 
 ```
 
-The local folder (here, relative path: source_hot) is sent (upload) to basic fasp server, source files are deleted after transfer. growing files will be sent only once they dont grow anymore (based ona 8 second cooloff period). If a transfer takes more than the execution period, then the subsequent execution is skipped (lock-port).
+The local folder (here, relative path: source_hot) is sent (upload) to basic fasp server, source files are deleted after transfer. growing files will be sent only once they don't grow anymore (based on an 8-second cooloff period). If a transfer takes more than the execution period, then the subsequent execution is skipped (lock-port).
 
-# Aspera Health check and Nagios
+# Health check and Nagios
 
-Each plugin provide a `health` command that will check the health status of the application. Example:
+Most plugin provide a `health` command that will check the health status of the application. Example:
 
 ```
-$ ascli console health
+ascli console health
 +--------+-------------+------------+
 | status | component   | message    |
 +--------+-------------+------------+
@@ -3964,13 +4208,13 @@ Typically, the health check uses the REST API of the application with the follow
 `ascli` can be called by Nagios to check the health status of an Aspera server. The output can be made compatible to Nagios with option `--format=nagios` :
 
 ```
-$ ascli server health transfer --to-folder=/Upload --format=nagios --progress=none
+ascli server health transfer --to-folder=/Upload --format=nagios --progress=none
 OK - [transfer:ok]
-$ ascli server health asctlstatus --cmd_prefix='sudo ' --format=nagios
+ascli server health asctlstatus --cmd_prefix='sudo ' --format=nagios
 OK - [NP:running, MySQL:running, Mongrels:running, Background:running, DS:running, DB:running, Email:running, Apache:running]
 ```
 
-# Module: `Aspera`
+# Ruby Module: `Aspera`
 
 Main components:
 
@@ -3981,8 +4225,8 @@ Main components:
 A working example can be found in the gem, example:
 
 ```
-$ ascli config gem_path
-$ cat $(ascli config gem_path)/../examples/transfer.rb
+ascli config gem_path
+cat $(ascli config gem_path)/../examples/transfer.rb
 ```
 
 This sample code shows some example of use of the API as well as
@@ -4017,132 +4261,143 @@ So, it evolved into `ascli`:
 
 # Changes (Release notes)
 
+* 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)
+    * 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`](#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.
+    * 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`
+    * 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 `*`
+    * 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`](#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`](#direct) are now in sub-key `"resume"`
+    * 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
+    * 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`
+    * 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
+    * 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
+    * 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
+    * 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`](#direct) agent (including gcm, etc..)
-	* added transfer spec param `apply_local_docroot` for [`direct`](#direct)
+    * 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)
+    * 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
+    * 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"
+    * fixes on multi-session: progress bat and transfer spec param for "direct"
 
 * 0.11.1
 
-	* enhanced short_link creation commands (see examples)
+    * enhanced short_link creation commands (see examples)
 
 * 0.11
 
-	* add option to provide file list directly to ascp like this (only for direct transfer agent):
-
-```
-... --sources=@ts --ts=@json:'{"paths":[],"EX_file_list":"filelist"}'
-```
+    * add transfer spec option (agent `direct` only) to provide file list directly to ascp: `EX_file_list`.
 
 * 0.10.18
 
@@ -4151,7 +4406,7 @@ So, it evolved into `ascli`:
 * 0.10.17
 
 	* fixed problem on `server` for option `ssh_keys`, now accepts both single value and list.
-	* new modifier: `@list:<saparator>val1<separator>...`
+	* new modifier: `@list:<separator>val1<separator>...`
 
 * 0.10.16
 
@@ -4173,7 +4428,7 @@ So, it evolved into `ascli`:
 * 0.10.12
 
 	* added support for AoC node registration keys
-	* replaced option : `local_resume` with `transfer_info` for agent [`direct`](#direct)
+	* 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
@@ -4205,7 +4460,7 @@ So, it evolved into `ascli`:
 
 * 0.10.6
 
-	* FaspManager: transfer spec `authentication` no more needed for local tranfer to use Aspera public keys. public keys will be used if there is a token and no key or password is provided.
+	* 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
@@ -4355,10 +4610,10 @@ So, it evolved into `ascli`:
 
 * 0.9.7
 
-	* homogeneous [_transfer-spec_](#transferspec) for `node` and [`direct`](#direct) transfer agents
+	* 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 paclages by specifying id=ALL
+	* 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
@@ -4438,16 +4693,16 @@ For issues 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 command nplugin.
+One can also [create one's own plugin](#createownplugin).
 
 ## Only one value for any option
 
 Some commands and sub commands may ask for the same option name.
-Currently, since option definition is position independant (last one wins), it is not possible
+Currently, since option definition is position independent (last one wins), it is not possible
 to give an option to a command and the same option with different value to a sub command.
 
-For instance, if an entity is identified by the option `id` but later on the command line another `id` option is required, the later will override the earlier one, and both entity will use the same id.
-As a workaround use another option, if available, to identify the entity.
+For instance, if an entity is identified by the option `id` but later on the command line another `id` option is required, then the later will override the earlier one, and both entity will use the same id.
+As a solution, use the position specific notation for selection, i.e. provide the identified just after command and do not use option `id`.
 
 This happens typically for the `node` sub command, e.g. identify the node by name instead of id.
 
@@ -4479,7 +4734,7 @@ 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).
 
-## Miscelaneous
+## Miscellaneous
 
 * remove rest and oauth classes and use ruby standard gems: