aspera-cli 4.13.0 → 4.14.0

data/README.md

@@ -1,12 +1,12 @@
 # Command Line Interface for IBM Aspera products
 <!-- markdownlint-disable MD033 MD003 MD053 -->
-<!-- cSpell:ignore devkit zcvf zxvf noded secondfile filesize sedemo eudemo webmail csum eascp loglevel cronfile magick keepalive inotify eastus bluemix trev sshfp struct genkey passout ibmaspera unpermitted schtasks taskschd -->
+<!-- cspell:ignore devkit zcvf zxvf noded secondfile filesize sedemo eudemo webmail csum eascp loglevel cronfile magick keepalive inotify eastus bluemix trev sshfp struct genkey passout ibmaspera unpermitted schtasks taskschd dascli -->
 
 [comment1]: # (Do not edit this README.md, edit docs/README.erb.md, for details, read docs/README.md)
 
 ##
 
-Version : 4.13.0
+Version : 4.14.0
 
 Laurent/2016-2023
 
@@ -92,7 +92,7 @@ ascli --version
 ```
 
 ```bash
-4.13.0
+4.14.0
 ```
 
 ### First use
@@ -196,9 +196,9 @@ The following sections provide information on the various installation methods.
 
 An internet connection is required for the installation. If you don't have internet for the installation, refer to section [Installation without internet access](#offline_install).
 
-### Docker container
+### Container
 
-The image is: [martinlaurent/ascli](https://hub.docker.com/r/martinlaurent/ascli).
+The container image is: [martinlaurent/ascli](https://hub.docker.com/r/martinlaurent/ascli).
 The container contains: Ruby, `ascli` and the Aspera Transfer SDK.
 To use the container, ensure that you have `podman` (or `docker`) installed.
 
@@ -206,7 +206,7 @@ To use the container, ensure that you have `podman` (or `docker`) installed.
 podman --version
 ```
 
-#### Container quick start
+#### Container: quick start
 
 **Wanna start quickly ?** With an interactive shell ? Execute this:
 
@@ -229,13 +229,13 @@ That is simple, but there are limitations:
 - Any generated file in the container will be lost on container (shell) exit. Including configuration files and downloaded files.
 - No possibility to upload files located on the host system
 
-#### Details on the container
+#### Container: Details
 
-The container image is built from this [Dockerfile](Dockerfile): the entry point is `ascli` and the default command is `help`.
+The container image is built from this [Dockerfile](Dockerfile.tmpl.erb): the entry point is `ascli` and the default command is `help`.
 
-If you want to run the image with a shell, execute with option: `--entrypoint bash`, and give argument `-l` (bash login to override the `help` default argument)
+If you want to run the image with a shell, execute with option: `--entrypoint bash`, and give argument `-l` (`bash` login option to override the `help` default argument)
 
-The container can also be execute for individual commands like this: (add `ascli` commands and options at the end of the command line, e.g. `-v` to display the version)
+The container can also be executed for individual commands like this: (add `ascli` commands and options at the end of the command line, e.g. `-v` to display the version)
 
 ```bash
 podman run --rm --tty --interactive martinlaurent/ascli:latest
@@ -254,11 +254,11 @@ ascli -v
 ```
 
 ```text
-4.13.0
+4.14.0
 ```
 
 In order to keep persistency of configuration on the host,
-you should mount your user's config folder to the container.
+you should specify your user's config folder as a volume for the container.
 To enable write access, a possibility is to run as `root` in the container (and set the default configuration folder to `/home/cliuser/.aspera/ascli`).
 Add options:
 
@@ -275,8 +275,8 @@ you can change the entry point, add option:
 --entrypoint bash
 ```
 
-You may also probably want that files downloaded in the container are in fact placed on the host.
-In this case you need also to mount the shared transfer folder:
+You may also probably want that files downloaded in the container are directed to the host.
+In this case you need also to specify the shared transfer folder as a volume:
 
 ```bash
 --volume $HOME/xferdir:/xferfiles
@@ -298,7 +298,7 @@ mkdir -p $HOME/.aspera/ascli
 asclish
 ```
 
-#### Sample container script
+#### Container: Sample start script
 
 A convenience sample script is also provided: download the script [`dascli`](../examples/dascli) from [the GIT repo](https://raw.githubusercontent.com/IBM/aspera-cli/main/examples/dascli) :
 
@@ -308,7 +308,7 @@ Some environment variables can be set for this script to adapt its behavior:
 
 | env var      | description                        | default                  | example                  |
 |--------------|------------------------------------|--------------------------|--------------------------|
-| ASCLI_HOME | configuration folder (persistency) | `$HOME/.aspera/ascli` | `$HOME/.ascliconfig`     |
+| ASCLI_HOME | configuration folder (persistency) | `$HOME/.aspera/ascli` | `$HOME/.ascli_config` |
 | docker_args  | additional options to `podman`     | &lt;empty&gt;            | `--volume /Users:/Users` |
 | image        | container image name               | martinlaurent/ascli      |                          |
 | version      | container image version            | latest                   | `4.8.0.pre`              |
@@ -339,7 +339,7 @@ echo 'Local file to transfer' > $xferdir/samplefile.txt
 >
 > **Note:** Do not use too many volumes, as the AUFS limits the number.
 
-#### Offline installation of the container
+#### Container: Offline installation
 
 - First create the image archive:
 
@@ -354,6 +354,50 @@ podman save martinlaurent/ascli|gzip>ascli_image_latest.tar.gz
 podman load -i ascli_image_latest.tar.gz
 ```
 
+#### Container: `aspera.conf`
+
+`ascp`'s configuration file `aspera.conf` is located in the container at: `/aspera_sdk/aspera.conf` (see Dockerfile).
+As the container is immutable, it is not recommended to modify this file.
+If one wants to change the content, it is possible to tell `ascp` to use another file using `ascp` option `-f`, e.g. by locating it on the host folder `$HOME/.aspera/ascli` mapped to the container folder `/home/cliuser/.aspera/ascli`:
+
+```bash
+echo '<CONF/>' > $HOME/.aspera/ascli/aspera.conf
+```
+
+Then, tell `ascp` to use that other conf file:
+
+```bash
+--transfer-info=@json:'{"ascp_args":["-f","/home/cliuser/.aspera/ascli/aspera.conf"]}'
+```
+
+#### Container: Singularity
+
+Singularity is another type of use of container.
+
+On Linux install:
+
+```console
+dnf install singularity-ce
+```
+
+Build an image like this:
+
+```bash
+singularity build ascli.sif docker://martinlaurent/ascli
+```
+
+The use like this:
+
+```bash
+singularity run ascli.sif
+```
+
+Or get a shell with access to the tool like this:
+
+```bash
+singularity shell ascli.sif
+```
+
 ### <a id="ruby"></a>Ruby
 
 Use this method to install on the native host.
@@ -459,25 +503,36 @@ brew install ruby
 
 #### Linux: package
 
-If your Linux distribution provides a standard Ruby package, you can use it provided that the version is compatible (check at beginning of section).
+If your Linux distribution provides a standard Ruby package, you can use it provided that the version supported.
 
-Example: RHEL 8 and 9: basic installation
+**Example:** RHEL 8+, Rocky Linux 8+, Centos 8 Stream: with extensions to compile native gems
 
-```bash
-yum module install ruby:3.1
-```
+- Check available ruby versions:
 
-Example: RHEL 8, Centos 8 Stream: with extensions to compile native gems
+  ```bash
+  dnf module list ruby
+  ```
 
-```bash
-yum install make automake gcc gcc-c++ kernel-devel
-yum install redhat-rpm-config
-dnf module reset ruby
-dnf module enable ruby:3.1
-dnf module -y install ruby:3.1/common
-```
+- If ruby was already installed with an older version, remove it:
 
-Other examples:
+  ```bash
+  dnf module -y reset ruby
+  ```
+
+- Install packages needed to build native gems:
+  
+    ```bash
+    dnf install -y make automake gcc gcc-c++ kernel-devel
+    ```
+
+- Enable the Ruby version you want:
+
+  ```bash
+  dnf module -y enable ruby:3.1
+  dnf install -y ruby-devel
+  ```
+
+**Other examples:**
 
 ```bash
 yum install -y ruby ruby-devel rubygems ruby-json
@@ -543,9 +598,10 @@ To upgrade to the latest version:
 gem update aspera-cli
 ```
 
-`ascli` checks every week if a new version is available and notify the user in a WARN log. To de-activate this feature set the option `version_check_days` to `0`, or specify a different period in days.
+`ascli` checks every week if a new version is available and notify the user in a WARN log.
+To de-activate this feature, globally set the option `version_check_days` to `0`, or specify a different period in days.
 
-To check manually:
+To check if a new version is available (independently of `version_check_days`):
 
 ```bash
 ascli conf check_update
@@ -696,21 +752,66 @@ Moreover all `ascp` options are supported either through transfer spec parameter
 
 #### Shell parsing for Unix-like systems: Linux, macOS, AIX
 
+Linux command line parsing is easy: It is fully documented in the shell's documentation.
+
 On Unix-like environments, this is typically a POSIX shell (bash, zsh, ksh, sh).
 In this environment the shell parses the command line, possibly replacing variables, etc...
-see [bash shell operation](https://www.gnu.org/software/bash/manual/bash.html#Shell-Operation).
-Then it builds a list of arguments and then `ascli` (Ruby) is executed.
+See [bash shell operation](https://www.gnu.org/software/bash/manual/bash.html#Shell-Operation).
+The shell builds the list of arguments and then `fork`/`exec` Ruby with that list.
 Ruby receives a list parameters from shell and gives it to `ascli`.
-So special character handling (quotes, spaces, env vars, ...) is first done in the shell.
+So special character handling (quotes, spaces, env vars, ...) is handled by the shell for any command executed.
 
 #### Shell parsing for Windows
 
-On Windows, `cmd.exe` is typically used.
-Windows process creation does not receive the list of arguments but just the whole line.
-It's up to the program to parse arguments. Ruby follows the Microsoft C/C++ parameter parsing rules.
+MS Windows command line parsing is not easy: It is not hasndled by the shell (`cmd.exe`), not handled by the operating system, but it is handled by the application (here Ruby).
+
+As far as `ascli` is concerned: it is close to a Linux shell parsing.
+
+Thanksfully, `ascli` provides a command to check the value of an argument after parsing: `config echo`.
+One can also run `ascli` with option `--log-level=debug` to display the command line after parsing.
+
+The following examples give the same result on Windows:
+
+- single quote protects the double quote
+
+  ```cmd
+   conf echo @json:'{"url":"https://..."}'
+  ```
+
+- triple double quotes are replaced with a single double quote
+
+  ```cmd
+   conf echo @json:{"""url""":"""https://..."""}
+  ```
+
+- double quote is escaped with backslash within double quotes
+
+  ```cmd
+   conf echo @json:"{\"url\":\"https://...\"}"
+  ```
+
+On Windows, `cmd.exe` is typically used to start .
+`cmd.exe` handles some special characters: `^"<>|%&`.
+Basically it handles I/O redirections (`<>|`), shell variables (`%`), multiple commands (`&`) and handles those special characters from the command line.
+Eventually, all those special characters are removed from the command line unless escaped with `^` or `"`.
+`"` are kept and given to the program.
+
+Then, Windows `CreateProcess` is called with just the whole command line as a single string, unlike Unix-like systems where the command line is split into arguments by the shell.
+
+It's up to the program to split arguments:
 
 - [Windows: How Command Line Parameters Are Parsed](https://daviddeley.com/autohotkey/parameters/parameters.htm#RUBY)
-- [Understand Quoting and Escaping of Windows Command Line Arguments](http://www.windowsinspired.com/understanding-the-command-line-string-and-arguments-received-by-a-windows-program/)
+- [Understand Quoting and Escaping of Windows Command Line Arguments](https://web.archive.org/web/20190316094059/http://www.windowsinspired.com/understanding-the-command-line-string-and-arguments-received-by-a-windows-program/)
+
+ is a Ruby program, so Ruby parses the command line into arguments and provides them to the program.
+Ruby vaguely follows the Microsoft C/C++ parameter parsing rules.
+(See `w32_cmdvector` in Ruby source [`win32.c`](https://github.com/ruby/ruby/blob/master/win32/win32.c#L1766)) : <!--cspell:disable-line-->
+
+- space characters: split arguments (space, tab, newline)
+- backslash: `\` escape single special character
+- globbing characters: `*?[]{}` for file globbing
+- double quotes: `"`
+- single quotes: `'`
 
 #### Extended Values (JSON, Ruby, ...)
 
@@ -727,12 +828,12 @@ Example: The shell parses three arguments (as strings: `1`, `2` and `3`), so the
 ascli conf echo 1 2 3
 ```
 
-```bash
+```ruby
 "1"
 ERROR: Argument: unprocessed values: ["2", "3"]
 ```
 
-`config echo` displays the value of the first argument using Ruby syntax: it surrounds a string with `"` and add `\` before special characters.
+`config echo` displays the value of the **first** argument using Ruby syntax: it surrounds a string with `"` and add `\` before special characters.
 
 > **Note:** It gets its value after shell command line parsing and `ascli` extended value parsing.
 
@@ -743,7 +844,7 @@ Depending on the case, a different `format` is used to display the actual value.
 For example, in the simple string `Hello World`, the space character is special for the shell, so it must be escaped so that a single value is represented.
 
 Double quotes are processed by the shell to create a single string argument.
-For POSIX shells, single quotes can also be used in this case, or protect the special character ` ` (space) with a backslash. <!-- markdownlint-disable-line -->
+For **POSIX shells**, single quotes can also be used in this case, or protect the special character ` ` (space) with a backslash. <!-- markdownlint-disable-line -->
 
 ```bash
 ascli conf echo "Hello World" --format=text
@@ -760,7 +861,7 @@ Hello World
 To be evaluated by shell, the shell variable must not be in single quotes.
 Even if the variable contains spaces it makes only one argument to `ascli` because word parsing is made before variable expansion by shell.
 
-> **Note:** we use a simple variable here: the variable is not necessarily an environment variable.
+> **Note:** we use a shell variable here: the variable is not necessarily an environment variable (`export`).
 
 ```bash
 MYVAR="Hello World"
@@ -843,6 +944,22 @@ ascli conf echo @ruby:"{'title'=>gets.chomp}" --format=json
 
 `gets` is Ruby's method of terminal input (terminated by `\n`), and `chomp` removes the trailing `\n`.
 
+#### Command line arguments from a file
+
+If you need to provide a list of command line argument from lines that are in a file, on Linux you can use the `xargs` command:
+
+```bash
+xargs -a lines.txt -d \\n ascli conf echo
+```
+
+This is equivalent to execution of:
+
+```bash
+ascli conf echo [line1] [line2] [line3] ...
+```
+
+If there are spaces in the lines, those are not taken as separator, as we provide option `-d \\n` to `xargs`.
+
 #### Extended value using special characters read from environmental variables or files
 
 Using a text editor or shell: create a file `title.txt` (and env var) that contains exactly the text required: `Test " ' & \` :
@@ -876,25 +993,50 @@ ascli conf echo @ruby:"{'title'=>ENV['MYTITLE']}" --format=json
 {"title":"Test \" ' & \\"}
 ```
 
-### Arguments : Commands and options
+### Commands, Options, Positional Values
 
-Arguments are the units of command line, as parsed by the shell, typically separated by spaces (and called "argv").
+Command line arguments are the units of command line, as parsed by the shell, typically separated by spaces (and called "argv").
 
-There are two types of command line arguments: Commands and Options. Example :
+`ascli` considers three types of command line arguments:
+
+- Commands
+- Options
+- Positional Values
 
 ```bash
 ascli command subcommand --option-name=VAL1 VAL2
 ```
 
 - executes *command*: `command subcommand`
-- with one *option*: `option_name`
-- this option is given a *value* of: `VAL1`
-- the command has one additional *argument*: `VAL2`
+- with one *option*: `option_name`and its *value*: `VAL1`
+- the command has one additional mandatory *argument*: `VAL2`
 
-When the value of a command, option or argument is constrained by a fixed list of values, it is possible to use the first letters of the value only, provided that it uniquely identifies a value. For example `ascli conf ov` is the same as `ascli config overview`.
+When the value of a command, option or argument is constrained by a fixed list of values.
+It is possible to use the first letters of the value only, provided that it uniquely identifies a value.
+For example `ascli conf ov` is the same as `ascli config overview`.
 
 The value of options and arguments is evaluated with the [Extended Value Syntax](#extended).
 
+#### Commands
+
+Commands are typically entity types or verbs to act on those entities.
+
+Example:
+
+```bash
+ascli conf ascp info
+```
+
+- `ascli` is the executable executed by the shell
+- `conf` is the first level command, and is also the name f the plugin to be used
+- `ascp` is the second level command, and is also the name of the component (singleton)
+- `info` is the third level command, and is also the action to be performed
+
+Typically, commands are located at the beginning of the command line.
+Order is significant.
+The provided command must match one of the supported commands in the given context.
+If a wrong , or no command is provided when expected, an error message is displayed and the list of supported commands is displayed.
+
 #### Options
 
 All options, e.g. `--log-level=debug`, are command line arguments that:
@@ -902,7 +1044,7 @@ All options, e.g. `--log-level=debug`, are command line arguments that:
 - start with `--`
 - have a name, in lowercase, using `-` as word separator in name  (e.g. `--log-level=debug`)
 - have a value, separated from name with a `=`
-- can be used by prefix, provided that it is unique. E.g. `--log-l=debug` is the same as `--log-level=debug`
+- can be used by prefix, provided that it is unique. E.g. `--log-l=debug` is the same as `--log-level=debug` (avoid)
 
 Exceptions:
 
@@ -910,17 +1052,24 @@ Exceptions:
 - some options (flags) don't take a value, e.g. `-r`
 - the special option `--` stops option processing and is ignored, following command line arguments are taken as arguments, including the ones starting with a `-`. Example:
 
-```bash
-ascli config echo -- --sample
-```
+  ```bash
+  ascli config echo -- --sample
+  ```
 
-```bash
-"--sample"
-```
+  ```bash
+  "--sample"
+  ```
 
 > **Note:** Here, `--sample` is taken as an argument, and not as an option, due to `--`.
 
-Options can be optional or mandatory, with or without (hardcoded) default value. Options can be placed anywhere on command line and evaluated in order.
+Options may have an (hardcoded) default value.
+
+Options can be placed anywhere on command line and evaluated in order.
+
+Options are typically either:
+
+- optional : typically to change the default behavior
+- mandatory : typically, connection information are options that are mandatory (so they can be placed in a config file)
 
 The value for *any* options can come from the following locations (in this order, last value evaluated overrides previous value):
 
@@ -932,9 +1081,16 @@ Environment variable starting with prefix: ASCLI_ are taken as option values, e.
 
 Options values can be displayed for a given command by providing the `--show-config` option: `ascli node --show-config`
 
-#### Commands and Arguments
+#### Positional Values
 
-Command line arguments that are not options are either commands or arguments. If an argument must begin with `-`, then either use the `@val:` syntax (see [Extended Values](#extended)), or use the `--` separator (see above).
+Positional Values are typically mandatory values for a command, such as entity creation data.
+
+If a Positional Values begins with `-`, then either use the `@val:` syntax (see [Extended Values](#extended)), or use the `--` separator (see above).
+
+The advantages of using a positional value instead of an option for the same are that the command line is shorter(no option name, just the position) and the value is clearly mandatory.
+
+The disadvantage is that it is not possible to define a default value in a config file or environment variable like for options.
+Nevertheless, [Extended Values](#extended) syntax is supported, so it is possible to retrieve a value from the config file or environment variable.
 
 ### Interactive Input
 
@@ -1006,6 +1162,16 @@ ascli aoc admin res user list --fields=name,email,ats_admin --query=@json:'{"sor
 
 > **Note:** `select` filters selected elements from the result of API calls, while the `query` parameters gives filtering parameters to the API when listing elements.
 
+#### entity identifier
+
+When a command is executed on a single entity, the entity is identified by a unique identifier that follows the command: e.g. `ascli aoc admin res user show 1234` where `1234` is the user identifier.
+
+> **Note:** The legacy option `id` is deprecated: `--id=1234` as it does not provide the possibility to have sub-entities.
+
+Only some commands provide the following capability: If the entity can also be uniquely identified by a name, then the name can be used instead of the identifier, using the **percent selector**: `ascli aoc admin res user show %name:john` where `john` is the user name.
+
+Syntax: `%<field>:<value>`
+
 #### Verbosity of output
 
 Output messages are categorized in 3 types:
@@ -1235,9 +1401,9 @@ ascli config open
 Older format for commands are still supported:
 
 ```bash
-ascli config id <name> set|delete|show|initialize|update
-ascli config over
-ascli config list
+ascli config preset set|delete|show|initialize|update <name>
+ascli config preset over
+ascli config preset list
 ```
 
 #### <a id="lprtconf"></a>Special Option preset: config
@@ -1268,13 +1434,37 @@ ascli config preset get default _plugin_name_
 
 #### <a id="config"></a>Plugin: `config`: Configuration
 
-Plugin `config` is used to configure `ascli` and also contains global options.
+Plugin `config` provides general commands for `ascli`:
+
+- Option preset, config file operations
+- wizard
+- vault
+- ascp
+
+The default configuration for `config` is read for any plugin invocation, this allows setting global options, such as `--log-level` or `--interactive`.
+When `ascli` starts, it looks for the `default` Option preset and checks the value for `config`.
+If set, it loads the option values for any plugin used.
+
+> **Note:** If no global default is set by the user, the tool will use `global_common_defaults` when setting global parameters (e.g. `conf ascp use`)
+
+Show current default (global) Option preset (`config` plugin):
+
+```console
+$ ascli conf preset get default config
+global_common_defaults
+```
+
+```bash
+ascli conf preset set global_common_defaults version_check_days 0
+```
 
-When `ascli` starts, it looks for the `default` Option preset and if there is a value for `config`, if so, it loads the option values for any plugin used.
+If the default global Option preset is not set:
 
-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`)
+```bash
+ascli conf preset set default config global_common_defaults
+```
 
-Sample commands
+#### Config sample commands
 
 ```bash
 config ascp connect info 'Aspera Connect for Windows'
@@ -1377,7 +1567,7 @@ Some options are global, some options are available only for some plugins. (the
 
 Options are loaded using this algorithm:
 
-- If option `--no-default` (or `-N`) is specified, then no default value is loaded is loaded for the plugin
+- If option `--no-default` (or `-N`) is specified, then no default value is loaded for the plugin
 - else it looks for the name of the plugin as key in section `default`, the value is the name of the default [option preset](#lprt) for it, and loads it.
 - If option `--preset=<name or extended value hash>` is specified (or `-Pxxxx`), this reads the [option preset](#lprt) specified from the configuration file, or of the value is a Hash, it uses it as options values.
 - Environment variables are evaluated
@@ -1459,7 +1649,7 @@ ascli config preset set default shares shares06
 - Display the content of configuration file in table format
 
 ```bash
-ascli config overview
+ascli config preset overview
 ```
 
 - Execute a command on the shares application using default parameters
@@ -1718,13 +1908,13 @@ Examples:
 - display debugging log on `stdout`:
 
 ```bash
-ascli conf over --log-level=debug --logger=stdout
+ascli conf pre over --log-level=debug --logger=stdout
 ```
 
 - log errors to `syslog`:
 
 ```bash
-ascli conf over --log-level=error --logger=syslog
+ascli conf pre over --log-level=error --logger=syslog
 ```
 
 When `ascli` is used interactively in a shell, the shell itself will usually log executed commands in the history file.
@@ -1848,7 +2038,7 @@ Only supported with the `direct` agent: To specify a proxy for legacy HTTP fallb
 
 ### FASP proxy (forward) for transfers
 
-To specify a FASP proxy (forward), set the [*transfer-spec*](#transferspec) parameter: `EX_fasp_proxy_url` (only supported with the `direct` agent).
+To specify a FASP proxy (forward), set the [*transfer-spec*](#transferspec) parameter: `proxy` (only supported with the `direct` agent).
 
 ### <a id="client"></a>FASP configuration
 
@@ -2184,11 +2374,13 @@ Parameters provided in option `transfer_info` are:
 | url                    | string | URL of the HTTP GW</br>Mandatory      |
 | upload_bar_refresh_sec | float  | Refresh rate for upload progress bar  |
 | upload_chunk_size      | int    | Size in bytes of chunks for upload    |
+| api_version            | string | v1 or v2, for force use of version    |
+| synchronous            | bool   | wait for each message acknowledgment  |
 
 Example:
 
 ```bash
-ascli faspex package recv --id=323 --transfer=httpgw --transfer-info=@json:'{"url":"https://asperagw.example.com:9443/aspera/http-gwy/v1"}'
+ascli faspex package recv 323 --transfer=httpgw --transfer-info=@json:'{"url":"https://asperagw.example.com:9443/aspera/http-gwy"}'
 ```
 
 > **Note:** The gateway only supports transfers authorized with a token.
@@ -2231,7 +2423,10 @@ The [*transfer-spec*](#transferspec) is a Hash (dictionary), so it is described
 
 It is possible to modify or add any of the supported [*transfer-spec*](#transferspec) parameter using the `ts` option.
 The `ts` option accepts a [Structured Value](#native) containing one or several [*transfer-spec*](#transferspec) parameters in a `Hash`.
-Multiple `ts` options on command line are cumulative.
+Multiple `ts` options on command line are cumulative, and Hash is deeply merged.
+To remove a (deep) key from transfer spec, set the value to `null`.
+
+> **Note:** Default transfer spec values can be displayed with command: `config ascp info --flat-hash=no` under field `ts`.
 
 It is possible to specify `ascp` options when the `transfer` option is set to [`direct`](#agt_direct) using `transfer_info` option parameter: `ascp_args`.
 Example: `--transfer-info=@json:'{"ascp_args":["-l","100m"]}'`.
@@ -2353,7 +2548,7 @@ Fields with EX_ prefix are extensions to transfer agent [`direct`](#agt_direct).
 | EX_license_text | string | Y | &nbsp; | &nbsp; | License file text override.<br/>By default ascp looks for license file near executable.<br/>(env:ASPERA_SCP_LICENSE) |
 | EX_no_read | bool | Y | &nbsp; | &nbsp; | no read source<br/>(--no-read) |
 | EX_no_write | bool | Y | &nbsp; | &nbsp; | no write on destination<br/>(--no-write) |
-| EX_proxy_password | string | Y | &nbsp; | &nbsp; | Password used for Aspera proxy server authentication.<br/>May be overridden by password in URL EX_fasp_proxy_url.<br/>(env:ASPERA_PROXY_PASS) |
+| EX_proxy_password | string | Y | &nbsp; | &nbsp; | Password used for Aspera proxy server authentication.<br/>May be overridden by password in URL provided in parameter: proxy.<br/>(env:ASPERA_PROXY_PASS) |
 | EX_ssh_key_paths | array | Y | &nbsp; | &nbsp; | Use public key authentication for SSH and specify the private key file paths<br/>(-i {array}) |
 
 #### Destination folder for transfers
@@ -2461,6 +2656,58 @@ ascli server upload --src-type=pair ~/Documents/Samples/200KB.1 /Upload/sample1
 
 > **Note:** There are some specific rules to specify a file list when using **Aspera on Cloud**, refer to the AoC plugin section.
 
+#### Source directory structure on destination
+
+This section is not specific to `ascli`, it is `ascp` behaviour.
+
+The transfer destination is normally expected to designate a destination folder.
+
+But there is one exception: The destination specifies the new item name when the following are met:
+
+- there is a single source item (file or folder)
+- transfer spec `create_dir` is not set to `true` (`ascp` option `-d` not provided)
+- destination is not an existing folder
+- the `dirname` of destination is an existing folder
+
+For this reason it is recommended to set `create_dir` to `true` for consistent behaviour between single and multiple items transfer, this is the default in `ascli`.
+
+If a simple source file list is provided (no `destination` in `paths`, i.e. no `file_pair_list` provided), the destination folder is used as destination folder for each source file, and source file folder names are not preserved.
+
+The inner structure of source items that are folder is preserved on destination.
+
+A leading `/` on destination is ignored (relative to docroot) unless docroot is not set (relative to home).
+
+In the following table source folder `d3` contains 2 files: `f1` and `d4/f2`.
+
+| Source files | Destination | Folders on Dest.  |`create_dir`| Destination Files           |
+|--------------|-------------|-------------------|------------|-----------------------------|
+| f1           | d/f         | -                 | false      | Error: `d` does not exist.  |
+| f1           | d/f         | d                 | false      | d/f    (renamed)            |
+| f1           | d/f/.       | d                 | false      | d/f    (renamed)            |
+| f1           | d/f         | d/f               | false      | d/f/f1                      |
+| f1 f2        | d           | d                 | false      | d/f1 d/f2                   |
+| d3           | d           | -                 | false      | d/f1 d/f2  (renamed)        |
+| f1           | d           | -                 | true       | d/f1                        |
+| f1 f2        | d           | -                 | true       | d/f1 d/f2                   |
+| d1/f1 d2/f2  | d           | -                 | true       | d/f1 d/f2                   |
+| d3           | d           | -                 | true       | d/d3/f1 d/d3/d4/f2          |
+
+If a file par list is provided then it is possible to rename or specify a different destination folder for each source (relative to the destination).
+
+If transfer spec has a `src_base`, it has the side effect that the simple source file list is considered as a file pair list, and so the lower structure of source folders is preserved on destination.
+
+| Source files      | Destination |`src_base`| Destination Files           |
+|-------------------|-------------|----------|-----------------------------|
+| d1/d2/f2 d1/d3/f3 | d           | d1       | d/d2/f2 d/d3/f3             |
+
+Advanced Example: Send files `./file1` and `./folder2/files2` to server (e.g. `/Upload`) and keep the original file names and folders, i.e. send `file1` to `/Upload/file1` and `files2` to `/Upload/folder2/files2`.
+
+- If files are specified as `./file1 ./folder2/files2`, then destination will be: `/Upload/file1 /Upload/files2`
+- One possibility is to specify a file pair list: `--src-type=pair file1 file1 folder2/files2 folder2/files2`
+- Another possibility is to specify a source base: `--src-base=$PWD $PWD/file1 $PWD/folder2/files2` (note that `.` cannot be used as source base)
+- Similarly, create a temporary soft link (Linux): `ln -s . tmp_base` and use `--src-base=tmp_base tmp_base/file1 tmp_base/folder2/files2`
+- One can also similarly use `--sources=@ts` and specify the list of files in the `paths` field of transfer spec with both `source` and `destination` for each file.
+
 #### <a id="multisession"></a>Support of multi-session
 
 Multi session, 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.
@@ -2487,11 +2734,10 @@ When multi-session is used, one separate UDP port is used per session (refer to
 
 #### Content protection
 
-Also known as Client-side encryption at rest (CSEAR), content protection allows a client to send files to a server
-which will store them encrypted (upload), and decrypt files as they are being downloaded from a server, both
-using a passphrase, only known by users sharing files. Files stay encrypted on server side.
+Also known as Client-side encryption at rest (CSEAR), content protection allows a client to send files to a server which will store them encrypted (upload), and decrypt files as they are being downloaded from a server, both using a passphrase, only known by users sharing files.
+Files stay encrypted on server side.
 
-activating CSEAR consists in using transfer spec parameters:
+Activating CSEAR consists in using transfer spec parameters:
 
 - `content_protection` : activate encryption (`encrypt` for upload) or decryption (`decrypt` for download)
 - `content_protection_password` : the passphrase to be used.
@@ -2653,10 +2899,13 @@ One of the adapters, used in this manual, for testing, is `faux`. It is a pseudo
 
 ### <a id="faux_testing"></a>`faux:` for testing
 
-This is an extract of the man page of `ascp`. This feature is a feature of `ascp`, not `ascli`.
+This is an extract of the man page of `ascp`.
+This feature is a feature of `ascp`, not `ascli`.
 
 This adapter can be used to simulate a file or a directory.
 
+To discard data at the destination, the destination argument is set to `faux://`.
+
 To send uninitialized data in place of an actual source file, the source file is replaced with an argument of the form:
 
 ```bash
@@ -2710,8 +2959,6 @@ The sequence parameter is applied as follows:
 
 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 gibibytes of random data to file myfile to directory /Upload
@@ -2737,7 +2984,7 @@ ascli server upload "faux:///mydir?file=testfile&count=1m&size=0&inc=2&seq=seque
 ```text
 ascli -h
 NAME
-        ascli -- a command line tool for Aspera Applications (v4.13.0)
+        ascli -- a command line tool for Aspera Applications (v4.14.0)
 
 SYNOPSIS
         ascli COMMANDS [OPTIONS] [ARGS]
@@ -2767,52 +3014,52 @@ ARGS
         Some commands require mandatory arguments, e.g. a path.
 
 OPTIONS: global
-        --interactive=ENUM           use interactive input of missing params: [no], yes
-        --ask-options=ENUM           ask even optional options: [no], yes
-        --format=ENUM                output format: text, nagios, ruby, json, jsonpp, yaml, [table], csv
-        --display=ENUM               output only some information: [info], data, error
-        --fields=VALUE               comma separated list of fields, or ALL, or DEF
-        --select=VALUE               select only some items in lists, extended value: hash (column, value)
-        --table-style=VALUE          table display style
-        --flat-hash=ENUM             display hash values as additional keys: no, [yes]
-        --transpose-single=ENUM      single object fields output vertically: no, [yes]
-        --show-secrets=ENUM          show secrets on command output: [no], yes
-    -h, --help                       Show this message.
-        --bash-comp                  generate bash completion for command
-        --show-config                Display parameters used for the provided action.
-    -r, --rest-debug                 more debug for HTTP calls
-    -v, --version                    display version
-    -w, --warnings                   check for language warnings
-        --ui=ENUM                    method to start browser: text, [graphical]
+        --interactive=ENUM           Use interactive input of missing params: [no], yes
+        --ask-options=ENUM           Ask even optional options: [no], yes
+        --format=ENUM                Output format: text, nagios, ruby, json, jsonpp, yaml, [table], csv
+        --display=ENUM               Output only some information: [info], data, error
+        --fields=VALUE               Comma separated list of fields, or ALL, or DEF
+        --select=VALUE               Select only some items in lists: column, value (Hash)
+        --table-style=VALUE          Table display style
+        --flat-hash=ENUM             Display deep values as additional keys: no, [yes]
+        --transpose-single=ENUM      Single object fields output vertically: no, [yes]
+        --show-secrets=ENUM          Show secrets on command output: [no], yes
+    -h, --help                       Show this message
+        --bash-comp                  Generate bash completion for command
+        --show-config                Display parameters used for the provided action
+    -r, --rest-debug                 More debug for HTTP calls (REST)
+    -v, --version                    Display version
+    -w, --warnings                   Check for language warnings
+        --ui=ENUM                    Method to start browser: text, [graphical]
         --log-level=ENUM             Log level: debug, info, [warn], error, fatal, unknown
-        --logger=ENUM                logging method: [stderr], stdout, syslog
-        --lock-port=VALUE            prevent dual execution of a command, e.g. in cron
-        --http-options=VALUE         options for http socket (extended value)
-        --insecure=ENUM              do not validate HTTPS certificate: no, [yes]
-        --once-only=ENUM             process only new items (some commands): [no], yes
-        --log-secrets=ENUM           show passwords in logs: [no], yes
-        --cache-tokens=ENUM          save and reuse Oauth tokens: no, [yes]
+        --logger=ENUM                Logging method: [stderr], stdout, syslog
+        --lock-port=VALUE            Prevent dual execution of a command, e.g. in cron
+        --http-options=VALUE         Options for http socket (Hash)
+        --insecure=ENUM              Do not validate HTTPS certificate: [no], yes
+        --once-only=ENUM             Process only new items (some commands): [no], yes
+        --log-secrets=ENUM           Show passwords in logs: [no], yes
+        --cache-tokens=ENUM          Save and reuse Oauth tokens: no, [yes]
 
 COMMAND: config
-SUBCOMMANDS: ascp check_update coffee detect documentation echo email_test export_to_cli file flush_tokens folder gem genkey id initdemo list lookup open overview plugin preset proxy_check secure smtp_settings vault wizard
+SUBCOMMANDS: ascp check_update coffee detect documentation echo email_test file flush_tokens folder gem genkey initdemo open plugin preset proxy_check smtp_settings vault wizard
 OPTIONS:
-        --query=VALUE                additional filter for API calls (extended value) (some commands)
-        --value=VALUE                extended value for create, update, list filter
-        --property=VALUE             name of property to set
-        --id=VALUE                   resource identifier (modify,delete,show)
+        --query=VALUE                Additional filter for for some commands (list/delete) (Hash)
+        --value=VALUE                Value for create, update, list filter (Hash) (deprecated: Use positional value for create/modify or option: query for list/delete)
+        --property=VALUE             Name of property to set (modify operation)
+        --id=VALUE                   Resource identifier (deprecated: Use identifier after verb (modify,delete,show))
         --bulk=ENUM                  Bulk operation (only some): [no], yes
-        --bfail=ENUM                 Bulk operation error handling: [no], yes
-        --config-file=VALUE          read parameters from file in YAML format, current=/usershome/.aspera/ascli/config.yaml
-    -N, --no-default                 do not load default configuration for plugin
+        --bfail=ENUM                 Bulk operation error handling: no, [yes]
+        --config-file=VALUE          Read parameters from file in YAML format, current=/usershome/.aspera/ascli/config.yaml
+    -N, --no-default                 Do not load default configuration for plugin
         --override=ENUM              Wizard: override existing value: [no], yes
-        --use-generic-client=ENUM    Wizard: AoC: use global or org specific jwt client id: [no], yes
-        --default=ENUM               Wizard: set as default configuration for specified plugin (also: update): [no], yes
+        --use-generic-client=ENUM    Wizard: AoC: use global or org specific jwt client id: no, [yes]
+        --default=ENUM               Wizard: set as default configuration for specified plugin (also: update): no, [yes]
         --test-mode=ENUM             Wizard: skip private key check step: [no], yes
-    -P, --presetVALUE                load the named option preset from current config file
+    -P, --presetVALUE                Load the named option preset from current config file
         --pkeypath=VALUE             Wizard: path to private key for JWT
         --ascp-path=VALUE            Path to ascp
         --use-product=VALUE          Use ascp from specified product
-        --smtp=VALUE                 SMTP configuration (extended value: hash)
+        --smtp=VALUE                 SMTP configuration (Hash)
         --fpac=VALUE                 Proxy auto configuration script
         --proxy-credentials=VALUE    HTTP proxy credentials (Array with user and password)
         --secret=VALUE               Secret for access keys
@@ -2824,65 +3071,63 @@ OPTIONS:
         --notif-template=VALUE       Email ERB template for notification of transfers
         --version-check-days=VALUE   Period in days to check new version (zero to disable)
         --plugin-folder=VALUE        Folder where to find additional plugins
-        --ts=VALUE                   Override transfer spec values (Hash, e.g. use @json: prefix), current={"create_dir"=>true}
+        --ts=VALUE                   Override transfer spec values (Hash)
         --to-folder=VALUE            Destination folder for transferred files
         --sources=VALUE              How list of transferred files is provided (@args,@ts,Array)
-        --src-type=ENUM              Type of file list: list, pair
-        --transfer=ENUM              Type of transfer agent: direct, node, connect, httpgw, trsdk
+        --src-type=ENUM              Type of file list: [list], pair
+        --transfer=ENUM              Type of transfer agent: [direct], node, connect, httpgw, trsdk
         --transfer-info=VALUE        Parameters for transfer agent (Hash)
-        --progress=ENUM              Type of progress bar: none, native, multi
+        --progress=ENUM              Type of progress bar: none, [native], multi
 
 
 COMMAND: shares
-SUBCOMMANDS: admin health repository
+SUBCOMMANDS: admin files health
 OPTIONS:
         --url=VALUE                  URL of application, e.g. https://org.asperafiles.com
-        --username=VALUE             username to log in
-        --password=VALUE             user's password
-        --type=ENUM                  Type of user/group for operations: any, local, ldap, saml
+        --username=VALUE             Username to log in
+        --password=VALUE             User's password
+        --type=ENUM                  Type of user/group for operations: [any], local, ldap, saml
 
 
 COMMAND: node
 SUBCOMMANDS: access_key api_details asperabrowser async basic_token browse central delete download events health info license mkdir mkfile mklink rename search service space ssync stream sync transfer upload watch_folder
 OPTIONS:
         --url=VALUE                  URL of application, e.g. https://org.asperafiles.com
-        --username=VALUE             username to log in
-        --password=VALUE             user's password
-        --validator=VALUE            identifier of validator (optional for central)
+        --username=VALUE             Username to log in
+        --password=VALUE             User's password
+        --validator=VALUE            Identifier of validator (optional for central)
         --asperabrowserurl=VALUE     URL for simple aspera web ui
-        --sync-name=VALUE            sync name
-        --path=VALUE                 file or folder path for gen4 operation "file"
-        --token-type=ENUM            type of token used for transfers: aspera, basic, hybrid
-        --default-ports=ENUM         use standard FASP ports or get from node api (gen4): [no], yes
+        --sync-name=VALUE            Sync name
+        --default-ports=ENUM         Use standard FASP ports or get from node api (gen4): no, [yes]
 
 
 COMMAND: orchestrator
 SUBCOMMANDS: health info plugins processes workflow
 OPTIONS:
         --url=VALUE                  URL of application, e.g. https://org.asperafiles.com
-        --username=VALUE             username to log in
-        --password=VALUE             user's password
-        --params=VALUE               parameters hash table, use @json:{"param":"value"}
-        --result=VALUE               specify result value as: 'work step:parameter'
-        --synchronous=ENUM           work step:parameter expected as result: [no], yes
-        --ret-style=ENUM             how return type is requested in api: header, arg, ext
-        --auth-style=ENUM            authentication type: arg_pass, head_basic, apikey
+        --username=VALUE             Username to log in
+        --password=VALUE             User's password
+        --params=VALUE               Start parameters (Hash)
+        --result=VALUE               Specify result value as: 'work step:parameter'
+        --synchronous=ENUM           Work step:parameter expected as result: [no], yes
+        --ret-style=ENUM             How return type is requested in api: header, [arg], ext
+        --auth-style=ENUM            Authentication type: arg_pass, [head_basic], apikey
 
 
 COMMAND: bss
 SUBCOMMANDS: subscription
 OPTIONS:
         --url=VALUE                  URL of application, e.g. https://org.asperafiles.com
-        --username=VALUE             username to log in
-        --password=VALUE             user's password
+        --username=VALUE             Username to log in
+        --password=VALUE             User's password
 
 
 COMMAND: alee
 SUBCOMMANDS: entitlement
 OPTIONS:
         --url=VALUE                  URL of application, e.g. https://org.asperafiles.com
-        --username=VALUE             username to log in
-        --password=VALUE             user's password
+        --username=VALUE             Username to log in
+        --password=VALUE             User's password
 
 
 COMMAND: ats
@@ -2901,17 +3146,18 @@ COMMAND: faspex5
 SUBCOMMANDS: admin bearer_token gateway health packages postprocessing shared_folders user version
 OPTIONS:
         --url=VALUE                  URL of application, e.g. https://org.asperafiles.com
-        --username=VALUE             username to log in
-        --password=VALUE             user's password
+        --username=VALUE             Username to log in
+        --password=VALUE             User's password
         --client-id=VALUE            OAuth client identifier
         --client-secret=VALUE        OAuth client secret
         --redirect-uri=VALUE         OAuth redirect URI for web authentication
-        --auth=ENUM                  OAuth type of authentication: boot, link, web, jwt
-        --box=VALUE                  Package inbox, either shared inbox name or one of ["inbox", "inbox_history", "inbox_all", "inbox_all_history", "outbox", "outbox_history", "pending", "pending_history", "all"]
+        --auth=ENUM                  OAuth type of authentication: boot, link, web, [jwt]
         --private-key=VALUE          OAuth JWT RSA private key PEM value (prefix file path with @file:)
-        --passphrase=VALUE           RSA private key passphrase
-        --shared-folder=VALUE        Shared folder source for package files
-        --link=VALUE                 public link for specific operation
+        --passphrase=VALUE           OAuth JWT RSA private key passphrase
+        --link=VALUE                 Public link authorization (specific operations)
+        --box=VALUE                  Package inbox, either shared inbox name or one of ["inbox", "inbox_history", "inbox_all", "inbox_all_history", "outbox", "outbox_history", "pending", "pending_history", "all"] or ALL
+        --shared-folder=VALUE        Send package with files from shared folder
+        --group-type=ENUM            Shared inbox or workgroup: [shared_inboxes], workgroups
 
 
 COMMAND: cos
@@ -2930,50 +3176,50 @@ COMMAND: faspex
 SUBCOMMANDS: address_book dropbox health login_methods me package source v4
 OPTIONS:
         --url=VALUE                  URL of application, e.g. https://org.asperafiles.com
-        --username=VALUE             username to log in
-        --password=VALUE             user's password
-        --link=VALUE                 public link for specific operation
-        --delivery-info=VALUE        package delivery information (extended value)
-        --source-name=VALUE          create package from remote source (by name)
+        --username=VALUE             Username to log in
+        --password=VALUE             User's password
+        --link=VALUE                 Public link for specific operation
+        --delivery-info=VALUE        Package delivery information (Hash)
+        --source-name=VALUE          Create package from remote source (by name)
         --storage=VALUE              Faspex local storage definition
-        --recipient=VALUE            use if recipient is a dropbox (with *)
-        --box=ENUM                   package box: inbox, archive, sent
+        --recipient=VALUE            Use if recipient is a dropbox (with *)
+        --box=ENUM                   Package box: [inbox], archive, sent
 
 
 COMMAND: preview
 SUBCOMMANDS: check events scan test trevents
 OPTIONS:
         --url=VALUE                  URL of application, e.g. https://org.asperafiles.com
-        --username=VALUE             username to log in
-        --password=VALUE             user's password
-        --skip-format=ENUM           skip this preview format (multiple possible): png, mp4
-        --folder-reset-cache=ENUM    force detection of generated preview by refresh cache: [no], header, read
-        --skip-types=VALUE           skip types in comma separated list
-        --previews-folder=VALUE      preview folder in storage root
-        --temp-folder=VALUE          path to temp folder
-        --skip-folders=VALUE         list of folder to skip
-        --case=VALUE                 basename of output for for test
-        --scan-path=VALUE            subpath in folder id to start scan in (default=/)
-        --scan-id=VALUE              folder id in storage to start scan in, default is access key main folder id
-        --mimemagic=ENUM             use Mime type detection of gem mimemagic: [no], yes
-        --overwrite=ENUM             when to overwrite result file: always, never, [mtime]
-        --file-access=ENUM           how to read and write files in repository: [local], remote
-        --max-size=VALUE             maximum size (in bytes) of preview file
-        --thumb-vid-scale=VALUE      png: video: size (ffmpeg scale argument)
-        --thumb-vid-fraction=VALUE   png: video: time percent position of snapshot
-        --thumb-img-size=VALUE       png: non-video: height (and width)
-        --thumb-text-font=VALUE      png: plaintext: font to render text with imagemagick convert (identify -list font)
-        --video-conversion=ENUM      mp4: method for preview generation: [reencode], blend, clips
-        --video-png-conv=ENUM        mp4: method for thumbnail generation: [fixed], animated
-        --video-scale=VALUE          mp4: all: video scale (ffmpeg)
-        --video-start-sec=VALUE      mp4: all: start offset (seconds) of video preview
-        --reencode-ffmpeg=VALUE      mp4: reencode: options to ffmpeg
-        --blend-keyframes=VALUE      mp4: blend: # key frames
-        --blend-pauseframes=VALUE    mp4: blend: # pause frames
-        --blend-transframes=VALUE    mp4: blend: # transition blend frames
-        --blend-fps=VALUE            mp4: blend: frame per second
-        --clips-count=VALUE          mp4: clips: number of clips
-        --clips-length=VALUE         mp4: clips: length in seconds of each clips
+        --username=VALUE             Username to log in
+        --password=VALUE             User's password
+        --skip-format=ENUM           Skip this preview format (multiple possible): png, mp4
+        --folder-reset-cache=ENUM    Force detection of generated preview by refresh cache: [no], header, read
+        --skip-types=VALUE           Skip types in comma separated list
+        --previews-folder=VALUE      Preview folder in storage root
+        --temp-folder=VALUE          Path to temp folder
+        --skip-folders=VALUE         List of folder to skip
+        --case=VALUE                 Basename of output for for test
+        --scan-path=VALUE            Subpath in folder id to start scan in (default=/)
+        --scan-id=VALUE              Folder id in storage to start scan in, default is access key main folder id
+        --mimemagic=ENUM             Use Mime type detection of gem mimemagic: [no], yes
+        --overwrite=ENUM             When to overwrite result file: always, never, [mtime]
+        --file-access=ENUM           How to read and write files in repository: [local], remote
+        --max-size=VALUE             Maximum size (in bytes) of preview file
+        --thumb-vid-scale=VALUE      Png: video: size (ffmpeg scale argument)
+        --thumb-vid-fraction=VALUE   Png: video: time percent position of snapshot
+        --thumb-img-size=VALUE       Png: non-video: height (and width)
+        --thumb-text-font=VALUE      Png: plaintext: font to render text with imagemagick convert (identify -list font)
+        --video-conversion=ENUM      Mp4: method for preview generation: [reencode], blend, clips
+        --video-png-conv=ENUM        Mp4: method for thumbnail generation: [fixed], animated
+        --video-scale=VALUE          Mp4: all: video scale (ffmpeg)
+        --video-start-sec=VALUE      Mp4: all: start offset (seconds) of video preview
+        --reencode-ffmpeg=VALUE      Mp4: reencode: options to ffmpeg
+        --blend-keyframes=VALUE      Mp4: blend: # key frames
+        --blend-pauseframes=VALUE    Mp4: blend: # pause frames
+        --blend-transframes=VALUE    Mp4: blend: # transition blend frames
+        --blend-fps=VALUE            Mp4: blend: frame per second
+        --clips-count=VALUE          Mp4: clips: number of clips
+        --clips-length=VALUE         Mp4: clips: length in seconds of each clips
 
 
 COMMAND: sync
@@ -2987,10 +3233,10 @@ COMMAND: aoc
 SUBCOMMANDS: admin automation bearer_token files gateway organization packages reminder servers tier_restrictions user
 OPTIONS:
         --url=VALUE                  URL of application, e.g. https://org.asperafiles.com
-        --username=VALUE             username to log in
-        --password=VALUE             user's password
-        --auth=ENUM                  OAuth type of authentication: web, jwt
-        --operation=ENUM             client operation for transfers: push, pull
+        --username=VALUE             Username to log in
+        --password=VALUE             User's password
+        --auth=ENUM                  OAuth type of authentication: web, [jwt]
+        --operation=ENUM             Client operation for transfers: [push], pull
         --client-id=VALUE            OAuth API client identifier
         --client-secret=VALUE        OAuth API client secret
         --redirect-uri=VALUE         OAuth API client redirect URI
@@ -3002,26 +3248,25 @@ OPTIONS:
         --link=VALUE                 Public link to shared resource
         --new-user-option=VALUE      New user creation option for unknown package recipients
         --from-folder=VALUE          Source folder for Folder-to-Folder transfer
-        --validate-metadata=ENUM     Validate shared inbox metadata: [no], yes
+        --validate-metadata=ENUM     Validate shared inbox metadata: no, [yes]
 
 COMMAND: node
 SUBCOMMANDS: access_key api_details asperabrowser async basic_token browse central delete download events health info license mkdir mkfile mklink rename search service space ssync stream sync transfer upload watch_folder
 OPTIONS:
-        --validator=VALUE            identifier of validator (optional for central)
+        --validator=VALUE            Identifier of validator (optional for central)
         --asperabrowserurl=VALUE     URL for simple aspera web ui
-        --sync-name=VALUE            sync name
-        --path=VALUE                 file or folder path for gen4 operation "file"
-        --token-type=ENUM            type of token used for transfers: aspera, basic, hybrid
-        --default-ports=ENUM         use standard FASP ports or get from node api (gen4): [no], yes
+        --sync-name=VALUE            Sync name
+        --default-ports=ENUM         Use standard FASP ports or get from node api (gen4): no, [yes]
 
 
 COMMAND: server
 SUBCOMMANDS: browse cp delete df download du health info ls md5sum mkdir mv rename rm sync upload
 OPTIONS:
         --url=VALUE                  URL of application, e.g. https://org.asperafiles.com
-        --username=VALUE             username to log in
-        --password=VALUE             user's password
+        --username=VALUE             Username to log in
+        --password=VALUE             User's password
         --ssh-keys=VALUE             SSH key path list (Array or single)
+        --passphrase=VALUE           SSH private key passphrase
         --ssh-options=VALUE          SSH options (Hash)
 
 
@@ -3029,10 +3274,10 @@ COMMAND: console
 SUBCOMMANDS: health transfer
 OPTIONS:
         --url=VALUE                  URL of application, e.g. https://org.asperafiles.com
-        --username=VALUE             username to log in
-        --password=VALUE             user's password
-        --filter-from=DATE           only after date
-        --filter-to=DATE             only before date
+        --username=VALUE             Username to log in
+        --password=VALUE             User's password
+        --filter-from=DATE           Only after date
+        --filter-to=DATE             Only before date
 
 
 ```
@@ -3080,10 +3325,10 @@ For this, specify the option: `--use-generic-client=no`.
 
 This will guide you through the steps to create.
 
-If the wizard does not detect the application but you know the application, you can force it using option `value`:
+If the wizard does not detect the application but you know the application, you can force it using option `query`:
 
 ```bash
-ascli config wizard --value=aoc
+ascli config wizard --query=aoc
 ```
 
 ### <a id="aocmanual"></a>Configuration: using manual setup
@@ -3351,7 +3596,7 @@ To execute an action on a specific resource, select it using one of those method
 
 - *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 `id` : `aoc admin res node show 123`
 - provide option `name` : `aoc admin res node show --name=abc`
 
 #### <a id="res_create"></a>Creating a resource
@@ -3406,7 +3651,7 @@ The secret is provided using the `secret` option.
 For example in a command like:
 
 ```bash
-ascli aoc admin res node --id=123 --secret="my_secret_here" v3 info
+ascli aoc admin res node 123 --secret="my_secret_here" v3 info
 ```
 
 It is also possible to store secrets in the [secret vault](#vault) and then automatically find the related secret using the [config finder](#config_finder).
@@ -3464,6 +3709,36 @@ The option `default_ports` ([yes]/no) allows ascli to retrieve the server ports
 
 Refer to section "Examples" of [ATS](#ats) and substitute command `ats` with `aoc admin ats`.
 
+#### Files with type `link`
+
+Aspera on Cloud Shared folders are implemented through a special type of file: `link`.
+A `link` is the equivalent of a symbolic link on a file system: it points to another folder (not file).
+
+Listing a link (in terminal position of path) will information on the link itself, not the content of the folder it points to.
+To list the target folder content, add a `/` a the end of the path.
+
+Example:
+
+```console
+$ ascli aoc files br the_link
+Current Workspace: Default (default)
++------------+------+----------------+------+----------------------+--------------+
+| name       | type | recursive_size | size | modified_time        | access_level |
++------------+------+----------------+------+----------------------+--------------+
+| the_link   | link |                |      | 2021-04-28T09:17:14Z | edit         |
++------------+------+----------------+------+----------------------+--------------+
+```
+
+```console
+$ ascli aoc files br the_link/
+Current Workspace: Default (default)
++-------------+------+----------------+------+----------------------+--------------+
+| name        | type | recursive_size | size | modified_time        | access_level |
++-------------+------+----------------+------+----------------------+--------------+
+| file_inside | file |                |      | 2021-04-26T09:00:00Z | edit         |
++-------------+------+----------------+------+----------------------+--------------+
+```
+
 #### Example: Bulk creation of users
 
 ```bash
@@ -3507,7 +3782,7 @@ echo $thelist
 ```
 
 ```bash
-ascli aoc admin res user --bulk=yes --id=@json:"$thelist" delete
+ascli aoc admin res user delete @json:"$thelist" --bulk=yes
 ```
 
 ```output
@@ -3548,13 +3823,13 @@ ascli aoc user workspaces list
 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)
 
 ```bash
-ascli aoc admin resource node --name=_node_name_ --secret=_secret_ v4 access_key create --value=@json:'{"storage":{"path":"/folder1"}}'
+ascli aoc admin resource node --name=_node_name_ --secret=_secret_ v4 access_key create @json:'{"storage":{"path":"/folder1"}}'
 ```
 
 #### Example: Display transfer events (ops/transfer)
 
 ```bash
-ascli aoc admin res node --secret=_secret_ v3 transfer list --value=@json:'[["q","*"],["count",5]]'
+ascli aoc admin res node --secret=_secret_ v3 transfer list --query=@json:'[["q","*"],["count",5]]'
 ```
 
 Examples of query (TODO: cleanup):
@@ -3752,7 +4027,7 @@ jfqslfdjlfdjfhdjklqfhdkl
 #### Example: delete all registration keys
 
 ```bash
-ascli aoc admin res client list --fields=id --format=csv|ascli aoc admin res client delete --bulk=yes --id=@lines:@stdin:
+ascli aoc admin res client list --fields=id --format=csv|ascli aoc admin res client delete @lines:@stdin: --bulk=yes
 ```
 
 ```output
@@ -3837,12 +4112,13 @@ The webmail-like application.
 General syntax:
 
 ```bash
-ascli aoc packages send --value=[package extended value] [other parameters such as file list and transfer parameters]
+ascli aoc packages send [package extended value] [other parameters such as file list and transfer parameters]
 ```
 
 Notes:
 
-- 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.
+- Package creation parameter are sent as positional mandatory parameter.
+  Refer to the AoC package creation API, or display an existing package in JSON to list attributes.
 - List allowed shared inbox destinations with: `ascli aoc packages shared_inboxes list`
 - Use fields: `recipients` and/or `bcc_recipients` to provide the list of recipients: user or shared inbox.
   - Provide either ids as expected by API: `"recipients":[{"type":"dropbox","id":"1234"}]`
@@ -3854,19 +4130,19 @@ Notes:
 #### Example: Send a package with one file to two users, using their email
 
 ```bash
-ascli aoc packages send --value=@json:'{"name":"my title","note":"my note","recipients":["laurent.martin.aspera@fr.ibm.com","other@example.com"]}' my_file.dat
+ascli aoc packages send @json:'{"name":"my title","note":"my note","recipients":["laurent.martin.aspera@fr.ibm.com","other@example.com"]}' my_file.dat
 ```
 
 #### Example: Send a package to a shared inbox with metadata
 
 ```bash
-ascli aoc packages send --workspace=eudemo --value=@json:'{"name":"my pack title","recipients":["Shared Inbox With Meta"],"metadata":{"Project Id":"123","Type":"Opt2","CheckThose":["Check1","Check2"],"Optional Date":"2021-01-13T15:02:00.000Z"}}' ~/Documents/Samples/200KB.1
+ascli aoc packages send --workspace=eudemo @json:'{"name":"my pack title","recipients":["Shared Inbox With Meta"],"metadata":{"Project Id":"123","Type":"Opt2","CheckThose":["Check1","Check2"],"Optional Date":"2021-01-13T15:02:00.000Z"}}' ~/Documents/Samples/200KB.1
 ```
 
 It is also possible to use identifiers and API parameters:
 
 ```bash
-ascli aoc packages send --workspace=eudemo --value=@json:'{"name":"my pack title","recipients":[{"type":"dropbox","id":"12345"}],"metadata":[{"input_type":"single-text","name":"Project Id","values":["123"]},{"input_type":"single-dropdown","name":"Type","values":["Opt2"]},{"input_type":"multiple-checkbox","name":"CheckThose","values":["Check1","Check2"]},{"input_type":"date","name":"Optional Date","values":["2021-01-13T15:02:00.000Z"]}]}' ~/Documents/Samples/200KB.1
+ascli aoc packages send --workspace=eudemo @json:'{"name":"my pack title","recipients":[{"type":"dropbox","id":"12345"}],"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
 ```
 
 #### Example: List packages in a given shared inbox
@@ -3925,7 +4201,7 @@ ascli aoc files browse /src_folder
 Let's send a package with the file `10M.dat` from subfolder /src_folder in a package:
 
 ```bash
-ascli aoc files node_info /src_folder --format=json --display=data | ascli aoc packages send --value=@json:'{"name":"test","recipients":["laurent.martin.aspera@fr.ibm.com"]}' 10M.dat --transfer=node --transfer-info=@json:@stdin:
+ascli aoc files node_info /src_folder --format=json --display=data | ascli aoc packages send @json:'{"name":"test","recipients":["laurent.martin.aspera@fr.ibm.com"]}' 10M.dat --transfer=node --transfer-info=@json:@stdin:
 ```
 
 #### <a id="aoccargo"></a>Receive new packages only (Cargo)
@@ -3933,10 +4209,10 @@ ascli aoc files node_info /src_folder --format=json --display=data | ascli aoc p
 It is possible to automatically download new packages, like using Aspera Cargo:
 
 ```bash
-ascli aoc packages recv --id=ALL --once-only=yes --lock-port=12345
+ascli aoc packages recv ALL --once-only=yes --lock-port=12345
 ```
 
-- `--id=ALL` (case sensitive) will download all packages
+- `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 running two downloads in parallel
 
@@ -3965,46 +4241,28 @@ ascli aoc files download <single file path>
 
 #### Shared folders
 
-Shared folder by users are managed through **permissions**.
+Shared folder created by users are managed through **permissions**.
 For creation, parameters are the same as for node api [permissions](https://developer.ibm.com/apis/catalog/aspera--aspera-node-api/api/API--aspera--node-api#post960739960).
-`ascli` expects the same payload for creation, but it will automatically populated required tags if needed.
-Also, the pseudo key `with` is added: it will lookup the name in the contacts and fill the proper type and id.
+`ascli` expects the same payload for creation, but it will automatically populate required tags if needed.
+Also, the pseudo key `with` is available: it will lookup the name in the contacts and fill the proper type and id.
 The pseudo parameter `link_name` allows changing default "shared as" name.
 
 - List permissions on a shared folder as user
 
 ```bash
-ascli aoc files file --path=/shared_folder_test1 perm list
+ascli aoc files perm /shared_folder_test1 list
 ```
 
 - Share a personal folder with other users
 
 ```bash
-ascli aoc files file --path=/shared_folder_test1 perm create @json:'{"with":"laurent"}'
+ascli aoc files perm /shared_folder_test1 create @json:'{"with":"laurent"}'
 ```
 
 - Revoke shared access
 
 ```bash
-ascli aoc files file --path=/shared_folder_test1 perm delete 6161
-```
-
-- List shared folders in node
-
-```bash
-ascli aoc admin res node --id=8669 shared_folders
-```
-
-- List shared folders in workspace
-
-```bash
-ascli aoc admin res workspace --id=10818 shared_folders
-```
-
-- List members of shared folder
-
-```bash
-ascli aoc admin res node --id=8669 v4 perm 82 show
+ascli aoc files perm /shared_folder_test1 delete 6161
 ```
 
 #### Cross Organization transfers
@@ -4039,42 +4297,52 @@ Explanation:
 
 #### Find Files
 
-The command `aoc files find [--value=expression]` will recursively scan storage to find files matching the expression criteria. It works also on node resource using the v4 command. (see examples)
+The command `aoc files find [--query=expression]` will recursively scan storage to find files matching the expression criteria. It works also on node resource using the v4 command. (see examples)
 
 The expression can be of 3 formats:
 
 - empty (default) : all files, equivalent to value: `exec:true`
-- not starting with `exec:` : the expression is a regular expression, using [Ruby Regex](https://ruby-doc.org/core/Regexp.html) syntax. equivalent to value: `exec:f['name'].match(/expression/)`
+- 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$'`
+  For instance, to find files with a special extension, use `--query='\.myext$'`
 
-- starting with `exec:` : the Ruby code after the prefix is executed for each entry found. The entry variable name is `f`. The file is displayed if the result of the expression is true;
+- 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>'`)
+Examples of expressions: (using like this: `--query=exec:'<expression>'`)
 
 - Find files more recent than 100 days
 
-```bash
-f["type"].eql?("file") and (DateTime.now-DateTime.parse(f["modified_time"]))<100
-```
+  ```ruby
+  f["type"].eql?("file") and (DateTime.now-DateTime.parse(f["modified_time"]))<100
+  ```
 
 - Find files older than 1 year on a given node and store in file list
 
-```bash
-ascli aoc admin res node --name='my node name' --secret='my_secret_here' 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
-```
+  ```ruby
+  f["type"].eql?("file") and (DateTime.now-DateTime.parse(f["modified_time"]))<100
+  ```
+
+  ```bash
+  ascli aoc admin res node --name='my node name' --secret='my_secret_here' v4 find / --fields=path --query='exec:<above expression here>' --format=csv > my_file_list.txt
+  ```
+
+- Find files larger than 1MB
+
+  ```ruby
+  f["type"].eql?("file") and f["size"].to_i>1000000
+  ```
 
 - Delete the files, one by one
 
-```bash
-cat my_file_list.txt|while read path;do echo ascli aoc admin res node --name='my node name' --secret='my_secret_here' v4 delete "$path" ;done
-```
+  ```bash
+  cat my_file_list.txt|while read path;do echo ascli aoc admin res node --name='my node name' --secret='my_secret_here' v4 delete "$path" ;done
+  ```
 
 - Delete the files in bulk
 
-```bash
-cat my_file_list.txt | ascli aoc admin res node --name='my node name' --secret='my_secret_here' v3 delete @lines:@stdin:
-```
+  ```bash
+  cat my_file_list.txt | ascli aoc admin res node --name='my node name' --secret='my_secret_here' v3 delete @lines:@stdin:
+  ```
 
 ### AoC sample commands
 
@@ -4113,18 +4381,18 @@ aoc admin res workspace_membership list
 aoc admin resource node --name=my_aoc_ak_name --secret=my_aoc_ak_secret do browse /
 aoc admin resource node --name=my_aoc_ak_name --secret=my_aoc_ak_secret do delete /folder1
 aoc admin resource node --name=my_aoc_ak_name --secret=my_aoc_ak_secret do mkdir /folder1
-aoc admin resource node --name=my_aoc_ak_name --secret=my_aoc_ak_secret do v3 access_key create --value=@json:'{"id":"testsub1","storage":{"path":"/folder1"}}'
+aoc admin resource node --name=my_aoc_ak_name --secret=my_aoc_ak_secret do v3 access_key create @json:'{"id":"testsub1","storage":{"path":"/folder1"}}'
 aoc admin resource node --name=my_aoc_ak_name --secret=my_aoc_ak_secret do v3 events
 aoc admin resource node do name my_aoc_ak_name --secret=my_aoc_ak_secret v3 access_key delete testsub1
 aoc admin resource workspace list
 aoc admin resource workspace_membership list --fields=ALL --query=@json:'{"page":1,"per_page":50,"embed":"member","inherited":false,"workspace_id":11363,"sort":"name"}'
 aoc admin subscription
-aoc automation workflow action my_wf_id create --value=@json:'{"name":"toto"}'
-aoc automation workflow create --value=@json:'{"name":"test_workflow"}'
+aoc automation workflow action my_wf_id create @json:'{"name":"toto"}' \
+aoc automation workflow create @json:'{"name":"test_workflow"}'
 aoc automation workflow delete my_wf_id
 aoc automation workflow list
+aoc automation workflow list --query=@json:'{"show_org_workflows":"true"}' --scope=admin:all
 aoc automation workflow list --select=@json:'{"name":"test_workflow"}' --fields=id --format=csv --display=data
-aoc automation workflow list --value=@json:'{"show_org_workflows":"true"}' --scope=admin:all
 aoc bearer_token --display=data --scope=user:all
 aoc faspex
 aoc files bearer /
@@ -4133,27 +4401,28 @@ aoc files browse /
 aoc files browse / --link=my_aoc_publink_folder
 aoc files delete /testsrc
 aoc files download --transfer=connect /200KB.1
-aoc files file modify --path=my_aoc_test_folder
-aoc files file permission --path=my_aoc_test_folder list
-aoc files file show --path=/200KB.1
-aoc files file show my_file_id
-aoc files find / --value='\.partial$'
+aoc files find / --query='\.partial$'
 aoc files http_node_download --to-folder=. /200KB.1
 aoc files mkdir /testsrc
+aoc files modify my_aoc_test_folder
+aoc files permission my_aoc_test_folder list
 aoc files rename /somefolder testdst
-aoc files short_link create --to-folder=/testdst --value=private
-aoc files short_link create --to-folder=/testdst --value=public
-aoc files short_link list --value=@json:'{"purpose":"shared_folder_auth_link"}'
+aoc files short_link create /testdst private
+aoc files short_link create testdst public
+aoc files short_link list /testdst private
+aoc files show %id:my_file_id
+aoc files show /200KB.1
 aoc files sync ad st --sync-info=@json:'{"name":"syncv2","reset":true,"direction":"pull","local":{"path":"my_local_sync_dir"},"remote":{"path":"/testdst"}}'
 aoc files sync ad st --sync-info=@json:'{"sessions":[{"name":"syncv1","direction":"pull","local_dir":"my_local_sync_dir","remote_dir":"/testdst","reset":true}]}'
 aoc files sync start --sync-info=@json:'{"name":"syncv2","reset":true,"direction":"pull","local":{"path":"my_local_sync_dir"},"remote":{"path":"/testdst"}}'
 aoc files sync start --sync-info=@json:'{"sessions":[{"name":"syncv1","direction":"pull","local_dir":"my_local_sync_dir","remote_dir":"/testdst","reset":true}]}'
+aoc files thumbnail my_aoc_media_file
 aoc files transfer --from-folder=/testsrc --to-folder=/testdst testfile.bin
 aoc files upload --to-folder=/ testfile.bin --link=my_aoc_publink_folder
 aoc files upload --to-folder=/testsrc testfile.bin
 aoc files upload Test.pdf --transfer=node --transfer-info=@json:@stdin:
 aoc files v3 info
-aoc gateway --value=https://localhost:12345/aspera/faspex & jobs -p
+aoc gateway https://localhost:12345/aspera/faspex
 aoc org --link=my_aoc_publink_recv_from_aocuser
 aoc organization
 aoc packages browse "my_package_id" /contents
@@ -4162,13 +4431,13 @@ aoc packages list --query=@json:'{"dropbox_name":"my_aoc_shbx_name","sort":"-rec
 aoc packages recv "my_package_id" --to-folder=.
 aoc packages recv ALL --to-folder=. --once-only=yes --lock-port=12345
 aoc packages recv ALL --to-folder=. --once-only=yes --lock-port=12345 --query=@json:'{"dropbox_name":"my_aoc_shbx_name","archived":false,"received":true,"has_content":true,"exclude_dropbox_packages":false,"include_draft":false}' --ts=@json:'{"resume_policy":"sparse_csum","target_rate_kbps":50000}'
-aoc packages send --value=@json:'{"name":"Important files delivery","recipients":["my_email_external_user"]}' --new-user-option=@json:'{"package_contact":true}' testfile.bin
-aoc packages send --value=@json:'{"name":"Important files delivery","recipients":["my_email_internal_user"],"note":"my note"}' testfile.bin
-aoc packages send --value=@json:'{"name":"Important files delivery"}' testfile.bin --link=my_aoc_publink_send_aoc_user --password=my_aoc_publink_send_use_pass
-aoc packages send --value=@json:'{"name":"Important files delivery"}' testfile.bin --link=my_aoc_publink_send_shd_inbox
-aoc packages send --workspace="my_aoc_shbx_ws" --value=@json:'{"name":"Important files delivery","recipients":["my_aoc_shbx_name"],"metadata":[{"input_type":"single-text","name":"Project Id","values":["123"]},{"input_type":"single-dropdown","name":"Type","values":["Opt2"]},{"input_type":"multiple-checkbox","name":"CheckThose","values":["Check1","Check2"]},{"input_type":"date","name":"Optional Date","values":["2021-01-13T15:02:00.000Z"]}]}' testfile.bin
-aoc packages send --workspace="my_aoc_shbx_ws" --value=@json:'{"name":"Important files delivery","recipients":["my_aoc_shbx_name"],"metadata":{"Project Id":"456","Type":"Opt2","CheckThose":["Check1","Check2"],"Optional Date":"2021-01-13T15:02:00.000Z"}}' testfile.bin
-aoc packages send --workspace="my_aoc_shbx_ws" --value=@json:'{"name":"Important files delivery","recipients":["my_aoc_shbx_name"]}' testfile.bin
+aoc packages send --workspace="my_aoc_shbx_ws" @json:'{"name":"Important files delivery","recipients":["my_aoc_shbx_name"],"metadata":[{"input_type":"single-text","name":"Project Id","values":["123"]},{"input_type":"single-dropdown","name":"Type","values":["Opt2"]},{"input_type":"multiple-checkbox","name":"CheckThose","values":["Check1","Check2"]},{"input_type":"date","name":"Optional Date","values":["2021-01-13T15:02:00.000Z"]}]}' testfile.bin
+aoc packages send --workspace="my_aoc_shbx_ws" @json:'{"name":"Important files delivery","recipients":["my_aoc_shbx_name"],"metadata":{"Project Id":"456","Type":"Opt2","CheckThose":["Check1","Check2"],"Optional Date":"2021-01-13T15:02:00.000Z"}}' testfile.bin
+aoc packages send --workspace="my_aoc_shbx_ws" @json:'{"name":"Important files delivery","recipients":["my_aoc_shbx_name"]}' testfile.bin
+aoc packages send @json:'{"name":"Important files delivery","recipients":["my_email_external_user"]}' --new-user-option=@json:'{"package_contact":true}' testfile.bin
+aoc packages send @json:'{"name":"Important files delivery","recipients":["my_email_internal_user"],"note":"my note"}' testfile.bin
+aoc packages send @json:'{"name":"Important files delivery"}' testfile.bin --link=my_aoc_publink_send_aoc_user --password=my_aoc_publink_send_use_pass
+aoc packages send @json:'{"name":"Important files delivery"}' testfile.bin --link=my_aoc_publink_send_shd_inbox
 aoc packages shared_inboxes list
 aoc remind --username=my_aoc_user_email
 aoc servers
@@ -4295,7 +4564,7 @@ ascli ats access_key create --cloud=azure --region=eastus --params=@json:'{"id":
 delete all my access keys:
 
 ```bash
-for k in $(ascli ats access_key list --field=id --format=csv);do ascli ats access_key id $k delete;done
+ascli ats access_key list --field=id --format=csv | ascli ats access_key delete @lines:@stdin: --bulk=yes
 ```
 
 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.
@@ -4384,7 +4653,7 @@ ascli server --url=ssh://_server_address_:33001 ... --ts=@json:'{"token":"Basic
 
 > **Note:** If you need to use the Aspera public keys, then specify an empty token: `--ts=@json:'{"token":""}'` : Aspera public SSH keys will be used, but the protocol will ignore the empty token.
 
-The value of the `ssh_keys` option can be a single value or an array.
+The value of the `ssh_keys` option can be a single value or an `Array`.
 Each value is a **path** to a private key and is expanded (`~` is replaced with the user's home folder).
 
 Examples:
@@ -4433,6 +4702,9 @@ ascli server --ssh-options=@json:'{"use_agent": false}' ...
 
 > **Note:** This can also be set using a preset.
 
+If one of the SSH private keys is passphrase-protected, then option `passphrase` can be used.
+It is equivalent to setting both options `ssh_options.passphrase` and `ts.ssh_private_key_passphrase`.
+
 ### Other session channels for `server`
 
 URL schemes `local` and `https` are also supported (mainly for testing purpose).
@@ -4455,6 +4727,12 @@ ascli server download /aspera-test-dir-large/200MB
 
 `initdemo` creates a [option preset](#lprt) `demoserver` and set it as default for plugin `server`.
 
+If an SSH private key is used for authentication with a passphrase, the passphrase needs to be provided to both options: `ssh_options`, for browsing, and `ts` for transfers:
+
+```bash
+ascli server --url=ssh://_server_address_here_:33001 --username=_user_here_ --ssh_keys=_private_key_path_here_ --passphrase=_passphrase_here_
+```
+
 ## <a id="node"></a>Plugin: `node`: IBM Aspera High Speed Transfer Server Node
 
 This plugin gives access to capabilities provided by HSTS node API.
@@ -4469,24 +4747,6 @@ It is possible to:
 - transfer (upload / download)
 - ...
 
-For transfers, it is possible to control how transfer is authorized using option: `token_type`:
-
-- `aspera` : api `<upload|download>_setup` is called to create the transfer spec including the Aspera token, used as is.
-- `hybrid` : same as `aspera`, but token is replaced with basic token like `basic`
-- `basic` : transfer spec is created like this:
-
-```json
-{
-  "remote_host": "<address of node url>",
-  "remote_user": "xfer",
-  "ssh_port": 33001,
-  "token": "Basic <base 64 encoded user/pass>",
-  "direction": "[send|receive]"
-}
-```
-
-> **Note:** the port is assumed to be the default Aspera SSH port `33001` and transfer user is assumed to be `xfer`.
-
 ### Central
 
 The central subcommand uses the "reliable query" API (session and file).
@@ -4571,43 +4831,48 @@ When node api is used with an **Access key**, extra information can be retrieved
 > **Note:** Display of preview on terminal requires installation of extra gem: `rmagick`
 
 ```bash
-gem install rmagick
+dnf install -y ImageMagick-devel
+gem install rmagick rainbow
 ```
 
 For example it is possible to display the preview of a file, if it exists, using:
 
 ```bash
-ascli aoc files file thumbnail --path=/preview_samples/Aspera.mpg
+ascli aoc files thumbnail /preview_samples/Aspera.mpg
 ```
 
 Using direct node access and an access key , one can do:
 
 ```bash
-ascli node access_key do self file thumbnail --path=/preview_samples/Aspera.mpg
+ascli node access_key do self thumbnail /preview_samples/Aspera.mpg
 ```
 
+> **Note:** To specify the file by its file id, use the selector syntax: `%id:_file_id_here_`
+>
+> **Note:** To force textual display of the preview on iTerm, prefix command with: `env -u TERM_PROGRAM -u LC_TERMINAL`
+
 ### Create access key
 
 ```bash
-ascli node access_key create --value=@json:'{"id":"myaccesskey","secret":"my_secret_here","storage":{"type":"local","path":"/data/mydir"}}'
+ascli node access_key create @json:'{"id":"myaccesskey","secret":"my_secret_here","storage":{"type":"local","path":"/data/mydir"}}'
 ```
 
 ### Node sample commands
 
 ```bash
-node access_key create --value=@json:'{"id":"testingAK1","storage":{"type":"local","path":"/"}}'
+node access_key create @json:'{"id":"testingAK1","storage":{"type":"local","path":"/"}}'
 node access_key delete testingAK1
 node access_key do my_aoc_ak_name browse /
 node access_key do my_aoc_ak_name delete /folder2
 node access_key do my_aoc_ak_name delete testfile1
 node access_key do my_aoc_ak_name download testfile1 --to-folder=.
-node access_key do my_aoc_ak_name file show --path=/testfile1
-node access_key do my_aoc_ak_name file show 1
-node access_key do my_aoc_ak_name file thumbnail --path=/testfile1
 node access_key do my_aoc_ak_name find /
 node access_key do my_aoc_ak_name mkdir /folder1
 node access_key do my_aoc_ak_name node_info /
 node access_key do my_aoc_ak_name rename /folder1 folder2
+node access_key do my_aoc_ak_name show %id:1
+node access_key do my_aoc_ak_name show /testfile1
+node access_key do my_aoc_ak_name thumbnail /testfile1
 node access_key do my_aoc_ak_name upload 'faux:///testfile1?1k' --default_ports=no
 node access_key list
 node api_details
@@ -4624,7 +4889,6 @@ node delete @list:,folder_1/todelete,folder_1/tdlink,folder_1/delfile
 node delete folder_1/10MB.2
 node delete testfile.bin
 node download testfile.bin --to-folder=.
-node download testfile.bin --to-folder=. --token-type=hybrid
 node health
 node info --fpac='function FindProxyForURL(url,host){return "DIRECT"}'
 node license
@@ -4632,14 +4896,14 @@ node mkdir folder_1/todelete
 node mkfile folder_1/delfile1 "hello world"
 node mklink folder_1/todelete folder_1/tdlink
 node rename folder_1 delfile1 delfile
-node search / --value=@json:'{"sort":"mtime"}'
+node search / --query=@json:'{"sort":"mtime"}'
 node service create @json:'{"id":"service1","type":"WATCHD","run_as":{"user":"user1"}}'
 node service delete service1
 node service list
 node space /
 node ssync bandwidth my_syncid
 node ssync counters my_syncid
-node ssync create --value=@json:'{"configuration":{"name":"sync1","local":{"path":"my_local_path"},"remote":{"host":"my_host","port":my_port,"user":"my_username","pass":"my_password","path":"my_remote_path"}}}'
+node ssync create @json:'{"configuration":{"name":"sync1","local":{"path":"my_local_path"},"remote":{"host":"my_host","port":my_port,"user":"my_username","pass":"my_password","path":"my_remote_path"}}}'
 node ssync delete my_syncid
 node ssync files my_syncid
 node ssync list
@@ -4652,11 +4916,10 @@ node sync ad st --sync-info=@json:'{"name":"syncv2","reset":true,"direction":"pu
 node sync ad st --sync-info=@json:'{"sessions":[{"name":"syncv1","direction":"pull","local_dir":"my_local_sync_dir","remote_dir":"/aspera-test-dir-tiny","reset":true}]}'
 node sync start --sync-info=@json:'{"name":"syncv2","reset":true,"direction":"pull","local":{"path":"my_local_sync_dir"},"remote":{"path":"/aspera-test-dir-tiny"}}'
 node sync start --sync-info=@json:'{"sessions":[{"name":"syncv1","direction":"pull","local_dir":"my_local_sync_dir","remote_dir":"/aspera-test-dir-tiny","reset":true}]}'
-node transfer list --value=@json:'{"active_only":true}'
+node transfer list --query=@json:'{"active_only":true}'
 node upload --to-folder=folder_1 --sources=@ts --ts=@json:'{"paths":[{"source":"/aspera-test-dir-small/10MB.2"}],"precalculate_job_size":true}' --transfer=node --transfer-info=@json:'{"url":"my_node_url","username":"my_node_user","password":"my_node_pass_here"}'
-node upload --username=my_aoc_ak_name --password=my_aoc_ak_secret testfile.bin --token-type=basic
+node upload --username=my_aoc_ak_name --password=my_aoc_ak_secret testfile.bin
 node upload testfile.bin --to-folder=folder_1 --ts=@json:'{"target_rate_cap_kbps":10000}'
-node upload testfile.bin --to-folder=folder_1 --ts=@json:'{"target_rate_cap_kbps":10000}' --token-type=hybrid
 ```
 
 ## <a id="faspex5"></a>Plugin: `faspex5`: IBM Aspera Faspex v5
@@ -4665,22 +4928,37 @@ IBM Aspera's newer self-managed application.
 
 3 authentication methods are supported:
 
-- jwt
-- web
-- boot
+- jwt : general purpose, private-key based authentication
+- link : public link authentication
+- web : requires authentication with web browser
+- boot : use authentication token copied from browser (experimental)
 
 ### Faspex 5 JWT authentication
 
-This is the **recommended** method to use.
+This is the general purpose and **recommended** method to use.
 
-For `jwt`, create an API client in Faspex with JWT support:
+Activation is in two steps:
 
-- Select a private key file: if you don't have any refer to section [Private Key](#private_key)
-- Navigate to the web UI: Admin &rarr; Configurations &rarr; API Clients &rarr; Create
-- Activate JWT
-- Paste **public** key in the appropriate section
-- Click on Create Button
-- Take note of Client Id (and Client Secret, but not used in current version)
+- The admninistrator must create an API client in Faspex with JWT support
+
+  This operation is generally done only once:
+
+  - As Admin, Navigate to the web UI: Admin &rarr; Configurations &rarr; API Clients &rarr; Create
+  - Give a name, like `ascli`
+  - Activate JWT
+  - There is an option to set a general public key allowing the owner of the private key to impersonate any user. Unless you want to do this, leave this field empty.
+  - Click on `Create` Button
+  - Take note of Client Id (and Client Secret, but not used in current version)
+
+- The user uses a private key and sets the public key in his faspex 5 profile
+
+  This operation is done by each user using the CLI.
+
+  - As user, click on the user logo, left to the app switcher on top right.
+  - Select `Account Settings`
+  - on the bottom in the text field: `Public key in PEM format` paste the **public** key corresponding to the private key used by the user.
+
+  **Note:** If you don't have any refer to section [Private Key](#private_key)
 
 Then use these options:
 
@@ -4692,19 +4970,31 @@ Then use these options:
 --private-key=@file:.../path/to/key.pem
 ```
 
-> **Note:** The `private_key` option must contain the PEM value of the private key which can be read from a file using the modifier: `@file:`, e.g. `@file:/path/to/key.pem`.
+> **Note:** The `private_key` option must contain the PEM **value** (not file path) of the private key which can be read from a file using the modifier: `@file:`, e.g. `@file:/path/to/key.pem`.
+
+As usual, typically a user will create preset to avoid having to type these options each time.
+
+Example:
+
+```bash
+ascli conf preset update myf5 --auth=jwt --client-id=_client_id_here_ --client-secret=my_secret_here --username=_username_here_ --private-key=@file:.../path/to/key.pem
+
+ascli conf preset set default faspx5 myf5
+
+ascli faspex5 user profile show
+```
 
 ### Faspex 5 web authentication
 
-For `web` method, create an API client in Faspex without JWT:
+The admninistrator must create an API client in Faspex for an external web app support:
 
-- Navigate to the web UI: Admin &rarr; Configurations &rarr; API Clients &rarr; Create
+- As Admin, Navigate to the web UI: Admin &rarr; Configurations &rarr; API Clients &rarr; Create
 - Do not Activate JWT
 - Set **Redirect URI** to `https://127.0.0.1:8888`
-- Click on Create Button
+- Click on `Create` Button
 - Take note of Client Id (and Client Secret, but not used in current version)
 
-Then use options:
+The user will use the following options:
 
 ```text
 --auth=web
@@ -4717,7 +5007,7 @@ Then use options:
 
 For `boot` method: (will be removed in future)
 
-- Open a Web Browser
+- As user: Open a Web Browser
 - Start developer mode
 - Login to Faspex 5
 - Find the first API call with `Authorization` header, and copy the value of the token (series of base64 values with dots)
@@ -4725,26 +5015,14 @@ For `boot` method: (will be removed in future)
 Use this token as password and use `--auth=boot`.
 
 ```bash
-ascli conf id f5boot update --url=https://localhost/aspera/faspex --auth=boot --password=_token_here_
+ascli conf preset update f5boot --url=https://localhost/aspera/faspex --auth=boot --password=_token_here_
 ```
 
-### Faspex 5 packages
-
-The `value` option provided to command `faspex5 package send` is the same as for the Faspex 5 API: `POST /packages`.
-
-In addition, `ascli` adds some convenience: the field `recipients` is normally an Array of Hash, each with field `name` and optionally `recipient_type`, but it is also possible to provide an Array of String, with simply a recipient name.
-Then `ascli` will lookup existing contacts, and if a single match is found will use it, and set the `name` and `recipient_type` accordingly.
-
-> **Note:** The lookup is case insensitive and on partial matches.
-
-On reception, option `box` (default to `inbox`) can be set to the same values as API accepts, or to the name of a shared inbox.
-If the value `ALL` is provided to option `box`, then all packages are selected.
-
 ### Faspex 5 sample commands
 
 Most commands are directly REST API calls.
-Parameters to commands are carried through option `value`, as extended value.
-Usually using JSON format with prefix `@json:`.
+Parameters to commands are carried through option `query`, as extended value, for `list`, or through positional parameter for creation.
+One can conveniently use the JSON format with prefix `@json:`.
 
 > **Note:** The API is listed in [Faspex 5 API Reference](https://developer.ibm.com/apis/catalog?search="faspex+5") under **IBM Aspera Faspex API**.
 
@@ -4757,80 +5035,182 @@ faspex5 admin res node list
 faspex5 admin res oauth_clients list
 faspex5 admin res registrations list
 faspex5 admin res saml_configs list
+faspex5 admin res shared_inboxes invite %name:'ascli shinbox' johnny@example.com
 faspex5 admin res shared_inboxes list
+faspex5 admin res shared_inboxes members %name:'ascli shinbox' create %name:john@example.com
+faspex5 admin res shared_inboxes members %name:'ascli shinbox' delete %name:john@example.com
+faspex5 admin res shared_inboxes members %name:'ascli shinbox' delete %name:johnny@example.com
+faspex5 admin res shared_inboxes members %name:'ascli shinbox' list
 faspex5 admin res workgroups list
 faspex5 admin smtp show
 faspex5 admin smtp test my_email_external
 faspex5 bearer_token
-faspex5 gateway --value=https://localhost:12345/aspera/faspex &\
+faspex5 gateway https://localhost:12345/aspera/faspex
 faspex5 health
-faspex5 packages list --value=@json:'{"mailbox":"inbox","state":["released"]}'
+faspex5 packages list --box=my_faspex5_shinbox
+faspex5 packages list --box=my_faspex5_workgroup --group-type=workgroups
+faspex5 packages list --query=@json:'{"mailbox":"inbox","state":["released"]}'
 faspex5 packages receive "my_package_id" --to-folder=.  --ts=@json:'{"content_protection_password":"abc123_yo"}'
+faspex5 packages receive --box=my_faspex5_shinbox "my_package_id" --to-folder=.
+faspex5 packages receive --box=my_faspex5_workgroup --group-type=workgroups "my_package_id" --to-folder=.
 faspex5 packages receive ALL --once-only=yes --to-folder=.
 faspex5 packages receive INIT --once-only=yes
-faspex5 packages send --value=@json:'{"title":"test title","recipients":["my_shinbox"],"metadata":{"Options":"Opt1","TextInput":"example text"}}' testfile.bin
-faspex5 packages send --value=@json:'{"title":"test title","recipients":[{"name":"my_f5_user"}]}' testfile.bin --ts=@json:'{"content_protection_password":"my_passphrase_here"}'
+faspex5 packages send @json:'{"title":"test title","recipients":["my_shinbox"],"metadata":{"Options":"Opt1","TextInput":"example text"}}' testfile.bin
+faspex5 packages send @json:'{"title":"test title","recipients":["my_workgroup"]}' testfile.bin
+faspex5 packages send @json:'{"title":"test title","recipients":[{"name":"my_f5_user"}]}' testfile.bin --ts=@json:'{"content_protection_password":"my_passphrase_here"}'
 faspex5 packages show "my_package_id"
-faspex5 postprocessing --value=@json:'{"url":"https://localhost:8443/domain","processing":{"script_folder":"tests"},"certificate":{"key":"../local/k","cert":"../local/c","chain":"../local/ch"}}' &\
+faspex5 packages show --box=my_faspex5_shinbox "my_package_id"
+faspex5 packages show --box=my_faspex5_workgroup --group-type=workgroups "my_package_id"
+faspex5 postprocessing @json:'{"url":"https://localhost:8443/domain","processing":{"script_folder":"tests"},"certificate":{"key":"../local/k","cert":"../local/c","chain":"../local/ch"}}'
 faspex5 user profile modify @json:'{"preference":{"connect_disabled":false}}'
 faspex5 user profile show
 ```
 
-Other examples:
+### Faspex 5: inbox selection
+
+By default, package operations (send, receive, list) are done on the user's inbox.
+
+To select another inbox, use option `box` with one of the following values:
+
+- inbox
+- inbox_history
+- inbox_all
+- inbox_all_history
+- outbox
+- outbox_history
+- pending
+- pending_history
+- all
+- ALL (only admin)
+- name of a shared inbox or workgroup
+
+> **Note:** specify if the box is a shared inbox or a workgroup using option `group_type` with either `shared_inboxes` or `workgroups`
+
+### Faspex 5: Send a package
+
+The `Hash` creation parameter provided to command `faspex5 packages send` corresponds to the Faspex 5 API: `POST /packages`.
+
+Required fields are `title` and `recipients`.
+Example using `@json:` format:
+
+```json
+{"title":"some title","recipients":[{"recipient_type":"user","name":"user@example.com"}]}
+```
+
+`recipient_type` is one of (Refer to API):
 
-- list packages
+- user
+- workgroup
+- external_user
+- distribution_list
+- shared_inbox
 
-  The following parameters in option `value` are supported:
+`ascli` adds some convenience: The API expects the field `recipients` to be an `Array` of `Hash`, each with field `name` and optionally `recipient_type`.
+It is also possible to provide an `Array` of `String`, with simply a recipient name.
+Then `ascli` will lookup existing contacts among all possible types, use it if a single match is found, and set the `name` and `recipient_type` accordingly.
+Else an exception is sent.
 
-  - `q` : a filter on name (case insensitive, matches if value is contained in name)
-  - `max` : maximum number of items to retrieve (stop pages when the maximum is passed)
-  - `pmax` : maximum number of pages to request (stop pages when the maximum is passed)
-  - `offset` : native api parameter, in general do not use (added by `ascli`)
-  - `limit` : native api parameter, number of items par api call, in general do not use (added by `ascli`)
+> **Note:** The lookup is case insensitive and on partial matches.
+
+```json
+{"title":"some title","recipients":["user@example.com"]}
+```
+
+If the lookup needs to be only on certain types, you can specify the field: `recipient_types` with either a single value or an Array of values (from the list above). e.g. :
+
+```json
+{"title":"test title","recipient_types":"user","recipients":["user1@example.com","user2@example.com"]}
+```
 
-- Send a package with metadata
+### Faspex 5:  Send a package with metadata
 
 The interface is the one of the API (Refer to API documentation, or look at request in browser):
 
 ```bash
-ascli faspex5 package send --value=@json:'{"title":"test title","recipients":["ascli shared inbox"],"metadata":{"Confidential":"Yes","Drop menu":"Option 1"}}' 'faux:///test1?k1'
+ascli faspex5 packages send @json:'{"title":"test title","recipients":["my shared inbox"],"metadata":{"Confidential":"Yes","Drop menu":"Option 1"}}' 'faux:///test1?k1'
 ```
 
 Basically, add the field `metadata`, with one key per metadata and the value is directly the metadata value.
 
-- List all shared inboxes
+### Faspex 5: Receive a package
+
+The (numeric) identifier of the package t receive is given as argument to command `faspex5 packages receive`.
+
+> **Note:** option `box` applies.
+
+### Faspex 5: List packages
+
+The following parameters in option `query` are supported:
+
+- `q` : a filter on name (case insensitive, matches if value is contained in name)
+- `max` : maximum number of items to retrieve (stop pages when the maximum is passed)
+- `pmax` : maximum number of pages to request (stop pages when the maximum is passed)
+- `offset` : native api parameter, in general do not use (added by `ascli`)
+- `limit` : native api parameter, number of items par api call, in general do not use (added by `ascli`)
+
+Admin only: If the value `ALL` is provided to option `box`, then all packages are selected.
+
+### Faspex 5: List all shared inboxes
+
+```bash
+ascli faspex5 admin res shared list --query=@json:'{"all":true}' --fields=id,name
+```
+
+Shared inbox members can also be listed, added, removed, and external users can be invited to a shared inbox.
+
+```bash
+ascli faspex5 admin res shared_inboxes invite '%name:ascli shinbox' john@example.com
+```
+
+It is equivalent to:
 
 ```bash
-ascli faspex5 admin res shared list --value=@json:'{"all":true}' --fields=id,name
+ascli faspex5 admin res shared_inboxes invite '%name:ascli shinbox' @json:'{"email_address":"john@example.com"}'
+```
+
+Other payload parameters are possible in Hash format:
+
+```json
+{"description":"blah","prevent_http_upload":true,"custom_link_expiration_policy":false,"invitation_expires_after_upload":false,"set_invitation_link_expiration":false,"invitation_expiration_days":3
 ```
 
-- Create Metadata profile
+### Faspex 5: Create Metadata profile
 
 ```bash
-ascli faspex5 admin res metadata_profiles create --value=@json:'{"name":"the profile","default":false,"title":{"max_length":200,"illegal_chars":[]},"note":{"max_length":400,"illegal_chars":[],"enabled":false},"fields":[{"ordering":0,"name":"field1","type":"text_area","require":true,"illegal_chars":[],"max_length":100},{"ordering":1,"name":"fff2","type":"option_list","require":false,"choices":["opt1","opt2"]}]}'
+ascli faspex5 admin res metadata_profiles create @json:'{"name":"the profile","default":false,"title":{"max_length":200,"illegal_chars":[]},"note":{"max_length":400,"illegal_chars":[],"enabled":false},"fields":[{"ordering":0,"name":"field1","type":"text_area","require":true,"illegal_chars":[],"max_length":100},{"ordering":1,"name":"fff2","type":"option_list","require":false,"choices":["opt1","opt2"]}]}'
 ```
 
-- Create a Shared inbox with specific metadata profile
+### Faspex 5: Create a Shared inbox with specific metadata profile
 
 ```bash
-ascli faspex5 admin res shared create --value=@json:'{"name":"the shared inbox","metadata_profile_id":1}'
+ascli faspex5 admin res shared create @json:'{"name":"the shared inbox","metadata_profile_id":1}'
 ```
 
-- List content in Shared folder and send package from remote source
+### Faspex 5: List content in Shared folder and send package from remote source
 
 ```bash
 ascli faspex5 shared_folders list
 ```
 
+```markdown
++----+----------+---------+-----+
+| id | name     | node_id | ... |
++----+----------+---------+-----+
+| 3  | partages | 2       | ... |
++----+----------+---------+-----+
+```
+
 ```bash
-ascli faspex5 shared_folders br 3 /folder
+ascli faspex5 shared_folders br %name:partages /folder
 ```
 
 ```bash
-ascli faspex5 package send --value=@json:'{"title":"hello","recipients":[{"name":"_recipient_here_"}]}' --shared-folder=3 /folder/file
+ascli faspex5 packages send @json:'{"title":"hello","recipients":[{"name":"_recipient_here_"}]}' --shared-folder=%name:partages /folder/file
 ```
 
-- receive all packages (cargo)
+> **Note:** The shared folder can be identified by its numerical `id` or by name using percent selector: `%<field>:<value>`. e.g. `--shared-folder=3`
+
+### Faspex 5: receive all packages (cargo)
 
 To receive all packages, only once, through persistency of already received packages:
 
@@ -4844,7 +5224,7 @@ To initialize, and skip all current package so that next time `ALL` is used, onl
 ascli faspex5 packages receive INIT --once-only=yes
 ```
 
-### Faspex 4-style postprocessing script with Faspex 5
+### Faspex 5: Faspex 4-style postprocessing
 
 `ascli` provides command `postprocessing` in plugin `faspex5` to emulate Faspex 4 postprocessing.
 It implements Faspex 5 web hooks, and calls a local script with the same environment as Faspex 4.
@@ -4852,7 +5232,7 @@ It implements Faspex 5 web hooks, and calls a local script with the same environ
 It is invoked like this:
 
 ```bash
-ascli faspex5 postprocessing --value=@json:'{"url":"http://localhost:8080/processing"}'
+ascli faspex5 postprocessing @json:'{"url":"http://localhost:8080/processing"}'
 ```
 
 The following parameters are supported:
@@ -4947,7 +5327,7 @@ The command is `package recv`, possible methods are:
 - provide a `faspe:` URI with option `link`
 
 ```bash
-ascli faspex package recv --id=12345
+ascli faspex package recv 12345
 ascli faspex package recv --link=faspe://...
 ```
 
@@ -4996,9 +5376,9 @@ In this example the notification template is directly provided on command line.
 Example:
 
 ```bash
-ascli faspex v4 dropbox create --value=@json:'{"dropbox":{"e_wg_name":"test1","e_wg_desc":"test1"}}'
+ascli faspex v4 dropbox create @json:'{"dropbox":{"e_wg_name":"test1","e_wg_desc":"test1"}}'
 ascli faspex v4 dropbox list
-ascli faspex v4 dropbox delete --id=36
+ascli faspex v4 dropbox delete 36
 ```
 
 ### Remote sources
@@ -5036,7 +5416,7 @@ It is possible to tell `ascli` to download newly received packages, much like th
 cargo client, or drive. Refer to the [same section](#aoccargo) in the Aspera on Cloud plugin:
 
 ```bash
-ascli faspex packages recv --id=ALL --once-only=yes --lock-port=12345
+ascli faspex packages recv ALL --once-only=yes --lock-port=12345
 ```
 
 ### Faspex 4 sample commands
@@ -5086,20 +5466,20 @@ shares admin group list
 shares admin node list
 shares admin share list --fields=-status,status_message
 shares admin share user_permissions 1 list
-shares admin user add --type=ldap --value=the_name
-shares admin user app_authorizations 1 modify --value=@json:'{"app_login":true}'
+shares admin user add --type=ldap the_name
+shares admin user app_authorizations 1 modify @json:'{"app_login":true}'
 shares admin user app_authorizations 1 show
-shares admin user import --type=saml --value=@json:'{"id":"the_id","name_id":"the_name"}'
+shares admin user import --type=saml @json:'{"id":"the_id","name_id":"the_name"}'
 shares admin user list
 shares admin user share_permissions 1 list
 shares admin user share_permissions 1 show 1
+shares files browse /
+shares files delete my_shares_upload/testfile.bin
+shares files download --to-folder=. my_shares_upload/testfile.bin
+shares files download --to-folder=. my_shares_upload/testfile.bin --transfer=httpgw --transfer-info=@json:'{"url":"https://my_http_gw_fqdn/aspera/http-gwy"}'
+shares files upload --to-folder=my_shares_upload testfile.bin
+shares files upload --to-folder=my_shares_upload testfile.bin --transfer=httpgw --transfer-info=@json:'{"url":"https://my_http_gw_fqdn/aspera/http-gwy"}'
 shares health
-shares repository browse /
-shares repository delete my_shares_upload/testfile.bin
-shares repository download --to-folder=. my_shares_upload/testfile.bin
-shares repository download --to-folder=. my_shares_upload/testfile.bin --transfer=httpgw --transfer-info=@json:'{"url":"https://my_http_gw_fqdn/aspera/http-gwy"}'
-shares repository upload --to-folder=my_shares_upload testfile.bin
-shares repository upload --to-folder=my_shares_upload testfile.bin --transfer=httpgw --transfer-info=@json:'{"url":"https://my_http_gw_fqdn/aspera/http-gwy"}'
 ```
 
 ## <a id="console"></a>Plugin: `console`: IBM Aspera Console
@@ -5154,8 +5534,8 @@ If you have those parameters already, then following options shall be provided:
 For example, let us create a default configuration:
 
 ```bash
-ascli conf id mycos update --bucket=mybucket --endpoint=https://s3.us-east.cloud-object-storage.appdomain.cloud --apikey=abcdefgh --crn=crn:v1:bluemix:public:iam-identity::a/xxxxxxx
-ascli conf id default set cos mycos
+ascli conf preset update mycos --bucket=mybucket --endpoint=https://s3.us-east.cloud-object-storage.appdomain.cloud --apikey=abcdefgh --crn=crn:v1:bluemix:public:iam-identity::a/xxxxxxx
+ascli conf preset set default cos mycos
 ```
 
 Then, jump to the transfer example.
@@ -5218,8 +5598,8 @@ The required options for this method are:
 For example, let us create a default configuration:
 
 ```bash
-ascli conf id mycos update --bucket=laurent --service-credentials=@val:@json:@file:~/service_creds.json --region=us-south
-ascli conf id default set cos mycos
+ascli conf preset update mycos --bucket=laurent --service-credentials=@val:@json:@file:~/service_creds.json --region=us-south
+ascli conf preset set default cos mycos
 ```
 
 ### Operations, transfers
@@ -5347,7 +5727,7 @@ ascli preview check
 #### Image: ImageMagick and optipng
 
 ```bash
-yum install -y ImageMagick optipng
+dnf install -y ImageMagick optipng
 ```
 
 You may also install `ghostscript` which adds fonts to ImageMagick.
@@ -5481,12 +5861,12 @@ ascli preview scan --skip-folders=@json:'["/not_here"]'
 
 The option `folder_reset_cache` forces the node service to refresh folder contents using various methods.
 
-When scanning the option `value` has the same behavior as for the `node find` command.
+When scanning the option `query` has the same behavior as for the `node find` command.
 
 For instance to filter out files beginning with `._` do:
 
 ```bash
-... --value='exec:!f["name"].start_with?("._") or f["name"].eql?(".DS_Store")'
+--query='exec:!f["name"].start_with?("._") or f["name"].eql?(".DS_Store")'
 ```
 
 ### Preview File types
@@ -5547,10 +5927,10 @@ If the `mimemagic` gem complains about missing mime info file:
 
   - Close the `cmd` and restart a new one if needed to get refreshed env vars
 
-- Linux:
+- Linux RHEL 8+:
 
 ```bash
-yum install shared-mime-info
+dnf install shared-mime-info
 ```
 
 - macOS:
@@ -5597,8 +5977,9 @@ The `smtp` option is a hash table (extended value) with the following fields:
 | field        | default             | example                    | description                      |
 |--------------|---------------------|----------------------------|----------------------------------|
 | `server`     | -                   | smtp.gmail.com             | SMTP server address              |
-| `tls`        | true                | false                      | use of TLS                       |
-| `port`       | TLS: 587<br/>25     | 587                        | port for service                 |
+| `tls`        | true                | true                       | enable STARTTLS (port 587)       |
+| `ssl`        | false               | false                      | enable TLS (port 465)            |
+| `port`       | 587 or 465 or 25    | 587                        | port for service                 |
 | `domain`     | domain of server    | gmail.com                  | email domain of user             |
 | `username`   | -                   | john@example.com           | user to authenticate on SMTP server, leave empty for open auth. |
 | `password`   | -                   | my_password_here           | password for above username      |
@@ -5812,7 +6193,7 @@ Interesting `ascp` features are found in its arguments: (see `ascp` manual):
 - `ascp` has an option to send only files not modified since the last X seconds: `--exclude-newer-than`, `--exclude-older-than` (`exclude_newer_than`,`exclude_older_than`)
 - `--src-base` (`src_base`) if top level folder name shall not be created on destination
 
-> **Note:** `ascli` takes transfer parameters exclusively as a [*transfer-spec*](#transferspec), with `--ts` parameter.
+> **Note:** `ascli` takes transfer parameters exclusively as a [*transfer-spec*](#transferspec), with `ts` option.
 >
 > **Note:** Most, but not all, native `ascp` arguments are available as standard [*transfer-spec*](#transferspec) parameters.
 >