aspera-cli 4.20.0 → 4.21.0

data/README.md

@@ -5,7 +5,7 @@ Do not edit this README.md, edit docs/README.erb.md, for details, read docs/READ
 markdownlint-disable MD033 MD003 MD053
 cspell:ignore Serban Antipolis
 PANDOC_META_BEGIN
-subtitle: "ascli 4.20.0"
+subtitle: "ascli 4.21.0"
 PANDOC_META_END
 -->
 
@@ -15,7 +15,7 @@ PANDOC_META_END
 
 ## Introduction
 
-Version : 4.20.0
+Version : 4.21.0
 
 Laurent/2016-2025
 
@@ -27,9 +27,9 @@ Ruby Gem: [https://rubygems.org/gems/aspera-cli](https://rubygems.org/gems/asper
 
 Ruby Doc: [https://www.rubydoc.info/gems/aspera-cli](https://www.rubydoc.info/gems/aspera-cli)
 
-Minimum required Ruby version: >= 2.6.
+Minimum required Ruby version: >= 2.7.
 
-> **Deprecation notice**: the minimum Ruby version will be 3.0 in a future version.
+> **Deprecation notice**: the minimum Ruby version will be 3.1 in a future version.
 
 [Aspera APIs on IBM developer](https://developer.ibm.com/?size=30&q=aspera&DWContentType[0]=APIs&sort=title_asc)
 [Link 2](https://developer.ibm.com/apis/catalog/?search=aspera)
@@ -112,7 +112,7 @@ Once the gem is installed, `ascli` shall be accessible:
 
 ```console
 $ ascli --version
-4.20.0
+4.21.0
 ```
 
 ### First use
@@ -211,9 +211,9 @@ The direct installation is recommended and consists in installing:
 - [aspera-cli](#ruby-gem-aspera-cli) <!-- markdownlint-disable-line -->
 - [Aspera SDK (`ascp`)](#fasp-protocol-ascp)
 
-Ruby version: >= 2.6.
+Ruby version: >= 2.7.
 
-> **Deprecation notice**: the minimum Ruby version will be 3.0 in a future version.
+> **Deprecation notice**: the minimum Ruby version will be 3.1 in a future version.
 
 The following sections provide information on the various installation methods.
 
@@ -228,9 +228,9 @@ Use this method to install on the native host (e.g. your Windows, macOS or Linux
 
 A Ruby interpreter is required to run `ascli`.
 
-Required Ruby version: >= 2.6.
+Required Ruby version: >= 2.7.
 
-> **Deprecation notice**: the minimum Ruby version will be 3.0 in a future version.
+> **Deprecation notice**: the minimum Ruby version will be 3.1 in a future version.
 
 **Ruby can be installed using any method** : rpm, yum, dnf, rvm, brew, Windows installer, ... .
 
@@ -322,15 +322,17 @@ rubyinstaller-devkit-3.2.2-1-x64.exe /silent /currentuser /noicons /dir=C:\asper
 
 #### macOS: `brew`
 
-**macOS** come with Ruby.
-Nevertheless, [Apple has deprecated it](https://developer.apple.com/documentation/macos-release-notes/macos-catalina-10_15-release-notes), and it will be removed in the future, so better not to rely on it.
+**macOS** comes with Ruby.
+Nevertheless, it is an old unsupported version and [Apple has deprecated it](https://developer.apple.com/documentation/macos-release-notes/macos-catalina-10_15-release-notes), and it will be removed in the future, so better not to rely on it.
 
-The recommended way is to either user `RVM` or use [Homebrew](https://brew.sh/).
+The recommended way is to either use [Homebrew](https://brew.sh/) or [RVM](https://rvm.io/).
 
 ```bash
 brew install ruby
 ```
 
+This installs a recent ruby suitable for `ascli`.
+
 #### Linux: Package
 
 If your Linux distribution provides a standard Ruby package, you can use it provided that the version supported.
@@ -738,7 +740,7 @@ ascli -v
 ```
 
 ```text
-4.20.0
+4.21.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.
@@ -1501,16 +1503,33 @@ To redirect results to a file, use option `output`.
 
 Depending on action, the output will contain:
 
-- `single_object` : displayed as a 2 dimensional table: one line per attribute, first column is attribute name, and second is attribute value. Nested hashes are collapsed.
-- `object_list` : displayed as a 2 dimensional table: one line per item, one column per attribute.
-- `value_list` : a table with one column.
-- `empty` : nothing
-- `status` : a message
-- `other_struct` : a complex structure that cannot be displayed as an array
+| Result Type     | Description |
+|-----------------|-------------------|
+| `single_object` | displayed as a 2 dimensional table: one line per field, first column is field name, and second is field value. Nested hashes are collapsed. |
+| `object_list`   | displayed as a 2 dimensional table: one line per item, one column per field. |
+| `value_list`    | a table with one column. |
+| `empty`         | nothing |
+| `status`        | a message |
+| `other_struct`  | a complex structure that cannot be displayed as an array |
+
+#### Option: `format`
+
+The style of output can be set using the `format` option:
+
+| `format` | Output formatting |
+|----------|-------------------|
+| `table`  | Text table (default) |
+| `text`   | Value as `String` |
+| `ruby`   | Ruby code |
+| `json`   | JSON code |
+| `jsonpp` | JSON pretty printed |
+| `yaml`   | YAML |
+| `csv`    | Comma Separated Values |
+| `image`  | Image URL or Image data |
 
-#### Format of output
+By default, result of type `single_object` and `object_list` are displayed using format `table`.
 
-By default, result of type single_object and object_list are displayed using format `table`.
+#### Option: `table_style`
 
 The table style can be customized with option: `table_style` which expects a `Hash`, options are the ones described in gem [`terminal-table`](https://github.com/tj/terminal-table).
 
@@ -1522,28 +1541,64 @@ ascli config preset over --table-style=@ruby:'{border: :unicode_thick_edge}'
 
 > **Note:** Other border styles exist, not limited to: `:unicode`, `:unicode_round`.
 
-In a table format, when displaying **Objects** (single, or list), by default, sub object are flattened (option `flat_hash`).
-For example, object `{"user":{"id":1,"name":"toto"}}` will have attributes: `user.id` and `user.name`.
-Setting option `flat_hash` to `false` will only display one field: `user` and value is the sub `Hash`.
-When in flatten mode, it is possible to filter fields using the option `fields` using the compound field name using `.` (dot) as separator.
+#### Option: `flat_hash`: `.`-join keys
+
+This optin controls how object fields are displayed for complex objects.
+
+Effective only when `format` is `table` to display `single_object` or `object_list`.
+
+If value is `no`, then object's `field` names are only the first level keys of the `Hash` result and values that are `Hash` are displayed as such in Ruby syntax.
+
+If value is `yes` (default), then object are flattened, i.e. deep `Hash` are transformed into 1-level Hash, where keys are `.`-junction of deep keys.
+In this case, it is possible to filter fields using the option `fields` using the compound field name using `.` (dot) as separator.
+
+Example: Result of command is a list of objects with a single object:
+
+```console
+$ ascli conf echo @json:'[{"user":{"id":1,"name":"toto"},"project":"blah"}]'
+╭─────────┬───────────┬─────────╮
+│ user.id │ user.name │ project │
+╞═════════╪═══════════╪═════════╡
+│ 1       │ toto      │ blah    │
+╰─────────┴───────────┴─────────╯
+
+$ ascli conf echo @json:'[{"user":{"id":1,"name":"toto"},"project":"blah"}]' --flat-hash=no
+╭───────────────────────────┬─────────╮
+│ user                      │ project │
+╞═══════════════════════════╪═════════╡
+│ {"id"=>1, "name"=>"toto"} │ blah    │
+╰───────────────────────────┴─────────╯
+```
+
+#### Option: `multi_single`
+
+This option controls if object fields are displayed as columns or lines.
+
+If value is `no` (default), `object_list` are displayed with one object per line, with fields as columns (see above).
+`single_object` are displayed with one field per line (and columns are: `field`, `value`).
 
-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.
+If an `object_list` has a single element, it is possible to have `ascli` display the object as a single object (one field per line instead of columns) with option: `multi_single` set to `single`.
 
-The style of output can be set using the `format` option, supporting:
+This parameter can be set as a global default with:
 
-- `table` : Text table (default)
-- `text` : Value as String
-- `ruby` : Ruby code
-- `json` : JSON code
-- `jsonpp` : JSON pretty printed
-- `yaml` : YAML
-- `csv` : Comma Separated Values
-- `image` : Image URL or Image data
+```bash
+ascli config preset set GLOBAL multi_single single
+```
+
+In case multiple objects are returned, it is possible to display one table per object with option `multi_single` set to `yes`.
+
+```console
+$ ascli conf echo @json:'[{"user":{"id":1,"name":"toto"},"project":"blash"}]' --multi-single=yes
+╭───────────┬───────╮
+│ field     │ value │
+╞═══════════╪═══════╡
+│ user.id   │ 1     │
+│ user.name │ toto  │
+│ project   │ blash │
+╰───────────┴───────╯
+```
 
-#### Verbosity of output
+#### Option: `display`: Verbosity of output
 
 Output messages are categorized in 3 types:
 
@@ -1557,13 +1612,17 @@ The option `display` controls the level of output:
 - `data` display `data` and `error` messages
 - `error` display only error messages.
 
-By default, secrets are removed from output: option `show_secrets` defaults to `no`, unless `display` is `data`, to allows piping results.
-To hide secrets from output, set option `show_secrets` to `no`.
+#### Option: `show_secrets`: Hide or show secrets in results
+
+If value is `no` (default), then secrets are redacted from command results.
+
+If value is `yes`, then secrets shown in clear in results.
 
-#### Option: `fields`: Selection of output object properties
+If `display` is `data`, secrets are included to allows piping results.
 
-By default, a `table` output format will display one line per entry, and columns for each fields (attributes, properties).
-Depending on the command, columns may include by default all fields, or only some selected fields.
+#### Option: `fields`: Selection of output object fields
+
+Depending on the command, results may include by default all fields, or only some selected fields.
 It is possible to define specific columns to be displayed, by setting the `fields` option.
 
 The `fields` option is a list that can be either a comma separated list or an extended value `Array`.
@@ -1572,8 +1631,8 @@ Individual elements of the list can be:
 
 - **property** : add property to the current list
 - `-`**property** : remove property from the current list
-- `DEF` : default list of properties (that's the default, when not set)
-- `ALL` : all properties
+- `DEF` : default list of fields (that's the default, when not set)
+- `ALL` : all fields
 - A Ruby `RegEx` : using `@ruby:'/.../'`, or `@re:...` add those matching to the list
 
 Examples:
@@ -1581,13 +1640,13 @@ Examples:
 - `a,b,c` : the list of attributes specified as a comma separated list (overrides the all default)
 - `@json:'["a","b","c"]'` : `Array` extended value: same as above
 - `b,DEF,-a` : default property list, remove `a` and add `b` in first position
-- `@ruby:'/^server/'` : Display all properties whose name begin with `server`
+- `@ruby:'/^server/'` : Display all fields whose name begin with `server`
 
 #### Option: `select`
 
 Table output (`object_list`) can be filtered using option `select`.
 This option is either a `Hash` or `Proc`.
-The `Proc` takes as argument a line (`Hash`) in the table and is a Ruby lambda expression that returns `true` or `false`.
+The `Proc` takes as argument a line (`Hash`) in the table and is a Ruby lambda expression that shall returns `true` to select or `false` to remove an entry.
 
 Example:
 
@@ -1616,19 +1675,26 @@ 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 user show 1234` where `1234` is the user's identifier.
+Syntax: `%<field>:<value>`
 
-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 user show %name:john` where `john` is the user name.
+When a command is executed on a single entity, the entity is identified by a unique identifier that follows the command.
+For example, in the following command, `1234` is the user's identifier:
 
-Syntax: `%<field>:<value>`
+```bash
+ascli aoc admin user show 1234
+```
 
-> **Note:** The legacy option `id` is deprecated: `--id=1234` (options have a single value and thus do not provide the possibility to identify sub-entities)
+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**.
+For example, if the name of the user is `john` and a field for this entity named `name` has a value `john`:
+
+```bash
+ascli aoc admin user show %name:john
+```
 
 ### Extended Value Syntax
 
-Most options and arguments are specified by a simple string (e.g. username or url).
+Most options and arguments are specified by a simple string (e.g. `username` or `url`).
 Sometime it is convenient to read a value from a file: for example read the PEM value of a private key, or a list of files.
 Some options expect a more complex value such as `Hash` or `Array`.
 
@@ -1644,31 +1710,31 @@ Decoders act like a function with its parameter on right hand side and are recog
 
 The following decoders are supported:
 
-| Decoder  | Parameter| Returns | Description |
-|----------|----------|---------|-------------|
-| `base64` | String   | String  | Decode a base64 encoded string |
-| `csvt`   | String   | Array   | Decode a titled CSV value |
-| `env`    | String   | String  | Read from a named env var name, e.g. `--password=@env:MYPASSVAR` |
-| `file`   | String   | String  | Read value from specified file (prefix `~/` is replaced with the users home folder), e.g. `--key=@file:~/.ssh/mykey` |
-| `json`   | String   | Any     | Decode JSON values (convenient to provide complex structures) |
-| `lines`  | String   | Array   | Split a string in multiple lines and return an array |
-| `list`   | String   | Array   | Split a string in multiple items taking first character as separator and return an array |
-| `none`   | None     | Nil     | A null value |
-| `path`   | String   | String  | Performs path expansion on specified path (prefix `~/` is replaced with the users home folder), e.g. `--config-file=@path:~/sample_config.yml` |
-| `preset` | String   | Hash    | Get whole option preset value by name. Sub-values can also be used using `.` as separator. e.g. `foo.bar` is `conf[foo][bar]` |
-| `extend` | String   | String  | Evaluates embedded extended value syntax in string |
-| `re`     | String   | Regexp  | Ruby Regular Expression (short for `@ruby:/.../`) |
-| `ruby`   | String   | Any     | Execute specified Ruby code |
-| `secret` | None     | String  | Ask password interactively (hides input) |
-| `stdin`  | None     | String  | Read from stdin in text mode (no value on right) |
-| `stdbin` | None     | String  | Read from stdin in binary mode (no value on right) |
-| `uri`    | String   | String  | Read value from specified URL, e.g. `--fpac=@uri:http://serv/f.pac` |
-| `val`    | String   | String  | Prevent decoders on the right to be decoded. e.g. `--key=@val:@file:foo` sets the option `key` to value `@file:foo`. |
-| `yaml`   | String   | Any     | Decode YAML |
-| `zlib`   | String   | String  | Un-compress zlib data |
+| Decoder  | Parameter| Returns  | Description |
+|----------|----------|----------|-------------|
+| `base64` | `String` | `String` | Decode a base64 encoded string |
+| `csvt`   | `String` | `Array`  | Decode a titled CSV value |
+| `env`    | `String` | `String` | Read from a named env var name, e.g. `--password=@env:MYPASSVAR` |
+| `file`   | `String` | `String` | Read value from specified file (prefix `~/` is replaced with the users home folder), e.g. `--key=@file:~/.ssh/mykey` |
+| `json`   | `String` | Any      | Decode JSON values (convenient to provide complex structures) |
+| `lines`  | `String` | `Array`  | Split a string in multiple lines and return an array |
+| `list`   | `String` | `Array`  | Split a string in multiple items taking first character as separator and return an array |
+| `none`   | None     | Nil      | A null value |
+| `path`   | `String` | `String` | Performs path expansion on specified path (prefix `~/` is replaced with the users home folder), e.g. `--config-file=@path:~/sample_config.yml` |
+| `preset` | `String` | `Hash`   | Get whole option preset value by name. Sub-values can also be used using `.` as separator. e.g. `foo.bar` is `conf[foo][bar]` |
+| `extend` | `String` | `String` | Evaluates embedded extended value syntax in string |
+| `re`     | `String` | `Regexp` | Ruby Regular Expression (short for `@ruby:/.../`) |
+| `ruby`   | `String` | Any      | Execute specified Ruby code |
+| `secret` | None     | `String` | Ask password interactively (hides input) |
+| `stdin`  | None     | `String` | Read from stdin in text mode (no value on right) |
+| `stdbin` | None     | `String` | Read from stdin in binary mode (no value on right) |
+| `uri`    | `String` | `String` | Read value from specified URL, e.g. `--fpac=@uri:http://serv/f.pac` |
+| `val`    | `String` | `String` | Prevent decoders on the right to be decoded. e.g. `--key=@val:@file:foo` sets the option `key` to value `@file:foo`. |
+| `yaml`   | `String` | Any      | Decode YAML |
+| `zlib`   | `String` | `String` | Un-compress zlib data |
 
 > **Note:** A few commands support a value of type `Proc` (lambda expression).
-For example, the **Extended Value** `@ruby:'->(i){i["attr"]}'` is a lambda expression that returns the value of attribute `attr` of the `Hash` `i`.
+For example, the **Extended Value** `@ruby:'->(i){i["attr"]}'` is a lambda expression that returns the value for key `attr` of the `Hash` `i`.
 
 To display the result of an extended value, use the `config echo` command.
 
@@ -1726,14 +1792,14 @@ ascli config echo @json:@extend:'{"hello":true,"version":"@preset:config.version
 
 ```output
 +---------+-----------+
-| key     | value     |
+| field   | value     |
 +---------+-----------+
 | hello   | true      |
 | version | 4.14.0    |
 +---------+-----------+
 ```
 
-Example: Create a `Hash` from YAML provided as **heredoc**:
+Example: Create a `Hash` from YAML provided as shell **heredoc**:
 
 ```bash
 ascli config echo @yaml:@stdin: --format=json<<EOF
@@ -1753,7 +1819,7 @@ EOF
 
 ### Configuration and Persistency Folder
 
-`ascli` configuration and other runtime files (token cache, file lists, persistency files, SDK) are stored by default in `[User's home folder]/.aspera/ascli`.
+`ascli` configuration and persistency files (token cache, file lists, persistency files) are stored by default in `[User's home folder]/.aspera/ascli`.
 
 > **Note:** `[User's home folder]` is found using Ruby's `Dir.home` (`rb_w32_home_dir`).
 It uses the `HOME` env var primarily, and on MS Windows it also looks at `%HOMEDRIVE%%HOMEPATH%` and `%USERPROFILE%`.
@@ -1782,9 +1848,9 @@ ascli config folder
 C:\Users\Kenji\.aspera\ascli
 ```
 
-When OAuth is used (AoC, Faspex4 api v4, Faspex5) `ascli` keeps a cache of generated bearer tokens in folder `persist_store` in configuration folder by default.
+When OAuth is used (AoC, Faspex5) `ascli` keeps a cache of generated bearer tokens in folder `persist_store` in configuration folder by default.
 Option `cache_tokens` (**yes**/no) allows to control if Oauth tokens are cached on file system, or generated for each request.
-The command `config flush_tokens` clears that cache.
+The command `config tokens flush` clears that cache.
 Tokens are kept on disk for a maximum of 30 minutes (`TOKEN_CACHE_EXPIRY_SEC`) and garbage collected after that.
 When a token has expired, then a new token is generated, either using a refresh_token if it is available, or by the default method.
 
@@ -1958,7 +2024,6 @@ ascp products list
 ascp products use 'IBM Aspera Connect'
 ascp show
 ascp spec
-ascp use /usr/bin/ascp
 check_update
 coffee
 coffee --ui=text
@@ -1977,6 +2042,8 @@ echo -- --special-string
 echo @base64:SGVsbG8gV29ybGQK
 echo @csvt:@stdin:
 echo @env:USER
+echo @json:'[{"user":{"id":1,"name":"foo"},"project":"bar"}]' --multi-single=single
+echo @json:'[{"user":{"id":1,"name":"foo"},"project":"bar"}]' --multi-single=yes
 echo @lines:@stdin:
 echo @list:,1,2,3
 echo @secret:
@@ -1990,7 +2057,6 @@ echo hello
 email_test --notify-to=my_email_external
 file
 file --logger=syslog --log-level=debug
-flush_tokens
 folder
 gem name
 gem path
@@ -2006,6 +2072,7 @@ preset delete conf_name
 preset initialize conf_name @json:'{"p1":"v1","p2":"v2"}'
 preset list
 preset overview
+preset set GLOBAL version_check_days 0
 preset set conf_name param value
 preset set default shares conf_name
 preset show conf_name
@@ -2017,6 +2084,7 @@ 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
+tokens flush
 vault create my_label @json:'{"password":"my_password_here","description":"my secret"}'
 vault delete my_label
 vault info
@@ -2397,10 +2465,10 @@ The following options can be specified in the option `image`:
 
 | Option     | Type    | Description |
 |------------|---------|-------------|
-| reserve    | Integer | Lines reserved to display a status |
-| text       | Bool    | Display text instead of image|
-| double     | Bool    | Display double text resolution (half characters) |
-| font_ratio | Float   | Font height/width ratio in terminal |
+| reserve    | `Integer` | Lines reserved to display a status |
+| text       | `Bool`    | Display text instead of image|
+| double     | `Bool`    | Display double text resolution (half characters) |
+| font_ratio | `Float`   | Font height/width ratio in terminal |
 
 ```bash
 ascli config image https://eudemo.asperademo.com/wallpaper.jpg --ui=text --image=@json:'{"text":true}'
@@ -2433,12 +2501,12 @@ The gem is equipped with traces, mainly for debugging and learning APIs.
 By default logging level is `warn` and the output channel is `stderr`.
 To increase debug level, use option `log_level` (e.g. using command line `--log-level=xx`, env var `ASCLI_LOG_LEVEL`, or an [Option Preset](#option-preset)).
 
-By default passwords and secrets are removed from logs.
-Use option `log_secrets` set to `yes` to reveal secrets in logs.
+By default passwords and secrets are redacted from logs.
+Set option `log_secrets` to `yes` to include secrets in logs.
 
-Available loggers: `stdout`, `stderr`, `syslog`.
+Option `logger`: `stdout`, `stderr`, `syslog`.
 
-Available levels: `debug`, `info`, `warn`, `error`.
+Option `log_level`: `debug`, `info`, `warn`, `error`.
 
 > **Note:** When using the `direct` agent (`ascp`), additional transfer logs can be activated using `ascp` options and `ascp_args`, see [`direct`](#agent-direct).
 
@@ -2491,7 +2559,7 @@ HTTP connection parameters (not `ascp` wss) can be adjusted using option `http_o
 | `retry_on_error`          | 0             | `ascli` |
 | `retry_sleep`             | nil           | `ascli` |
 
-Time values are in set **seconds** and can be of type either integer or float.
+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).
 
@@ -2645,7 +2713,7 @@ ascli config ascp info
 
 ```output
 +--------------------+-----------------------------------------------------------+
-| key                | value                                                     |
+| field              | value                                                     |
 +--------------------+-----------------------------------------------------------+
 | ascp               | /Users/laurent/.aspera/ascli/sdk/ascp                     |
 ...
@@ -2794,19 +2862,19 @@ The `transfer_info` option accepts the following optional parameters to control
 
 | Name                   | Type    | Description |
 |------------------------|---------|-------------|
-| `wss`                  | Bool    | Web Socket Session<br/>Enable use of web socket session in case it is available<br/>Default: true |
-| `quiet`                | Bool    | If `true`, then `ascp` progress bar is not shown.<br/>Default: `false` |
-| `trusted_certs`        | Array   | List of repositories for trusted certificates. |
-| `client_ssh_key`       | String  | SSH Keys to use for token-based transfers. One of: `dsa_rsa`, `rsa`, `per_client`. Default: `rsa` |
-| `ascp_args`            | Array   | Array of strings with native `ascp` arguments.<br/>Default: `[]` |
-| `spawn_timeout_sec`    | Float   | Multi session<br/>Verification time that `ascp` is running<br/>Default: `3` |
-| `spawn_delay_sec`      | Float   | Multi session<br/>Delay between startup of sessions<br/>Default: `2` |
-| `multi_incr_udp`       | Bool    | Multi Session<br/>Increment UDP port on multi-session<br/>If `true`, each session will have a different UDP port starting at `fasp_port` (or default 33001)<br/>Else, each session will use `fasp_port` (or `ascp` default)<br/>Default: `true` on Windows, else `false` |
-| `resume`               | Hash    | Resume parameters. See below |
-| `resume.iter_max`      | Integer | Max number of retry on error<br/>Default: `7` |
-| `resume.sleep_initial` | Integer | First Sleep before retry<br/>Default: `2` |
-| `resume.sleep_factor`  | Integer | Multiplier of sleep period between attempts<br/>Default: `2` |
-| `resume.sleep_max`     | Integer | Default: `60` |
+| `wss`                  | `Bool`    | Web Socket Session<br/>Enable use of web socket session in case it is available<br/>Default: true |
+| `quiet`                | `Bool`    | If `true`, then `ascp` progress bar is not shown.<br/>Default: `false` |
+| `trusted_certs`        | `Array`   | List of repositories for trusted certificates. |
+| `client_ssh_key`       | `String` | SSH Keys to use for token-based transfers. One of: `dsa_rsa`, `rsa`, `per_client`. Default: `rsa` |
+| `ascp_args`            | `Array`   | Array of strings with native `ascp` arguments.<br/>Default: `[]` |
+| `spawn_timeout_sec`    | `Float`   | Multi session<br/>Verification time that `ascp` is running<br/>Default: `3` |
+| `spawn_delay_sec`      | `Float`   | Multi session<br/>Delay between startup of sessions<br/>Default: `2` |
+| `multi_incr_udp`       | `Bool`    | Multi Session<br/>Increment UDP port on multi-session<br/>If `true`, each session will have a different UDP port starting at `fasp_port` (or default 33001)<br/>Else, each session will use `fasp_port` (or `ascp` default)<br/>Default: `true` on Windows, else `false` |
+| `resume`               | `Hash`    | Resume parameters. See below |
+| `resume.iter_max`      | `Integer` | Max number of retry on error<br/>Default: `7` |
+| `resume.sleep_initial` | `Integer` | First Sleep before retry<br/>Default: `2` |
+| `resume.sleep_factor`  | `Integer` | Multiplier of sleep period between attempts<br/>Default: `2` |
+| `resume.sleep_max`     | `Integer` | Default: `60` |
 
 In case of transfer interruption, the agent will **resume** a transfer up to `iter_max` time.
 Sleep between iterations is given by the following formula where `iter_index` is the current iteration index, starting at 0:
@@ -2938,12 +3006,12 @@ This is especially useful for direct node-to-node transfers.
 
 Parameters provided in option `transfer_info` are:
 
-| Name     | Type   | Description |
-|----------|--------|-------------|
-| url      | string | URL of the node API</br>Mandatory |
-| username | string | Node api user or access key</br>Mandatory |
-| password | string | Password, secret or bearer token</br>Mandatory |
-| root_id  | string | Root file id</br>Mandatory only for bearer token |
+| Nam  e     | Type   | Description                                      |
+|------------|--------|--------------------------------------------------|
+| `url`      | `String` | URL of the node API</br>Mandatory                |
+| `username` | `String` | Node api user or access key</br>Mandatory        |
+| `password` | `String` | Password, secret or bearer token</br>Mandatory   |
+| `root_id`  | `String` | Root file id</br>Mandatory only for bearer token |
 
 Like any other option, `transfer_info` can get its value from a pre-configured [Option Preset](#option-preset) :
 
@@ -2972,10 +3040,10 @@ Parameters provided in option `transfer_info` are:
 
 | Name                   | Type   | Description                           |
 |------------------------|--------|---------------------------------------|
-| url                    | string | URL of the HTTP GW</br>Mandatory      |
-| upload_chunk_size      | int    | Size in bytes of chunks for upload<br/>Default: `64000`    |
-| api_version            | string | Force use of version (`v1`, `v2`)<br/>Default: `v2`       |
-| synchronous            | bool   | Wait for each message acknowledgment<br/>Default: `false`  |
+| url                    | `String` | URL of the HTTP GW</br>Mandatory      |
+| upload_chunk_size      | `Integer`    | Size in bytes of chunks for upload<br/>Default: `64000`    |
+| api_version            | `String` | Force use of version (`v1`, `v2`)<br/>Default: `v2`       |
+| synchronous            | `Bool`   | Wait for each message acknowledgment<br/>Default: `false`  |
 
 Example:
 
@@ -2996,9 +3064,9 @@ Options for `transfer_info` are:
 
 | Name     | Type   | Description |
 |----------|--------|-------------|
-| `url`      | string | IP address and port listened by the daemon</br>Mandatory<br/>Default: `:0` |
-| `external` | bool   | Use external daemon, do not start one.<br/>Default: `false` |
-| `keep`     | bool   | Keep the daemon running after exiting `ascli`<br/>Default: `false` |
+| `url`      | `String` | IP address and port listened by the daemon</br>Mandatory<br/>Default: `:0` |
+| `external` | `Bool`   | Use external daemon, do not start one.<br/>Default: `false` |
+| `keep`     | `Bool`   | Keep the daemon running after exiting `ascli`<br/>Default: `false` |
 
 > **Note:** If port zero is specified in the URL, then the daemon will listen on a random available port. If no address is specified, then `127.0.0.1` is used.
 
@@ -3098,8 +3166,8 @@ Columns:
 | destination_root_id | string | &nbsp; | &nbsp; | &nbsp; | &nbsp; | &nbsp; | The file ID of the destination root directory.<br/>Required when using Bearer token auth for the destination node.<br/>(&lt;ignored&gt;) |
 | dgram_size | int | Y | Y | Y | Y | Y | UDP datagram size in bytes<br/>(-Z {int}) |
 | direction | string | Y | Y | Y | Y | Y | Direction of transfer (on client side)<br/>Allowed values: send, receive<br/>(--mode (conversion){enum}) |
-| exclude_newer_than | int | Y | &nbsp; | &nbsp; | &nbsp; | &nbsp; | skip src files with mtime > arg<br/>(--exclude-newer-than {int}) |
-| exclude_older_than | int | Y | &nbsp; | &nbsp; | &nbsp; | &nbsp; | skip src files with mtime < arg<br/>(--exclude-older-than {int}) |
+| exclude_newer_than | string | Y | Y | Y | Y | Y | Exclude files, but not directories, from the transfer if they are newer than the specified number of seconds added to the source computer's epoch. e.g. "-86400" for newer than a day back.<br/>(--exclude-newer-than {string}) |
+| exclude_older_than | string | Y | Y | Y | Y | Y | Exclude files, but not directories, from the transfer if they are older than the specified number of seconds added to the source computer's epoch. e.g. "-86400" for older than a day back.<br/>(--exclude-older-than {string}) |
 | fasp_port | int | Y | Y | Y | Y | Y | Specifies fasp (UDP) port.<br/>(-O {int}) |
 | fasp_url | string | &nbsp; | &nbsp; | &nbsp; | &nbsp; | &nbsp; | Only used in Faspex.<br/>(&lt;ignored&gt;) |
 | file_checksum | string | Y | Y | &nbsp; | &nbsp; | &nbsp; | Enable checksum reporting for transferred files by specifying the hash to use.<br/>Allowed values: sha-512, sha-384, sha-256, sha1, md5, none<br/>(&lt;ignored&gt;) |
@@ -3155,7 +3223,7 @@ Columns:
 | ssh_private_key_passphrase | string | Y | &nbsp; | &nbsp; | &nbsp; | &nbsp; | The passphrase associated with the transfer user's SSH private key. Available as of 3.7.2.<br/>(env:ASPERA_SCP_PASS) |
 | sshfp | string | Y | Y | Y | Y | Y | Check it against server SSH host key fingerprint<br/>(--check-sshfp {string}) |
 | symlink_policy | string | Y | Y | Y | Y | Y | Handle source side symbolic links<br/>Allowed values: follow, copy, copy+force, skip<br/>(--symbolic-links {enum}) |
-| tags | hash | Y | Y | Y | Y | Y | Metadata for transfer as JSON<br/>(--tags64 (conversion){hash}) |
+| tags | hash | Y | Y | Y | Y | Y | Metadata for transfer as JSON. Key `aspera` is reserved. Key `aspera.xfer_retry` specified a retry timeout for node api initiated transfers.<br/>(--tags64 (conversion){hash}) |
 | target_rate_cap_kbps | int | &nbsp; | &nbsp; | Y | &nbsp; | &nbsp; | Returned by upload/download_setup node API.<br/>(&lt;ignored&gt;) |
 | target_rate_kbps | int | Y | Y | Y | Y | Y | Specifies desired speed for the transfer.<br/>(-l {int}) |
 | target_rate_percentage | string | Y | Y | Y | Y | Y | TODO: remove ?<br/>(&lt;ignored&gt;) |
@@ -3166,6 +3234,7 @@ Columns:
 | write_threads | int | &nbsp; | &nbsp; | &nbsp; | &nbsp; | &nbsp; | ascp4 only<br/>(&lt;ignored&gt;) |
 | wss_enabled | bool | Y | Y | Y | Y | Y | Server has Web Socket service enabled<br/>(&lt;special&gt;) |
 | wss_port | int | Y | Y | Y | Y | Y | TCP port used for websocket service feed<br/>(&lt;special&gt;) |
+| xfer_max_retries | int | &nbsp; | Y | &nbsp; | &nbsp; | &nbsp; | maximum number of retries, for node API initiated transfers. Shall not exceed aspera.conf `transfer_manager_max_retries` (default 5).<br/>(&lt;ignored&gt;) |
 
 #### Destination folder for transfers
 
@@ -3610,7 +3679,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.20.0)
+        ascli -- a command line tool for Aspera Applications (v4.21.0)
 
 SYNOPSIS
         ascli COMMANDS [OPTIONS] [ARGS]
@@ -3649,8 +3718,7 @@ OPTIONS: global
         --select=VALUE               Select only some items in lists: column, value (Hash, Proc)
         --table-style=VALUE          Table display style (Hash)
         --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
+        --multi-single=ENUM          (Table) Control how object list is displayed as single table, or multiple objects: [no], yes, single
         --show-secrets=ENUM          Show secrets on command output: [no], yes
         --image=VALUE                Options for image display (Hash)
     -h, --help                       Show this message
@@ -3707,7 +3775,7 @@ OPTIONS: global
         --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
+SUBCOMMANDS: ascp check_update coffee detect documentation echo email_test file folder gem genkey image initdemo open platform plugins preset proxy_check pubkey remote_certificate smtp_settings test tokens vault wizard
 
 
 COMMAND: shares
@@ -4781,7 +4849,7 @@ So, for example, the creation of a node using ATS in IBM Cloud looks like (see o
   First, Retrieve the ATS node address
 
   ```bash
-  ascli aoc admin ats cluster show --cloud=softlayer --region=eu-de --fields=transfer_setup_url --format=csv --transpose-single=no
+  ascli aoc admin ats cluster show --cloud=softlayer --region=eu-de --fields=transfer_setup_url --format=csv
   ```
 
   Then use the returned address for the `url` key to actually create the AoC Node entity:
@@ -4845,6 +4913,20 @@ If a user recipient (email) is not already registered and the workspace allows e
 - if the option `new_user_option` is `@json:{"package_contact":true}` (default), then a public link is sent and the external user does not need to create an account
 - if the option `new_user_option` is `@json:{}`, then external users are invited to join the workspace
 
+#### List packages
+
+By default, when using `aoc packages list`, the following `query` is performed:
+
+| query parameter            | value |
+|----------------------------|-------|
+| `archived`                 | `false` |
+| `has_content`              | `true`  |
+| `received`                 | `true`  |
+| `completed`                | `true`  |
+| `workspace_id`             | based on current workspace |
+| `exclude_dropbox_packages` | `true` or `false` depending if watching a dropbox|
+| `dropbox_id`               | set accoring to `dropbox_name` |
+
 #### Example: Send a package with one file to two users, using their email
 
 ```bash
@@ -4886,7 +4968,7 @@ ascli aoc packages list --query=@json:'{"dropbox_name":"My Shared Inbox","archiv
 Using shared inbox identifier: first retrieve the id of the shared inbox, and then list packages with the appropriate filter.
 
 ```bash
-shared_box_id=$(ascli aoc packages shared_inboxes show --name='My Shared Inbox' --format=csv --display=data --fields=id --transpose-single=no)
+shared_box_id=$(ascli aoc packages shared_inboxes show --name='My Shared Inbox' --format=csv --display=data --fields=id)
 ```
 
 ```bash
@@ -4938,6 +5020,26 @@ ascli aoc packages recv ALL --once-only=yes --lock-port=12345
 
 Typically, one would execute this command on a regular basis, using the method of your choice: see [Scheduler](#scheduler).
 
+### Example: Content of a received Package
+
+Some `node` operations are available for a package, such as `browse` and `find`.
+
+To list the content of a package, use command `packages browse <package id> <folder>`:
+
+```bash
+ascli aoc package browse my5CnbeWng /
+```
+
+To list recursively, use command `find`.
+
+To download only some of the files listed in the package, just add the path of the files on the command line.
+
+For advanced users, it's also possible to pipe node information for the package and use node operations:
+
+```bash
+ascli aoc package node_info <package id here> / --format=json --show-secrets=yes --display=data | ascli node -N --preset=@json:@stdin: access_key do self browse /
+```
+
 ### Files
 
 The Files application presents a **Home** folder to users in a given workspace.
@@ -5092,7 +5194,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 organization --query=@json:'{"status":"completed","direction":"receive","limit":2}' --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 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":"/"}}'
@@ -5117,8 +5219,10 @@ admin group list
 admin kms_profile list
 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 delete /folder_sub
 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 mkdir /folder_sub
+admin node do %name:my_node_name --secret=my_ak_secret v3 access_key create @json:'{"id":"testsub1","storage":{"path":"/folder_sub"}}'
 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
@@ -5189,13 +5293,14 @@ files v3 info
 gateway --pid-file=pid_aocfxgw https://localhost:12345/aspera/faspex &
 org --url=my_public_link_recv_from_aoc_user
 organization
-packages browse package_id3 /contents
+packages browse package_id3 /
 packages list
 packages list --query=@json:'{"dropbox_name":"my_shared_inbox_name","sort":"-received_at","archived":false,"received":true,"has_content":true,"exclude_dropbox_packages":false}'
 packages receive ALL --once-only=yes --to-folder=. --lock-port=12345
 packages receive ALL --once-only=yes --to-folder=. --lock-port=12345 --query=@json:'{"dropbox_name":"my_shared_inbox_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}'
 packages receive INIT --once-only=yes --query=@json:'{"dropbox_name":"my_shared_inbox_name"}'
 packages receive package_id3 --to-folder=.
+packages receive package_id3 --to-folder=. /
 packages send --workspace=my_workspace_shared_inbox --validate-metadata=yes @json:'{"name":"$(notdir test) PACKAGE_TITLE_BASE","recipients":["my_shared_inbox_meta"],"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"]}]}' test_file.bin
 packages send --workspace=my_workspace_shared_inbox --validate-metadata=yes @json:'{"name":"$(notdir test) PACKAGE_TITLE_BASE","recipients":["my_shared_inbox_meta"],"metadata":{"Project Id":"456","Type":"Opt2","CheckThose":["Check1","Check2"],"Optional Date":"2021-01-13T15:02:00.000Z"}}' test_file.bin
 packages send --workspace=my_workspace_shared_inbox --validate-metadata=yes @json:'{"name":"$(notdir test) PACKAGE_TITLE_BASE","recipients":["my_shared_inbox_meta"],"metadata":{"Type":"Opt2","CheckThose":["Check1","Check2"],"Optional Date":"2021-01-13T15:02:00.000Z"}}' test_file.bin
@@ -5290,7 +5395,7 @@ ascli ats api_key create
 
 ```output
 +--------+----------------------------------------------+
-| key    | value                                        |
+| field  | value                                        |
 +--------+----------------------------------------------+
 | id     | ats_XXXXXXXXXXXXXXXXXXXXXXXX                 |
 | secret | YYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYY |
@@ -5392,7 +5497,7 @@ delete my_inside_folder
 delete my_upload_folder/to.delete
 df
 download my_inside_folder/test_file.bin --to-folder=. --transfer-info=@json:'{"wss":false,"resume":{"iter_max":1}}'
-download my_inside_folder/test_file.bin --to-folder=my_upload_folder --transfer=node
+download my_large_file --to-folder=my_upload_folder --transfer=node --ts=@json:'{"resume_policy":"none"}'
 du /
 health transfer --to-folder=my_upload_folder --format=nagios
 info
@@ -5413,7 +5518,7 @@ upload --sources=@ts --transfer-info=@json:'{"ascp_args":["--file-pair-list","fi
 upload --sources=@ts --ts=@json:'{"paths":[{"source":"test_file.bin","destination":"my_inside_folder/other_name_4"}]}' --transfer=trsdk
 upload --src-type=pair 'test_file.bin' my_inside_folder/other_name_2 --notify-to=my_email_external --transfer-info=@json:'{"ascp_args":["-l","100m"]}'
 upload --src-type=pair --sources=@json:'["test_file.bin","my_inside_folder/other_name_3"]' --transfer-info=@json:'{"quiet":false}' --ts=@json:'{"use_ascp4":true}' --progress=no
-upload --src-type=pair test_file.bin my_upload_folder/other_name_5 --ts=@json:'{"cipher":"aes-192-gcm","content_protection":"encrypt","content_protection_password":"my_secret_here","cookie":"biscuit","create_dir":true,"delete_before_transfer":false,"delete_source":false,"exclude_newer_than":1,"exclude_older_than":10000,"fasp_port":33001,"http_fallback":false,"multi_session":0,"overwrite":"diff+older","precalculate_job_size":true,"preserve_access_time":true,"preserve_creation_time":true,"rate_policy":"fair","resume_policy":"sparse_csum","symlink_policy":"follow"}'
+upload --src-type=pair test_file.bin my_upload_folder/other_name_5 --ts=@json:'{"cipher":"aes-192-gcm","content_protection":"encrypt","content_protection_password":"my_secret_here","cookie":"biscuit","create_dir":true,"delete_before_transfer":false,"delete_source":false,"exclude_newer_than":"-1","exclude_older_than":"-10000","fasp_port":33001,"http_fallback":false,"multi_session":0,"overwrite":"diff+older","precalculate_job_size":true,"preserve_access_time":true,"preserve_creation_time":true,"rate_policy":"fair","resume_policy":"sparse_csum","symlink_policy":"follow"}'
 upload --to-folder=my_upload_folder/target_hot --lock-port=12345 --transfer-info=@json:'{"ascp_args":["--remove-after-transfer","--remove-empty-directories","--exclude-newer-than=-8","--src-base","source_hot"]}' source_hot
 ```
 
@@ -5523,6 +5628,8 @@ This plugin gives access to capabilities provided by the HSTS node API.
 The authentication is `username` and `password` or `access_key` and `secret` through options: `username` and `password`.
 
 > **Note:** Capabilities of this plugin are used in other plugins which access to the node API, such as `aoc`, `ats`, `shares`.
+>
+> **Note:** This plugin can be used with any type of **Aspera Node**, either on-prem or ATS, provided that you have node api credentials. Those credentials can be either Node API user or Access Key (e.g. on ATS).
 
 ### File Operations
 
@@ -5792,7 +5899,7 @@ 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.
 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).
+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.
 A bearer token is authorized on the node by creating `permissions` on a **folder**.
@@ -5923,7 +6030,6 @@ 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 /tst_nd_ak
 access_key do my_ak_name node_info /
 access_key do my_ak_name rename /tst_nd_ak test_nd_ak2
@@ -6152,7 +6258,7 @@ admin contacts list
 admin distribution_lists create @json:'{"name":"test4","contacts":[{"name":"john@example.com"}]}'
 admin distribution_lists delete %name:test4
 admin distribution_lists list --query=@json:'{"type":"global"}'
-admin event app
+admin event app --query=@json:'{"max":20}'
 admin event web
 admin jobs list --query=@json:'{"job_type":"email","status":"failed"}' --fields=id,error_desc
 admin metadata_profiles list
@@ -6320,7 +6426,7 @@ To list the content of a package, use command `faspex5 packages browse /`.
 
 Option `query` is available.
 
-To list recursively add option `--query=@json:{"recursive":true}`.
+To list recursively add option `--query=@json:'{"recursive":true}'`.
 
 > **Note:** Option `recursive` makes recursive API calls, so it can take a long time on large packages.
 
@@ -6393,15 +6499,15 @@ ascli faspex5 admin shared create @json:'{"name":"the shared inbox","metadata_pr
 ### Faspex 5: List content in Shared folder and send package from remote source
 
 ```bash
-ascli faspex5 shared_folders list
+ascli faspex5 shared_folders list --fields=id,name
 ```
 
 ```markdown
-+----+----------+---------+-----+
-| id | name     | node_id | ... |
-+----+----------+---------+-----+
-| 3  | partages | 2       | ... |
-+----+----------+---------+-----+
++----+----------+
+| id | name     |
++----+----------+
+| 3  | partages |
++----+----------+
 ```
 
 ```bash
@@ -6471,6 +6577,22 @@ ascli faspex5 packages list --box=ALL --format=yaml --fields=id | ascli faspex5
 > **Note:** Above command will mark all packages for deletion, and will be permanently removed after the configured period (`clean_deleted` command).
 > It is possible to add a filter to the list command to only delete packages matching some criteria, e.g. using `--select=@ruby:`.
 
+### Faspex 5: Admin: Unlock user
+
+To unlock a user, you can de-activate and then re-activate the user:
+
+```bash
+ascli faspex5 admin accounts modify %name:some.user@example.com @json:'{"account_activated":false}'
+```
+
+```bash
+ascli faspex5 admin accounts modify %name:some.user@example.com @json:'{"account_activated":true}'
+```
+
+> **Note:** here we use the convenient percent selector, but the numerical if can be used as well.
+
+To send a password reset link to a user, use command `reset_password` on the `account`.
+
 ### Faspex 5: Faspex 4-style postprocessing
 
 `ascli` provides command `postprocessing` in plugin `faspex5` to emulate Faspex 4 postprocessing.
@@ -6486,15 +6608,15 @@ The following parameters are supported:
 
 | parameter                  | type    | default                | description                                         |
 |----------------------------|---------|------------------------|-----------------------------------------------------|
-| url                        | string  | http://localhost:8080  | Base url on which requests are listened             | <!-- markdownlint-disable-line -->
-| certificate                | hash    | nil                    | Certificate information (if HTTPS)                  |
-| certificate.key            | string  | nil                    | Path to private key file                            |
-| certificate.cert           | string  | nil                    | Path to certificate                                 |
-| certificate.chain          | string  | nil                    | Path to intermediary certificates                   |
-| processing                 | hash    | nil                    | Behavior of post processing                         |
-| processing.script_folder   | string  | .                      | Prefix added to script path                         |
-| processing.fail_on_error   | bool    | false                  | Fail if true and process exit with non zero         |
-| processing.timeout_seconds | integer | 60                     | Max. execution time before script is killed         |
+| url                        | `String` | http://localhost:8080  | Base url on which requests are listened             | <!-- markdownlint-disable-line -->
+| certificate                | `Hash`    | nil                    | Certificate information (if HTTPS)                  |
+| certificate.key            | `String` | nil                    | Path to private key file                            |
+| certificate.cert           | `String` | nil                    | Path to certificate                                 |
+| certificate.chain          | `String` | nil                    | Path to intermediary certificates                   |
+| processing                 | `Hash`    | nil                    | Behavior of post processing                         |
+| processing.script_folder   | `String` | .                      | Prefix added to script path                         |
+| processing.fail_on_error   | `Bool`    | false                  | Fail if true and process exit with non zero         |
+| processing.timeout_seconds | `Integer` | 60                     | Max. execution time before script is killed         |
 
 Parameter `url` defines:
 
@@ -6551,6 +6673,8 @@ curl -H "Authorization: $(ascli ascli bearer)" https://faspex5.example.com/asper
 
 ## Plugin: `faspex`: IBM Aspera Faspex v4
 
+> **Note:** Faspex v4 is end of support since Sept. 30th, 2024. So this plugin for faspex v4 is deprecated. If you still need to use Faspex4, then use `ascli` version 4.19.0 or earlier.
+>
 > **Note:** For full details on Faspex API, refer to: [Reference on Developer Site](https://developer.ibm.com/apis/catalog/?search=faspex)
 
 This plugin uses APIs versions 3 Faspex v4.
@@ -7281,6 +7405,7 @@ If the preview generator does not have access to files on the file system (it is
 
 ```bash
 check --skip-types=office
+events --once-only=yes --skip-types=office --log-level=info
 scan --scan-id=1 --skip-types=office --log-level=info --file-access=remote --ts=@json:'{"target_rate_kbps":1000000}'
 scan --skip-types=office --log-level=info
 show --base=test my_docx
@@ -7385,7 +7510,7 @@ Interesting `ascp` features are found in its arguments: (see `ascp` manual):
 
 > **Note:** `ascli` takes transfer parameters exclusively as a [**transfer-spec**](#transfer-specification), with `ts` option.
 >
-> **Note:** Most, but not all, native `ascp` arguments are available as standard [**transfer-spec**](#transfer-specification) parameters.
+> **Note:** Usual native `ascp` arguments are available as standard [**transfer-spec**](#transfer-specification) parameters, but not special or advanced options.
 >
 > **Note:** Only for the [`direct`](#agent-direct) transfer agent (not others, like connect or node), native `ascp` arguments can be provided with parameter `ascp_args` of option `transfer_info` .