aspera-cli 4.4.0 → 4.5.0

data/docs/README.erb.md

@@ -16,7 +16,9 @@ Ruby Doc: [<%=gemspec.metadata['documentation_uri']%>](<%=gemspec.metadata['docu
 
 Required Ruby version: <%=gemspec.required_ruby_version%>
 
-# <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
 
 <%=tool%> is designed to be used as a command line tool to:
 
@@ -39,21 +41,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, <%=tool%> 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
-
 <%=tool%> is typically executed in a shell, either interactively or in a script. <%=tool%> 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 <%=tool%> (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 <%=tool%>. So special character handling (quotes, spaces, env vars, ...) is done in the shell.
@@ -66,12 +65,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:
 
 ```
-$ <%=cmd%> conf echo "Hello World" arg2 3
+<%=cmd%> 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 (<%=tool%>), next command line arguments are shown in the error message.
 
 # Quick Start
 
@@ -82,7 +84,10 @@ First, follow the section: [Installation](#installation) (Ruby, Gem, FASP) to st
 Once the gem is installed, <%=tool%> shall be accessible:
 
 ```
-$ <%=cmd%> --version
+<%=cmd%> --version
+```
+
+```
 <%=gemspec.version.to_s%>
 ```
 
@@ -95,8 +100,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:
 
 ```
-$ <%=cmd%> config initdemo
-$ <%=cmd%> server browse /
+<%=cmd%> config initdemo
+```
+
+```
+<%=cmd%> server browse /
+```
+
+```
 :............:...........:......:........:...........................:.......................:
 :   zmode    :   zuid    : zgid :  size  :           mtime           :         name          :
 :............:...........:......:........:...........................:.......................:
@@ -115,11 +126,26 @@ If you want to use <%=tool%> with another server, and in order to make further c
 * download a file
 
 ```
-$ <%=cmd%> config id myserver update --url=ssh://demo.asperasoft.com:33001 --username=asperaweb --password=_demo_pass_
+<%=cmd%> config preset update myserver --url=ssh://demo.asperasoft.com:33001 --username=asperaweb --password=_demo_pass_
+```
+
+```
 updated: myserver
-$ <%=cmd%> config id default set server myserver
+```
+
+```
+<%=cmd%> config preset set default server myserver
+```
+
+```
 updated: default&rarr;server to myserver
-$ <%=cmd%> server browse /aspera-test-dir-large
+```
+
+```
+<%=cmd%> server browse /aspera-test-dir-large
+```
+
+```
 :............:...........:......:..............:...........................:............................:
 :   zmode    :   zuid    : zgid :     size     :           mtime           :            name            :
 :............:...........:......:..............:...........................:............................:
@@ -136,7 +162,13 @@ $ <%=cmd%> 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                       :
 :............:...........:......:..............:...........................:............................:
-$ <%=cmd%> server download /aspera-test-dir-large/200MB
+```
+
+```
+<%=cmd%> server download /aspera-test-dir-large/200MB
+```
+
+```
 Time: 00:00:02 ========================================================================================================== 100% 100 Mbps Time: 00:00:00
 complete
 ```
@@ -147,9 +179,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:
 
@@ -159,33 +191,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, <%=tool%> 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 <%=cmd%> https://raw.githubusercontent.com/IBM/aspera-cli/develop/bin/dascli
-$ chmod a+x <%=cmd%>
+curl -o <%=cmd%> https://raw.githubusercontent.com/IBM/aspera-cli/develop/bin/dascli
+```
+
+```
+chmod a+x <%=cmd%>
 ```
 
 Install the container image:
 
 ```
-$ ./<%=cmd%> install
+./<%=cmd%> install
 ```
 
 Start using it !
@@ -195,9 +230,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/<%=cmd%>` 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: <%=tool%> and add a `--volume` stanza.
 
-## <a name="ruby"></a>Ruby
+## <a id="ruby"></a>Ruby
 
 Use this method to install on the native host.
 
@@ -209,7 +244,7 @@ Required Ruby version: <%=gemspec.required_ruby_version%>. Ruby version 3 is als
 
 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 <%=gemspec.required_ruby_version%> : use it !
 
@@ -222,31 +257,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.
@@ -259,7 +294,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).
@@ -267,8 +302,11 @@ If so, one can rename the login script: `mv /etc/profile.d/rvm.sh /etc/profile.d
 To activate ruby (and <%=cmd%>) later, source it:
 
 ```
-# source /etc/profile.d/rvm.sh.ok
-# rvm version
+source /etc/profile.d/rvm.sh.ok
+```
+
+```
+rvm version
 ```
 
 ### Windows: Installer
@@ -281,16 +319,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 <%=gemspec.name%> using `sudo` :
+macOS 10.13+ (High Sierra) comes with a recent Ruby. So you can use it directly. You will need to install <%=gemspec.name%> using `sudo` :
 
 ```
-$ sudo gem install <%=gemspec.name%><%=geminstadd%>
+sudo gem install <%=gemspec.name%><%=geminstadd%>
 ```
 
 Alternatively, if you use [Homebrew](https://brew.sh/) already you can install Ruby with it:
 
 ```
-$ brew install ruby
+brew install ruby
 ```
 
 ### Linux: package
@@ -300,90 +338,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-<%=cmd%>.tgz .rvm
-```
-
-Get the Aspera SDK. Execute:
-
-```
-$ <%=cmd%> conf --show-config|grep sdk_url
-```
+wget https://cache.ruby-lang.org/pub/ruby/2.7/ruby-2.7.2.tar.gz
 
-Then download the SDK archive from that URL.
+gzip -d ruby-2.7.2.tar.gz
 
-Another method for the SDK is to install the SDK (`<%=cmd%> conf ascp install`) on the first system, and archive `$HOME/.aspera`.
+tar xvf ruby-2.7.2.tar
 
-Transfer those 2 archives to the target system without internet access.
+cd ruby-2.7.2
 
-On the target system:
+./configure --prefix=/opt/ruby
 
-* 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)
+make ruby.imp
 
-```
-source path_to_rvm_root/scripts/rvm
-rvm use 2.7.2
-```
-
-For the SDK, either install from archive:
+make
 
-```
-$ <%=cmd%> conf ascp install --sdk-url=file:///SDK.zip
+make install
 ```
 
-or restore the `$HOME/.aspera` folder for the user.
-
-## <a name="the_gem"></a>`<%=gemspec.name%>` gem
+## <a id="the_gem"></a>`<%=gemspec.name%>` gem
 
 Once you have Ruby and rights to install gems: Install the gem and its dependencies:
 
 ```
-# gem install <%=gemspec.name%><%=geminstadd%>
+gem install <%=gemspec.name%><%=geminstadd%>
 ```
 
 To upgrade to the latest version:
 
 ```
-# gem update <%=gemspec.name%>
+gem update <%=gemspec.name%>
 ```
 
 <%=tool%> 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.
@@ -391,12 +395,10 @@ To upgrade to the latest version:
 To check manually:
 
 ```
-# <%=cmd%> conf check_update
+<%=cmd%> 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:
@@ -404,17 +406,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:
 
 ```
-$ <%=cmd%> conf ascp install
+<%=cmd%> 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
-$ <%=cmd%> conf ascp install --sdk-url=file:///SDK.zip
+curl -Lso SDK.zip https://ibm.biz/aspera_sdk
+```
+
+```
+<%=cmd%> 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.
@@ -434,36 +439,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 <%=cmd%>):
+* Archive (zip, tar) the main RVM folder (includes <%=cmd%>):
 
 ```
-$ cd ~
-$ tar zcvf rvm_<%=cmd%>.tgz .rvm
+cd $HOME && tar zcvf rvm-<%=cmd%>.tgz .rvm
 ```
 
-* retrieve the SDK:
+* Get the Aspera SDK.
 
 ```
-$ curl -Lso SDK.zip https://ibm.biz/aspera_sdk
+<%=cmd%> conf --show-config --fields=sdk_url
+```
+
+* Download the SDK archive from that URL.
+
+```
+curl -Lso SDK.zip https://ibm.biz/aspera_sdk
+```
+
+* Transfer those 2 files to the target system
+
+* On target system
+
+```
+cd $HOME
+
+tar zxvf rvm-<%=cmd%>.tgz
+
+source ~/.rvm/scripts/rvm
+
+<%=cmd%> conf ascp install --sdk-url=file:///SDK.zip
 ```
 
-* on the system without internet access:
+* Add those lines to shell init (`.profile`)
 
 ```
-$ cd ~
-$ tar zxvf rvm_<%=cmd%>.tgz
-$ source ~/.rvm/scripts/rvm
-$ <%=cmd%> conf ascp install --sdk-url=file:///SDK.zip
+source ~/.rvm/scripts/rvm
 ```
 
-# <a name="cli"></a>Command Line Interface: <%=tool%>
+# <a id="cli"></a>Command Line Interface: <%=tool%>
 
 The `<%=gemspec.name%>` Gem provides a command line interface (CLI) which interacts with Aspera Products (mostly using REST APIs):
 
@@ -492,7 +516,7 @@ The `<%=gemspec.name%>` Gem provides a command line interface (CLI) which intera
 Basic usage is displayed by executing:
 
 ```
-$ <%=cmd%> -h
+<%=cmd%> -h
 ```
 
 Refer to sections: [Usage](#usage) and [Sample Commands](#commands).
@@ -506,7 +530,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 :
 
 ```
-$ <%=cmd%> command --option-name=VAL1 VAL2
+<%=cmd%> command --option-name=VAL1 VAL2
 ```
 
 * executes _command_: `command`
@@ -534,13 +558,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:
 
 ```
-$ <%=cmd%> config echo -- --sample
+<%=cmd%> 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):
 
@@ -561,7 +588,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
@@ -578,8 +605,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
@@ -604,12 +631,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:
 
 ```
-$ <%=cmd%> aoc admin res user list --fields=name,email,ats_admin --query=@json:'{"sort":"name"}' --select=@json:'{"ats_admin":true}'
+<%=cmd%> aoc admin res user list --fields=name,email,ats_admin --query=@json:'{"sort":"name"}' --select=@json:'{"ats_admin":true}'
+```
+
+```
 :...............................:..................................:...........:
 :             name              :              email               : ats_admin :
 :...............................:..................................:...........:
@@ -622,7 +652,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)
@@ -636,7 +666,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
@@ -645,7 +675,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).
 
@@ -682,23 +712,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:
 
 ```
-$ <%=cmd%> config echo @zlib:@base64:@file:myfile.dat
+<%=cmd%> 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:
 
 ```
-$ <%=cmd%> config echo @ruby:'{"token_verification_key"=>File.read("pubkey.txt")}'
+<%=cmd%> 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
-$ <%=cmd%> config echo @csvt:@file:test.csv
+```
+
+```
+<%=cmd%> config echo @csvt:@file:test.csv
+```
+
+```
 :......:.....................:
 : name :        email        :
 :......:.....................:
@@ -710,13 +749,16 @@ $ <%=cmd%> config echo @csvt:@file:test.csv
 Example: create a hash and include values from preset named "config" of config file in this hash
 
 ```
-$ <%=cmd%> config echo @incps:@json:'{"hello":true,"incps":["config"]}'
+<%=cmd%> 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.
 
@@ -727,7 +769,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
 
 <%=tool%> configuration and other runtime files (token cache, file lists, persistency files, SDK) are stored in folder `[User's home folder]/.aspera/<%=cmd%>`.
 
@@ -737,49 +779,52 @@ It uses the `HOME` env var primarily, and on MS Windows it also looks at `%HOMED
 The main folder can be displayed using :
 
 ```
-$ <%=cmd%> config folder
+<%=cmd%> config folder
+```
+
+```
 /Users/kenji/.aspera/<%=cmd%>
 ```
 
-It can be overriden using the envinonment variable `<%=evp%>HOME`.
+It can be overridden using the environment variable `<%=evp%>HOME`.
 
 Example (Windows):
 
 ```
-$ set <%=evp%>HOME=C:\Users\Kenji\.aspera\<%=cmd%>
-$ <%=cmd%> config folder
+set <%=evp%>HOME=C:\Users\Kenji\.aspera\<%=cmd%>
+<%=cmd%> config folder
 C:\Users\Kenji\.aspera\<%=cmd%>
 ```
 
-## <a name="configfile"></a>Configuration file
+## <a id="configfile"></a>Configuration file
 
 On the first execution of <%=tool%>, 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, <%=tool%> provides commands to read and modify it using the `config` command.
 
-All options for <%=tool%> can be set on command line, or by env vars, or using <%=prsts%> in the configuratin file.
+All options for <%=tool%> can be set on command line, or by env vars, or using <%=prsts%> 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/<%=cmd%>/config.yaml` (this can be overriden with option `--config-file=path` or equivalent env var).
+The default configuration file is: `$HOME/.aspera/<%=cmd%>/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: <%=prsts%>. Then, instead of specifying some common options on the command line (e.g. address, credentials), it is possible to invoke the ones of a <%=prst%> (e.g. `mypreset`) using the option: `-Pmypreset` or `--preset=mypreset`.
 
-### <a name="lprt"></a><%=prstt%>
+### <a id="lprt"></a><%=prstt%>
 
 A <%=prst%> is simply a collection of parameters and their associated values in a named section in the configuration file.
 
 A named <%=prst%> can be modified directly using <%=tool%>, which will update the configuration file :
 
 ```
-$ <%=cmd%> config id <<%=opprst%>> set|delete|show|initialize|update
+<%=cmd%> config preset set|delete|show|initialize|update <<%=opprst%>>
 ```
 
 The command `update` allows the easy creation of <%=prst%> by simply providing the options in their command line format, e.g. :
 
 ```
-$ <%=cmd%> config id demo_server update --url=ssh://demo.asperasoft.com:33001 --username=asperaweb --password=_demo_pass_ --ts=@json:'{"precalculate_job_size":true}'
+<%=cmd%> 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 <%=prst%> `demo_server` with all provided options.
@@ -787,39 +832,48 @@ $ <%=cmd%> config id demo_server update --url=ssh://demo.asperasoft.com:33001 --
 The command `set` allows setting individual options in a <%=prst%>.
 
 ```
-$ <%=cmd%> config id demo_server set password _demo_pass_
+<%=cmd%> 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)_.
 
 ```
-$ <%=cmd%> config id demo_server initialize @json:'{"url":"ssh://demo.asperasoft.com:33001","username":"asperaweb","password":"_demo_pass_","ts":{"precalculate_job_size":true}}'
+<%=cmd%> 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:
 
 ```
-$ <%=cmd%> config open
+<%=cmd%> config preset over
 ```
 
-A full terminal based overview of the configuration can be displayed using:
+A list of <%=prst%> can be displayed using:
 
 ```
-$ <%=cmd%> config over
+<%=cmd%> config preset list
 ```
 
-A list of <%=prst%> 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:
 
 ```
-$ <%=cmd%> config list
+<%=cmd%> config open
 ```
 
-### <a name="lprtconf"></a>Special <%=prstt%>: config
+Older format for commands are still supported:
+
+```
+<%=cmd%> config id <name> set|delete|show|initialize|update
+<%=cmd%> config over
+<%=cmd%> config list
+```
+
+
+### <a id="lprtconf"></a>Special <%=prstt%>: config
 
 This preset name is reserved and contains a single key: `version`. This is the version of <%=tool%> which created the file.
 
-### <a name="lprtdef"></a>Special <%=prstt%>: default
+### <a id="lprtdef"></a>Special <%=prstt%>: 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.
 
@@ -830,16 +884,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:
 
 ```
-$ <%=cmd%> config id default set _plugin_name_ _default_preset_for_plugin_
-$ <%=cmd%> config id default get _plugin_name_
+<%=cmd%> config preset set default _plugin_name_ _default_preset_for_plugin_
+<%=cmd%> 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 <%=prstt%> config) is used to configure <%=tool%> but it also contains global options.
 
-When <%=tool%> starts, it lookjs for the `default` <%=prstt%> and if there is a value for `config`, if so, it loads the option values for any plugin used.
+When <%=tool%> starts, it looks for the `default` <%=prstt%> 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`)
 
@@ -878,10 +932,10 @@ The user may create as many <%=prsts%> as needed. For instance, a particular <%=
 
 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:
 
 ```
-$ <%=cmd%> config id my_aoc_org set private_key @val:@file:"$HOME/.aspera/<%=cmd%>/aocapikey"
+<%=cmd%> config preset set my_aoc_org private_key @val:@file:"$HOME/.aspera/<%=cmd%>/aocapikey"
 ```
 
 This creates the <%=prst%>:
@@ -917,26 +971,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 <%=prst%> for the main plugin with:
 
 ```
-$ <%=cmd%> config id cli_default set interactive no
-$ <%=cmd%> config id default set config cli_default
+<%=cmd%> config preset set cli_default interactive no
+```
+
+```
+<%=cmd%> config preset set default config cli_default
 ```
 
 A <%=prst%> value can be removed with `unset`:
 
 ```
-$ <%=cmd%> config id cli_default unset interactive
+<%=cmd%> config preset unset cli_default interactive
 ```
 
 Example: Define options using command line:
 
 ```
-$ <%=cmd%> -N --url=x --password=y --username=y node --show-config
+<%=cmd%> -N --url=x --password=y --username=y node --show-config
 ```
 
 Example: Define options using a hash:
 
 ```
-$ <%=cmd%> -N --preset=@json:'{"url":"x","password":"y","username":"y"}' node --show-config
+<%=cmd%> -N --preset=@json:'{"url":"x","password":"y","username":"y"}' node --show-config
 ```
 
 ### Examples
@@ -946,44 +1003,120 @@ only username/password and url are required (either on command line, or from con
 Those can usually be provided on the command line:
 
 ```
-$ <%=cmd%> shares repo browse / --url=https://10.25.0.6 --username=john --password=4sp3ra
+<%=cmd%> shares repo browse / --url=https://10.25.0.6 --username=john --password=4sp3ra
 ```
 
 This can also be provisioned in a config file:
 
+* Build <%=prst%>
+
 ```
-1$ <%=cmd%> config id shares06 set url https://10.25.0.6
-2$ <%=cmd%> config id shares06 set username john
-3$ <%=cmd%> config id shares06 set password 4sp3ra
-4$ <%=cmd%> config id default set shares shares06
-5$ <%=cmd%> config overview
-6$ <%=cmd%> shares repo browse /
+<%=cmd%> config preset set shares06 url https://10.25.0.6
+<%=cmd%> config preset set shares06 username john
+<%=cmd%> config preset set shares06 password 4sp3ra
 ```
 
-The three first commands build a <%=prst%>.
 Note that this can also be done with one single command:
 
 ```
-$ <%=cmd%> config id shares06 init @json:'{"url":"https://10.25.0.6","username":"john","password":"4sp3ra"}'
+<%=cmd%> config preset init shares06 @json:'{"url":"https://10.25.0.6","username":"john","password":"4sp3ra"}'
+```
+
+or
+
+```
+<%=cmd%> config preset update shares06 --url=https://10.25.0.6 --username=john --password=4sp3ra
+```
+
+* Define this <%=prst%> as the default <%=prst%> for the specified plugin (`shares`)
+
+```
+<%=cmd%> config preset set default shares shares06
+```
+
+* Display the content of configuration file in table format
+
+```
+<%=cmd%> config overview
+```
+
+* Execute a command on the shares application using default parameters
+
+```
+<%=cmd%> 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
+
+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:
+
+```
+<%=cmd%> conf id my_secrets set 'access_key1' 'secret1'
+
+<%=cmd%> conf id my_secrets set 'access_key2' 'secret2'
+
+<%=cmd%> conf id default get config
+
+cli_default
 ```
 
-The fourth command defines this <%=prst%> as the default <%=prst%> for the
-specified application ("shares"). The 5th command displays the content of configuration file in table format.
-Alternative <%=prsts%> can be used with option "-P&lt;<%=prst%>&gt;"
-(or --preset=&lt;<%=prst%>&gt;)
+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:`):
 
-Eventually, the last command shows a call to the shares application using default parameters.
+```
+<%=cmd%> 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:
+
+```
+<%=cmd%> conf vault get --username=access_key1
+```
 
 ## Plugins
 
 The CLI tool uses a plugin mechanism. The first level command (just after <%=tool%> 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/<%=cmd%>/plugins
-$ cat<<EOF>~/.aspera/<%=cmd%>/plugins/test.rb
+mkdir -p ~/.aspera/<%=cmd%>/plugins
+cat<<EOF>~/.aspera/<%=cmd%>/plugins/test.rb
 require 'aspera/cli/plugin'
 module Aspera
   module Cli
@@ -998,39 +1131,78 @@ end # Aspera
 EOF
 ```
 
-## Debugging
+### <a id="plugins"></a>Plugins: Application URL and Authentication
+
+<%=tool%> 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:
 
-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 `<%=evp%>LOG_LEVEL`.
+* url
+* username
+* password
 
-It is also possible to activate traces before initialisation using env var `AS_LOG_LEVEL`.
+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 `<%=evp%>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:
+
+```
+<%=cmd%> 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
+
+<%=tool%> 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`). <%=tool%> 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
 
@@ -1039,13 +1211,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:
 
 ```
-$ <%=cmd%> config proxy_check --fpac=file:///./proxy.pac http://www.example.com
+<%=cmd%> 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:
 
@@ -1057,9 +1229,9 @@ The `config` plugin also allows specification for the use of a local FASP client
 ### Show path of currently used `ascp`
 
 ```
-$ <%=cmd%> config ascp show
+<%=cmd%> config ascp show
 /Users/laurent/.aspera/ascli/sdk/ascp
-$ <%=cmd%> config ascp info
+<%=cmd%> config ascp info
 +--------------------+-----------------------------------------------------------+
 | key                | value                                                     |
 +--------------------+-----------------------------------------------------------+
@@ -1067,7 +1239,7 @@ $ <%=cmd%> config ascp info
 ...
 ```
 
-### Selection of `ascp` location for [`direct`](#direct) agent
+### Selection of `ascp` location for [`direct`](#agt_direct) agent
 
 By default, <%=tool%> uses any found local product with ascp, including SDK.
 
@@ -1078,7 +1250,7 @@ For a permanent change, the command `config ascp use` sets the same parameter fo
 Using a POSIX shell:
 
 ```
-$ <%=cmd%> config ascp use '/Users/laurent/Applications/Aspera CLI/bin/ascp'
+<%=cmd%> 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
@@ -1087,7 +1259,7 @@ Saved to default global preset global_common_defaults
 Windows:
 
 ```
-$ <%=cmd%> config ascp use C:\Users\admin\.aspera\ascli\sdk\ascp.exe
+<%=cmd%> 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
@@ -1100,7 +1272,7 @@ If the path has spaces, read section: [Shell and Command line parsing](#parsing)
 Locally installed Aspera products can be listed with:
 
 ```
-$ <%=cmd%> config ascp products list
+<%=cmd%> config ascp products list
 :.........................................:................................................:
 :                  name                   :                    app_root                    :
 :.........................................:................................................:
@@ -1111,7 +1283,7 @@ $ <%=cmd%> 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`.
 
@@ -1120,14 +1292,14 @@ Using the option use_product finds the ascp binary of the selected product.
 To permanently use the ascp of a product:
 
 ```
-$ <%=cmd%> config ascp products use 'Aspera Connect'
+<%=cmd%> 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
 
 ```
-$ <%=cmd%> config ascp connect list
+<%=cmd%> config ascp connect list
 :...............................................:......................................:..............:
 :                      id                       :                title                 :   version    :
 :...............................................:......................................:..............:
@@ -1140,7 +1312,7 @@ $ <%=cmd%> 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 :
 :...............................................:......................................:..............:
-$ <%=cmd%> config ascp connect id 'Aspera Connect for Mac Intel 10.6' links list
+<%=cmd%> config ascp connect id 'Aspera Connect for Mac Intel 10.6' links list
 :.............................................:..........................:.......................................................................:..........:...............:
 :                    title                    :           type           :                                 href                                  : hreflang :      rel      :
 :.............................................:..........................:.......................................................................:..........:...............:
@@ -1153,11 +1325,11 @@ $ <%=cmd%> 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 :
 :.............................................:..........................:.......................................................................:..........:...............:
-$ <%=cmd%> config ascp connect id 'Aspera Connect for Mac Intel 10.6' links id 'Mac Intel Installer' download --to-folder=.
+<%=cmd%> 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`).
 
@@ -1166,102 +1338,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.
 
-<%=tool%> 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.
+<%=tool%> 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 <%=tool%> uses a local ascp, equivalent to specifying `--transfer=direct`.
-<%=tool%> will detect locally installed Aspera products.
+The `direct` agent directly executes a local ascp.
+This is the default for <%=tool%>.
+This is equivalent to specifying `--transfer=direct`.
+<%=tool%> 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:
 
 ```
-$ <%=cmd%> ... --transfer-info=@json:'{"wss":true,"resume":{"iter_max":10}}'
-$ <%=cmd%> ... --transfer-info=@json:'{"spawn_delay_sec":2.5,"multi_incr_udp":false}'
+<%=cmd%> ... --transfer-info=@json:'{"wss":true,"resume":{"iter_max":10}}'
+<%=cmd%> ... --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:
 
-By specifying option: `--transfer=connect`, <%=tool%> will start transfers
-using the locally installed Aspera Connect Client.
+* `EX_fasp_proxy_url`
+* `EX_http_proxy_url` (proxy for legacy http fallback)
+* `EX_ascp_args`
 
-### Aspera Node API : Node to node transfers
+### <a id="agt_connect"></a>IBM Aspera Connect Client GUI
+
+By specifying option: `--transfer=connect`, <%=tool%> will start transfers using the locally installed Aspera Connect Client. There are no option for `transfer_info`.
+
+### <a id="agt_node"></a>Aspera Node API : Node to node transfers
 
 By specifying option: `--transfer=node`, the CLI will start transfers in an Aspera
 Transfer Server using the Node API, either on a local or remote node.
+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 <%=prst%> :
-`--transfer-info=@preset:<psetname>` or specified using the option syntax :
+Like any other option, `transfer_info` can get its value from a pre-configured <%=prst%> :
+`--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:
 
 ```
-$ <%=cmd%> faspex package recv --id=323 --transfer=httpgw --transfer-info=@json:'{"url":"https://asperagw.example.com:9443/aspera/http-gwy/v1"}'
+<%=cmd%> 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:
@@ -1274,9 +1453,9 @@ is described in a _transfer-spec_ (Transfer Specification), such as:
 
 <%=tool%> 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:
 
@@ -1285,21 +1464,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:
 
 ```
-$ <%=cmd%> config ascp spec
-$ <%=cmd%> config ascp spec --select=@json:'{"f":"Y"}' --fields=-f,n,c
+<%=cmd%> config ascp spec
+<%=cmd%> config ascp spec --select=@json:'{"d":"Y"}' --fields=-d,n,c
 ```
 
 Columns:
@@ -1307,9 +1487,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 <%=tool%>).
+`ascp` argument or environment variable is provided in description.
+
+Fields with EX_ prefix are extensions to transfer agent [`direct`](#agt_direct). (only in <%=tool%>).
 
 <%=spec_table%>
 
@@ -1327,17 +1508,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:
 
 ```
-$ <%=cmd%> server upload ~/mysample.file secondfile
+<%=cmd%> server upload ~/mysample.file secondfile
 ```
 
 This is equivalent to:
 
 ```
-$ <%=cmd%> server upload --sources=@args ~/mysample.file secondfile
+<%=cmd%> 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).
@@ -1363,13 +1544,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`:
 
@@ -1379,10 +1566,10 @@ In case the file list is provided on the command line i.e. using `--sources=@arg
 Example:
 
 ```
-$ <%=cmd%> server upload --src-type=pair ~/Documents/Samples/200KB.1 /Upload/sample1
+<%=cmd%> 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:
 
@@ -1395,7 +1582,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.
 
@@ -1446,16 +1633,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 <%=tool%> is not executed several times in parallel.
 
 For instance when <%=tool%> 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:
@@ -1475,7 +1660,7 @@ Example:
 Run this same command in two separate terminals within less than 30 seconds:
 
 ```
-ascli config echo @ruby:'sleep(30)' --lock-port=12345
+<%=cmd%> config echo @ruby:'sleep(30)' --lock-port=12345
 ```
 
 The first instance will sleep 30 seconds, the second one will immediately exit like this:
@@ -1489,14 +1674,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:
 
 ```
-$ <%=cmd%> conf ascp info
+<%=cmd%> conf ascp info
 +--------------------+-----------------------------------------------------------+
 | key                | value                                                     |
 +--------------------+-----------------------------------------------------------+
------8<----snip---------
+-----8<-----snip-----8<-----
 | product_name       | IBM Aspera SDK                                            |
 | product_version    | 4.0.1.182389                                              |
 | process            | pvcl                                                      |
@@ -1521,20 +1706,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 <%=tool%>
+This is an extract of the man page of `ascp`. This feature is a feature of `ascp`, not <%=tool%>.
 
 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:
+
+```
+faux:///filename?filesize
+```
+
+where:
 
-* `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).
+* `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:
 
@@ -1542,21 +1733,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:
@@ -1564,40 +1755,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
 
 ```
-$ <%=cmd%> server upload faux:///myfile\?20g --to-folder=/Upload
+<%=cmd%> server upload faux:///myfile\?20g --to-folder=/Upload
 ```
 
 * Upload a file /tmp/sample but do not save results to disk (no docroot on destination)
 
 ```
-$ <%=cmd%> server upload /tmp/sample --to-folder=faux://
+<%=cmd%> 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
 
 ```
-$ <%=cmd%> server upload "faux:///mydir?file=testfile&count=1m&size=0&inc=2&seq=sequential" --to-folder=/Upload
+<%=cmd%> 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,44 +1797,28 @@ A non complete list of commands used in unit tests:
 ...and more
 ```
 
-## <a name="usage"></a>Usage
+## <a id="usage"></a>Usage
 
 ```
-$ <%=cmd%> -h
+<%=cmd%> -h
 <%=File.read(ENV["INCL_USAGE"])%>
 
 ```
 
 Note that actions and parameter values can be written in short form.
 
-# <a name="plugins"></a>Plugins: Application URL and Authentication
-
-<%=tool%> 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
 
 <%=tool%> provides a configuration wizard. Here is a sample invocation :
 
 ```
-$ <%=cmd%> config wizard
+<%=cmd%> config wizard
 option: url> https://myorg.ibmaspera.com
 Detected: Aspera on Cloud
 Preparing preset: aoc_myorg
@@ -1659,7 +1834,7 @@ Setting config preset as default for aspera
 saving config file
 Done.
 You can test with:
-$ <%=cmd%> aoc user info show
+<%=cmd%> aoc user info show
 ```
 
 Optionally, it is possible to create a new organization-specific "integration".
@@ -1667,7 +1842,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.
 
@@ -1679,7 +1854,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 [<%=prst%> for Aspera on Cloud](#aocpreset).
 
@@ -1687,7 +1862,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.<%=tool%> 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.
 
@@ -1711,31 +1886,31 @@ Note: for web based authentication, <%=tool%> listens on a local port (e.g. spec
 
 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><%=prst%> for Aspera on Cloud
+### <a id="aocpreset"></a><%=prst%> for Aspera on Cloud
 
 If you did not use the wizard, you can also manually create a <%=prst%> for <%=tool%> in its configuration file.
 
 Lets create an <%=prst%> called: `my_aoc_org` using `ask` interactive input (client info from previous step):
 
 ```
-$ <%=cmd%> config id my_aoc_org ask url client_id client_secret
+<%=cmd%> 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 <%=prst%> as default configuration for the `aspera` plugin:
 
 ```
-$ <%=cmd%> config id default set aoc my_aoc_org
+<%=cmd%> 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.
 
@@ -1750,13 +1925,13 @@ This can be done using any of the following method:
 * using the CLI:
 
 ```
-$ <%=cmd%> config genkey ~/.aspera/<%=cmd%>/aocapikey
+<%=cmd%> config genkey ~/.aspera/<%=cmd%>/aocapikey
 ```
 
 * `ssh-keygen`:
 
 ```
-$ ssh-keygen -t rsa -f ~/.aspera/<%=cmd%>/aocapikey -N ''
+ssh-keygen -t rsa -f ~/.aspera/<%=cmd%>/aocapikey -N ''
 ```
 
 * `openssl`
@@ -1764,11 +1939,11 @@ $ ssh-keygen -t rsa -f ~/.aspera/<%=cmd%>/aocapikey -N ''
 (on some openssl implementation (mac) there is option: -nodes (no DES))
 
 ```
-$ APIKEY=~/.aspera/<%=cmd%>/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/<%=cmd%>/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
@@ -1787,13 +1962,13 @@ If you are not using the built-in client_id and secret, JWT needs to be authoriz
 * Using command line
 
 ```
-$ <%=cmd%> aoc admin res client list
+<%=cmd%> aoc admin res client list
 :............:.........:
 :     id     :  name   :
 :............:.........:
 : BJLPObQiFw : <%=cmd%> :
 :............:.........:
-$ <%=cmd%> aoc admin res client --id=BJLPObQiFw modify @json:'{"jwt_grant_enabled":true,"explicit_authorization_required":false}'
+<%=cmd%> aoc admin res client modify --id=BJLPObQiFw @json:'{"jwt_grant_enabled":true,"explicit_authorization_required":false}'
 modified
 ```
 
@@ -1814,14 +1989,14 @@ open the previously generated public key located here: `$HOME/.aspera/<%=cmd%>/a
 * Using command line
 
 ```
-$ <%=cmd%> aoc admin res user list
+<%=cmd%> aoc admin res user list
 :........:................:
 :   id   :      name      :
 :........:................:
 : 109952 : Tech Support   :
 : 109951 : LAURENT MARTIN :
 :........:................:
-$ <%=cmd%> aoc user info modify @ruby:'{"public_key"=>File.read(File.expand_path("~/.aspera/<%=cmd%>/aocapikey.pub"))}'
+<%=cmd%> aoc user info modify @ruby:'{"public_key"=>File.read(File.expand_path("~/.aspera/<%=cmd%>/aocapikey.pub"))}'
 modified
 ```
 
@@ -1829,7 +2004,7 @@ Note: the `aspera user info show` command can be used to verify modifications.
 
 ### <%=prst%> modification for JWT
 
-To activate default use of JWT authentication for <%=tool%> using the <%=prst%>, do the folowing:
+To activate default use of JWT authentication for <%=tool%> using the <%=prst%>, do the following:
 
 * change auth method to JWT
 * provide location of private key
@@ -1838,7 +2013,7 @@ To activate default use of JWT authentication for <%=tool%> using the <%=prst%>,
 Execute:
 
 ```
-$ <%=cmd%> config id my_aoc_org update --auth=jwt --private-key=@val:@file:~/.aspera/<%=cmd%>/aocapikey --username=laurent.martin.aspera@fr.ibm.com
+<%=cmd%> config preset update my_aoc_org --auth=jwt --private-key=@val:@file:~/.aspera/<%=cmd%>/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.
@@ -1846,26 +2021,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 <%=prst%> created: <%=tool%> can be used:
 
 ```
-$ <%=cmd%> aoc files br /
+<%=cmd%> 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 
+
+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
+### Listing resources
 
 The command `aoc admin res <type> list` lists all entities of given type. It uses paging and multiple requests if necessary.
 
@@ -1887,7 +2065,7 @@ Other parameters are directly sent as parameters to the GET request on API.
 
 `page` and `per_page` are normally added by <%=tool%> 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).
 
@@ -1899,7 +2077,7 @@ Examples:
 <%=cmd%> 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:
 
 ```
 <%=cmd%> aoc admin res user list --query=@json:'{"q":"last_login_at:<2018-05-28"}'
@@ -1915,40 +2093,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).
 
-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:
+To execute an action on a specific resource, select it using one of those methods:
+
+* *recommended:* give id directly on command line *after the action*: `aoc admin res node show 123`
+* give name on command line *after the action*: `aoc admin res node show name abc`
+* 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:
 
 ```
-$ <%=cmd%> aoc admin res node --id="access_key1" --secret="secret1" v3 info
+<%=cmd%> 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:
 
 ```
-$ <%=cmd%> conf id my_secrets set 'access_key1' 'secret1'
-$ <%=cmd%> conf id my_secrets set 'access_key2' 'secret2'
-$ <%=cmd%> conf id default get config
-"cli_default"
+<%=cmd%> 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`:
 
 ```
-$ <%=cmd%> 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:
+
+```
+<%=cmd%> aoc admin analytics transfers --once-only=yes --lock-port=12345 \
+--query=@json:'{"status":"completed","direction":"receive"}' \
+--notif-to=active --notif-template=@file:mytemplate.erb
+```
 
-#### Examples
+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].
 
-* Bulk creation
+### 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 <%=cmd%> 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
 
 ```
-$ <%=cmd%> aoc admin res user create --bulk=yes @json:'[{"email":"dummyuser1@example.com"},{"email":"dummyuser2@example.com"}]'
+<%=cmd%> aoc admin res user create --bulk=yes @json:'[{"email":"dummyuser1@example.com"},{"email":"dummyuser2@example.com"}]'
 :.......:.........:
 :  id   : status  :
 :.......:.........:
@@ -1957,20 +2180,20 @@ $ <%=cmd%> aoc admin res user create --bulk=yes @json:'[{"email":"dummyuser1@exa
 :.......:.........:
 ```
 
-* Find with filter and delete
+### Example: Find with filter and delete
 
 ```
-$ <%=cmd%> aoc admin res user list --query='@json:{"q":"dummyuser"}' --fields=id,email
+<%=cmd%> aoc admin res user list --query='@json:{"q":"dummyuser"}' --fields=id,email
 :.......:........................:
 :  id   :         email          :
 :.......:........................:
 : 98398 : dummyuser1@example.com :
 : 98399 : dummyuser2@example.com :
 :.......:........................:
-$ thelist=$(<%=cmd%> aoc admin res user list --query='@json:{"q":"dummyuser"}' --fields=id --format=json --display=data|jq -cr 'map(.id)')
-$ echo $thelist
+thelist=$(<%=cmd%> aoc admin res user list --query='@json:{"q":"dummyuser"}' --fields=id --format=json --display=data|jq -cr 'map(.id)')
+echo $thelist
 ["113501","354061"]
-$ <%=cmd%> aoc admin res user --bulk=yes --id=@json:"$thelist" delete
+<%=cmd%> aoc admin res user --bulk=yes --id=@json:"$thelist" delete
 :.......:.........:
 :  id   : status  :
 :.......:.........:
@@ -1979,18 +2202,18 @@ $ <%=cmd%> 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}"}'
+<%=cmd%> aoc admin res user list --query=@ruby:'{"deactivated"=>true,"q"=>"last_login_at:<#{(DateTime.now.to_time.utc-2*365*86400).iso8601}"}'
 ```
 
 To delete them use the same method as before
 
-* Display current user's workspaces
+### Example: Display current user's workspaces
 
 ```
-$ <%=cmd%> aoc user workspaces
+<%=cmd%> aoc user workspaces
 :......:............................:
 :  id  :            name            :
 :......:............................:
@@ -2000,18 +2223,18 @@ $ <%=cmd%> 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)
 
 ```
-$ <%=cmd%> aoc admin resource node --name=_node_name_ --secret=_secret_ v4 access_key create --value=@json:'{"storage":{"path":"/folder1"}}'
+<%=cmd%> 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)
 
 ```
-$ <%=cmd%> aoc admin res node --secret=_secret_ v3 transfer list --value=@json:'[["q","*"],["count",5]]'
+<%=cmd%> aoc admin res node --secret=_secret_ v3 transfer list --value=@json:'[["q","*"],["count",5]]'
 ```
 
 Examples of query (TODO: cleanup):
@@ -2029,16 +2252,16 @@ Examples of query (TODO: cleanup):
               # active_only=true|false
 ```
 
-* Display node events (events)
+### Example: Display node events (events)
 
 ```
-$ <%=cmd%> aoc admin res node --secret=_secret_ v3 events
+<%=cmd%> aoc admin res node --secret=_secret_ v3 events
 ```
 
-* display members of a workspace
+### Example: Display members of a workspace
 
 ```
-$ <%=cmd%> aoc admin res workspace_membership list --fields=member_type,manager,member.email --query=@json:'{"embed":"member","inherited":false,"workspace_id":11363,"sort":"name"}'
+<%=cmd%> 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           :
 :.............:.........:..................................:
@@ -2057,7 +2280,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
 
@@ -2076,7 +2299,7 @@ WS2ID=$(<%=cmd%> aoc admin res workspace list --query=@json:'{"q":"'"$WS2"'"}' -
 c- Extract membership information
 
 ```
-$ <%=cmd%> aoc admin res workspace_membership list --fields=manager,member_id,member_type,workspace_id --query=@json:'{"workspace_id":'"$WS1ID"'}' --format=jsonpp > ws1_members.json
+<%=cmd%> 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:
@@ -2094,13 +2317,13 @@ jq '[.[] | {member_type,member_id,workspace_id,manager,workspace_id:"'"$WS2ID"'"
 e- Add members to second workspace
 
 ```
-$ <%=cmd%> aoc admin res workspace_membership create --bulk=yes @json:@file:ws2_members.json
+<%=cmd%> 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
 
 ```
-$ <%=cmd%> aoc admin res user list --fields=email --query=@json:'{"q":"last_login_at:<2018-05-28"}'
+<%=cmd%> aoc admin res user list --fields=email --query=@json:'{"q":"last_login_at:<2018-05-28"}'
 :...............................:
 :             email             :
 :...............................:
@@ -2109,20 +2332,20 @@ $ <%=cmd%> aoc admin res user list --fields=email --query=@json:'{"q":"last_logi
 :...............................:
 ```
 
-* List "Limited" users
+### Example: List "Limited" users
 
 ```
-$ <%=cmd%> aoc admin res user list --fields=email --select=@json:'{"member_of_any_workspace":false}'
+<%=cmd%> 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)
 
 ```
-$ <%=cmd%> conf wizard --url=https://sedemo.ibmaspera.com --username=laurent.martin.aspera@fr.ibm.com
+<%=cmd%> 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:
@@ -2141,7 +2364,7 @@ Setting config preset as default for aspera
 saving config file
 Done.
 You can test with:
-$ <%=cmd%> aoc user info show
+<%=cmd%> 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.
@@ -2151,20 +2374,20 @@ Then, create two shared folders located in two regions, in your files home, in a
 Then, transfer between those:
 
 ```
-$ <%=cmd%> -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}'
+<%=cmd%> -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
 
 ```
-$ <%=cmd%> aoc admin res admin/client create @json:'{"data":{"name":"laurentnode","client_subject_scopes":["alee","aejd"],"client_subject_enabled":true}}' --fields=token --format=csv
+<%=cmd%> 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
 
 ```
-$ <%=cmd%> aoc admin res admin/client list --fields=id --format=csv|<%=cmd%> aoc admin res admin/client delete --bulk=yes --id=@lines:@stdin:
+<%=cmd%> aoc admin res client list --fields=id --format=csv|<%=cmd%> aoc admin res client delete --bulk=yes --id=@lines:@stdin:
 +-----+---------+
 | id  | status  |
 +-----+---------+
@@ -2175,81 +2398,107 @@ $ <%=cmd%> aoc admin res admin/client list --fields=id --format=csv|<%=cmd%> aoc
 +-----+---------+
 ```
 
-* 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.
+
+So, for example, the creation of a node using ATS in IBM Cloud looks like (see other example in this manual):
 
-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"}'
+* create the access key on ATS
+
+```
+<%=cmd%> 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
 
 ```
-$ <%=cmd%> aoc admin res node --id=8669 shared_folders
+<%=cmd%> 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
 
 ```
-$ <%=cmd%> aoc admin res workspace --id=10818 shared_folders
+<%=cmd%> 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.
 
 ```
-$ <%=cmd%> aoc admin res node --id=8669 v4 perm 82 show
+shbxid=$(<%=cmd%> aoc user shared_inboxes --select=@json:'{"dropbox.name":"My Shared Inbox"}' --format=csv --fields=dropbox_id --display=data)
+
+<%=cmd%> 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:
 
 ```
-$ <%=cmd%> aoc packages send --value=[package extended value] [other parameters such as file list and transfer parameters]
+<%=cmd%> 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". <%=cmd%> 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: `<%=cmd%> 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"}]` . <%=cmd%> 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
+
 ```
-$ <%=cmd%> 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
+<%=cmd%> 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
+
 ```
-$ <%=cmd%> aoc package send --value=@json:'{"name":"my file in shared inbox","recipients":["The Shared Inbox"]}' my_file.dat --ts=@json:'{"target_rate_kbps":100000}'
+<%=cmd%> 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
+
 ```
-$ <%=cmd%> 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
+<%=cmd%> 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:
 
 ```
-$ <%=cmd%> aoc packages recv --id=ALL --once-only=yes --lock-port=12345
+<%=cmd%> 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:
 
@@ -2257,101 +2506,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)
+### Shared folders
 
-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>'`)
-
-* 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
+<%=cmd%> 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
 
 ```
-$ <%=cmd%> 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
+<%=cmd%> 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 <%=cmd%> aoc admin res node --name='my node name' --secret='my secret' v4 delete "$path" ;done
+<%=cmd%> aoc admin res node --id=8669 v4 perm 82 show
 ```
 
-* Delete the files in bulk
+### Cross Organization transfers
 
-```
-cat my_file_list.txt | <%=cmd%> 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 <%=prst%> 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 <%=prst%>: 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 <%=prst%>: e.g. `org2`
+* Check that access works and locate the destination folder `mydestfolder`
+* execute the following:
 
 ```
-$ <%=cmd%> aoc admin analytics transfers
+<%=cmd%> -Porg1 aoc files node_info /mydestfolder --format=json --display=data | <%=cmd%> -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
 
 ```
-$ <%=cmd%> 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.
+```
+<%=cmd%> 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 <%=cmd%> 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 <%=cmd%> 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 | <%=cmd%> 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 :
 
@@ -2361,10 +2616,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
 
@@ -2383,78 +2641,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:
 
 ```
-$ <%=cmd%> config id my_ibm_ats update --ibm-api-key=my_secret_api_key_here_8f8d9fdakjhfsashjk678
-$ <%=cmd%> config id default set ats my_ibm_ats
-$ <%=cmd%> ats api_key instances
+<%=cmd%> config preset update my_ibm_ats --ibm-api-key=my_secret_api_key_here_8f8d9fdakjhfsashjk678
+<%=cmd%> config preset set default ats my_ibm_ats
+<%=cmd%> ats api_key instances
 +--------------------------------------+
 | instance                             |
 +--------------------------------------+
 | aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee |
 +--------------------------------------+
-$ <%=cmd%> config id my_ibm_ats update --instance=aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee
-$ <%=cmd%> ats api_key create
+<%=cmd%> config preset update my_ibm_ats --instance=aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee
+<%=cmd%> ats api_key create
 +--------+----------------------------------------------+
 | key    | value                                        |
 +--------+----------------------------------------------+
 | id     | ats_XXXXXXXXXXXXXXXXXXXXXXXX                 |
 | secret | YYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYY |
 +--------+----------------------------------------------+
-$ <%=cmd%> config id my_ibm_ats update --ats-key=ats_XXXXXXXXXXXXXXXXXXXXXXXX --ats-secret=YYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYY
+<%=cmd%> config preset update my_ibm_ats --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 <%=prst%> 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 <%=prst%>: 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 <%=prst%>: e.g. `org2`
-* Check that access works and locate the destination folder `mydestfolder`
-* execute the following:
 
-```
-$ <%=cmd%> -Porg1 aoc files node_info /mydestfolder --format=json --display=data | <%=cmd%> -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):
 
 ```
-$ <%=cmd%> 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_"}'
+<%=cmd%> 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:
 
 ```
-$ <%=cmd%> 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"}}'
+<%=cmd%> 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:
 
 ```
-$ <%=cmd%> 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":"/"}}'
+<%=cmd%> 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":"/"}}'
 
 ```
 
@@ -2463,7 +2690,7 @@ $ <%=cmd%> ats access_key create --cloud=azure --region=eastus --params=@json:'{
 Example: create access key on Azure:
 
 ```
-$ <%=cmd%> 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":"/"}}'
+<%=cmd%> 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":"/"}}'
 
 ```
 
@@ -2473,74 +2700,77 @@ delete all my access keys:
 for k in $(<%=cmd%> ats access_key list --field=id --format=csv);do <%=cmd%> 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:
 
 ```
-$ <%=cmd%> server --url=ssh://... --ts=@json:'{"token":"Basic abc123"}'
+<%=cmd%> 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:
 
 ```
-$ <%=cmd%> server --ssh-keys=~/.ssh/id_rsa
-$ <%=cmd%> server --ssh-keys=@list:,~/.ssh/id_rsa
-$ <%=cmd%> server --ssh-keys=@json:'["~/.ssh/id_rsa"]'
+<%=cmd%> server --ssh-keys=~/.ssh/id_rsa
+<%=cmd%> server --ssh-keys=@list:,~/.ssh/id_rsa
+<%=cmd%> 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:
 
 ```
-$ <%=cmd%> server --ssh-options=@ruby:'{use_agent: false}' ...
+<%=cmd%> 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:
 
 ```
-$ <%=cmd%> config id aspera_demo_server update --url=ssh://demo.asperasoft.com:33001 --username=asperaweb --password=_demo_pass_
-$ <%=cmd%> config id default set server aspera_demo_server
-$ <%=cmd%> server browse /aspera-test-dir-large
-$ <%=cmd%> server download /aspera-test-dir-large/200MB
+<%=cmd%> config initdemo
+<%=cmd%> server browse /aspera-test-dir-large
+<%=cmd%> server download /aspera-test-dir-large/200MB
 ```
 
-This creates a <%=prst%> "aspera_demo_server" and set it as default for application "server"
-
+`initdemo` creates a <%=prst%> `demoserver` and set it as default for plugin `server`.
 
 # Plugin: IBM Aspera High Speed Transfer Server (node)
 
@@ -2572,12 +2802,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:
 
 ```
-$ <%=cmd%> node central file list
+<%=cmd%> node central file list
 ```
 
 by providing the `validator` option, offline transfer validation can be done.
@@ -2589,7 +2819,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).
 
 ```
-$ <%=cmd%> 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
+<%=cmd%> 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
@@ -2602,9 +2832,9 @@ Refer to [Aspera documentation](https://download.asperasoft.com/download/docs/en
 * configure a watchfolder to define automated transfers
 
 ```
-$ <%=cmd%> node service create @json:'{"id":"mywatchd","type":"WATCHD","run_as":{"user":"user1"}}'
-$ <%=cmd%> node service create @json:'{"id":"mywatchfolderd","type":"WATCHFOLDERD","run_as":{"user":"user1"}}'
-$ <%=cmd%> node watch_folder create @json:'{"id":"mywfolder","source_dir":"/watch1","target_dir":"/","transport":{"host":"10.25.0.4","user":"user1","pass":"mypassword"}}'
+<%=cmd%> node service create @json:'{"id":"mywatchd","type":"WATCHD","run_as":{"user":"user1"}}'
+<%=cmd%> node service create @json:'{"id":"mywatchfolderd","type":"WATCHFOLDERD","run_as":{"user":"user1"}}'
+<%=cmd%> 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
@@ -2612,13 +2842,13 @@ $ <%=cmd%> node watch_folder create @json:'{"id":"mywfolder","source_dir":"/watc
 Follow the Aspera Transfer Server configuration to activate this feature.
 
 ```
-$ <%=cmd%> node central file list --validator=<%=cmd%> --data=@json:'{"file_transfer_filter":{"max_result":1}}'
+<%=cmd%> node central file list --validator=<%=cmd%> --data=@json:'{"file_transfer_filter":{"max_result":1}}'
 :..............:..............:............:......................................:
 : session_uuid :    file_id   :   status   :              path                    :
 :..............:..............:............:......................................:
 : 1a74444c-... : 084fb181-... : validating : /home/xfer.../PKG - my title/200KB.1 :
 :..............:..............:............:......................................:
-$ <%=cmd%> node central file update --validator=<%=cmd%> --data=@json:'{"files":[{"session_uuid": "1a74444c-...","file_id": "084fb181-...","status": "completed"}]}'
+<%=cmd%> node central file update --validator=<%=cmd%> --data=@json:'{"files":[{"session_uuid": "1a74444c-...","file_id": "084fb181-...","status": "completed"}]}'
 updated
 ```
 
@@ -2634,7 +2864,7 @@ Create another configuration for the Azure ATS instance: in section "node", name
 Then execute the following command:
 
 ```
-$ <%=cmd%> node download /share/sourcefile --to-folder=/destinationfolder --preset=awsshod --transfer=node --transfer-info=@preset:azureats
+<%=cmd%> 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
@@ -2643,7 +2873,7 @@ to download files.
 ## Create access key
 
 ```
-$ <%=cmd%> node access_key create --value=@json:'{"id":"eudemo-sedemo","secret":"mystrongsecret","storage":{"type":"local","path":"/data/asperafiles"}}'
+<%=cmd%> node access_key create --value=@json:'{"id":"eudemo-sedemo","secret":"mystrongsecret","storage":{"type":"local","path":"/data/asperafiles"}}'
 ```
 
 # Plugin: IBM Aspera Faspex5
@@ -2668,7 +2898,7 @@ For boot method: (will be removed in future)
 Use it as password and use `--auth=boot`.
 
 ```
-$ <%=cmd%> conf id f5boot update --url=https://localhost/aspera/faspex --auth=boot --password=ABC.DEF.GHI...
+<%=cmd%> conf id f5boot update --url=https://localhost/aspera/faspex --auth=boot --password=ABC.DEF.GHI...
 ```
 
 Ready to use Faspex5 with CLI.
@@ -2714,7 +2944,7 @@ If no parameter `max` or `pmax` is provided, then all packages will be listed in
 ### Example
 
 ```
-$ <%=cmd%> faspex package list --box=inbox --recipient='*my_dropbox' --query=@json:'{"max":20,"pmax":2,"count":20}'
+<%=cmd%> 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`.
@@ -2728,14 +2958,14 @@ The command is `package recv`, possible methods are:
 * provide a `faspe:` URI with option `link`
 
 ```
-$ <%=cmd%> faspex package recv --id=12345
-$ <%=cmd%> faspex package recv --link=faspe://...
+<%=cmd%> faspex package recv --id=12345
+<%=cmd%> faspex package recv --link=faspe://...
 ```
 
 If the package is in a specific dropbox, add option `recipient` for both the `list` and `recv` commands.
 
 ```
-$ <%=cmd%> faspex package list --recipient='*thedropboxname'
+<%=cmd%> 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.
@@ -2747,7 +2977,7 @@ The command is `faspex package send`. Package information (title, note, metadata
 Example:
 
 ```
-$ <%=cmd%> 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
+<%=cmd%> 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"]`
@@ -2764,7 +2994,7 @@ Like for any transfer, a notification can be sent by email using parameters: `no
 Example:
 
 ```
-$ <%=cmd%> 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"]%>}'
+<%=cmd%> 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:`
@@ -2774,9 +3004,9 @@ In this example the notification template is directly provided on command line.
 Example:
 
 ```
-$ <%=cmd%> faspex v4 dropbox create --value=@json:'{"dropbox":{"e_wg_name":"test1","e_wg_desc":"test1"}}'
-$ <%=cmd%> faspex v4 dropbox list
-$ <%=cmd%> faspex v4 dropbox delete --id=36
+<%=cmd%> faspex v4 dropbox create --value=@json:'{"dropbox":{"e_wg_name":"test1","e_wg_desc":"test1"}}'
+<%=cmd%> faspex v4 dropbox list
+<%=cmd%> faspex v4 dropbox delete --id=36
 ```
 
 ## Remote sources
@@ -2814,7 +3044,7 @@ It is possible to tell <%=tool%> to download newly received packages, much like
 cargo client, or drive. Refer to the [same section](#aoccargo) in the Aspera on Cloud plugin:
 
 ```
-$ <%=cmd%> faspex packages recv --id=ALL --once-only=yes --lock-port=12345
+<%=cmd%> faspex packages recv --id=ALL --once-only=yes --lock-port=12345
 ```
 
 # Plugin: IBM Aspera Shares
@@ -2824,7 +3054,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 <%=cmd%> shares2 admin users list --value=@json:'{"page":'$p'}';done
+for p in 1 2 3;do <%=cmd%> shares2 admin users list --value=@json:'{"page":'$p'}';done
 ```
 
 # Plugin: IBM Cloud Object Storage
@@ -2833,9 +3063,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:
 
@@ -2847,15 +3077,15 @@ If you have those parameters already, then following options shall be provided:
 For example, let us create a default configuration:
 
 ```
-$ <%=cmd%> 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
-$ <%=cmd%> conf id default set cos mycos
+<%=cmd%> 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
+<%=cmd%> 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
 
@@ -2864,11 +3094,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:
 
@@ -2903,8 +3133,8 @@ The required options for this method are:
 For example, let us create a default configuration:
 
 ```
-$ <%=cmd%> conf id mycos update --bucket=laurent --service-credentials=@val:@json:@file:~/service_creds.json --region=us-south
-$ <%=cmd%> conf id default set cos mycos
+<%=cmd%> conf id mycos update --bucket=laurent --service-credentials=@val:@json:@file:~/service_creds.json --region=us-south
+<%=cmd%> conf id default set cos mycos
 ```
 
 ## Operations, transfers
@@ -2914,8 +3144,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:
 
 ```
-$ <%=cmd%> cos node info
-$ <%=cmd%> cos node upload 'faux:///sample1G?1g'
+<%=cmd%> cos node info
+<%=cmd%> 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.
@@ -2944,8 +3174,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`
@@ -2958,16 +3190,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`:
 
@@ -2984,7 +3218,7 @@ Other OSes should work as well, but are note tested.
 To check if all tools are found properly, execute:
 
 ```
-$ <%=cmd%> preview check
+<%=cmd%> preview check
 ```
 
 ### mimemagic
@@ -2992,22 +3226,22 @@ $ <%=cmd%> 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
@@ -3023,25 +3257,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
@@ -3053,9 +3287,11 @@ Like any <%=tool%> commands, parameters can be passed on command line or using a
 Note that the `xfer` user has a special protected shell: `aspshell`, so changing identity requires specification of alternate shell:
 
 ```
-# su -s /bin/bash - xfer
-$ <%=cmd%> config id previewconf update --url=https://localhost:9092 --username=my_access_key --password=my_secret --skip-types=office --lock-port=12346
-$ <%=cmd%> config id default set preview previewconf
+su -s /bin/bash - xfer
+
+<%=cmd%> config preset update previewconf --url=https://localhost:9092 --username=my_access_key --password=my_secret --skip-types=office --lock-port=12346
+
+<%=cmd%> config preset set default preview previewconf
 ```
 
 Here we assume that Office file generation is disabled, else remove this option.
@@ -3064,7 +3300,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:
 
 ```
-$ <%=cmd%> -Ppreviewconf node browse /
+<%=cmd%> -Ppreviewconf node browse /
 ```
 
 This shall list the contents of the storage root of the access key.
@@ -3080,8 +3316,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$ <%=cmd%> preview scan --overwrite=always
+su -s /bin/bash - xfer
+
+<%=cmd%> preview scan --overwrite=always
 ```
 
 When the preview generator is first executed it will create a file: `.aspera_access_key`
@@ -3095,13 +3332,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_<%=cmd%>`, 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
@@ -3111,13 +3348,13 @@ exec timeout ${tmout} <%=cmd%> "${@}"
 Here the cronjob is created for user `xfer`.
 
 ```
-xfer$ crontab<<EOF
+crontab<<EOF
 0    * * * *  /home/xfer/cron_<%=cmd%> preview scan --logger=syslog --display=error
 2-59 * * * *  /home/xfer/cron_<%=cmd%> 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)
 
@@ -3142,12 +3379,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:
 
 ```
-$ <%=cmd%> preview scan --skip-folders=@json:'["/not_here"]'
+<%=cmd%> 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:
 
@@ -3166,7 +3403,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
@@ -3186,7 +3423,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`
 
@@ -3216,28 +3453,28 @@ The `smtp` option is a hash table (extended value) with the following fields:
 ## Example of configuration:
 
 ```
-$ <%=cmd%> config id smtp_google set server smtp.google.com
-$ <%=cmd%> config id smtp_google set username john@gmail.com
-$ <%=cmd%> config id smtp_google set password P@ssw0rd
+<%=cmd%> config preset set smtp_google server smtp.google.com
+<%=cmd%> config preset set smtp_google username john@gmail.com
+<%=cmd%> config preset set smtp_google password P@ssw0rd
 ```
 
 or
 
 ```
-$ <%=cmd%> config id smtp_google init @json:'{"server":"smtp.google.com","username":"john@gmail.com","password":"P@ssw0rd"}'
+<%=cmd%> config preset init smtp_google @json:'{"server":"smtp.google.com","username":"john@gmail.com","password":"P@ssw0rd"}'
 ```
 
 or
 
 ```
-$ <%=cmd%> config id smtp_google update --server=smtp.google.com --username=john@gmail.com --password=P@ssw0rd
+<%=cmd%> 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:
 
 ```
-$ <%=cmd%> config id cli_default set smtp @val:@preset:smtp_google
-$ <%=cmd%> config id default set config cli_default
+<%=cmd%> config preset set cli_default smtp @val:@preset:smtp_google
+<%=cmd%> config preset set default config cli_default
 ```
 
 ## Email templates
@@ -3259,8 +3496,8 @@ Other variables are defined depending on context.
 Check settings with `smtp_settings` command. Send test email with `email_test`.
 
 ```
-$ <%=cmd%> config --smtp=@preset:smtp_google smtp
-$ <%=cmd%> config --smtp=@preset:smtp_google email --notif-to=sample.dest@example.com
+<%=cmd%> config --smtp=@preset:smtp_google smtp
+<%=cmd%> config --smtp=@preset:smtp_google email --notif-to=sample.dest@example.com
 ```
 
 ## Notifications for transfer status
@@ -3269,7 +3506,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:
 
@@ -3293,7 +3530,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)
@@ -3305,7 +3542,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.
 
@@ -3316,7 +3553,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
 
@@ -3343,7 +3580,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"}
@@ -3358,7 +3595,7 @@ Nodejs: [https://www.npmjs.com/package/aspera](https://www.npmjs.com/package/asp
 ## Help
 
 ```
-$ asession -h
+asession -h
 <%=File.read(ENV["INCL_ASESSION"])%>
 ```
 
@@ -3397,7 +3634,7 @@ Note that:
 
 * <%=tool%> 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
 
@@ -3412,18 +3649,18 @@ Once <%=tool%> parameters are defined, run the command using the OS native sched
 ## Example
 
 ```
-$ <%=cmd%> 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"]}'
+<%=cmd%> 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:
 
 ```
-$ <%=cmd%> console health
+<%=cmd%> console health
 +--------+-------------+------------+
 | status | component   | message    |
 +--------+-------------+------------+
@@ -3440,13 +3677,13 @@ Typically, the health check uses the REST API of the application with the follow
 <%=tool%> 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` :
 
 ```
-$ <%=cmd%> server health transfer --to-folder=/Upload --format=nagios --progress=none
+<%=cmd%> server health transfer --to-folder=/Upload --format=nagios --progress=none
 OK - [transfer:ok]
-$ <%=cmd%> server health asctlstatus --cmd_prefix='sudo ' --format=nagios
+<%=cmd%> 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:
 
@@ -3457,8 +3694,8 @@ Main components:
 A working example can be found in the gem, example:
 
 ```
-$ <%=cmd%> config gem_path
-$ cat $(<%=cmd%> config gem_path)/../examples/transfer.rb
+<%=cmd%> config gem_path
+cat $(<%=cmd%> config gem_path)/../examples/transfer.rb
 ```
 
 This sample code shows some example of use of the API as well as
@@ -3495,130 +3732,141 @@ So, it evolved into <%=tool%>:
 
 * <%=gemspec.version.to_s%>
 
-	* 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: support transfer agent: [Transfer SDK](#agt_trsdk)
+    * new: support [http socket options](#http_options)
+    * new: logs hide passwords and secrets, option `log_passwords` to enable logging secrets
+    * new: `config vault` supports encrypted passwords, also macos keychain
+    * new: `config preset` command for consistency with id
+    * new: identifier can be provided using either option `id` or directly after the command, e.g. `delete 123` is the same as `delete --id=123`
+    * change: when using wss, use [ruby's CA certs](#certificates)
+    * change: unexpected parameter makes exit code not zero
+    * change: (break) options `id` and `name` cannot be specified at the same time anymore, use [positional identifer or name selection](#res_select)
+    * change: (break) `aoc admin res node` does not take workspace main node as default node if no `id` specified.
+    * change: (break): `orchestrator workflow status` requires id, and supports special id `ALL`
+    * fix: various smaller fixes and renaming of some internal classes (transfer agents and few other)
+
+* 4.4.0
+
+    * new: `aoc packages list` add possibility to add filter with option `query`
+    * new: `aoc admin res xxx list` now get all items by default #50
+    * new: `preset` option can specify name or hash value
+    * new: `node` plugin accepts bearer token and access key as credential
+    * new: `node` option `token_type` allows using basic token in addition to aspera type.
+    * change: `server`: option `username` not mandatory anymore: xfer user is by default. If transfer spec token is provided, password or keys are optional, and bypass keys are used by default. 
+    * change: (break) resource `apps_new` of `aoc` replaced with `application` (more clear)
 
 * 4.3.0
 
-	* new: parameter `multi_incr_udp` for option `transfer_info`: control if UDP port is incremented when multi-session is used on [`direct`](#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 <%=tool%> 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 <%=tool%> 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 [<%=gemspec.homepage%>](<%=gemspec.homepage%>) 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 [<%=gemspec.homepage%>](<%=gemspec.homepage%>) 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
 
@@ -3627,7 +3875,7 @@ So, it evolved into <%=tool%>:
 * 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
 
@@ -3649,7 +3897,7 @@ So, it evolved into <%=tool%>:
 * 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
@@ -3681,7 +3929,7 @@ So, it evolved into <%=tool%>:
 
 * 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
@@ -3831,10 +4079,10 @@ So, it evolved into <%=tool%>:
 
 * 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
@@ -3914,16 +4162,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.
 
@@ -3955,7 +4203,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: