aspera-cli 4.19.0 → 4.20.0

data/README.md

@@ -1,8 +1,13 @@
 # Command Line Interface for IBM Aspera products
-<!-- markdownlint-disable MD033 MD003 MD053 -->
-<!-- cspell:ignore Serban Antipolis -->
+<!--
+Do not edit this README.md, edit docs/README.erb.md, for details, read docs/README.md
 
-[comment1]: # (Do not edit this README.md, edit docs/README.erb.md, for details, read docs/README.md)
+markdownlint-disable MD033 MD003 MD053
+cspell:ignore Serban Antipolis
+PANDOC_META_BEGIN
+subtitle: "ascli 4.20.0"
+PANDOC_META_END
+-->
 
 [![Gem Version](https://badge.fury.io/rb/aspera-cli.svg)](https://badge.fury.io/rb/aspera-cli)
 [![unit tests](https://github.com/IBM/aspera-cli/actions/workflows/test.yml/badge.svg?branch=main)](https://github.com/IBM/aspera-cli/actions)
@@ -10,9 +15,9 @@
 
 ## Introduction
 
-Version : 4.19.0
+Version : 4.20.0
 
-Laurent/2016-2024
+Laurent/2016-2025
 
 This gem provides the `ascli` CLI (Command Line Interface) to IBM Aspera software.
 
@@ -37,6 +42,11 @@ A PDF version of this documentation is available here: [docs/Manual.pdf](docs/Ma
 
 Refer to [BUGS.md](BUGS.md) and [CONTRIBUTING.md](CONTRIBUTING.md).
 
+This documentation does not provide ALL the detailed description of all options and commands.
+The reason is that most commands and payloads are directly Rest API calls on the various Aspera products.
+So, to get the full description of all options and commands, refer to the official Aspera API documentation.
+(To see which API is used, set option `--log-level=debug`)
+
 ### When to use and when not to use
 
 `ascli` is designed to be used as a command line tool to:
@@ -59,13 +69,23 @@ It is designed for:
 If the need is to perform operations programmatically in languages such as: C, Go, Python, nodejs, ... then it is better to directly use [Aspera APIs](https://ibm.biz/aspera_api)
 
 - Product APIs (REST) : e.g. AoC, Faspex, node
-- Transfer SDK : with gRPC interface and language stubs (C, C++, Python, .NET/C#, java, Ruby, etc...)
+- Transfer SDK : with gRPC interface and language stubs (C, C++, Python, .NET/C#, java, Go, Ruby, Rust, etc...)
 
 Using APIs (application REST API and transfer SDK) will prove to be easier to develop and maintain.
 Code examples here: <https://github.com/laurent-martin/aspera-api-examples>
 
 For scripting and ad'hoc command line operations, `ascli` is perfect.
 
+So, which is Aspera's CLI ? `ascli` or `ascp`
+
+`ascp` is the low level Aspera command line for **transfers**.
+It is in fact the implementation of the FASP protocol.
+So, ANY Aspera transfer leads to one ascp process running on client side and another on server side.
+`ascp` can be used as a command line, but it is very low level, and practically it can be used on command line only if there is no Aspera web ap (AoC, Faspex, etc..) and ONLY to do a transfer (send/receive), not for any operation on Aspera apps (e.g. listing remote files).
+`ascp` does not provide a configuration file to store credentials or options, it does not resume automatically on transfer error.
+
+In fact, `ascli` can do everything that `ascp` does, and much more, and in an easier way.
+
 ### Notations, Shell, Examples
 
 Command line operations examples are shown using a shell such as: `bash` or `zsh`.
@@ -92,7 +112,7 @@ Once the gem is installed, `ascli` shall be accessible:
 
 ```console
 $ ascli --version
-4.19.0
+4.20.0
 ```
 
 ### First use
@@ -515,15 +535,27 @@ This can be installed either be installing an Aspera transfer software, or using
 ascli config ascp install
 ```
 
+This command will retrieve the list of current archives for all platforms from: <https://ibm.biz/sdk_location> and then select the latest version for the current platform.
+In this case, the default value for option `sdk_url` is `DEF`.
+
 If a local SDK installation is preferred instead of fetching from internet: one can specify the location of the SDK file:
 
-```bash
-curl -Lso sdk.zip https://ibm.biz/aspera_transfer_sdk
-```
+1. Locate the appropriate SDK archive for your platform, by visiting either:
 
-```bash
-ascli config ascp install --sdk-url=file:///sdk.zip
-```
+    - [IBM API Hub](https://developer.ibm.com/apis/catalog?search=%22aspera%20transfer%20SDK%22)
+    - or looking at this file: <https://ibm.biz/sdk_location>
+
+2. Download the SDK archive using a browser, or `curl` or `wget`, etc...
+
+    ```bash
+    curl -Lso sdk.zip https://...
+    ```
+
+3. Install using the local archive
+
+    ```bash
+    ascli config ascp install --sdk-url=file:///sdk.zip
+    ```
 
 The format is: `file:///<path>`, where `<path>` can be either a relative path (not starting with `/`), or an absolute path.
 
@@ -706,7 +738,7 @@ ascli -v
 ```
 
 ```text
-4.19.0
+4.20.0
 ```
 
 In order to keep persistency of configuration on the host, you should specify your user's configuration folder as a volume for the container.
@@ -969,7 +1001,7 @@ ascli config echo @uri:https://localhost:9092/ping --cert-stores=myserver.pem
 
 ## Command Line Interface
 
-The command line tool is: ``ascli``
+The command line tool is: `ascli`
 
 The `aspera-cli` gem provides a command line interface (CLI) which interacts with Aspera Products (mostly using REST APIs):
 
@@ -1060,6 +1092,8 @@ Hello World
 2
 ```
 
+> **Note:** Use `pp` instead of `puts` to display as ruby Array.
+
 Once the shell has dealt with the command line "special" characters for it, the shell calls Windows' `CreateProcess` with just the whole command line as a single string.
 (Unlike Unix-like systems where the command line is split into arguments by the shell.)
 
@@ -1328,7 +1362,7 @@ The tokenization of the command line is typically done by the shell, refer to th
 `ascli` handles two types of command line arguments:
 
 - **Positional Arguments** : position is significant
-- **Options** : only order is significant, but not position
+- **Options** : only order is significant, but not absolute position
 
 For example:
 
@@ -1349,11 +1383,11 @@ The value of **Options** and **Positional Arguments** is evaluated with the [Ext
 **Positional Arguments** are either:
 
 - **Commands**, typically at the beginning
-- **Command Parameters** , e.g. creation data or entity identifier
+- **Command Parameters**, mandatory arguments, e.g. creation data or entity identifier
 
 When options are removed from the command line, the remaining arguments are typically **Positional Arguments** with a pre-defined order.
 
-**Commands** are typically entity types or verbs to act on those entities.
+**Commands** are typically entity types (e.g. `users`) or verbs (e.g. `create`) to act on those entities.
 Its value is a `String` that must belong to a fixed list of values in a given context.
 
 Example:
@@ -1372,19 +1406,22 @@ Order is significant.
 The provided command must match one of the supported commands in the given context.
 If wrong, or no command is provided when expected, an error message is displayed and the list of supported commands is displayed.
 
-Some sub-commands appear after entity selection (identifier), e.g. `ascli aoc admin res node do 8669 browse /`: `browse` is a sub-command of `node`.
+Standard **Commands** are: `create`, `show`, `list`, `modify`, `delete`.
+Some entities also support additional commands.
+When those additional commands are related to an entity also reachable in another context, then those commands are located below command `do`.
+For example sub-commands appear after entity selection (identifier), e.g. `ascli aoc admin node do 1234 browse /`: `browse` is a sub-command of `node`.
 
 **Command Parameters** are typically mandatory values for a command, such as entity creation data or entity identifier.
 
 > **Note:** It could also have been designed as an option.
-But since it is mandatory and typically these data need **not** be set in a configuration file, then it is better designed as a **Command Parameter**, and not designed an additional specific option.
-The advantages of using a **Command Parameter** instead of an option for the same are that the command line is shorter (no option name, just the position) and the value is clearly mandatory.
-The disadvantage is that it is not possible to define a default value in a configuration file or environment variable like for options.
+But since it is mandatory and typically these data do not need to be set in a configuration file, it is better designed as a Command Parameter, rather than as an additional specific option.
+The advantages of using a **Command Parameter** instead of an option for the same are that the command line is shorter (no option name, just the position), the value is clearly mandatory and position clearly indicates its role.
+The disadvantage is that it is not possible to define a default value in a configuration file or environment variable using an option value.
 Nevertheless, [Extended Values](#extended-value-syntax) syntax is supported, so it is possible to retrieve a value from the configuration file (using `@preset:`) or environment variable (using `@env:`).
 
 If a **Command Parameters** begins with `-`, then either use the `@val:` syntax (see [Extended Values](#extended-value-syntax)), or use the `--` separator (see below).
 
-A few **Command Parameters** are optional, they are located at the end of the command line.
+A few **Command Parameters** are optional, they are always located at the end of the command line.
 
 #### Options
 
@@ -1493,11 +1530,11 @@ When in flatten mode, it is possible to filter fields using the option `fields`
 Object lists are displayed one per line, with attributes as columns.
 Single objects (or tables with a single result) are transposed: one attribute per line.
 If transposition of single object is not desired, use option: `transpose_single` set to `no`.
+If option `multi_table` is `yes`, then elements of a table are displayed individually in a table.
 
 The style of output can be set using the `format` option, supporting:
 
 - `table` : Text table (default)
-- `multi` : List of elements are displayed as a list of tables
 - `text` : Value as String
 - `ruby` : Ruby code
 - `json` : JSON code
@@ -1555,7 +1592,7 @@ The `Proc` takes as argument a line (`Hash`) in the table and is a Ruby lambda e
 Example:
 
 ```bash
-ascli aoc admin res user list --fields=name,email,ats_admin --query=@json:'{"sort":"name"}' --select=@json:'{"ats_admin":true}'
+ascli aoc admin user list --fields=name,email,ats_admin --query=@json:'{"sort":"name"}' --select=@json:'{"ats_admin":true}'
 ```
 
 ```output
@@ -1580,10 +1617,10 @@ In above example, the same result is obtained with option:
 The percent selector allows identification of an entity by another unique identifier other than the native 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's identifier.
+e.g. `ascli aoc admin user show 1234` where `1234` is the user's identifier.
 
 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.
+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 user show %name:john` where `john` is the user name.
 
 Syntax: `%<field>:<value>`
 
@@ -1927,7 +1964,6 @@ coffee
 coffee --ui=text
 coffee --ui=text --image=@json:'{"text":true,"double":false}'
 coffee --ui=text --image=@json:'{"text":true}'
-detect https://faspex4.example.com/path
 detect https://faspex5.example.com/path
 detect https://node.example.com/path
 detect https://shares.example.com/path shares
@@ -1936,6 +1972,7 @@ detect https://tst.example.com/path httpgw
 detect my_org aoc
 doc
 doc transfer-parameters
+echo '<svg viewBox="0 0 100 100" xmlns="http://www.w3.org/2000/svg"><circle cx="50" cy="50" r="50" fill="#006699"/></svg>' --format=image
 echo -- --special-string
 echo @base64:SGVsbG8gV29ybGQK
 echo @csvt:@stdin:
@@ -1951,6 +1988,8 @@ echo @vault:my_preset.password
 echo @zlib:@stdin:
 echo hello
 email_test --notify-to=my_email_external
+file
+file --logger=syslog --log-level=debug
 flush_tokens
 folder
 gem name
@@ -1977,8 +2016,10 @@ pubkey @file:my_key
 remote_certificate chain https://node.example.com/path
 remote_certificate name https://node.example.com/path
 remote_certificate only https://node.example.com/path
+smtp_settings
 vault create my_label @json:'{"password":"my_password_here","description":"my secret"}'
 vault delete my_label
+vault info
 vault list
 vault show my_label
 wizard https://console.example.com/path console
@@ -2439,14 +2480,18 @@ To disable the warning, use option `silent_insecure` set to `no`.
 
 HTTP connection parameters (not `ascp` wss) can be adjusted using option `http_options`:
 
-| Parameter            | Default |
-|----------------------|---------|
-| `read_timeout`       | 60      |
-| `write_timeout`      | 60      |
-| `open_timeout`       | 60      |
-| `keep_alive_timeout` | 2       |
-
-Values are in set **seconds** and can be of type either integer or float.
+| Parameter                 | Default       | Where     |
+|---------------------------|---------------|-----------|
+| `read_timeout`            | 60            | ruby      |
+| `write_timeout`           | 60            | ruby      |
+| `open_timeout`            | 60            | ruby      |
+| `keep_alive_timeout`      | 2             | ruby      |
+| `user_agent`              | `ascli`     | `ascli` |
+| `download_partial_suffix` | .http_partial | `ascli` |
+| `retry_on_error`          | 0             | `ascli` |
+| `retry_sleep`             | nil           | `ascli` |
+
+Time values are in set **seconds** and can be of type either integer or float.
 Default values are the ones of Ruby:
 For a full list, refer to the Ruby library: [`Net::HTTP`](https://ruby-doc.org/stdlib/libdoc/net/http/rdoc/Net/HTTP.html).
 
@@ -2455,7 +2500,7 @@ Like any other option, those can be set either on command line, or in configurat
 Example:
 
 ```bash
-ascli aoc admin res package list --http-options=@json:'{"read_timeout":10.0}'
+ascli aoc admin package list --http-options=@json:'{"read_timeout":10.0}'
 ```
 
 ### Proxy
@@ -3565,7 +3610,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.19.0)
+        ascli -- a command line tool for Aspera Applications (v4.20.0)
 
 SYNOPSIS
         ascli COMMANDS [OPTIONS] [ARGS]
@@ -3597,14 +3642,15 @@ OPTIONS: global
         --interactive=ENUM           Use interactive input of missing params: [no], yes
         --ask-options=ENUM           Ask even optional options: [no], yes
         --struct-parser=ENUM         Default parser when expected value is a struct: json, ruby
-        --format=ENUM                Output format: text, nagios, ruby, json, jsonpp, yaml, [table], multi, csv, image
+        --format=ENUM                Output format: text, nagios, ruby, json, jsonpp, yaml, [table], csv, image
         --output=VALUE               Destination for results (String)
         --display=ENUM               Output only some information: [info], data, error
         --fields=VALUE               Comma separated list of: fields, or ALL, or DEF (String, Array, Regexp, Proc)
         --select=VALUE               Select only some items in lists: column, value (Hash, Proc)
         --table-style=VALUE          Table display style (Hash)
-        --flat-hash=ENUM             Display deep values as additional keys: no, [yes]
-        --transpose-single=ENUM      Single object fields output vertically: no, [yes]
+        --flat-hash=ENUM             (Table) Display deep values as additional keys: no, [yes]
+        --transpose-single=ENUM      (Table) Single object fields output vertically: no, [yes]
+        --multi-table=ENUM           (Table) Each element of a table are displayed as a table: [no], yes
         --show-secrets=ENUM          Show secrets on command output: [no], yes
         --image=VALUE                Options for image display (Hash)
     -h, --help                       Show this message
@@ -3619,17 +3665,12 @@ OPTIONS: global
         --log-secrets=ENUM           Show passwords in logs: [no], yes
         --clean-temp=ENUM            Cleanup temporary files on exit: no, [yes]
         --pid-file=VALUE             Write process identifier to file, delete on exit (String)
-
-COMMAND: config
-SUBCOMMANDS: ascp check_update coffee detect documentation echo email_test file flush_tokens folder gem genkey image initdemo open platform plugins preset proxy_check pubkey remote_certificate smtp_settings throw vault wizard
-OPTIONS:
         --home=VALUE                 Home folder for tool (String)
         --config-file=VALUE          Path to YAML file with preset configuration
         --secret=VALUE               Secret for access keys
         --vault=VALUE                Vault for secrets (Hash)
         --vault-password=VALUE       Vault password
-        --query=VALUE                Additional filter for for some commands (list/delete) (Hash)
-        --value=VALUE                Value for create, update, list filter (Hash) (deprecated: (4.14) Use positional value for create/modify or option: query for list/delete)
+        --query=VALUE                Additional filter for for some commands (list/delete) (Hash, Array)
         --property=VALUE             Name of property to set (modify operation)
         --bulk=ENUM                  Bulk operation (only some): [no], yes
         --bfail=ENUM                 Bulk operation error handling: no, [yes]
@@ -3657,7 +3698,7 @@ OPTIONS:
         --http-proxy=VALUE           URL for HTTP proxy with optional credentials (String)
         --cache-tokens=ENUM          Save and reuse OAuth tokens: no, [yes]
         --fpac=VALUE                 Proxy auto configuration script
-        --proxy-credentials=VALUE    HTTP proxy credentials for fpac. Array: user,password (Array)
+        --proxy-credentials=VALUE    HTTP proxy credentials for fpac: user, password (Array)
         --ts=VALUE                   Override transfer spec values (Hash)
         --to-folder=VALUE            Destination folder for transferred files
         --sources=VALUE              How list of transferred files is provided (@args,@ts,Array)
@@ -3665,6 +3706,9 @@ OPTIONS:
         --transfer=ENUM              Type of transfer agent: node, [direct], alpha, httpgw, connect, trsdk
         --transfer-info=VALUE        Parameters for transfer agent (Hash)
 
+COMMAND: config
+SUBCOMMANDS: ascp check_update coffee detect documentation echo email_test file flush_tokens folder gem genkey image initdemo open platform plugins preset proxy_check pubkey remote_certificate smtp_settings test vault wizard
+
 
 COMMAND: shares
 SUBCOMMANDS: admin files health
@@ -3684,7 +3728,8 @@ OPTIONS:
         --asperabrowserurl=VALUE     URL for simple aspera web ui
         --sync-name=VALUE            Sync name
         --default-ports=ENUM         Use standard FASP ports or get from node api (gen4): no, [yes]
-        --root-id=VALUE              File id of top folder if using bearer tokens
+        --node-cache=ENUM            Set to no to force actual file system read (gen4): no, [yes]
+        --root-id=VALUE              File id of top folder when using access key (override AK root id)
         --sync-info=VALUE            Information for sync instance and sessions (Hash)
 
 
@@ -3833,12 +3878,6 @@ OPTIONS:
         --workspace=VALUE            Name of workspace (String, NilClass)
         --new-user-option=VALUE      New user creation option for unknown package recipients (Hash)
         --validate-metadata=ENUM     Validate shared inbox metadata: no, [yes]
-        --validator=VALUE            Identifier of validator (optional for central)
-        --asperabrowserurl=VALUE     URL for simple aspera web ui
-        --sync-name=VALUE            Sync name
-        --default-ports=ENUM         Use standard FASP ports or get from node api (gen4): no, [yes]
-        --root-id=VALUE              File id of top folder if using bearer tokens
-        --sync-info=VALUE            Information for sync instance and sessions (Hash)
 
 
 COMMAND: server
@@ -3873,6 +3912,22 @@ Bulk creation and deletion of resources are possible using option `bulk` (`yes`,
 In that case, the operation expects an `Array` of `Hash` instead of a simple `Hash` using the [Extended Value Syntax](#extended-value-syntax).
 This option is available only for some of the resources: if you need it: try and see if the entities you try to create or delete support this option.
 
+### Option: `query`
+
+The `query` option can generally be used to add URL parameters to commands that list ressources.
+It takes either a `Hash` or an `Array`, corresponding to key/value pairs that appear in the query part of request.
+
+For example: `--query=@json:'{"p1":"v1","p2":"v2"}'` leads to query: `?p1=v1&p2=v2`.
+
+If the same parameter needs to be provided several times, then it's possible as well to provide an Array or 2-element Array: `--query=@json:'[["p1":,"v1"],["p2":"v2"]]'` leads to the same result as previously.
+
+If PHP's style array is used, then one can use either:
+
+- `--query=@json:'{"a":["[]","v1","v2"]}'`
+- `--query=@json:'[["a[]","v1"],["a[]","v2"]]'`
+
+Both result in: `?a[]=v1&a[]=v2`.
+
 ### Plugins
 
 `ascli` uses a plugin mechanism.
@@ -4016,7 +4071,7 @@ Let's start by a registration with web based authentication (auth=web):
   - leave the JWT part for now
 - **Save**
 
-> **Note:** For web based authentication, `ascli` listens on a local port (e.g. specified by the redirect_uri, in this example: 12345), and the browser will provide the OAuth code there. For ``ascli`, HTTP is required, and 12345 is the default port.
+> **Note:** For web based authentication, `ascli` listens on a local port (e.g. specified by the redirect_uri, in this example: 12345), and the browser will provide the OAuth code there. For `ascli`, HTTP is required, and 12345 is the default port.
 
 Once the client is registered, a **Client ID** and **Secret** are created, these values will be used in the next step.
 
@@ -4070,7 +4125,7 @@ If you are not using the built-in client_id and secret, JWT needs to be authoriz
 - Using command line
 
 ```bash
-ascli aoc admin res client list
+ascli aoc admin client list
 ```
 
 ```output
@@ -4082,7 +4137,7 @@ ascli aoc admin res client list
 ```
 
 ```bash
-ascli aoc admin res client modify my_BJbQiFw @json:'{"jwt_grant_enabled":true,"explicit_authorization_required":false}'
+ascli aoc admin client modify my_BJbQiFw @json:'{"jwt_grant_enabled":true,"explicit_authorization_required":false}'
 ```
 
 ```output
@@ -4107,7 +4162,7 @@ Open the previously generated public key located here: `$HOME/.aspera/ascli/my_p
 ##### Using command line
 
 ```bash
-ascli aoc admin res user list
+ascli aoc admin user list
 ```
 
 ```output
@@ -4194,7 +4249,7 @@ ascli aoc files bearer_token_node /
 ```
 
 ```bash
-ascli aoc admin res node v4 1234 --secret=_ak_secret_here_ bearer_token_node /
+ascli aoc admin node v4 1234 --secret=_ak_secret_here_ bearer_token_node /
 ```
 
 ### Administration
@@ -4205,7 +4260,8 @@ It allows actions (create, update, delete) on **resources**: users, group, nodes
 
 #### Listing resources
 
-The command `aoc admin res <type> list` lists all entities of given type. It uses paging and multiple requests if necessary.
+The command `aoc admin <type> list` lists all entities of given type.
+It uses paging and multiple requests if necessary.
 
 The option `query` can be optionally used.
 It expects a `Hash` using [Extended Value Syntax](#extended-value-syntax), generally provided using: `--query=@json:{...}`.
@@ -4236,19 +4292,19 @@ Examples:
 - List users with `laurent` in name:
 
 ```bash
-ascli aoc admin res user list --query=@json:'{"q":"laurent"}'
+ascli aoc admin user list --query=@json:'{"q":"laurent"}'
 ```
 
 - List users who logged-in before a date:
 
 ```bash
-ascli aoc admin res user list --query=@json:'{"q":"last_login_at:<2018-05-28"}'
+ascli aoc admin user list --query=@json:'{"q":"last_login_at:<2018-05-28"}'
 ```
 
 - List external users and sort in reverse alphabetical order using name:
 
 ```bash
-ascli aoc admin res user list --query=@json:'{"member_of_any_workspace":false,"sort":"-name"}'
+ascli aoc admin user list --query=@json:'{"member_of_any_workspace":false,"sort":"-name"}'
 ```
 
 Refer to the AoC API for full list of query parameters, or use the browser in developer mode with the web UI.
@@ -4261,17 +4317,17 @@ Resources are identified by a unique `id`, as well as a unique `name` (case inse
 
 To execute an action on a specific resource, select it using one of those methods:
 
-- **recommended**: give id directly on command line **after the action**: `aoc admin res node show 123`
-- Give name on command line **after the action**: `aoc admin res node show name abc`
-- Provide option `id` : `aoc admin res node show 123`
-- Provide option `name` : `aoc admin res node show --name=abc`
+- **recommended**: give id directly on command line **after the action**: `aoc admin node show 123`
+- Give name on command line **after the action**: `aoc admin node show name abc`
+- Provide option `id` : `aoc admin node show 123`
+- Provide option `name` : `aoc admin node show --name=abc`
 
 #### Creating a resource
 
 New resources (users, groups, workspaces, etc..) can be created using a command like:
 
 ```bash
-ascli aoc admin res create <resource type> @json:'{<...parameters...>}'
+ascli aoc admin create <resource type> @json:'{<...parameters...>}'
 ```
 
 Some of the API endpoints are described [here](https://developer.ibm.com/apis/catalog?search=%22aspera%20on%20cloud%20api%22). Sadly, not all.
@@ -4279,7 +4335,7 @@ Some of the API endpoints are described [here](https://developer.ibm.com/apis/ca
 Nevertheless, it is possible to guess the structure of the creation value by simply dumping an existing resource, and use the same parameters for the creation.
 
 ```bash
-ascli aoc admin res group show 12345 --format=json
+ascli aoc admin group show 12345 --format=json
 ```
 
 ```json
@@ -4291,7 +4347,7 @@ Remove the parameters that are either obviously added by the system: `id`, `crea
 And then craft your command:
 
 ```bash
-ascli aoc admin res group create @json:'{"description":"test to delete","name":"test 1 to delete","saml_group":false}'
+ascli aoc admin group create @json:'{"description":"test to delete","name":"test 1 to delete","saml_group":false}'
 ```
 
 If the command returns an error, example:
@@ -4318,7 +4374,7 @@ The secret is provided using the `secret` option.
 For example in a command like:
 
 ```bash
-ascli aoc admin res node 123 --secret="my_secret_here" v3 info
+ascli aoc admin node 123 --secret="my_secret_here" v3 info
 ```
 
 It is also possible to store secrets in the [secret vault](#secret-vault) and then automatically find the related secret using the [config finder](#configuration-finder).
@@ -4407,7 +4463,7 @@ Current Workspace: Default (default)
 #### Example: Bulk creation of users
 
 ```bash
-ascli aoc admin res user create --bulk=yes @json:'[{"email":"dummyuser1@example.com"},{"email":"dummyuser2@example.com"}]'
+ascli aoc admin user create --bulk=yes @json:'[{"email":"dummyuser1@example.com"},{"email":"dummyuser2@example.com"}]'
 ```
 
 ```output
@@ -4422,7 +4478,7 @@ ascli aoc admin res user create --bulk=yes @json:'[{"email":"dummyuser1@example.
 #### Example: Find with filter and delete
 
 ```bash
-ascli aoc admin res user list --query='@json:{"q":"dummyuser"}' --fields=id,email
+ascli aoc admin user list --query='@json:{"q":"dummyuser"}' --fields=id,email
 ```
 
 ```output
@@ -4435,7 +4491,7 @@ ascli aoc admin res user list --query='@json:{"q":"dummyuser"}' --fields=id,emai
 ```
 
 ```bash
-ascli aoc admin res user list --query='@json:{"q":"dummyuser"}' --fields=id --display=data --format=csv | ascli aoc admin res user delete @lines:@stdin: --bulk=yes
+ascli aoc admin user list --query='@json:{"q":"dummyuser"}' --fields=id --display=data --format=csv | ascli aoc admin user delete @lines:@stdin: --bulk=yes
 ```
 
 ```output
@@ -4450,7 +4506,7 @@ ascli aoc admin res user list --query='@json:{"q":"dummyuser"}' --fields=id --di
 #### Example: Find deactivated users since more than 2 years
 
 ```ruby
-ascli aoc admin res user list --query=@ruby:'{"deactivated"=>true,"q"=>"last_login_at:<#{(DateTime.now.to_time.utc-2*365*86400).iso8601}"}'
+ascli aoc admin user list --query=@ruby:'{"deactivated"=>true,"q"=>"last_login_at:<#{(DateTime.now.to_time.utc-2*365*86400).iso8601}"}'
 ```
 
 To delete them use the same method as before
@@ -4482,7 +4538,7 @@ ascli aoc admin resource node --name=_node_name_ --secret=_secret_ v4 access_key
 #### Example: Display transfer events (ops/transfer)
 
 ```bash
-ascli aoc admin res node --secret=_secret_ v3 transfer list --query=@json:'[["q","*"],["count",5]]'
+ascli aoc admin node --secret=_secret_ v3 transfer list --query=@json:'[["q","*"],["count",5]]'
 ```
 
 Examples of query:
@@ -4498,13 +4554,13 @@ Examples of query:
 #### Example: Display node events (events)
 
 ```bash
-ascli aoc admin res node --secret=_secret_ v3 events
+ascli aoc admin node --secret=_secret_ v3 events
 ```
 
 #### Example: Display members of a workspace
 
 ```bash
-ascli aoc admin res workspace_membership list --fields=member_type,manager,member.email --query=@json:'{"embed":"member","inherited":false,"workspace_id":11363,"sort":"name"}'
+ascli aoc admin workspace_membership list --fields=member_type,manager,member.email --query=@json:'{"embed":"member","inherited":false,"workspace_id":11363,"sort":"name"}'
 ```
 
 ```output
@@ -4512,7 +4568,7 @@ ascli aoc admin res workspace_membership list --fields=member_type,manager,membe
 | member_type | manager |           member.email           |
 +-------------+---------+----------------------------------+
 | user        | true    | john.curtis@email.com            |
-| user        | false   | someuser@example.com |
+| user        | false   | someuser@example.com             |
 | user        | false   | jean.dupont@me.com               |
 | user        | false   | another.user@example.com         |
 | group       | false   |                                  |
@@ -4532,20 +4588,20 @@ a- Get id of first workspace
 
 ```bash
 WS1='First Workspace'
-WS1ID=$(ascli aoc admin res workspace list --query=@json:'{"q":"'"$WS1"'"}' --select=@json:'{"name":"'"$WS1"'"}' --fields=id --format=csv)
+WS1ID=$(ascli aoc admin workspace list --query=@json:'{"q":"'"$WS1"'"}' --select=@json:'{"name":"'"$WS1"'"}' --fields=id --format=csv)
 ```
 
 b- Get id of second workspace
 
 ```bash
 WS2='Second Workspace'
-WS2ID=$(ascli aoc admin res workspace list --query=@json:'{"q":"'"$WS2"'"}' --select=@json:'{"name":"'"$WS2"'"}' --fields=id --format=csv)
+WS2ID=$(ascli aoc admin workspace list --query=@json:'{"q":"'"$WS2"'"}' --select=@json:'{"name":"'"$WS2"'"}' --fields=id --format=csv)
 ```
 
 c- Extract membership information
 
 ```bash
-ascli aoc admin res workspace_membership list --fields=manager,member_id,member_type,workspace_id --query=@json:'{"workspace_id":'"$WS1ID"'}' --format=jsonpp --output=ws1_members.json
+ascli aoc admin workspace_membership list --fields=manager,member_id,member_type,workspace_id --query=@json:'{"workspace_id":'"$WS1ID"'}' --format=jsonpp --output=ws1_members.json
 ```
 
 d- Convert to creation data for second workspace:
@@ -4563,13 +4619,13 @@ jq '[.[] | {member_type,member_id,workspace_id,manager,workspace_id:"'"$WS2ID"'"
 e- Add members to second workspace
 
 ```bash
-ascli aoc admin res workspace_membership create --bulk=yes @json:@file:ws2_members.json
+ascli aoc admin workspace_membership create --bulk=yes @json:@file:ws2_members.json
 ```
 
 #### Example: Get users who did not log since a date
 
 ```bash
-ascli aoc admin res user list --fields=email --query=@json:'{"q":"last_login_at:<2018-05-28"}'
+ascli aoc admin user list --fields=email --query=@json:'{"q":"last_login_at:<2018-05-28"}'
 ```
 
 ```output
@@ -4584,7 +4640,7 @@ ascli aoc admin res user list --fields=email --query=@json:'{"q":"last_login_at:
 #### Example: List **Limited** users
 
 ```bash
-ascli aoc admin res user list --fields=email --select=@json:'{"member_of_any_workspace":false}'
+ascli aoc admin user list --fields=email --select=@json:'{"member_of_any_workspace":false}'
 ```
 
 #### Example: Create a group, add to workspace and add user to group
@@ -4592,7 +4648,7 @@ ascli aoc admin res user list --fields=email --select=@json:'{"member_of_any_wor
 - Create the group and take note of `id`
 
 ```bash
-ascli aoc admin res group create @json:'{"name":"group 1","description":"my super group"}'
+ascli aoc admin group create @json:'{"name":"group 1","description":"my super group"}'
 ```
 
 Group: `11111`
@@ -4600,7 +4656,7 @@ Group: `11111`
 - Get the workspace id
 
 ```bash
-ascli aoc admin res workspace list --query=@json:'{"q":"myworkspace"}' --fields=id --format=csv --display=data
+ascli aoc admin workspace list --query=@json:'{"q":"myworkspace"}' --fields=id --format=csv --display=data
 ```
 
 Workspace: 22222
@@ -4608,13 +4664,13 @@ Workspace: 22222
 - Add group to workspace
 
 ```bash
-ascli aoc admin res workspace_membership create @json:'{"workspace_id":22222,"member_type":"user","member_id":11111}'
+ascli aoc admin workspace_membership create @json:'{"workspace_id":22222,"member_type":"user","member_id":11111}'
 ```
 
 - Get a user's id
 
 ```bash
-ascli aoc admin res user list --query=@json:'{"q":"manu.macron@example.com"}' --fields=id --format=csv --display=data
+ascli aoc admin user list --query=@json:'{"q":"manu.macron@example.com"}' --fields=id --format=csv --display=data
 ```
 
 User: 33333
@@ -4622,7 +4678,7 @@ User: 33333
 - Add user to group
 
 ```bash
-ascli aoc admin res group_membership create @json:'{"group_id":11111,"member_type":"user","member_id":33333}'
+ascli aoc admin group_membership create @json:'{"group_id":11111,"member_type":"user","member_id":33333}'
 ```
 
 #### Example: Perform a multi Gbps transfer between two remote shared folders
@@ -4670,7 +4726,7 @@ ascli -Paoc_show aoc files transfer --from-folder='IBM Cloud SJ' --to-folder='AW
 #### Example: Create registration key to register a node
 
 ```bash
-ascli aoc admin res client create @json:'{"data":{"name":"laurentnode","client_subject_scopes":["alee","aejd"],"client_subject_enabled":true}}' --fields=token --format=csv
+ascli aoc admin client create @json:'{"data":{"name":"laurentnode","client_subject_scopes":["alee","aejd"],"client_subject_enabled":true}}' --fields=token --format=csv
 ```
 
 ```output
@@ -4680,7 +4736,7 @@ jfqslfdjlfdjfhdjklqfhdkl
 #### Example: Delete all registration keys
 
 ```bash
-ascli aoc admin res client list --fields=id --format=csv|ascli aoc admin res client delete @lines:@stdin: --bulk=yes
+ascli aoc admin client list --fields=id --format=csv|ascli aoc admin client delete @lines:@stdin: --bulk=yes
 ```
 
 ```output
@@ -4731,7 +4787,7 @@ So, for example, the creation of a node using ATS in IBM Cloud looks like (see o
   Then use the returned address for the `url` key to actually create the AoC Node entity:
 
   ```bash
-  ascli aoc admin res node create @json:'{"name":"myname","access_key":"myaccesskeyid","ats_access_key":true,"ats_storage_type":"ibm-s3","url":"https://ats-sl-fra-all.aspera.io"}'
+  ascli aoc admin node create @json:'{"name":"myname","access_key":"myaccesskeyid","ats_access_key":true,"ats_storage_type":"ibm-s3","url":"https://ats-sl-fra-all.aspera.io"}'
   ```
 
 Creation of a node with a self-managed node is similar, but the command `aoc admin ats access_key create` is replaced with `node access_key create` on the private node itself.
@@ -4798,13 +4854,13 @@ ascli aoc packages send @json:'{"name":"my title","note":"my note","recipients":
 #### Example: Send a package to a shared inbox with metadata
 
 ```bash
-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
+ascli aoc packages send --workspace="my ws" @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 @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="my ws" @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
@@ -4907,13 +4963,47 @@ ascli aoc files download <single file path>
 
 #### Shared folders
 
-Shared folder created by users are managed through **permissions**.
+Like in AoC web UI, "Shared Folders" can be created and shared with either **Private** or **Public** links.
+**Private** links require the collaborator to log-in to access the shared folder.
+**Public** links include a passcode that enables the user to access the shared folder without login-in.
+
+Shared folders can be created either:
+
+- by users in a workspace: they can share personal folders with other users in the same workspace: `aoc files perm`
+- by administrators: they can share a folder with users in any workspace: `aoc admin node do [node id] perm`
+
+Technically (API), shared folder are managed through [permissions](https://developer.ibm.com/apis/catalog/aspera--aspera-node-api/Introduction) on node and an event is sent to AoC to create a **link** in the user's home folder to the shared folder.
+In both cases, it is necessary to specify a workspace.
+
+The basic payload (last argument at creation usually specified with `@json:`) is:
+
+```json
+{
+  "file_id": "50",
+  "access_levels": ["list","read","write","delete","mkdir","rename","preview"],
+  "access_type": "user",
+  "access_id": "john@example.com",
+  "tags": {...},
+}
+```
 
-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 populate required tags if needed.
+`ascli` expects the same payload for creation.
+`ascli` automatically populates this payload like this:
 
-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.
+- `file_id` : the id of the folder to share whose path is specified in the command line
+- `access_levels` : are set by default to full access.
+- `tags` : are set with expected values for AoC: user name who creates, and workspace in which the shared folder is created.
+- `access_type` and `access_id` : need to be set by the user, or using special key as follows.
+
+To change `access_levels`, just provide the list of levels in the `@json:` payload.
+
+In order to declare/create the shared folder in the workspace, a special value for `access_id` is used: `ASPERA_ACCESS_KEY_ADMIN_WS_[workspace id]]`. This is conveniently set by `ascli` using an empty string for the pseudo key `with`. In order to share a folder with a different, special tags are set, but this is conveniently done by `ascli` using the `as` key.
+
+The following optional additional helper keys are supported by `ascli`:
+
+- `with` : Recipient of shared folder. Can be a user name, a group name, or a workspace name. `ascli` will resolve the name to the proper type and id in fields `access_type` and `access_id`. If the value is the empty string, then it declares the shared folder in the workspace (first action to do, see below).
+- `link_name` : The name of the link file created in the user's home folder for private links.
+- `as` : The name of the link file created in the user's home folder for admin shared folders.
 
 - List permissions on a shared folder as user
 
@@ -4936,12 +5026,24 @@ ascli aoc files perm /shared_folder_test1 delete 6161
 Public and Private short links can be managed with command:
 
 ```bash
-ascli aoc files short_link private create _path_here_
-ascli aoc files short_link private list _path_here_
-ascli aoc files short_link public list _path_here_
+ascli aoc files short_link _path_here_ private create
+ascli aoc files short_link _path_here_ private list
+ascli aoc files short_link _path_here_ public list
 ascli aoc files short_link public delete _id_
 ```
 
+- Create an admin shared folder and shared with a user or group or workspace
+
+```bash
+ascli aoc admin node do 1234 mkdir folder_on_node
+ascli aoc admin node do 1234 perm folder_on_node create @json:'{"with":"","as":"folder_for_users"}' --workspace="my ws"
+ascli aoc admin node do 1234 perm folder_on_node create @json:'{"with":"john@example.com","as":"folder_for_users"}' --workspace="my ws"
+ascli aoc admin node do 1234 perm folder_on_node create @json:'{"with":"group 1","as":"folder_for_users"}' --workspace="my ws"
+ascli aoc admin node do 1234 perm folder_on_node create @json:'{"with":"my ws","as":"folder_for_users"}' --workspace="my ws"
+```
+
+> **Note:** The node can be conveniently identified using the **percent selector** instead of numerical id.
+
 #### Cross Organization transfers
 
 It is possible to transfer files directly between organizations without having to first download locally and then upload...
@@ -4979,7 +5081,7 @@ The command `aoc files find` allows to search for files in a given workspace.
 It works also on `node` resource using the `v4` command:
 
 ```bash
-ascli aoc admin res node --name='my node name' --secret='my_secret_here' v4 find ...
+ascli aoc admin node --name='my node name' --secret='my_secret_here' v4 find ...
 ```
 
 For instructions, refer to section `find` for plugin `node`.
@@ -4991,7 +5093,7 @@ For instructions, refer to section `find` for plugin `node`.
 ```bash
 admin analytics transfers nodes
 admin analytics transfers organization --query=@json:'{"status":"completed","direction":"receive"}' --notify-to=my_email_external --notify-template=@ruby:'%Q{From: <%=from_name%> <<%=from_email%>>\nTo: <<%=to%>>\nSubject: <%=ev["files_completed"]%> files received\n\n<%=ev.to_yaml%>}'
-admin analytics transfers users --once_only=yes
+admin analytics transfers users --once-only=yes
 admin application list
 admin ats access_key create --cloud=aws --region=my_region --params=@json:'{"id":"ak_aws","name":"my test key AWS","storage":{"type":"aws_s3","bucket":"my_bucket","credentials":{"access_key_id":"my_access_key","secret_access_key":"my_secret_key"},"path":"/"}}'
 admin ats access_key create --cloud=softlayer --region=my_region --params=@json:'{"id":"ak1ibmcloud","secret":"my_secret_here","name":"my test key","storage":{"type":"ibm-s3","bucket":"my_bucket","credentials":{"access_key_id":"my_access_key","secret_access_key":"my_secret_key"},"path":"/"}}'
@@ -5013,12 +5115,17 @@ admin dropbox list
 admin dropbox_membership list
 admin group list
 admin kms_profile list
-admin node do %name:my_ak_name --secret=my_ak_secret browse /
-admin node do %name:my_ak_name --secret=my_ak_secret delete /folder1
-admin node do %name:my_ak_name --secret=my_ak_secret mkdir /folder1
-admin node do %name:my_ak_name --secret=my_ak_secret v3 access_key create @json:'{"id":"testsub1","storage":{"path":"/folder1"}}'
-admin node do %name:my_ak_name --secret=my_ak_secret v3 access_key delete testsub1
-admin node do %name:my_ak_name --secret=my_ak_secret v3 events
+admin node do %name:my_node_name --secret=my_ak_secret browse /
+admin node do %name:my_node_name --secret=my_ak_secret delete /folder1
+admin node do %name:my_node_name --secret=my_ak_secret mkdir /folder1
+admin node do %name:my_node_name --secret=my_ak_secret v3 access_key create @json:'{"id":"testsub1","storage":{"path":"/folder1"}}'
+admin node do %name:my_node_name --secret=my_ak_secret v3 access_key delete testsub1
+admin node do %name:my_node_name --secret=my_ak_secret v3 events
+admin node do %name:my_node_name delete test_shared_folder
+admin node do %name:my_node_name mkdir test_shared_folder
+admin node do %name:my_node_name perm test_shared_folder create @json:'{"with":"","as":"other_name_shared"}' --workspace=my_workspace_shared_inbox
+admin node do %name:my_node_name perm test_shared_folder create @json:'{"with":"my_user_email","as":"other_name_shared"}' --workspace=my_workspace_shared_inbox
+admin node do %name:my_node_name perm test_shared_folder create @json:'{"with":"my_user_group","as":"other_name_shared"}' --workspace=my_workspace_shared_inbox
 admin node list
 admin operation list
 admin organization show
@@ -5051,15 +5158,17 @@ files browse my_remote_folder/
 files delete /testsrc
 files download --transfer=alpha testdst/test_file.bin
 files download --transfer=connect testdst/test_file.bin
+files find /
 files find / '\.partial$'
+files find / @ruby:'->(f){f["type"].eql?("file")}'
 files http_node_download --to-folder=. testdst/test_file.bin
 files mkdir /testsrc
 files modify my_test_folder
 files permission my_test_folder list
 files rename /some_folder testdst
-files short_link private create /testdst
-files short_link private list /testdst
-files short_link public create testdst
+files short_link /testdst private create
+files short_link /testdst private list
+files short_link /testdst public create
 files show %id:aoc_file_id
 files show /
 files show testdst/test_file.bin
@@ -5096,8 +5205,10 @@ packages send @json:'{"name":"$(notdir test) PACKAGE_TITLE_BASE","recipients":["
 packages send @json:'{"name":"$(notdir test) PACKAGE_TITLE_BASE"}' test_file.bin --url=my_public_link_send_aoc_user --password=my_public_link_send_use_pass
 packages send @json:'{"name":"$(notdir test) PACKAGE_TITLE_BASE"}' test_file.bin --url=my_public_link_send_shared_inbox
 packages shared_inboxes list
+packages shared_inboxes show %name:my_shared_inbox_name
 remind --username=my_user_email
 servers
+tier_restrictions
 user pref modify @json:'{"default_language":"en-us"}'
 user pref show
 user profile modify @json:'{"name":"dummy change"}'
@@ -5254,11 +5365,18 @@ cluster show 1f412ae7-869a-445c-9c05-02ad16813be2
 ## Plugin: `server`: IBM Aspera High Speed Transfer Server (SSH)
 
 The `server` plugin is used for operations on Aspera HSTS using SSH authentication.
-It is the legacy way of accessing an Aspera Server, often used for server to server transfers.
+It is the original way of accessing an Aspera Server, often used for server to server transfers.
 An SSH session is established, authenticated with either a password or an SSH private key,
 then commands `ascp` (for transfers) and `ascmd` (for file operations) are executed.
 
-> **Note:** The URL to be provided is usually: `ssh://_server_address_:33001`
+The URL to be provided with option `url` shall be like `ssh://_server_address_:33001`, then option `username` is used to specify the transfer user, and finally either option `password` or `ssh_keys` (with one or several paths) for the authentication.
+
+Typically:
+
+```console
+`ascli` server --url=ssh://hsts.example.com:33001 --username=john --password=_something_here_ ...
+`ascli` server --url=ssh://hsts.example.com:33001 --username=john --ssh-keys=~/.ssh/id_rsa ...
+```
 
 ### Server sample commands
 
@@ -5308,7 +5426,8 @@ If SSH is the session protocol (by default i.e. not WSS), then following session
 
 If `username` is not provided then the default transfer user `xfer` is used.
 
-If no SSH password or key is provided and a transfer token is provided in transfer spec (option `ts`), then standard SSH bypass keys are used.
+If neither SSH password nor key is provided and a transfer token is provided in transfer spec (option `ts`), then standard SSH bypass key(s) is used.
+
 Example:
 
 ```bash
@@ -5427,11 +5546,13 @@ Native API parameters can be placed in option `query`.
 
 Special parameters can be placed in option `query` for "gen3" browse:
 
-| Parameter | Description |
-|-----------|-------------|
+| Parameter   | Description |
+|-------------|-------------|
 | `recursive` | Recursively list files |
-| `max` | Maximum number of files to list |
-| `self` | Offset in the list |
+| `max`       | Maximum number of files to list |
+| `self`      | Offset in the list |
+
+Option `node_cache` can be set to `no` to avoid use of folder cache (Redis) and force actual read of file system.
 
 ### Operation `find` on **gen4/access key**
 
@@ -5508,6 +5629,24 @@ ascli node access_keys do self find / @ruby:'->(f){f["type"].eql?("file") and (D
 
 > **Note:** The pipe `|` character on the last line.
 
+### Listing transfer events
+
+When a transfer is run, its information is stored (typicall, 1 day) in the HSTS database (Redis).
+This information can be retrieved with command: `transfer list`.
+
+If the number of transfer is too large, then the list will be retrieved in several API calls.
+
+In addition, it is possible to list "only new information" using option `once_only`.
+
+```bash
+ascli node transfer list --once-only=yes
+```
+
+The `iteratin_token` that keeps memory of latest event is stored in the persistance repository of `ascli`.
+To reset it, add option: `--query=@json:'{"reset": true}'`.
+To list only a number of events, use the `max` parameter in query.
+Other parameters are directly transmitted to the underlying API (`GET /ops/transfers`).
+
 ### Central
 
 The central subcommand uses the **reliable query** API (session and file).
@@ -5562,8 +5701,8 @@ Follow the Aspera Transfer Server configuration to activate this feature.
 
 The following command lists one file that requires validation, and assign it to the unique validator identifier provided:
 
-```bash
-ascli node central file list --validator=ascli --data=@json:'{"file_transfer_filter":{"max_result":1}}'
+```json
+ascli node central file list --validator=ascli @json:'{"file_transfer_filter":{"max_result":1}}'
 ```
 
 ```output
@@ -5576,8 +5715,8 @@ ascli node central file list --validator=ascli --data=@json:'{"file_transfer_fil
 
 To update the status of the file, use the following command:
 
-```bash
-ascli node central file update --validator=ascli --data=@json:'{"files":[{"session_uuid": "1a74444c-...","file_id": "084fb181-...","status": "completed"}]}'
+```json
+ascli node central file update --validator=ascli @json:'{"files":[{"session_uuid": "1a74444c-...","file_id": "084fb181-...","status": "completed"}]}'
 ```
 
 ```output
@@ -5651,11 +5790,11 @@ ascli node info --field=@ruby:'/^access_key_configuration_capabilities.*/'
 
 Bearer tokens are part of the **gen4/access key** API.
 It follows the model of OAuth 2.
-For example they are used in Aspera on Cloud.
+For example, they are used in Aspera on Cloud.
 This is also available for developers for any application integrating Aspera.
 In this API, files, users and groups are identified by an id (a String, e.g. `"125"`, not necessarily numerical).
 
-Bearer tokens are typically generated by the authentication application, and then recognized by the node API.
+Bearer tokens are typically generated by the authentication application and then recognized by the node API.
 A bearer token is authorized on the node by creating `permissions` on a **folder**.
 
 Bearer tokens can be generated using command `bearer_token`: it takes two arguments:
@@ -5681,6 +5820,11 @@ Bearer tokens can be generated using command `bearer_token`: it takes two argume
 
 #### Bearer token: Environment
 
+An access key shall be created to grant access for transfers to its storage.
+The access_key and its secrets represent an administrative access to the storage as it has access rights to the whole storage of the access key.
+
+They way to create access keys depend slightly on the type of HSTS:
+
 - If a self-managed Aspera node is used, then a **node user admin** must be created:
   It has no `docroot` but has at least one file restriction (for testing, one can use `*` to accept creation of an access key with any storage root path).
   Refer to the Aspera HSTS documentation.
@@ -5689,12 +5833,10 @@ Bearer tokens can be generated using command `bearer_token`: it takes two argume
 
 - If Aspera on Cloud or ATS is used, then the SaaS API for access key creation is used.
 
-- An access key shall be created to grant access for transfers to its storage.
-  The access_key and its secrets represent an administrative access to the storage as it has access rights to the whole storage of the access key.
-
 #### Bearer token: Preparation
 
 Let's assume that the access key was created, and a default configuration is set to use this **access key**.
+Using `ascli`, an access key can be created using the `access_key create` on the node (using main node credentials) or ATS.
 
 - Create a private key (organization key) that will be used to sign bearer tokens:
 
@@ -5714,6 +5856,7 @@ Let's assume that the access key was created, and a default configuration is set
 
   > **Note:** Either the public or private key can be provided, and only the public key is used.
   > This will enable to check the signature of the bearer token.
+  > Above command is executed with access key credentials.
 
   Alternatively, use the following equivalent command, as `ascli` kindly extracts the public key with extension `.pub`:
 
@@ -5775,18 +5918,18 @@ ascli node -N --url=... --password="Bearer $(cat bearer.txt)" --root-id=$my_fold
 access_key create @json:'{"id":"my_username","secret":"my_password_here","storage":{"type":"local","path":"/"}}'
 access_key delete my_username
 access_key do my_ak_name browse /
-access_key do my_ak_name delete /folder2
-access_key do my_ak_name delete testfile1
-access_key do my_ak_name download testfile1 --to-folder=.
+access_key do my_ak_name delete /test_nd_ak2
+access_key do my_ak_name delete test_nd_ak3
+access_key do my_ak_name download test_nd_ak3 --to-folder=.
 access_key do my_ak_name find my_test_folder
 access_key do my_ak_name find my_test_folder @ruby:'->(f){f["name"].end_with?(".jpg")}'
 access_key do my_ak_name find my_test_folder exec:'f["name"].end_with?(".jpg")'
-access_key do my_ak_name mkdir /folder1
+access_key do my_ak_name mkdir /tst_nd_ak
 access_key do my_ak_name node_info /
-access_key do my_ak_name rename /folder1 folder2
+access_key do my_ak_name rename /tst_nd_ak test_nd_ak2
 access_key do my_ak_name show %id:1
-access_key do my_ak_name show /testfile1
-access_key do my_ak_name upload 'faux:///testfile1?1k' --default_ports=no
+access_key do my_ak_name show /test_nd_ak3
+access_key do my_ak_name upload 'faux:///test_nd_ak3?100k' --default-ports=no
 access_key do self permission %id:root_id create @json:'{"access_type":"user","access_id":"666"}'
 access_key do self show / --fields=id --output=root_id
 access_key list
@@ -5804,7 +5947,7 @@ basic_token
 bearer_token @file:my_private_key @json:'{"user_id":"666"}' --output=bearer_666
 browse / --log-level=trace2
 central file list
-central file modify --validator=1 --query=@json:'{"files":[]}'
+central file modify --validator=1 @json:'{"files":[]}'
 central session list
 delete @list:,my_upload_folder/a_folder,my_upload_folder/tdlink,my_upload_folder/a_file
 delete my_upload_folder/test_file.bin
@@ -5839,7 +5982,9 @@ sync admin status --sync-info=@json:'{"name":"my_node_sync2","reset":true,"direc
 sync admin status --sync-info=@json:'{"sessions":[{"name":"my_node_sync1","direction":"pull","local_dir":"/data/local_sync","remote_dir":"/aspera-test-dir-tiny","reset":true}]}'
 sync start --sync-info=@json:'{"name":"my_node_sync1","reset":true,"quiet":false,"direction":"pull","local":{"path":"/data/local_sync"},"remote":{"path":"/aspera-test-dir-tiny"}}'
 sync start --sync-info=@json:'{"name":"my_node_sync2","reset":true,"direction":"pull","local":{"path":"/data/local_sync"},"remote":{"path":"/aspera-test-dir-tiny"}}'
+transfer list --once-only=yes
 transfer list --query=@json:'{"active_only":true}'
+transfer list --query=@json:'{"reset":true}' --once-only=yes
 transfer sessions
 transport
 upload --to-folder=my_upload_folder --sources=@ts --ts=@json:'{"paths":[{"source":"/aspera-test-dir-small/10MB.2"}],"precalculate_job_size":true}' --transfer=node --transfer-info=@json:'{"url":"https://node.example.com/path@","username":"my_username","password":"my_password_here"}'
@@ -6012,7 +6157,7 @@ admin event web
 admin jobs list --query=@json:'{"job_type":"email","status":"failed"}' --fields=id,error_desc
 admin metadata_profiles list
 admin node list
-admin oauth_clients list
+admin oauth_clients list --query=@json:'[["client_types[]","public"]]'
 admin registrations list
 admin saml_configs list
 admin shared_inboxes invite %name:my_shared_box_name johnny@example.com
@@ -6205,26 +6350,26 @@ To keep the content encrypted, use option: `--ts=@json:'{"content_protection":nu
 If you are a regular user, to list work groups you belong to:
 
 ```bash
-ascli faspex5 admin res workgroup list
+ascli faspex5 admin workgroup list
 ```
 
 If you are admin or manager, add option: `--query=@json:'{"all":true}'`, this will list items you manage, even if you do not belong to them.
 Example:
 
 ```bash
-ascli faspex5 admin res shared list --query=@json:'{"all":true}' --fields=id,name
+ascli faspex5 admin 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:the shared inbox' john@example.com
+ascli faspex5 admin shared_inboxes invite '%name:the shared inbox' john@example.com
 ```
 
 It is equivalent to:
 
 ```bash
-ascli faspex5 admin res shared_inboxes invite '%name:the shared inbox' @json:'{"email_address":"john@example.com"}'
+ascli faspex5 admin shared_inboxes invite '%name:the shared inbox' @json:'{"email_address":"john@example.com"}'
 ```
 
 Other payload parameters are possible for `invite` in this last `Hash` **Command Parameter**:
@@ -6236,13 +6381,13 @@ Other payload parameters are possible for `invite` in this last `Hash` **Command
 ### Faspex 5: Create Metadata profile
 
 ```bash
-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"]}]}'
+ascli faspex5 admin 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"]}]}'
 ```
 
 ### Faspex 5: Create a Shared inbox with specific metadata profile
 
 ```bash
-ascli faspex5 admin res shared create @json:'{"name":"the shared inbox","metadata_profile_id":1}'
+ascli faspex5 admin shared create @json:'{"name":"the shared inbox","metadata_profile_id":1}'
 ```
 
 ### Faspex 5: List content in Shared folder and send package from remote source
@@ -6289,6 +6434,10 @@ There are two types of invitations of package submission: public or private.
 
 Public invitations are for external users, provide just the email address.
 
+```bash
+ascli faspex5 invitations create @json:'{"email_address":"john@example.com"}' --fields=access_url
+```
+
 Private invitations are for internal users, provide the user or shared inbox identifier through field `recipient_name`.
 
 ### Faspex 5: Cleanup packages
@@ -6369,7 +6518,30 @@ Then, the postprocessing script executed will be `script1.sh`.
 
 Environment variables at set to the values provided by the web hook which are the same as Faspex 4 postprocessing.
 
-### Faspex 5: Missing commands
+### Faspex 5: Faspex 4 Gateway
+
+> **Note:** This is not a feature for production. It's provided for testing only.
+
+For legacy faspex client applications that use the `send` API (only) of Faspex v4, the command `gateway` provides the capability to present an API compatible with Faspex 4, and it will call the Faspex 5 API.
+
+It takes a single argument which is the url at which the gateway will be located (locally):
+
+```bash
+ascli faspex5 gateway https://localhost:12345/aspera/faspex
+```
+
+There are many limitations:
+
+- It's only to emulate the Faspex 4 `send` API (send package)
+- No support for remote sources, only for an actual file transfer by the client
+- The client must use the transfer spec returned by the API (not faspe: URL)
+- tags returned in transfer spec must be used in transfer
+- only a single authentication is possible (per gateway) on Faspex5
+- no authentication of F4 side (ignored)
+
+Behavior: The API client calls the Faspex 4 API on the gateway, then the gateway transforms this into a Faspex5 API call, which returns a transfer spec, which is returned to the calling client. The calling client uses this to start a transfer to HSTS which is actually managed by Faspex 5.
+
+### Faspex 5: Get Bearer token to use API
 
 If a command is missing, then it is still possible to execute command by calling directly the API on the command line using `curl`:
 
@@ -6559,7 +6731,7 @@ package receive f4_prs2 --to-folder=. --box=sent
 package send --delivery-info=@json:'{"title":"$(notdir test) PACKAGE_TITLE_BASE","recipients":["*my_dbx"]}' test_file.bin
 package send --delivery-info=@json:'{"title":"$(notdir test) PACKAGE_TITLE_BASE","recipients":["*my_wkg"]}' test_file.bin
 package send --delivery-info=@json:'{"title":"$(notdir test) PACKAGE_TITLE_BASE","recipients":["my_email_internal","my_username"]}' test_file.bin
-package send --delivery-info=@json:'{"title":"$(notdir test) PACKAGE_TITLE_BASE","recipients":["my_email_internal"]}' --remote_source=%name:my_src sample_source.txt
+package send --delivery-info=@json:'{"title":"$(notdir test) PACKAGE_TITLE_BASE","recipients":["my_email_internal"]}' --remote-source=%name:my_src sample_source.txt
 package send --link=https://app.example.com/send_to_dropbox_path --delivery-info=@json:'{"title":"$(notdir test) PACKAGE_TITLE_BASE"}' test_file.bin
 package send --link=https://app.example.com/send_to_user_path --delivery-info=@json:'{"title":"$(notdir test) PACKAGE_TITLE_BASE"}' test_file.bin
 source info %name:my_src --storage=@preset:faspex4_storage
@@ -6603,12 +6775,12 @@ To figure out the entities payload, for example for creation, refer to the API d
 admin group all list
 admin node list
 admin share list --fields=DEF,-status,status_message
-admin share user_permissions 1 list
+admin share user_permissions 3 list
 admin user all app_authorizations 1 modify @json:'{"app_login":true}'
 admin user all app_authorizations 1 show
 admin user all list
 admin user all share_permissions 1 list
-admin user all share_permissions 1 show 1
+admin user all share_permissions 1 show 3
 admin user ldap add the_name
 admin user local list
 admin user saml import @json:'{"id":"the_id","name_id":"the_name"}'
@@ -6616,9 +6788,10 @@ files browse /
 files delete my_share1/new_folder
 files delete my_share1/test_file.bin
 files download --to-folder=. my_share1/test_file.bin
-files download --to-folder=. my_share1/test_file.bin --transfer=httpgw --transfer-info=@json:'{"url":"https://tst.example.com/path@"}'
+files download --to-folder=. my_share1/test_file.bin my_share1/test_file.bin --transfer=httpgw --transfer-info=@json:'{"url":"https://tst.example.com/path@"}'
 files mkdir my_share1/new_folder
 files upload --to-folder=https://shares.share1 'faux:///testfile?1m' --transfer=httpgw --transfer-info=@json:'{"url":"my_example.com/path@","synchronous":true,"api_version":"v1","upload_chunk_size":100000}'
+files upload --to-folder=https://shares.share1 sendfolder --transfer=httpgw --transfer-info=@json:'{"url":"my_example.com/path@","synchronous":true,"api_version":"v1","upload_chunk_size":100000}'
 files upload --to-folder=my_share1 test_file.bin
 files upload --to-folder=my_share1 test_file.bin --transfer=httpgw --transfer-info=@json:'{"url":"https://tst.example.com/path@"}'
 health
@@ -6684,7 +6857,7 @@ ascli config preset update mycos --bucket=mybucket --endpoint=https://s3.us-east
 ascli config preset set default cos mycos
 ```
 
-Then, jump to the transfer example.
+Then, jump to the [transfer example](#operations-transfers).
 
 ### Using service credential file
 
@@ -6759,14 +6932,13 @@ ascli cos node info
 ascli cos node upload 'faux:///sample1G?1g'
 ```
 
-> **Note:** A dummy file `sample1G` of size 2GB is generated using the `faux` PVCL (man `ascp` and section above), but you can, of course, send a real file by specifying a real file instead.
+> **Note:** A dummy file `sample1G` of size 2GB is generated using the `faux` PVCL (man `ascp` and section above), but you can, of course, send a real file by specifying a real file path instead.
 
 ### Cos sample commands
 
 > **Note:** Add `ascli cos` in front of the commands:
 
 ```bash
-node access_key show self
 node download test_file.bin --to-folder=.
 node info --bucket=my_bucket --endpoint=my_endpoint --apikey=my_api_key --crn=my_resource_instance_id
 node info --bucket=my_bucket --region=my_region --service-credentials=@json:@file:my_cos_svc_cred
@@ -6782,6 +6954,7 @@ node upload test_file.bin
 
 ```bash
 health
+info
 ```
 
 ## Plugin: `faspio`: Faspio Gateway
@@ -6806,7 +6979,8 @@ Retrieve information on subscription.
 > **Note:** Add `ascli alee` in front of the commands:
 
 ```bash
-health
+entitlement
+health -N
 ```
 
 ## Plugin: `preview`: Preview generator for AoC
@@ -7369,10 +7543,12 @@ A default e-mail template is used, but it can be overridden with option `notify_
 
 The environment provided contains the following additional variables:
 
-- `subject`
-- `body`
-- `global_transfer_status`
-- `ts`
+- `subject` : a default subject including transfer status
+- `status` : global status of transfer
+- `ts` : the [**transfer-spec**](#transfer-specification) used for the transfer
+- `from_email` : email of sender (from `smtp` configuration)
+- `from_name` : name of sender (from `smtp` configuration)
+- `to` : recipient of the email (from `notify_to`)
 
 Example of template:
 
@@ -7381,7 +7557,7 @@ From: <%=from_name%> <<%=from_email%>>
 To: <<%=to%>>
 Subject: <%=subject%>
 
-Transfer is: <%=global_transfer_status%>
+Transfer is: <%=status%>
 ```
 
 ## Tool: `asession`
@@ -7465,21 +7641,25 @@ asession -h
 USAGE
     asession
     asession -h|--help
-    asession <session spec extended value>
+    asession [<session spec extended value>]
     
     If no argument is provided, default will be used: @json:@stdin
     -h, --help display this message
-    <session spec extended value> a dictionary value (Hash)
+    <session spec extended value> a dictionary (Hash)
     The value can be either:
        the JSON description itself, e.g. @json:'{"xx":"yy",...}'
        @json:@stdin, if the JSON is provided from stdin
        @json:@file:<path>, if the JSON is provided from a file
-    Parameter spec is mandatory, it contains the transfer spec
+    The following keys are recognized in session spec:
+       spec : mandatory, contains the transfer spec
+       loglevel : modify log level (to stderr)
+       agent : modify transfer agent parameters, e.g. ascp_args
+       file_list_folder : location of temporary files
+       sdk : location of SDK (ascp)
     Asynchronous commands can be provided on STDIN, examples:
        {"type":"START","source":"/aspera-test-dir-tiny/200KB.2"}
        {"type":"START","source":"xx","destination":"yy"}
        {"type":"DONE"}
-Note: debug information can be placed on STDERR, using the "loglevel" parameter in session spec (debug=0)
 EXAMPLES
     asession @json:'{"spec":{"remote_host":"demo.asperasoft.com","remote_user":"asperaweb","ssh_port":33001,"remote_password":"demoaspera","direction":"receive","destination_root":"./test.dir","paths":[{"source":"/aspera-test-dir-tiny/200KB.1"}]}}'
     echo '{"spec":{"remote_host":...}}'|asession @json:@stdin