aspera-cli 4.27.0 → 4.27.2

data/docs/README.md

@@ -1,9 +1,17 @@
 # Command Line Interface for IBM Aspera products
 <!--
+EDITING GUIDELINES (developers and AI):
+- This file is the source template for the generated README.md. Edit this file, not README.md.
+- Do not use Unicode characters unless strictly necessary (e.g. wizard menu labels that must
+  match the actual on-screen UI text). Use plain ASCII equivalents instead:
+    apostrophe : ' (not ' or ')
+    dash       : - (not en-dash U+2013, not em-dash U+2014, not --)
+    ellipsis   : ... (not U+2026)
+- Emphasis style: use **bold** (double asterisks) only. Do not use *single asterisk italic*, _underscore_, or __double underscore__ style.
 DO NOT EDIT: THIS FILE IS GENERATED, edit docs/README.erb.md.
 PANDOC_DEFAULTS_BEGIN
 metadata:
-  subtitle: "ascli 4.27.0"
+  subtitle: "ascli 4.27.2"
   author: "Laurent Martin"
 PANDOC_DEFAULTS_END
 -->
@@ -25,7 +33,7 @@ Designed for automation, scripting, and integration scenarios, `ascli` enables o
 ### Key Features
 
 **Multi-Product Integration**
-: Unified interface supporting Aspera on Cloud, Faspex (v4 and v5), Shares, Node API, Console, Orchestrator, and High-Speed Transfer Server (HSTS).
+: Unified interface supporting Aspera on Cloud, Faspex 5, Shares, Node API, Console, Orchestrator, and High-Speed Transfer Server (HSTS).
 
 **Flexible Authentication**
 : Support for OAuth 2.0, JWT, Basic Authentication, and SSH key-based authentication across different Aspera products.
@@ -78,7 +86,7 @@ Internally, `ascli` integrates several components:
 For programmatic integration with languages such as C/C++, Go, Python, NodeJS, and others, it is recommended to use the [Aspera APIs](https://ibm.biz/aspera_api) directly.
 These include:
 
-- REST APIs for products like Aspera on Cloud (AoC), Faspex, and Node
+- REST APIs for products like Aspera on Cloud (AoC), Faspex 5, and Node
 - The Transfer Daemon with gRPC interfaces and language-specific stubs (C/C++, Python, .NET/C#, Java, Go, Ruby, Rust, and so on)
 
 These APIs are generally more suitable for long-term development and maintenance.
@@ -137,8 +145,8 @@ This section walks you through your first interaction with `ascli` on Linux.
 
 ```shell
 mkdir -p $HOME/bin
-tar zxvf ascli.4.27.0.linux-x86_64.tgz
-mv ascli.4.27.0.linux-x86_64 $HOME/bin/ascli
+tar zxvf ascli.4.27.2.linux-x86_64.tgz
+mv ascli.4.27.2.linux-x86_64 $HOME/bin/ascli
 export PATH=$PATH:$HOME/bin
 ```
 
@@ -152,7 +160,7 @@ ascli -v
 ```
 
 ```text
-4.27.0
+4.27.2
 ```
 
 - Install the Aspera transfer runtime (tested version), as it is not included in the `ascli` package:
@@ -424,17 +432,19 @@ brew install ruby
 > Do not use it.
 > Use the required version of Ruby.
 
-This installs a recent Ruby suitable for `ascli`.
+This installs a recent Ruby version suitable for `ascli`.
 
-To add Ruby to your `PATH` on Apple Silicon, add the following lines to your shell configuration file (that is, `~/.zshrc` if you are using `zsh`, or `~/.bash_profile` for `bash`):
+After installation, Homebrew's Ruby is not on the `PATH` by default (this is shown at the end of the `brew install ruby` output and by `brew info ruby`).
+Add it to your shell configuration file:
 
-```shell
-PATH="$(brew --prefix ruby)/bin:$($(brew --prefix ruby)/bin/gem env gemdir)/bin:$PATH"
-```
+- **zsh** (default shell on macOS — run this once in a terminal):
 
-> [!NOTE]
-> This is what is displayed at the end of the installation of the ruby tap,
-> same as the message from: `brew info ruby`
+  ```shell
+  echo 'PATH="$(brew --prefix ruby)/bin:$($(brew --prefix ruby)/bin/gem env gemdir)/bin:$PATH"' >> ~/.zprofile
+  source ~/.zprofile
+  ```
+
+- **bash** — replace `~/.zprofile` with `~/.bash_profile` in the commands above.
 
 #### Linux: Package
 
@@ -647,7 +657,7 @@ Those are not installed as part of dependencies because they involve compilation
 See [Gemfile](../Gemfile):
 
 | name | version | comment |
-|----------------------|----------|-------------------------------------------------------------------------------|
+|---------------------|----------|-------------------------------------------------------------------------------|
 | rake | ~> 13.0 |  |
 | debug | ~> 1.11 | (no jruby) |
 | grpc-tools | ~> 1.67 |  |
@@ -662,8 +672,6 @@ See [Gemfile](../Gemfile):
 | mcp | ~> 1.2 | for ascli mcp server (MCP protocol support) |
 | rack | ~> 3.0 | for ascli mcp server HTTP transport (required by mcp StreamableHTTPTransport) |
 | grpc | ~> 1.71 | (no jruby) for Aspera Transfer Daemon |
-| symmetric-encryption | ~> 4.6 | for encrypted hash file secrets |
-| bigdecimal | ~> 3.1 | if RUBY_VERSION >= '3.4' for symmetric-encryption ? |
 | base64 | ~> 0.3 | if RUBY_VERSION >= '3.4' remove from standard gems |
 | sqlite3 | ~> 2.7 | (no jruby) for async DB |
 | jdbc-sqlite3 | ~> 3.46 | (jruby) for async DB |
@@ -690,8 +698,6 @@ gem install solargraph -v '~> 0.48'
 gem install mcp -v '~> 1.2'
 gem install rack -v '~> 3.0'
 gem install grpc -v '~> 1.71'
-gem install symmetric-encryption -v '~> 4.6'
-gem install bigdecimal -v '~> 3.1'
 gem install base64 -v '~> 0.3'
 gem install sqlite3 -v '~> 2.7'
 gem install jdbc-sqlite3 -v '~> 3.46'
@@ -822,7 +828,12 @@ If installation from a local file is preferred (air-gapped installation) instead
 ascli config transferd install --sdk-url=file:///macos-arm64-1.1.3-c6c7a2a.zip
 ```
 
-The format is: `file:///<PATH>`, where `<PATH>` can be either a relative path (not starting with `/`), or an absolute path.
+The format is: `file:///<PATH>` (canonical form) or `file:<PATH>` (short form), where `<PATH>` can be either a relative path (not starting with `/`), or an absolute path (starting with `/`).
+
+| Form | Relative example | Absolute example |
+|------|-----------------|-----------------|
+| Canonical | `file:///mydir/archive.zip` | `file:////home/user/archive.zip` |
+| Short | `file:mydir/archive.zip` | `file:/home/user/archive.zip` |
 
 Supported platforms are listed in the [Release Notes](https://developer.ibm.com/apis/catalog/aspera--aspera-transfer-sdk/Release+notes) and archives can be downloaded from [Downloads](https://developer.ibm.com/apis/catalog/aspera--aspera-transfer-sdk/downloads/downloads.json).
 
@@ -887,11 +898,11 @@ Alternatively, the necessary gems can be packaged into a `tar.gz` archive as fol
 
 ```shell
 mkdir temp_folder
-gem install aspera-cli:4.27.0 --no-document --install-dir temp_folder
+gem install aspera-cli:4.27.2 --no-document --install-dir temp_folder
 find temp_folder
-mv temp_folder/cache aspera-cli-4.27.0-gems
+mv temp_folder/cache aspera-cli-4.27.2-gems
 rm -fr temp_folder
-tar zcvf aspera-cli-4.27.0-gems aspera-cli-4.27.0-gems.tgz
+tar zcvf aspera-cli-4.27.2-gems aspera-cli-4.27.2-gems.tgz
 ```
 
 #### Unix-like: Alternative installation using `rvm`
@@ -1025,7 +1036,7 @@ ascli -v
 ```
 
 ```text
-4.27.0
+4.27.2
 ```
 
 To keep persistency of configuration on the host, specify your user's configuration folder as a volume for the container.
@@ -1288,7 +1299,7 @@ ascli config echo @uri:https://curl.haxx.se/ca/cacert.pem --format=text
 To download that certificate store:
 
 ```shell
-ascli config echo @uri:https://curl.haxx.se/ca/cacert.pem --format=text --output=/tmp/cacert.pem
+ascli config echo @uri:https://curl.haxx.se/ca/cacert.pem --format=text --out.file=/tmp/cacert.pem
 ```
 
 Then, use this store by setting the option `cert_stores` (or env var `SSL_CERT_FILE`).
@@ -1296,7 +1307,7 @@ Then, use this store by setting the option `cert_stores` (or env var `SSL_CERT_F
 To trust a specific certificate (for example, self-signed), **provided that the `CN` is correct**, save the certificate chain to a file:
 
 ```shell
-ascli config remote_certificate chain https://localhost:9092 --insecure=yes --output=<SERVER_PRESET_NAME>.pem
+ascli config remote_certificate chain https://localhost:9092 --insecure=yes --out.file=<SERVER_PRESET_NAME>.pem
 ```
 
 > [!NOTE]
@@ -1430,28 +1441,25 @@ Typically, the `create` verb takes a resource creation data as a parameter.
 #### Identifiers
 
 Identifiers uniquely identify a resource.
-They are typically located immediately after a verb, itself placed after the resource type.
-Some resources accept selection using other unique identifier, other than the native identifier (typically: `id`), using the **percent selector**.
+They are typically located immediately after a verb like `show`, `modify` or `delete`, itself placed after the resource type, for example: `user show foobar`.
+Some resources accept selection using other unique identifier, other than the native identifier (typically: `id`), using the [**percent selector**](#percent-selector).
 
 ##### Percent selector
 
-Some resources provide the following capability:
-If the resource 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 resource named `name` has a value `john`:
+The **percent selector** is a special syntax that lets you identify a resource by any unique field, instead of its default identifier (typically a numeric `id`).
 
-```shell
-ascli aoc admin user show %name:john
-```
+Syntax: `%<FIELD>:<VALUE>`
 
-The percent selector allows identification of a resource by another unique identifier other than the native identifier (typically: `id`).
+- The leading `%` marks the argument as a percent selector (not a plain identifier).
+- `<FIELD>` is the name of the field to match on (e.g. `name`, `email`).
+- `<VALUE>` is the expected value of that field.
 
-Syntax: `%<FIELD>:<VALUE>`
+The tool then looks up the resource whose `<FIELD>` equals `<VALUE>` and uses its native identifier internally.
 
-When a command is executed on a resource, the resource is identified by a unique identifier that follows the command.
-For example, in the following command, `<USER_ID>` is the user's identifier:
+For example, to show the user whose `name` field is `john`:
 
 ```shell
-ascli aoc admin user show <USER_ID>
+ascli aoc admin user show %name:john
 ```
 
 #### Command Parameters
@@ -1601,7 +1609,9 @@ Command-line options, such as `--log-level=debug`, follow these conventions:
   Option name in config file use underscores (`_`) as word separators.
   Example: `--log-level=debug` is `log_level` in config file.
 - **Values**:
-  An option’s value is assigned using `=` (for example, `--log-level=debug`).
+  An option's value is assigned using `=` (for example, `--log-level=debug`).
+  Alternatively, the value can be provided as a separate, space-separated token (for example, `--log-level debug`).
+  Both forms are equivalent.
 - **Prefix Usage**:
   Options support prefix matching (see [Enumerations](#enumerations)), though full names are recommended.
 - **Optionality**:
@@ -1614,7 +1624,7 @@ Exceptions and Special Cases:
 - **Short Forms**
 
   Some options have short forms.
-  For example, `-Ptoto` is equivalent to `--preset=toto`.
+  For example, `-Ptoto` and `-P toto` are both equivalent to `--preset=toto` and `--preset toto`.
   See the manual or `-h` for details.
 - **Flags**
 
@@ -1626,9 +1636,10 @@ Exceptions and Special Cases:
 - [**dot-path notation**](#dot-path-notation)
 - **Cumulative Hashes**
 
-  When an option of type `Hash` is set, the value is deep-merged to an existing or default value.
-  Setting to `@none:` is equivalent to setting to `@json:{}`, that is, an empty `Hash`.
-  This can be used to start from an empty value, and not use the existing default value.
+  When an option of type `Hash` is set, the value is deep-merged with any existing value.
+  Setting to `@json:{}` starts from an empty hash (the existing value is discarded for that merge step).
+  Setting to `@none:` explicitly disables the option: it is set to `nil` and any preset or default value is prevented from restoring it.
+  This is useful, for example, to disable a vault or any Hash option that is configured in a default preset.
 
 Example:
 
@@ -1748,16 +1759,16 @@ The style of output can be set using the `format` option:
 
 By default, result of type `single_object` and `object_list` are displayed using format `table`.
 
-#### Option: `table_style`
+#### Option: `--out.table`
 
-The way `format`: `table` and `csv` are generated can be customized with option: `table_style` which expects a `Hash`.
+The way `format`: `table` and `csv` are generated can be customized with option `--out.table` which expects a `Hash`.
 
 For `format=table`, options are the ones described in gem [`terminal-table`](https://github.com/tj/terminal-table).
 
 For example, to display a table with thick Unicode borders:
 
 ```shell
-ascli config preset over --table-style=@ruby:'{border: :unicode_thick_edge}'
+ascli config preset over --out.table=@ruby:'{border: :unicode_thick_edge}'
 ```
 
 > [!NOTE]
@@ -1774,10 +1785,10 @@ For `format=csv`, options are described in gem [`csv`](https://ruby.github.io/cs
 For example, to display a CSV with headers and quotes:
 
 ```shell
-ascli config echo @json:'[{"name":"foo","id":1},{"name":"bar","id":8}]' --format=csv --table=@json:'{"headers":true,"force_quotes":true}'
+ascli config echo @json:'[{"name":"foo","id":1},{"name":"bar","id":8}]' --format=csv --out.table=@json:'{"headers":true,"force_quotes":true}'
 ```
 
-#### Option: `flat_hash`: Single level `Hash`
+#### Option: `--out.flat`: Single level `Hash`
 
 This option controls how object fields are displayed for complex objects.
 
@@ -1811,7 +1822,7 @@ ascli config echo @json:'{"A":"a","B":[{"name":"B1","value":"b1"},{"name":"B2","
 ╰────────┴───────╯
 ```
 
-For the same command, adding option `--flat=no`:
+For the same command, adding option `--out.flat=no`:
 
 ```text
 ╭───────┬────────────────────────────────────────────────────────────────────────╮
@@ -1824,7 +1835,7 @@ For the same command, adding option `--flat=no`:
 ╰───────┴────────────────────────────────────────────────────────────────────────╯
 ```
 
-#### Option: `multi_single`
+#### Option: `--out.table.pivot`
 
 This option controls how result fields are displayed as columns or lines, when option `format` is set to `table`.
 Default is `no`.
@@ -1852,7 +1863,7 @@ The display of result is as follows:
 This parameter can be set as a global default with:
 
 ```shell
-ascli config preset set GLOBAL multi_single single
+ascli config preset set GLOBAL out.table.pivot single
 ```
 
 Examples:
@@ -1860,7 +1871,7 @@ Examples:
 Simulate a result by executing this command:
 
 ```shell
-ascli config echo @json:'<JSON_VALUE>' --multi-single=<no|yes|single>
+ascli config echo @json:'<JSON_VALUE>' --out.table.pivot=<no|yes|single>
 ```
 
 Example 1: A list of one object
@@ -1925,7 +1936,7 @@ Display with `yes` (multiple Simple):
 ╰───────┴───────╯
 ```
 
-#### Option: `display`: Verbosity of output
+#### Option: `--out.level`: Verbosity of output
 
 Output messages are categorized in 3 types:
 
@@ -1933,17 +1944,17 @@ Output messages are categorized in 3 types:
 - `data` output contains the actual output of the command (object, or list of objects)
 - `error` output contains error messages
 
-The option `display` controls the level of output:
+The option `--out.level` controls the level of output:
 
 - `info` displays all messages: `info`, `data`, and `error`
 - `data` display `data` and `error` messages
 - `error` display only error messages.
 
-#### Option: `show_secrets`: Hide or show secrets in results
+#### Option: `--out.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.
-- If `display` is `data`, secrets are included to allow piping results.
+- If `--out.level` is `data`, secrets are included to allow piping results.
 
 #### Option: `fields`: Selection of output object fields
 
@@ -2000,15 +2011,22 @@ In the above example, the same result is obtained with option:
 --select=@ruby:'->(i){i["ats_admin"]}'
 ```
 
-Option `select` applies the filter after a possible "flattening" with option: `flat_hash`.
+Option `select` applies the filter after a possible "flattening" with option `--out.flat`.
 
 ### Extended Value Syntax
 
+An **Extended Value** is a structured value - typically a `Hash` (key/value dictionary) or `Array`, potentially nested - that is passed on the command line wherever a simple string is not sufficient.
+
 Most options and arguments are specified by a simple string (for example, `username` or `url`).
-Sometimes 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`.
+However, some situations require a complex structure:
 
-The [Extended Value](#extended-value-syntax) Syntax allows specifying such values and even reading values from other sources than the command line itself.
+- An option expects a **structured value** (`Hash`, `Array`) rather than a plain string.
+- The value is too long or complex to type inline (for example, a PEM private key, a JSON body).
+- The value must be **read from a file, an environment variable, or a URL** at runtime rather than embedded in the command.
+- The value needs **type coercion**: for example, an integer `1` instead of the string `"1"`, or a boolean `true`.
+
+The **Extended Value** syntax addresses all of these needs with a uniform, composable mechanism.
+It lets you specify **what the value is** and **how to obtain or decode it**, entirely on the command line.
 
 #### Syntax and Decoders
 
@@ -2046,11 +2064,11 @@ The following decoders are supported:
 | `s`      | Any      | `String` | Converts argument to `String`. |
 | `secret` | `String` | `String` | Ask password interactively (hides input). Argument is the prompt. |
 | `stdin`  | `String` | `String` | Read from stdin in text mode. Argument: `<empty>`, `bin` or `chomp`. |
-| `uri`    | `String` | `String` | Read value from specified URL. for example, `--fpac=@uri:http://serv/f.pac` |
+| `uri`    | `String` | `String` | Read value from specified URL. Supported schemes: `http:`, `https:`, `data:`, `file:`. for example, `--fpac=@uri:http://serv/f.pac` or `--key=@uri:file:/path/to/key.pem` |
 | `val`    | `String` | `String` | Prevent decoders on the right to be decoded. for example, `--key=@val:@file:foo` sets the option `key` to value `@file:foo`. |
 | `yaml`   | `String` | Any      | Decode YAML. |
 | `zlib`   | `String` | `String` | Decompress data using zlib. |
-| `<empty>`| None     | Any      | The empty modifier, resulting as argument `@:`, parses remaining positional arguments as a `Hash` or `Array` using [dot-path](#dot-path-notation) notation.<br/>Use `END` to stop collection when further positional arguments must follow. |
+| `<empty>`| None     | Any      | The **dot-path** modifier: argument `@:` collects the following positional arguments as `key.subkey=value` assignments and builds a `Hash` or `Array` using [dot-path](#dot-path-notation) notation. Shell-friendly alternative to `@json:` for structured values.<br/>See [Positional Arguments with Dot-path](#positional-arguments-with-dot-path) for full syntax. Use `END` to stop collection when further positional arguments must follow. |
 
 > [!NOTE]
 > A few commands support a value of type `Proc` (lambda expression).
@@ -2066,11 +2084,85 @@ It expects a `@` to close the embedded [Extended Value](#extended-value-syntax)
 Option `parser` allows definition of a default parser when the positional parameter or option expects a `Hash` or `Array`.
 For example, with `--parser=json`, the parameter `{}` will be parsed as an empty JSON Hash, even without prefix `@json:`.
 
+#### Syntax Equivalences
+
+There are four main ways to express a structured value (for example, a `Hash` with two keys).
+They are all equivalent and produce the same result:
+
+| Syntax | Example | Best for |
+|--------|---------|----------|
+| `@json:` | `@json:'{"name":"alice","age":30}'` | Scripts, API payloads, copy-paste from docs |
+| `@yaml:` | `@yaml:@stdin:` + here-doc | Multi-line or deeply nested structures |
+| `@ruby:` | `@ruby:'{"name"=>"alice","age"=>30}'` | Advanced use: lambdas, file reads, logic |
+| dot-path (`key.subkey=value`) via `@:` | `@: name=alice age=30` | Interactive CLI, simple structures, no quoting |
+
+All four examples above produce the same `Hash`: `{"name" => "alice", "age" => 30}`.
+
+```shell
+ascli config echo @json:'{"name":"alice","age":30}' --format=json
+ascli config echo @ruby:'{"name"=>"alice","age"=>30}' --format=json
+ascli config echo @: name=alice age=30 --format=json
+```
+
+```json
+{"name":"alice","age":30}
+```
+
+> [!NOTE]
+> The dot-path form (`key.subkey=value` assignments via `@:`) does **not** need quotes for simple string values and is the most shell-friendly.
+> The `@json:` form requires enclosing in single quotes to protect `"` from the shell.
+> The `@ruby:` form accepts both single and double quotes and supports arbitrary Ruby expressions.
+> The `@yaml:` form is most convenient when combined with a shell **here-document** (`<<EOF`).
+
+##### Equivalences: Positional Parameter vs Option
+
+The same `Hash` value `{"a":1,"b":"two"}` can be expressed differently depending on whether it is supplied as a **positional parameter** or as an **option**.
+
+**As a positional parameter** (argument to a command):
+
+```shell
+# JSON form
+some_command @json:'{"a":1,"b":"two"}'
+# Dot-path form (END is optional when no positional argument follows)
+some_command @: a=1 b=two
+some_command @: a=1 b=two END
+```
+
+**As an option** named `opt`:
+
+```shell
+# JSON form
+--opt=@json:'{"a":1,"b":"two"}'
+# Dot-path form via option name (each key as a separate option flag)
+--opt.a=1 --opt.b=two
+# Dot-path form via option value (consumes following positional arguments)
+--opt=@: a=1 b=two END
+```
+
+> [!NOTE]
+> `--opt.a=1 --opt.b=two` and `--opt=@json:'{"a":1,"b":"two"}'` and `--opt=@: a=1 b=two` all produce the same `Hash` assigned to option `opt`.
+> The `--opt.key=value` form is the most concise when only a few keys need to be set.
+> Use `END` with `@:` when further positional arguments follow on the command line; it is optional otherwise.
+
+#### Which Syntax to Choose?
+
+**When in doubt: start with dot-path** (`--opt.key=value` for options, `@: key=value` for positional arguments).
+It requires no quoting, auto-converts types, and reads naturally on the command line.
+Switch to `@json:` when you already have a JSON payload from an API doc or external tool.
+
+| Context | Recommended syntax | Reason |
+|---------|--------------------|--------|
+| Interactive CLI, simple values | dot-path `key.subkey=value` via `@:` or `--opt.key=value` | No quoting needed, auto-typed, readable |
+| Shell scripts, API payloads | `@json:` | Standard, portable, easy to copy from API docs |
+| Multi-line or nested structures in scripts | `@yaml:` + `@stdin:` heredoc | Readable, no escaping |
+| Dynamic values, lambdas, file reads | `@ruby:` | Full Ruby expressiveness |
+
 #### Common Usage Examples
 
-Example: Create a `Hash` value with the convenient `@json:` decoder:
+Example: Create a `Hash` value - for a small structure, the dot-path `key.subkey=value` form (via `@:`) is simpler; for larger or API-sourced structures, use `@json:`:
 
 ```shell
+ascli config echo @: key1=value1 key2=value2
 ascli config echo @json:'{"key1":"value1","key2":"value2"}'
 ```
 
@@ -2212,12 +2304,31 @@ This works for any `Hash` option or positional parameter that has a defined sche
 
 #### Testing Extended Value
 
-In case of doubt of argument values after parsing, one can test using command `config echo`.
-`config echo` takes exactly **one** argument which can use the [Extended Value](#extended-value-syntax) syntax.
+Two complementary commands help verify that a value is parsed as expected:
+
+| What to check | Tool | How |
+|---|---|---|
+| Value of a **positional parameter** | `config echo` | Pass the expression as the sole argument |
+| Value of an **option** | `--show-config` | Append `--show-config` to any command line |
+
+**Checking a positional parameter with `config echo`**:
+
+`config echo` takes exactly **one** argument which can use the [Extended Value](#extended-value-syntax) syntax, and displays its parsed value.
 Unprocessed command line arguments are shown in the error message.
 
-Example:
-The shell parses three arguments (as `String`: `1`, `2` and `3`), so the additional two arguments are not processed by the `echo` command.
+```shell
+ascli config echo @json:'{"a":1,"b":"two"}' --format=json
+ascli config echo @: a=1 b=two --format=json
+```
+
+```json
+{"a":1,"b":"two"}
+```
+
+> [!NOTE]
+> The value is shown after both shell command-line parsing and `ascli` [Extended Value](#extended-value-syntax) parsing.
+
+Example: the shell parses three arguments (`1`, `2`, `3`), but `config echo` only processes the first:
 
 ```shell
 ascli config echo 1 2 3
@@ -2228,10 +2339,19 @@ ascli config echo 1 2 3
 ERROR: Argument: unprocessed values: ["2", "3"]
 ```
 
-`config echo` displays the value of the **first** argument using the current output `format`.
+**Checking an option value with `--show-config`**:
 
-> [!NOTE]
-> It gets its value after shell command-line parsing and `ascli` [Extended Value](#extended-value-syntax) parsing.
+Adding `--show-config` to any command line performs a dry run and displays the resolved value of all options that would be used, without executing the command.
+
+To display a specific option, add `--fields=<option_name>`.
+Add `--flat=no` when the option holds a structured value (`Hash`, `Array`) to display it as-is rather than flattened into dot-path keys:
+
+```shell
+ascli --opt=@json:'{"a":1,"b":"two"}' some_plugin --show-config --fields=opt --flat=no
+ascli --opt.a=1 --opt.b=two some_plugin --show-config --fields=opt --flat=no
+```
+
+Both lines above display the same resolved value for option `opt`.
 
 In the following examples (using a POSIX shell, such as `bash`), several equivalent commands are provided.
 For all examples, most special character handling is not specific to `ascli`:
@@ -2421,6 +2541,22 @@ Example:
 ascli config preset set demo_server password <PASSWORD>
 ```
 
+The parameter name supports **dot-notation** to set nested hash options.
+If an intermediate hash already exists, the new value is **deep-merged** into it (existing sibling keys are preserved).
+
+```shell
+ascli config preset set GLOBAL out.table.pivot single
+ascli config preset set GLOBAL out.level data
+```
+
+The parameter value is **automatically coerced** to its natural type: integers, floats and booleans (`true`/`false`) are stored as native YAML types rather than strings.
+
+To **delete** a key from a preset, pass `@none:` as the value (evaluates to `nil`):
+
+```shell
+ascli config preset set GLOBAL out.table.pivot @none:
+```
+
 A full terminal based overview of the configuration can be displayed using:
 
 ```shell
@@ -2433,6 +2569,20 @@ A list of [Option Preset](#option-preset) can be displayed using:
 ascli config preset list
 ```
 
+Any key starting with `_` (underscore) in a preset is treated as a comment and is ignored when the preset is applied.
+This is useful to annotate presets directly in the configuration file:
+
+```yaml
+demo_server:
+  _comment: "Demo server - public credentials"
+  url: ssh://demo.asperasoft.com:33001
+  username: asperaweb
+  password: demoaspera
+```
+
+> [!NOTE]
+> Comment keys are preserved and visible in `config preset overview` for inspection, but are never injected as CLI options.
+
 A good practice is to not manually edit the configuration file and use modification commands instead.
 If necessary, the configuration file can be opened in a text editor with:
 
@@ -2473,7 +2623,9 @@ Usually, [Option presets](#option-preset) are used to contain pre-defined option
 When a plugin is invoked, the preset associated with the name of the plugin is loaded, unless the option `--no-default` (or `-N`) is used.
 
 > [!NOTE]
-> Special plugin name: `config` can be associated with a preset that is loaded initially, typically used for default values.
+> The special plugin name `config` in the `default` preset points to a preset containing **global default options**
+> (such as `--log-level`, `--vault`, `--interactive`), loaded before any plugin is invoked.
+> To set global default options, use the `GLOBAL` keyword (see [Plugin: `config`](#plugin-config-configuration)).
 
 Operations on this preset are done using regular `config` operations:
 
@@ -2528,7 +2680,8 @@ When `ascli` starts, it looks for the `default` Option Preset and checks the val
 If set, it loads the options independently of the plugin used.
 
 > [!NOTE]
-> If no global default is set by the user, `ascli` will use `global_common_defaults` when setting global options (for example, `config ascp use`)
+> If `default.config` is not set, `ascli` automatically uses `global_common_defaults` as the global preset name
+> and saves that mapping in the configuration file the first time the `GLOBAL` keyword is used.
 
 > [!TIP]
 > If you do not know the name of the global preset, you can use `GLOBAL` to refer to it.
@@ -2549,13 +2702,10 @@ Set a global parameter:
 ascli config preset set GLOBAL version_check_days 0
 ```
 
-If the default global Option Preset is not set, and you want to use a different name:
+If you want to use a custom name instead of `global_common_defaults`:
 
 ```shell
 ascli config preset set default config <GLOBAL_OPTIONS_NAME>
-```
-
-```shell
 ascli config preset set GLOBAL version_check_days 0
 ```
 
@@ -2584,12 +2734,12 @@ check_update
 coffee
 coffee --log-level=trace2 --log-format=caller
 coffee --ui=text
-coffee --ui=text --image.text=true
-coffee --ui=text --image=@json:'{"text":true,"double":false}'
+coffee --ui=text --out.img.text=true
+coffee --ui=text --out.img=@json:'{"text":true,"double":false}'
 commands
 detect app.example.com
-detect https://faspex5.example.com/path
-detect https://faspex5.example.com/path faspex5
+detect https://f5.example.com/path
+detect https://f5.example.com/path faspex5
 detect https://node.example.com/path
 detect https://server.example.com/path
 detect https://shares.example.com/path shares
@@ -2600,13 +2750,13 @@ doc
 doc github transfer-parameters
 doc local quick-start --ui=text
 doc toc
-echo '<svg viewBox="0 0 100 100" xmlns="http://www.w3.org/2000/svg"><circle cx="50" cy="50" r="50" fill="#069"/></svg>' --format=image --image.text=true
+echo '<svg viewBox="0 0 100 100" xmlns="http://www.w3.org/2000/svg"><circle cx="50" cy="50" r="50" fill="#069"/></svg>' --format=image --out.img.text=true
 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 @json:'[{"user":{"id":1,"name":"foo"},"project":"bar"}]' --out.table.pivot=single
+echo @json:'[{"user":{"id":1,"name":"foo"},"project":"bar"}]' --out.table.pivot=yes
 echo @lines:@stdin:
 echo @list:,1,2,3
 echo @secret:
@@ -2643,7 +2793,7 @@ preset initialize conf_name @json:'{"p1":"v1","p2":"v2"}'
 preset list
 preset overview
 preset set GLOBAL sdk_folder 'product:IBM Aspera Connect'
-preset set GLOBAL vault @: type=file file=/secure/vault_file
+preset set GLOBAL vault @: type=file name=/secure/vault_file
 preset set GLOBAL vault_password _simple_one_
 preset set GLOBAL version_check_days 0
 preset set conf_name param value
@@ -2668,12 +2818,12 @@ transferd list
 vault create @: label=my_label password=my_password_here 'description=my secret'
 vault delete foo --vault.type=system
 vault delete my_label
+vault ids
 vault info
 vault list
 vault show my_label
 wizard https://console.example.com/path console
-wizard https://faspex4.example.com/path faspex --username=test --password=test
-wizard https://faspex5.example.com/path faspex5 --key-path=my_private_key
+wizard https://f5.example.com/path faspex5 --key-path=my_private_key
 wizard https://node.example.com/path node --username=test --password=test
 wizard https://orch.example.com/path orchestrator --username=test --password=test
 wizard https://server.example.com/path server --username=my_username --password=my_password
@@ -2783,7 +2933,7 @@ Copy the completion script to Fish's completions directory:
 cp $(gem contents aspera-cli | grep fish_autocomplete) ~/.config/fish/completions/ascli.fish
 ```
 
-No further configuration is needed — Fish loads files from `~/.config/fish/completions/` automatically.
+No further configuration is needed - Fish loads files from `~/.config/fish/completions/` automatically.
 
 Once active, press `Tab` to complete commands at any depth:
 
@@ -2833,7 +2983,7 @@ The user is told where to place the associated public key PEM in the application
 
 #### Example of configuration for a plugin
 
-For Faspex, Shares, Node (including ATS, Aspera Transfer Service), Console,
+For Faspex 5, Shares, Node (including ATS, Aspera Transfer Service), Console,
 only username/password and URL are required (either on command line, or from configuration file).
 Those can be usually provided on the command line:
 
@@ -2894,7 +3044,7 @@ For security reasons, those secrets shall not be exposed in clear, either:
 
 Instead, they shall be hidden (logs, output) or encrypted (configuration).
 
-Terminal output (command result) secret removal is controlled by option `show_secrets` (default: `no`).
+Terminal output (command result) secret removal is controlled by option `--out.secrets` (default: `no`).
 Log secret removal is controlled by option `log_secrets` (default: `no`).
 Mandatory command line options can be requested interactively (for example, password) using option `interactive`.
 It is possible to use [Extended Value](#extended-value-syntax) `@secret:[name]` to ask for a secret interactively.
@@ -2907,24 +3057,20 @@ export ASCLI_PASSWORD
 
 Another possibility is to retrieve values from a secret vault.
 
-The vault is used with options `vault` and `vault_password`.
-
-`vault` shall be a `Hash` describing the vault:
-
-```json
-{"type":"system","name":"ascli"}
-```
-
-`vault_password` specifies the password for the vault.
-
-Although it can be specified on command line, for security reason you should avoid exposing the secret.
-For example, it can be securely specified on command line like this:
+The vault is configured with option `vault` (a `Hash` describing the vault type and parameters, see sections below) and unlocked with option `vault_password`.
+To avoid exposing the vault password in the shell history, provide it via an environment variable:
 
 ```shell
-read -s ASCLI_VAULT_PASSWORD
-export ASCLI_VAULT_PASSWORD
+export ASCLI_VAULT_PASSWORD=<YOUR_PASSWORD>
 ```
 
+> [!TIP]
+> Set it interactively using `read` so that it is not recorded in the shell history:
+>
+> ```shell
+> read -rs ASCLI_VAULT_PASSWORD && export ASCLI_VAULT_PASSWORD
+> ```
+
 #### Vault: IBM HashiCorp Vault
 
 <https://developer.hashicorp.com/vault>
@@ -2949,6 +3095,14 @@ vault server -dev -dev-root-token-id=dev-only-token
 | **type** | `String` | `file`: Encrypted file secret store. |
 | `name` | `String` | Path to the encrypted vault file. Relative paths are resolved from the configuration folder.<br/>Default: `vault.bin`. |
 | `type` | `String` | Vault type selector.<br/>Allowed values: `file`. |
+| **type** | `String` | `1password`: 1Password secret store (Connect REST API or CLI). |
+| `account` | `String` | Account shorthand for `op` (used when `source` is `cli`). Uses the default account if omitted. |
+| `source` | `String` | Backend source. Use `api` for the Connect REST API, `cli` for the `op` CLI.<br/>Allowed values: `api`, `cli`.<br/>Default: `api`. |
+| `token` | `String` | Bearer token for the Connect API (required when `source` is `api`). Defaults to the value of `vault_password`. |
+| `type` | `String` | Vault type selector.<br/>Allowed values: `1password`. |
+| `url` | `String` | Base URL of the 1Password Connect server (required when `source` is `api`).<br/>Example: `http://localhost:8080`. |
+| `vault_id` | `String` | ID of the 1Password vault to use (required when `source` is `api`). |
+| `vault` | `String` | Name or ID of the 1Password vault to use with the CLI (used when `source` is `cli`). Uses the default vault if omitted. |
 
 ```shell
 --vault=@json:'{"type":"vault","url":"http://127.0.0.1:8200"}' --vault_password=dev-only-token
@@ -2973,21 +3127,106 @@ It is possible to store and use secrets encrypted in a file using option `vault`
 {"type":"file","name":"vault.bin"}
 ```
 
-#### Vault: Operations
+To configure the encrypted file vault as the default, set the `vault` option in the global preset:
+
+```shell
+ascli config preset set GLOBAL vault @: type=file name=vault.bin
+```
+
+The vault file is created automatically on first use - no explicit initialization is needed.
+
+> [!WARNING]
+> The `vault_password` option should **not** be stored in the config file: doing so would protect secrets with a password that is itself stored in plain text, defeating the purpose of the vault.
+> Use an environment variable as described above.
+
+#### Vault: 1Password
+
+Use `type: 1password` with a `source` parameter to select the backend.
 
-For this use the `config vault` command.
+##### Source: API (Connect REST API)
 
-Then secrets can be manipulated using commands:
+<https://developer.1password.com/docs/connect/>
+
+[1Password Connect](https://developer.1password.com/docs/connect/) exposes a local REST API backed by a 1Password vault.
+Deploy the Connect server with Docker, then point `ascli` at it:
+
+```shell
+docker run -d --name op-connect \
+  -p 8080:8080 \
+  -v /path/to/1password-credentials.json:/home/opuser/.op/1password-credentials.json \
+  1password/connect-api:latest
+```
+
+```shell
+--vault=@json:'{"type":"1password","source":"api","url":"http://localhost:8080","vault_id":"<VAULT_ID>"}' \
+--vault_password=<CONNECT_TOKEN>
+```
+
+> [!TIP]
+> The `vault_id` is the alphanumeric ID shown in the 1Password web app under **Vault Settings**.
+> The `vault_password` holds the Connect bearer token generated when creating the Connect server credentials.
+
+> [!NOTE]
+> The [1Password Service Accounts API](https://developer.1password.com/docs/service-accounts/) is also supported: use `url=https://api.1password.com` with a service account token as `vault_password`.
+> No local server is required in that case.
+
+##### Source: Cli (`op` CLI)
+
+<https://developer.1password.com/docs/cli/>
+
+Requires the `op` CLI to be installed and signed in.
+No server to deploy — authentication is handled by the 1Password desktop app (biometric unlock) or by `op signin`.
+
+```shell
+--vault=@json:'{"type":"1password","source":"cli"}'
+# or, to target a specific vault and account:
+--vault=@json:'{"type":"1password","source":"cli","vault":"<VAULT_NAME>","account":"<ACCOUNT_SHORTHAND>"}'
+```
+
+> [!TIP]
+> Install `op` on macOS with `brew install 1password-cli`, then connect it to the desktop app:
+> `op signin`
+
+#### Vault: Operations
+
+Secrets can be manipulated using the `config vault` command:
 
 - `create`
 - `show`
 - `list`
 - `delete`
+- `import`
+
+To add a new password entry in the vault for label `<NAME>`:
+
+```shell
+ascli config vault create @: label=<NAME> password=@secret:password description='for this account'
+```
+
+#### Vault: Migration between vaults
+
+To migrate all secrets from one vault backend to another (for example, from the encrypted file vault to 1Password), use `vault overview` piped into `vault import`.
+
+> [!NOTE]
+> Use `overview` (not `list`) as the source: `list` returns only labels, while `overview` returns the full secret details needed for import.
 
 ```shell
-ascli config vault create @json:'{"label":"<NAME>","password":"<PASSWORD>","description":"for this account"}'
+ascli config vault overview --format=json --out.level=data \
+  --vault=@json:'{"type":"file","name":"<SOURCE_VAULT_FILE>"}' \
+  --vault_password=<SOURCE_PASSWORD> | \
+ascli config vault import @json:@stdin: --bulk \
+  --vault=@json:'{"type":"1password","url":"<CONNECT_URL>","vault_id":"<VAULT_ID>"}' \
+  --vault_password=<CONNECT_TOKEN>
 ```
 
+> [!TIP]
+> Use `--out.level=data` on the `overview` command so that only the raw JSON array is written to stdout, with no table headers or status lines.
+
+The `import` command accepts a JSON array where each element is a vault secret object (same schema as `create`).
+`--bulk` makes each entry reported individually in the result table; omit it to get a single-line summary.
+On error (for example a duplicate label), the default behavior is to stop (`--bfail=yes`).
+Pass `--bfail=no` to skip failures and continue with the remaining entries.
+
 #### Configuration Finder
 
 When a secret is needed by a sub command, the command can search for existing configurations in the configuration file by setting option `secret` to the special value `PRESET`.
@@ -3003,25 +3242,37 @@ Example:
 ascli config preset update <PRESET_NAME> --url=... --username=... --password=...
 ```
 
-For a more secure storage one can do:
+For more secure storage, first create a vault entry (see [Vault: Operations](#vault-operations)), then refer to it in the preset:
 
 ```shell
 ascli config preset update <PRESET_NAME> --url=... --username=... --password=@val:@vault:<VAULT_LABEL>.password
 ```
 
+> [!NOTE]
+> Use `@val:` in front of `@vault:` so that the [Extended Value](#extended-value-syntax) is not evaluated.
+
+To migrate existing clear-text passwords from presets to the vault in one step, use the `secure` command.
+The vault must already be configured (option `vault`, see [Secret Vault](#secret-vault)).
+
 ```shell
-ascli config vault create @json:'{"label":"<VAULT_LABEL>","password":"<PASSWORD>"}'
+ascli config preset secure
 ```
 
-> [!NOTE]
-> Use `@val:` in front of `@vault:` so that the [Extended Value](#extended-value-syntax) is not evaluated.
+This scans all presets (or a single one if a name is provided) and, for every option whose name ends with `password` or `secret`, moves the value into the vault and replaces it with a `@vault:` reference.
+
+```shell
+ascli config preset secure <PRESET_NAME>
+```
+
+When a vault is configured, the `update`, `set`, and `ask` preset commands automatically move secret values (options ending with `password` or `secret`) into the vault as they are written, so no manual migration is needed.
+To disable this behavior for a single command, pass `--vault=@none:`.
 
 ### Private Key
 
 Some Aspera applications allow the user to be authenticated using [Public Key Cryptography](https://en.wikipedia.org/wiki/Public-key_cryptography):
 
 - For SSH: Server
-- For OAuth JWT: AoC, Faspex5, Faspex, Shares
+- For OAuth JWT: AoC, Faspex5, Shares
 
 It consists in using a pair of associated keys: a private key and a public key.
 The same pair can be used for multiple applications.
@@ -3157,7 +3408,7 @@ Examples:
 - Display image as colorized text (requires `rmagick`)
 
 ```shell
-ascli config image https://eudemo.asperademo.com/wallpaper.jpg --ui=text --image.text=true
+ascli config image https://eudemo.asperademo.com/wallpaper.jpg --ui=text --out.img.text=true
 ```
 
 - Display image from byte stream as image in terminal (requires iTerm2-compatible terminal)
@@ -3574,12 +3825,10 @@ Parameters in transfer-spec can be modified with option `ts`.
 
 #### Asynchronous Transfer Mode
 
-For agents that delegate transfers to an external daemon (`desktop`, `node`, `connect`, `transferd`),
-the transfer lives entirely in that daemon — `ascli` does not need to stay connected while it runs.
 Adding `asynchronous: true` to the `transfer` option makes `ascli` return immediately after
 submitting the transfer, without waiting for completion.
 
-The returned `job_id` can be used at any time, even in a later invocation, to check progress:
+The returned `job_id` can be used at any time to check progress:
 
 ```shell
 # Start a download and return immediately
@@ -3596,21 +3845,28 @@ ascli config transfer list
 ascli config transfer cleanup
 ```
 
-| Agent | Async support | Status source |
-|---|---|---|
-| `desktop` | ✅ | JSON-RPC `get_transfer` (auto-discovered URL) |
-| `node` | ✅ | REST `ops/transfers/{id}` |
-| `connect` | ✅ | REST `transfers/info/{id}` (auto-discovered URL) |
-| `transferd` | ✅ | gRPC `monitor_transfers` |
-| `direct` | ✅ in-process only | `@sessions` (not persisted across process restarts) |
-| `httpgw` | ❌ | Synchronous by nature — error if requested |
+All transfer agents support asynchronous mode:
+
+| Agent       | Status source                                                                 | Persisted across restart |
+| ----------- | ----------------------------------------------------------------------------- | ------------------------ |
+| `desktop`   | JSON-RPC `get_transfer` (auto-discovered URL)                                 | Yes |
+| `node`      | REST `ops/transfers/{id}`                                                     | Yes |
+| `connect`   | REST `transfers/info/{id}` (auto-discovered URL)                              | Yes |
+| `transferd` | gRPC `monitor_transfers`                                                      | Yes |
+| `direct`    | In-process thread state (re-queryable while process lives, e.g. MCP mode)    | No — returns `unknown` after restart |
+| `httpgw`    | In-process thread state (re-queryable while process lives, e.g. MCP mode)    | No — returns `unknown` after restart |
+
+For `direct` and `httpgw`, the transfer runs as a Ruby thread inside the `ascli` process.
+The `job_id` is persisted on disk but the live thread state is only available as long as the same process is running.
+If the process is restarted, `config transfer status` returns `unknown` for those jobs.
 
 > [!NOTE]
-> **`asynchronous` and MCP** — When `ascli` is used as an MCP server, an AI assistant calling
+> **`asynchronous` and MCP** - When `ascli` is used as an MCP server, an AI assistant calling
 > a transfer command may time out or cancel the request and retry, causing duplicate transfers.
-> Using `asynchronous: true` eliminates this risk: the transfer is submitted once to the external
-> daemon, the `job_id` is returned immediately, and the AI can poll
+> Using `asynchronous: true` eliminates this risk: the transfer is submitted immediately,
+> the `job_id` is returned, and the AI can poll
 > `config transfer status <job_id>` to track progress without any risk of duplication.
+> This works with all agents, including `direct` and `httpgw`.
 
 #### Agent: Direct
 
@@ -3651,14 +3907,14 @@ max( sleep_max, sleep_initial * sleep_factor ^ iter_index )
 To display the native progress bar of `ascp`, use:
 
 ```shell
---progress-bar=no --transfer.quiet=false`
+--progress-bar=no --transfer.quiet=false
 ```
 
 To skip usage of management port (which disables custom progress bar), set option `monitor` to `false`.
 In that, use the native progress bar:
 
 ```shell
---transfer.monitor=false --transfer.quiet=false`
+--transfer.monitor=false --transfer.quiet=false
 ```
 
 By default, Ruby's root CA store is used to validate any HTTPS endpoint used by `ascp` (for example, WSS).
@@ -3936,7 +4192,7 @@ Parameters provided in option `transfer` are:
 Example:
 
 ```shell
-ascli faspex package recv 323 --transfer.url=https://asperagw.example.com:9443/aspera/http-gwy --transfer=httpgw
+ascli faspex5 packages recv 323 --transfer.url=https://asperagw.example.com:9443/aspera/http-gwy --transfer=httpgw
 ```
 
 > [!NOTE]
@@ -4019,7 +4275,7 @@ To remove a (deep) key from transfer spec, set the value to `null`.
 > Default transfer spec values can be displayed with command:
 
 ```shell
-ascli config ascp info --fields=ts --flat-hash=no
+ascli config ascp info --fields=ts --out.flat=no
 ```
 
 It is possible to specify `ascp` options when the `transfer` option is set to [`direct`](#agent-direct) using `transfer` option parameter: `ascp_args`.
@@ -4086,7 +4342,7 @@ ascli config ascp schema transferd --format=jsonpp
 | T | Transferd |
 
 | Field | Type | Description |
-|--------------------------------|-----------------------|----------------------------------------------------------------------------------|
+|--------------------------------|-----------------|----------------------------------------------------------------------------------|
 | `apply_local_docroot` | `Bool` | Apply local docroot to source paths.<br/>(A, T)<br/>(`--apply-local-docroot`) |
 | `authentication` | `String` | Set to `token` for SSH bypass keys, else password asked if not provided.<br/>(C) |
 | `cipher_allowed` | `String` | Returned by node API. Valid literals include `aes-128` and `none`.<br/>(C)<br/>Allowed values: `none`, `aes-128`, `aes-192`, `aes-256`, `aes-128-cfb`, `aes-192-cfb`, `aes-256-cfb`, `aes-128-gcm`, `aes-192-gcm`, `aes-256-gcm`. |
@@ -4108,7 +4364,7 @@ ascli config ascp schema transferd --format=jsonpp
 | `fasp_proxy` | `Hash` | Proxy for communications between the remote server and the (local) client.<br/>(T) |
 | `file_checksum` | `String` | Enable checksum reporting for transferred files by specifying the hash to use.<br/>(A, N)<br/>Allowed values: `sha-512`, `sha-384`, `sha-256`, `sha1`, `md5`, `none`.<br/>Default: `none`.<br/>(`--file-checksum={enum}`) |
 | `http_fallback_port` | `Integer` | Specifies HTTP port when no cipher is used.<br/>(`-t {integer}`) |
-| `http_fallback` | `["boolean", "string"]` | When true(1), attempts to perform an HTTP transfer if a FASP transfer cannot be performed.<br/>(`-y (conversion){boolean\|string}`) |
+| `http_fallback` | `Bool, String` | When true(1), attempts to perform an HTTP transfer if a FASP transfer cannot be performed.<br/>(`-y (conversion){boolean\|string}`) |
 | `https_fallback_port` | `Integer` | Specifies HTTPS port when cipher is used.<br/>(`-t {integer}`) |
 | `icos` | `Hash` | Configuration parameters for IBM Cloud Object Storage (ICOS).<br/>(T) |
 | `keepalive` | `Bool` | The session is running in persistent session mode.<br/>(A, T)<br/>(`--keepalive`) |
@@ -4137,7 +4393,7 @@ ascli config ascp schema transferd --format=jsonpp
 | `preserve_remote_acls` | `String` | Preserve remote access control lists.<br/>(A, T)<br/>Allowed values: `none`, `native`, `metafile`.<br/>Default: `none`.<br/>(`--remote-preserve-acls={enum}`) |
 | `preserve_remote_extended_attrs` | `String` | Preserve remote extended attributes.<br/>(A, T)<br/>Allowed values: `none`, `native`, `metafile`.<br/>Default: `none`.<br/>(`--remote-preserve-xattrs={enum}`) |
 | `preserve_source_access_time` | `Bool` | Preserve the time logged for when the source file was accessed.<br/>(A, T)<br/>(`--preserve-source-access-time`) |
-| `preserve_times` | `Bool` | Preserve file timestamps.<br/>(A, N, T)<br/>(`-p {boolean}`) |
+| `preserve_times` | `Bool` | Preserve file timestamps.<br/>(A, N, T)<br/>(`-p`) |
 | `proxy` | `String` | Specify the address of the Aspera high-speed proxy server.<br/>`dnat(s)://[user[:password]@]server:port`<br/>Default ports for DNAT and DNATS protocols are 9091 and 9092.<br/>Password, if specified here, overrides the value of environment variable `ASPERA_PROXY_PASS`.<br/>(A)<br/>(`--proxy={string}`) |
 | `rate_policy_allowed` | `String` | Specifies most aggressive rate policy that is allowed. Returned by node API.<br/>(C)<br/>Allowed values: `low`, `fair`, `high`, `fixed`. |
 | `rate_policy` | `String` | The transfer rate policy to use when sharing bandwidth. Allowable values:<br/>- `high` : When sharing bandwidth, transfer at twice the rate of a transfer using a fair policy.<br/>- `fair` : (Default) Share bandwidth equally with other traffic.<br/>- `low` : Use only unused bandwidth.<br/>- `fixed` : Transfer at the target rate, regardless of the actual network capacity. Do not share bandwidth. Aspera recommends that you do not use this setting except under special circumstances,  otherwise the destination storage can be damaged.<br/>Allowed values: `low`, `fair`, `high`, `fixed`.<br/>(`--policy={enum}`) |
@@ -4151,7 +4407,7 @@ ascli config ascp schema transferd --format=jsonpp
 | `remove_empty_source_directory` | `Bool` | Remove empty source subdirectories and remove the source directory itself, if empty.<br/>(A)<br/>(`--remove-empty-source-directory`) |
 | `remove_skipped` | `Bool` | Must also have `remove_after_transfer` set to `true`. Defaults to `false`. If `true`, skipped files will be removed as well.<br/>(A, C, N)<br/>(`--remove-skipped`) |
 | `resume_policy` | `String` | If a transfer is interrupted or fails to finish, this policy directs the transfer to resume without retransferring the files. Allowable values:<br/>- `none` : Always re-transfer the entire file.<br/>- `attrs` : Compare file attributes and resume if they match, and re-transfer if they do not.<br/>- `sparse_csum` : Compare file attributes and the sparse file checksums; resume if they match, and re-transfer if they do not.<br/>- `full_csum` : Compare file attributes and the full file checksums; resume if they match, and re-transfer if they do not.<br/>Note: transferd uses values: `attributes`, `sparse_checksum`, `full_checksum`.<br/>Allowed values: `none`, `attrs`, `sparse_csum`, `full_csum`.<br/>Default: `faspmgr:none;other:sparse_csum`.<br/>(`-k (conversion){enum}`) |
-| `retry_duration` | `["integer", "string"]` | Specifies how long to wait before retrying transfer (e.g. `5min`).<br/>(T) |
+| `retry_duration` | `Integer, String` | Specifies how long to wait before retrying transfer (e.g. `5min`).<br/>(T) |
 | `save_before_overwrite` | `Bool` | If a transfer would result in an existing file <filename>.<ext> being overwritten, move that file to <filename>.yyyy.mm.dd.hh.mm.ss.index.<ext> (where index is set to 1 at the beginning of each new second and incremented for each file saved in this manner during the same second) in the same directory  before writing the new file.<br/>File attributes are maintained in the renamed file.<br/>(A, N, T)<br/>(`--save-before-overwrite`) |
 | `skip_duplicate_check` | `Bool` | Don't check for duplicate files at the destination.<br/>(A, T)<br/>(`--skip-dir-traversal-dupes`) |
 | `skip_special_files` | `Bool` | All assets other than files, directories and symbolic links are considered special. A transfer will fail if the user attempts to transfer special assets. If `true`, `ascp` skips special assets and proceeds with the transfer of all other assets.<br/>(A, T)<br/>(`--skip-special-files`) |
@@ -4501,7 +4757,7 @@ Define a name for the server, for example: `ascli_job` as `<NAME>` below.
 
     [Service]
     Type=oneshot
-    ExecStart=/home/xfer/bin/ascli_tool preview scan --logger=syslog --display=error
+    ExecStart=/home/xfer/bin/ascli_tool preview scan --logger=syslog --out.level=error
     User=xfer
     Group=xfer
     ```
@@ -4554,8 +4810,8 @@ Example of `crontab` for user `xfer`.
 
 ```shell
 crontab<<EOF
-0    * * * *  /home/xfer/bin/ascli_tool preview scan --logger=syslog --display=error
-2-59 * * * *  /home/xfer/bin/ascli_tool preview trev --logger=syslog --display=error
+0    * * * *  /home/xfer/bin/ascli_tool preview scan --logger=syslog --out.level=error
+2-59 * * * *  /home/xfer/bin/ascli_tool preview trev --logger=syslog --out.level=error
 EOF
 ```
 
@@ -4865,10 +5121,10 @@ Key query parameters:
 ```text
 ascli -h
 NAME
-        ascli -- a command line tool for Aspera Applications (v4.27.0)
+        ascli -- a command line tool for Aspera Applications (v4.27.2)
 
 SYNOPSIS
-        ascli COMMANDS [OPTIONS] [ARGS]
+        ascli [GLOBAL_OPTIONS] <command> [OPTIONS] [ARGS]
 
 DESCRIPTION
         Use Aspera application to perform operations on command line.
@@ -4887,79 +5143,80 @@ COMMANDS
 OPTIONS
         Options begin with a '-' (minus), and value is provided on command line.
         Special values are supported beginning with special prefix @pfx:, where pfx is one of:
-        val, base64, csvt, env, file, uri, json, lines, list, none, path, re, ruby, s, secret, stdin, yaml, zlib, extend, , preset, vault
-        Dates format is 'DD-MM-YY HH:MM:SS', or 'now' or '-<num>h'
+        val, base64, csvt, env, file, uri, json, lines, list, none, path, re, ruby, s, secret, stdin, yaml, zlib, extend, preset, vault
+        Dates format is 'YYYY-MM-DD HH:MM:SS', or 'now' or '-<num>h'
 
 ARGS
         Some commands require mandatory arguments, e.g. a path.
 
-OPTIONS: config
-    --interactive=ENUM          Use interactive input of missing params
-    --ask-options=ENUM          Ask even optional options
-    --display=ENUM              Output only some information
-    --format=ENUM               Output format
-    --output=VALUE              Destination for results
-    --fields=VALUE              Comma separated list of: fields, or ALL, or DEF
-    --select=VALUE              Select only some items in lists: column, value
-    --table-style=VALUE         (Table) Display style
-    --flat-hash=ENUM            (Table) Display deep values as additional keys
-    --multi-single=ENUM         (Table) Control how object list is displayed as single table, or multiple objects
-    --show-secrets=ENUM         Show secrets on command output
-    --image=VALUE               Options for displaying images and thumbnails in the terminal
--h, --help                      Show this message
-    --show-config               Display parameters used for the provided action
--v, --version                   Display version
-    --ui=ENUM                   Method to start browser
-    --invalid-characters=VALUE  Replacement character and invalid filename characters
-    --log-level=ENUM            Log level
-    --log-format=VALUE          Log formatter
-    --logger=ENUM               Logging method
-    --log=VALUE                 Logging options (dot-notation: level, type, format, secrets)
-    --lock-port=VALUE           Prevent dual execution of a command, e.g. in cron
-    --once-only=ENUM            Process only new items (some commands)
-    --log-secrets=ENUM          Show passwords in logs
-    --clean-temp=ENUM           Cleanup temporary files on exit
-    --temp-folder=VALUE         Temporary folder
-    --pid-file=VALUE            Write process identifier to file, delete on exit
-    --parser=ENUM               Default parser for structured parameters and options
-    --home=VALUE                Home folder for tool
-    --config-file=VALUE         Path to YAML file with preset configuration
-    --secret=VALUE              Secret for access keys
-    --vault=VALUE               Secret vault configuration
-    --vault-password=VALUE      Vault password
-    --progress-bar=ENUM         Display progress bar
-    --fpac=VALUE                Proxy auto configuration script
-    --proxy-credentials=VALUE   HTTP proxy credentials for fpac: user, password
-    --sql=VALUE                 SQL suffix appended to sqlite3 queries for admin subcommands (e.g. WHERE clause)
--P, --preset=VALUE              Load the named option preset from current config file
-    --version-check-days=VALUE  Period in days to check new version (zero to disable)
-    --plugin-folder=VALUE       Folder where to find additional plugins
-    --sdk-url=VALUE             Ascp: URL to get Aspera Transfer Executables
-    --locations-url=VALUE       Ascp: URL to get download locations of Aspera Transfer Daemon
-    --sdk-folder=VALUE          Ascp: Path to folder with ascp (or product with "product:")
-    --smtp=VALUE                SMTP email server configuration
-    --notify-to=VALUE           Email: Recipient for notification of transfers
-    --notify-template=VALUE     Email: ERB template for notification of transfers
-    --cache-tokens=ENUM         Save and reuse OAuth tokens
-    --query=VALUE               Additional filter for for some commands (list/delete)
-    --bulk=ENUM                 Bulk operation (only some)
-    --bfail=ENUM                Bulk operation error handling
--N, --no-default                Do not load default configuration for plugin
-    --override=ENUM             Wizard: override existing value
-    --default=ENUM              Wizard: set as default configuration for specified plugin (also: update)
-    --key-path=VALUE            Wizard: path to private key for JWT
-    --insecure=ENUM             HTTP/S: Do not validate any certificate
-    --ignore-certificate=VALUE  HTTP/S: Do not validate certificate for these URLs
-    --warn-insecure=ENUM        HTTP/S: Issue a warning if certificate is ignored
-    --cert-stores=VALUE         HTTP/S: List of folder with trusted certificates
-    --http-options=VALUE        HTTP/S connection parameters for REST calls (not `ascp` WSS)
-    --http-proxy=VALUE          HTTP/S: URL for proxy with optional credentials
-    --ts=VALUE                  Override transfer spec values
-    --to-folder=VALUE           Destination folder for transferred files
-    --sources=VALUE             How list of transferred files is provided (@args,@ts,Array)
-    --src-type=ENUM             Type of file list
-    --transfer=VALUE            Transfer agent type, or agent parameters with optional agent key
-    --transfer-info=VALUE       Parameters for transfer agent
+OPTIONS: global
+    --interactive=yes|no           Use interactive input of missing params
+    --ask-options=yes|no           Ask even optional options
+    --out=HASH                     Output rendering options (dot-notation: format, level, file, fields, select, table[.pivot], flat, secrets, img)
+    --display=info|data|error      Output only some information (deprecated: use --out.level)
+    --format=ENUM                  Output format (also: --out.format)
+    --output=VALUE                 Destination for results (deprecated: use --out.file)
+    --fields=LIST                  Comma separated list of: fields, or ALL, or DEF (also: --out.fields)
+    --select=HASH                  Select only some items in lists: column, value (also: --out.select)
+    --table-style=HASH             (Table) Display style (deprecated: use --out.table)
+    --flat-hash=yes|no             (Table) Display deep values as additional keys (deprecated: use --out.flat)
+    --multi-single=no|yes|single   (Table) Control how object list is displayed as single table, or multiple objects (deprecated: use --out.table.pivot)
+    --show-secrets=yes|no          Show secrets on command output (deprecated: use --out.secrets)
+    --image=HASH                   Options for displaying images and thumbnails in the terminal (deprecated: use --out.img)
+-h, --help                         Show this message
+    --show-config                  Display parameters used for the provided action
+-v, --version                      Display version
+    --ui=text|graphical            Method to start browser
+    --invalid-characters=VALUE     Replacement character and invalid filename characters
+    --log-level=ENUM               Log level
+    --log-format=VALUE             Log formatter
+    --logger=stderr|stdout|syslog  Logging method
+    --log=HASH                     Logging options (dot-notation: level, type, format, secrets)
+    --lock-port=INT                Prevent dual execution of a command, e.g. in cron
+    --once-only=yes|no             Process only new items (some commands)
+    --log-secrets=yes|no           Show passwords in logs
+    --clean-temp=yes|no            Cleanup temporary files on exit
+    --temp-folder=VALUE            Temporary folder
+    --pid-file=VALUE               Write process identifier to file, delete on exit
+    --parser=none|json|ruby|yaml   Default parser for structured parameters and options
+    --home=VALUE                   Home folder for tool
+    --config-file=VALUE            Path to YAML file with preset configuration
+    --secret=VALUE                 Secret for access keys
+    --vault=HASH                   Secret vault configuration
+    --vault-password=VALUE         Vault password
+    --progress-bar=yes|no          Display progress bar
+    --fpac=VALUE                   Proxy auto configuration script
+    --proxy-credentials=LIST       HTTP proxy credentials for fpac: user, password
+    --sql=VALUE                    SQL suffix appended to sqlite3 queries for admin subcommands (e.g. WHERE clause)
+-P, --preset=VALUE                 Load the named option preset from current config file
+    --version-check-days=INT       Period in days to check new version (zero to disable)
+    --plugin-folder=VALUE          Folder where to find additional plugins
+    --sdk-url=VALUE                Ascp: URL to get Aspera Transfer Executables
+    --locations-url=VALUE          Ascp: URL to get download locations of Aspera Transfer Daemon
+    --sdk-folder=VALUE             Ascp: Path to folder with ascp (or product with "product:")
+    --smtp=HASH                    SMTP email server configuration
+    --notify-to=VALUE              Email: Recipient for notification of transfers
+    --notify-template=VALUE        Email: ERB template for notification of transfers
+    --cache-tokens=yes|no          Save and reuse OAuth tokens
+    --query=HASH                   Additional filter for for some commands (list/delete)
+    --bulk=yes|no                  Bulk operation (only some)
+    --bfail=yes|no                 Bulk operation error handling
+-N, --no-default                   Do not load default configuration for plugin
+    --override=yes|no              Wizard: override existing value
+    --default=yes|no               Wizard: set as default configuration for specified plugin (also: update)
+    --key-path=VALUE               Wizard: path to private key for JWT
+    --insecure=yes|no              HTTP/S: Do not validate any certificate
+    --ignore-certificate=LIST      HTTP/S: Do not validate certificate for these URLs
+    --warn-insecure=yes|no         HTTP/S: Issue a warning if certificate is ignored
+    --cert-stores=LIST             HTTP/S: List of folder with trusted certificates
+    --http-options=HASH            HTTP/S connection parameters for REST calls (not `ascp` WSS)
+    --http-proxy=VALUE             HTTP/S: URL for proxy with optional credentials
+    --ts=HASH                      Override transfer spec values
+    --to-folder=VALUE              Destination folder for transferred files
+    --sources=VALUE                How list of transferred files is provided (@args,@ts,Array)
+    --src-type=list|pair           Type of file list
+    --transfer=HASH                Transfer agent type, or agent parameters with optional agent key
+    --transfer-info=HASH           Parameters for transfer agent (deprecated: use --transfer instead)
 
 PLUGINS
     alee            Aspera License Entitlement Engine
@@ -4967,7 +5224,6 @@ PLUGINS
     ats             Aspera Transfer Service
     console         Console
     cos             IBM Cloud Object Storage
-    faspex          Faspex v4
     faspex5         Faspex v5
     faspio          faspio Gateway
     httpgw          HTTP Gateway
@@ -5011,8 +5267,6 @@ For example: `--query=@json:'{"p[]":["v1","v2"]}'` leads to query: `?p[]=v1&p[]=
 `ascli` uses a plugin mechanism.
 The first level command (just after `ascli` on the command line) is the name of the concerned plugin which will execute the command.
 Each plugin usually represents commands sent to a specific application.
-For instance, the plugin `faspex` allows operations on **Aspera Faspex**.
-
 Available plugins can be found using command:
 
 ```shell
@@ -5031,7 +5285,7 @@ ascli config plugin list
 
 Most plugins will take the URL option: `url` to identify their location.
 
-REST APIs of Aspera legacy applications (Aspera Node, Faspex 4, Shares, Console, Orchestrator) use simple username/password authentication: HTTP Basic Authentication using options: `username` and `password`.
+REST APIs of Aspera legacy applications (Aspera Node, Shares, Console, Orchestrator) use simple username/password authentication: HTTP Basic Authentication using options: `username` and `password`.
 
 Aspera on Cloud and Faspex 5 rely on OAuth.
 
@@ -5257,10 +5511,9 @@ ascli config echo "@json:$(@{ k = $var; x = $true } | ConvertTo-Json -Compress)"
 
 Some values provided to `ascli` (options, **Command Parameters**) are expected to be [Extended Value](#extended-value-syntax), that is, not a simple `String`, but a composite structure (`Hash`, `Array`).
 
-Typically, the `@json:` modifier is used, it expects a [JSON](https://www.json.org/) value.
-JSON itself has some special syntax: for example `"` is used to enclose a `String` which may be difficult to specify in shells for whom it is a special character.
-
-The [dot-path](#dot-path-notation) can also be used and can be easier to use because it does usually not require special characters.
+For small structures with a few keys, the [dot-path](#dot-path-notation) `key.subkey=value` notation (using `@:` to collect positional arguments, or `--opt.key=value` directly for options) is often the most convenient: it requires no quoting and reads naturally on the command line.
+For larger or more complex structures (deep nesting, arrays of hashes, values copied from API documentation), the `@json:` modifier is typically a better fit.
+`@json:` expects a [JSON](https://www.json.org/) value; note that `"` is used to enclose a `String` in JSON, which may be difficult to specify in shells — enclose the whole argument in single quotes to avoid this.
 
 Any option or **Command Parameter** expecting a `Hash` value accepts the special value `help` to display its schema.
 See [Schema Discovery with `help`](#schema-discovery-with-help).
@@ -5788,7 +6041,9 @@ 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](#extended-value-syntax) syntax, generally provided using: `--query=@json:{...}`.
+It expects a `Hash` using [Extended Value](#extended-value-syntax) syntax.
+For a single filter key, the dot-path option form is the most direct (for example, `--query.sort=name`).
+For multiple keys or values copied from API documentation, `--query=@json:{...}` is more suitable.
 Values are directly sent to the API call and used as a filter on server side.
 
 The following parameters are supported:
@@ -6019,7 +6274,7 @@ ascli aoc admin user list --query.q=dummyuser --fields=id,email
 ```
 
 ```shell
-ascli aoc admin user list --query.q=dummyuser --fields=id --display=data --format=csv | ascli aoc admin user delete @lines:@stdin: --bulk=yes
+ascli aoc admin user list --query.q=dummyuser --fields=id --out.level=data --format=csv | ascli aoc admin user delete @lines:@stdin: --bulk=yes
 ```
 
 ```text
@@ -6149,7 +6404,7 @@ WS2ID=$(ascli aoc admin workspace list --query=@json:'{"q":"'"$WS2"'"}' --select
 c- Extract membership information
 
 ```shell
-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
+ascli aoc admin workspace_membership list --fields=manager,member_id,member_type,workspace_id --query=@json:'{"workspace_id":'"$WS1ID"'}' --format=jsonpp --out.file=ws1_members.json
 ```
 
 d- Convert to creation data for second workspace:
@@ -6224,7 +6479,7 @@ ascli aoc admin workspace_membership create @json:'{"workspace_id":<WORKSPACE_ID
 - Get a user's ID
 
 ```shell
-ascli aoc admin 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 --out.level=data
 ```
 
 User: <USER_ID>
@@ -6305,13 +6560,13 @@ Follow these steps to configure a new HSTS and link it to your existing Aspera o
   This key remains constant for the lifetime of your Organization.
 
 ```shell
-ascli aoc admin organization show --fields=oauth_token_verification_key --show-secrets=yes --output=mypubkey.pem
+ascli aoc admin organization show --fields=oauth_token_verification_key --out.secrets=yes --out.file=mypubkey.pem
 ```
 
   It can also be retrieved from an existing node:
 
 ```shell
-ascli aoc admin node do %name:'<NODE_NAME>' v3 access_keys show self --fields=token_verification_key --show-secrets=yes --output=mypubkey.pem
+ascli aoc admin node do %name:'<NODE_NAME>' v3 access_keys show self --fields=token_verification_key --out.secrets=yes --out.file=mypubkey.pem
 ```
 
 - Create an Access Key on the Self-Managed HSTS
@@ -6321,7 +6576,7 @@ ascli aoc admin node do %name:'<NODE_NAME>' v3 access_keys show self --fields=to
 > [!TIP]
 > In this command, "master node credentials" allowing access key creation are used.
 > The `id` and `secret` parameters are optional.
-> If you omit them, you must add `--show-secrets=yes` to the command.
+> If you omit them, you must add `--out.secrets=yes` to the command.
 > Record the generated secret immediately; it cannot be retrieved later, only reset.
 
 ```shell
@@ -6366,7 +6621,7 @@ ascli node access_key do self permission / create @: access_type=user access_id=
 The following command will create and display a secret token to register a self-managed Aspera Transfer Server:
 
 ```shell
-ascli aoc admin client_registration_token create @json:'{"data":{"name":"laurentnode","client_subject_scopes":["alee","aejd"],"client_subject_enabled":true}}' --fields=token --show-secrets=yes
+ascli aoc admin client_registration_token create @json:'{"data":{"name":"laurentnode","client_subject_scopes":["alee","aejd"],"client_subject_enabled":true}}' --fields=token --out.secrets=yes
 ```
 
 #### Example: Create an ATS Node
@@ -6427,7 +6682,7 @@ This is a two-steps procedure:
    Or, alternatively:
 
    ```shell
-   ascli aoc admin application instance list --query.aspera_app_type=packages --query.workspace_id=<WORKSPACE_ID> --fields=id --display=data
+   ascli aoc admin application instance list --query.aspera_app_type=packages --query.workspace_id=<WORKSPACE_ID> --fields=id --out.level=data
    ```
 
    This displays the <APP_ID>.
@@ -6448,6 +6703,12 @@ See [File list](#list-of-files-for-transfers).
 
 The Aspera on Cloud **Packages** app lets you assemble copies of any number of files and folders into a digital "package" and send the package to others, pretty much like a web-mail application.
 
+> [!NOTE]
+> All `aoc packages` commands operate in a workspace context. The workspace is inferred
+> automatically when a default workspace is configured in the application. If no default is
+> set, provide one explicitly with `--workspace=NAME`. List available workspaces with
+> `ascli aoc user workspaces list`.
+
 #### Send a Package
 
 General syntax:
@@ -6518,7 +6779,7 @@ ascli aoc files browse /src_folder
 To send a package with the file `10M.dat` from subfolder /src_folder:
 
 ```shell
-ascli aoc files node_info /src_folder --format=json --display=data | ascli aoc packages send @json:'{"name":"test","recipients":["someuser@example.com"]}' 10M.dat --transfer=@json:@stdin:
+ascli aoc files node_info /src_folder --format=json --out.level=data | ascli aoc packages send @json:'{"name":"test","recipients":["someuser@example.com"]}' 10M.dat --transfer=@json:@stdin:
 ```
 
 #### Receive packages
@@ -6608,7 +6869,7 @@ Use command `find` to list recursively.
 For advanced users, it is also possible to pipe node information for the package and use node operations:
 
 ```shell
-ascli aoc package node_info <PACKAGE_ID> / --format=json --show-secrets=yes --display=data | ascli node -N --preset=@json:@stdin: access_key do self browse /
+ascli aoc package node_info <PACKAGE_ID> / --format=json --out.secrets=yes --out.level=data | ascli node -N --preset=@json:@stdin: access_key do self browse /
 ```
 
 #### List packages
@@ -6653,7 +6914,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.
 
 ```shell
-shared_box_id=$(ascli aoc packages shared_inboxes show --name='My Shared Inbox' --format=csv --display=data --fields=id)
+shared_box_id=$(ascli aoc packages shared_inboxes show --name='My Shared Inbox' --format=csv --out.level=data --fields=id)
 ```
 
 ```shell
@@ -6666,6 +6927,10 @@ The Files application presents a **Home** folder to users in a given workspace.
 Files located here are either user's files, or shared folders.
 
 > [!NOTE]
+> All `aoc files` commands operate in a workspace context. The workspace is inferred
+> automatically when a default workspace is configured in the application. If no default is
+> set, provide one explicitly with `--workspace=NAME`. List available workspaces with
+> `ascli aoc user workspaces list`.
 > All commands under `files` are the same as under `access_keys do self` for plugin `node`, that is, **gen4/access key** operations.
 
 #### Download Files
@@ -6746,7 +7011,7 @@ ascli aoc files permission --workspace=<WORKSPACE_NAME> <PATH_TO_FOLDER> ...
 
 > [!NOTE]
 > The workspace is identified by name, and folder by path, relative to the user's home.
-> To use an identifier instead, one can use the percent selector, like `%id:<WS_ID>`.
+> To use an identifier instead, one can use the [percent selector](#percent-selector), like `%id:<WS_ID>`.
 
 ##### Admin Shared Folders
 
@@ -6758,7 +7023,7 @@ ascli aoc admin node do <NODE_ID> permission --workspace=<WORKSPACE_NAME> <PATH_
 
 > [!TIP]
 > The node is identified by identifier.
-> To use a name instead, one can use the percent selector, like `%name:"<NODE_NAME>"`.
+> To use a name instead, one can use the [percent selector](#percent-selector), like `%name:"<NODE_NAME>"`.
 > The path is identifier by a path, one can specify a file ID, with `%id:123`.
 > If the ID is left blank: `%id:`, then it means `*`, that is, "all".
 
@@ -6987,7 +7252,7 @@ Procedure to send a file from org1 to org2:
 - Execute the following:
 
 ```shell
-ascli -Porg1 aoc files node_info <DEST_FOLDER> --format=json --display=data | ascli -Porg2 aoc files upload <SOURCE_FILE> --transfer=@json:@stdin:
+ascli -Porg1 aoc files node_info <DEST_FOLDER> --format=json --out.level=data | ascli -Porg2 aoc files upload <SOURCE_FILE> --transfer=@json:@stdin:
 ```
 
 Explanation:
@@ -6997,7 +7262,7 @@ Explanation:
 - `aoc` uses the Aspera on Cloud plugin
 - `files node_info /<DEST_FOLDER>` generates transfer information including the Node API credential and root ID, suitable for the next command
 - `--format=json` formats the output as JSON (instead of the default text table)
-- `--display=data` displays only the result, removing other information such as workspace name
+- `--out.level=data` displays only the result, removing other information such as workspace name
 - `|` pipes the standard output of the first command into the second one
 - `-Porg2 aoc` uses the Aspera on Cloud plugin and loads credentials for `org2`
 - `files upload <SOURCE_FILE>` uploads the file named `<SOURCE_FILE>` (located in `org2`) to `org1`
@@ -7040,7 +7305,7 @@ admin ats cluster list
 admin ats cluster show --cloud=aws --region=eu-west-1
 admin ats cluster show 1f412ae7-869a-445c-9c05-02ad16813be2
 admin auth_providers list
-admin bearer_token --display=data
+admin bearer_token --out.level=data
 admin client list
 admin client_access_key list
 admin client_registration_token create @json:'{"data":{"name":"test_client_reg1","client_subject_scopes":["alee","aejd"],"client_subject_enabled":true}}'
@@ -7095,7 +7360,7 @@ automation workflow delete <id>
 automation workflow list
 automation workflow list --query.show_org_workflows=@val:true
 automation workflow list --select.name=test_workflow --fields=id
-bearer_token --display=data
+bearer_token --out.level=data
 files bearer /
 files bearer_token_node / --cache-tokens=no
 files browse /
@@ -7127,7 +7392,7 @@ files show testdst/test_file.bin
 files sync admin status /data/local_sync
 files sync pull /testdst --to-folder=/data/local_sync @json:'{"reset":true,"transport":{"target_rate":my_bps}}'
 files thumbnail my_test_folder/video_file.mpg
-files thumbnail my_test_folder/video_file.mpg --query=@json:'{"text":true,"double":true}'
+files thumbnail my_test_folder/video_file.mpg --query.text=true --query.double=true
 files transfer push /testsrc --to-folder=/testdst test_file.bin
 files upload --to-folder=/ test_file.bin --url=my_public_link_folder_no_pass
 files upload --to-folder=/testsrc test_file.bin
@@ -7142,8 +7407,8 @@ 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 <id> --to-folder=.
 packages receive <id> --to-folder=. /
-packages receive ALL --once-only=yes --to-folder=. --lock-port=50101 --package-folder.fld.0=name --package-folder.fld.1=id --package-folder.opt=true
-packages receive ALL --once-only=yes --to-folder=. --lock-port=50101 --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 ALL --once-only=yes --to-folder=. --query.max=5 --lock-port=50101 --package-folder.fld.0=name --package-folder.fld.1=id --package-folder.opt=true
+packages receive ALL --once-only=yes --to-folder=. --query.max=5 --lock-port=50101 --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.dropbox_name=my_shared_inbox_name
 packages send --workspace=my_workspace_shared_inbox --validate-metadata=yes @json:'{"name":"package title","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":"package title","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
@@ -7782,7 +8047,7 @@ ascli node access_key create @json:'{"id":"<ACCESS_KEY>","secret":"<SECRET>","st
 > [!TIP]
 > The `id` and `secret` fields are optional.
 > If not provided, they will be generated and returned into the result.
-> In that case, provide option `--show-secrets=yes` to get the generated secret.
+> In that case, provide option `--out.secrets=yes` to get the generated secret.
 
 Access keys support extra overriding parameters using parameter: `configuration` and sub keys `transfer` and `server`.
 For example, an access key can be modified or created with the following options:
@@ -7914,7 +8179,7 @@ ascli node access_key modify %id:self @ruby:'{token_verification_key: File.read(
 - Create a Bearer token for the user:
 
   ```shell
-  ascli node bearer_token @file:./myorgkey.pem @json:'{"user_id":"'$my_user_id'","_validity":3600}' --output=bearer.txt
+  ascli node bearer_token @file:./myorgkey.pem @json:'{"user_id":"'$my_user_id'","_validity":3600}' --out.file=bearer.txt
   ```
 
 > [!NOTE]
@@ -8161,7 +8426,7 @@ For more information on the JWT method, refer to the section below.
 If you have generated a private key with the wizard and lost the public key, you can retrieve the public key like this:
 
 ```shell
-ascli faspex5 --show-config --show-secrets=yes --fields=private_key | ascli config pubkey @stdin: --show-secrets=yes
+ascli faspex5 --show-config --out.secrets=yes --fields=private_key | ascli config pubkey @stdin: --out.secrets=yes
 ```
 
 ### Faspex 5 JWT authentication
@@ -8307,7 +8572,7 @@ admin smtp test my_email_external
 admin workgroups list
 bearer_token
 gateway @: url=https://localhost:12346/aspera/faspex
-health --url=https://faspex5.example.com/path
+health --url=https://f5.example.com/path
 invitation list
 invitations create @: email_address=aspera.user1+u@gmail.com
 packages browse <id> --query.recursive=true
@@ -8320,13 +8585,13 @@ packages list --query=@json:'{"mailbox":"inbox","status":"completed"}'
 packages receive --box=my_shared_box_name <id> --to-folder=.
 packages receive --box=my_workgroup --group-type=workgroups <id> --to-folder=.
 packages receive <id> --to-folder=. --ts.content_protection_password=my_secret_here
-packages receive ALL --once-only=yes --to-folder=.
+packages receive ALL --once-only=yes --to-folder=. --query.max=5
 packages receive INIT --once-only=yes
 packages send --url=my_public_link_send_f5_user @json:'{"title":"test title"}' test_file.bin
 packages send --url=my_public_link_send_shared_box @json:'{"title":"test title"}' test_file.bin
-packages send @json:'{"title":"test title","recipients":["my_shared_box_name"],"metadata":{"Options":"Opt1","TextInput":"example text"}}' test_file.bin
+packages send @: 'title=for shared inbox' recipients.0=my_shared_box_name metadata.Options=Opt1 'metadata.TextInput=example text' END test_file.bin
+packages send @: 'title=test title' recipients.0.name=my_username END test_file.bin --ts.content_protection_password=my_secret_here
 packages send @json:'{"title":"test title","recipients":["my_workgroup"]}' test_file.bin
-packages send @json:'{"title":"test title","recipients":[{"name":"my_username"}]my_meta}' test_file.bin --ts.content_protection_password=my_secret_here
 packages send @json:'{"title":"test_webhook_ascli","recipients":["my_shared_box_name"]}' 'faux:///test1?1m'
 packages show --box=my_shared_box_name <id>
 packages show --box=my_workgroup --group-type=workgroups <id>
@@ -8334,20 +8599,21 @@ packages show <id>
 packages status <f5_pack_send_shared> @list:,failed,completed
 packages status <id>
 postprocessing @json:'{"url":"https://localhost:8553/asclihook","script_folder":"/path/to/scripts","cert":".../localhost.p12","key":"changeit"}'
-shared browse %name:my_src
+shared browse %name:my_shared_folder_name
 shared list
 shared_folders browse %name:my_shared_folder_name
 shared_folders list
 user account
 user account --query.expand=true
-user profile modify @json:'{"preference":{"connect_disabled":false}}'
+user profile modify @: preference.rows_per_page=10
 user profile show
 version
 ```
 
 Most commands correspond directly to REST API calls.
 Parameters to commands are carried through option `query`, as [Extended Value](#extended-value-syntax), for `list`, or through **Command Parameter** for creation.
-One can conveniently use the JSON format with prefix `@json:`.
+For a single parameter, the dot-path option form is the most direct (for example, `--query.status=completed`).
+For multiple parameters or when copying directly from API documentation, `@json:` is more suitable.
 
 > [!TIP]
 > The API is listed in [Faspex 5 API Reference](https://developer.ibm.com/apis/catalog?search="faspex+5") under **IBM Aspera Faspex API**.
@@ -8550,7 +8816,7 @@ Option `--once-only=yes` can be used, for "cargo-like" behavior.
 Special package ID `INIT` initializes the persistency of already received packages when option `--once-only=yes` is used.
 
 Special package ID `ALL` selects all packages (of the selected box).
-In this case, typically, only `completed` packages should be downloaded, so use option `--query=@json:'{"status":"completed"}'`.
+In this case, typically, only `completed` packages should be downloaded, so use option `--query.status=completed` (or equivalently `--query=@json:'{"status":"completed"}'`).
 
 If a package is password protected, then the content protection password is asked interactively.
 To keep the content encrypted, use option: `--ts=@json:'{"content_protection":null}'`, or provide the password instead of `null`.
@@ -8559,6 +8825,10 @@ To keep the content encrypted, use option: `--ts=@json:'{"content_protection":nu
 
 ### Faspex 5: List all shared inboxes and work groups
 
+> [!NOTE]
+> **Shared inboxes** (`faspex5 admin shared_inboxes`) are package recipients (dropboxes), accessible under the **Packages** app.
+> They are distinct from **shared folders** (`faspex5 shared_folders`), which are node-based storage access points accessible under the **Files** app.
+
 If you are a regular user, to list work groups you belong to:
 
 ```shell
@@ -8604,6 +8874,10 @@ 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
 
+> [!NOTE]
+> **Shared folders** (`faspex5 shared_folders`) provide node-based storage access, accessible under the **Files** app.
+> They are distinct from **shared inboxes** (`faspex5 admin shared_inboxes`), which are package recipients (dropboxes) accessible under the **Packages** app.
+
 ```shell
 ascli faspex5 shared_folders list --fields=id,name
 ```
@@ -8625,7 +8899,7 @@ ascli faspex5 packages send @json:'{"title":"hello","recipients":[{"name":"_reci
 ```
 
 > [!TIP]
-> The shared folder can be identified by its numerical `id` or by name using percent selector: `%<FIELD>:<VALUE>`. for example, `--shared-folder=3`
+> The shared folder can be identified by its numerical `id` or by name using [percent selector](#percent-selector): `%<FIELD>:<VALUE>`. for example, `--shared-folder=3`
 
 ### Faspex 5: Receive all packages (cargo)
 
@@ -8703,7 +8977,7 @@ ascli faspex5 admin accounts modify %name:some.user@example.com @json:'{"account
 ```
 
 > [!TIP]
-> This example uses the percent selector, but the numerical ID can be used as well.
+> This example uses the [percent selector](#percent-selector), but the numerical ID can be used as well.
 
 To send a password reset link to a user, use command `reset_password` on the `account`.
 
@@ -8792,210 +9066,6 @@ If a command is missing, then it is still possible to execute command by calling
 curl -H "Authorization: $(ascli ascli bearer)" https://faspex5.example.com/aspera/faspex/api/v5/api_endpoint_here
 ```
 
-## Plugin: `faspex`: IBM Aspera Faspex v4
-
-> [!WARNING]
-> Faspex v4 is end of support since September 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.
-The `v4` command requires the use of API v4, refer to the Faspex Admin manual on how to activate.
-
-### Listing Packages
-
-Command: `faspex package list`
-
-#### Option `box`
-
-By default, it looks in box `inbox`, but the following boxes are also supported: `archive` and `sent`, selected with option `box`.
-
-#### Option `recipient`
-
-A user can receive a package because the recipient is:
-
-- The user himself (default)
-- The user is member of a dropbox/workgroup: filter using option `recipient` set with value `*<name of dropbox/workgroup>`
-
-#### Option `query`
-
-As inboxes may be large, it is possible to use the following query parameters:
-
-| Parameter    | Evaluation | Description                                                          |
-|--------------|------------|----------------------------------------------------------------------|
-| `count`      | API        | Number of items in one API call result (default=0, equivalent to 10) |
-| `page`       | API        | ID of page in call (default=0) |
-| `startIndex` | API        | Index of item to start (default=0) |
-| `max`        | `ascli`  | Maximum number of items |
-| `pmax`       | `ascli`  | Maximum number of pages |
-
-(SQL query is `LIMIT <STARTINDEX>, <COUNT>`)
-
-The API is listed in [Faspex 4 API Reference](https://developer.ibm.com/apis/catalog/?search=faspex) under **Services (API v.3)**.
-
-If no parameter `max` or `pmax` is provided, then all packages will be listed in the inbox, which results in paged API calls (using parameters: `count` and `page`).
-By default, `count` is `0` (`10`), it can be increased to issue less HTTP calls.
-
-#### Example: List packages in dropbox
-
-```shell
-ascli faspex package list --box=inbox --recipient='*<DROPBOX>' --query=@json:'{"max":20,"pmax":2,"count":20}'
-```
-
-List a maximum of 20 items grouped by pages of 20, with maximum 2 pages in received box (inbox) when received in dropbox `*<DROPBOX>`.
-
-### Receiving a Package
-
-The command is `package recv`, possible methods are:
-
-- Provide a package ID with option `id`
-- Provide a public link with option `link`
-- Provide a `faspe:` URI with option `link`
-
-```shell
-ascli faspex package recv 12345
-ascli faspex package recv --link=faspe://...
-```
-
-If the package is in a specific **dropbox**/**workgroup**, add option `recipient` for both the `list` and `recv` commands.
-
-```shell
-ascli faspex package list --recipient='*dropbox_name'
-ascli faspex package recv 125 --recipient='*dropbox_name'
-```
-
-If `id` is set to `ALL`, then all packages are downloaded, and if option `once_only` is used, a persistency file is created to keep track of already downloaded packages.
-
-### Sending a Package
-
-The command is `faspex package send`.
-Package information (title, note, metadata, options) is provided in option `delivery_info`.
-The content of `delivery_info` is directly the contents of the `send` v3 [API of Faspex 4](https://developer.ibm.com/apis/catalog/aspera--aspera-faspex-client-sdk/API%20v.3:%20Send%20Packages).
-
-Example:
-
-```shell
-ascli faspex package send --delivery-info=@json:'{"title":"<TITLE>","recipients":["someuser@example.com"]}' /tmp/file1 /home/bar/file2
-```
-
-If the recipient is a dropbox or workgroup: provide the name of the dropbox or workgroup preceded with `*` in the `recipients` field of the `delivery_info` option:
-`"recipients":["*MyDropboxName"]`
-
-Additional optional parameters in mandatory option `delivery_info`:
-
-- Package Note: : `"note":"note this and that"`
-- Package Metadata: `"metadata":{"Meta1":"Val1","Meta2":"Val2"}`
-
-It is possible to send from a remote source using option `remote_source`, providing either the numerical ID, or the name of the remote source using percent selector: `%name:<NAME>`.
-
-Remote source can be browsed if option `storage` is provided.
-`storage` is a `Hash` [Extended Value](#extended-value-syntax).
-The key is the storage name, as listed in `source list` command.
-The value is a `Hash` with the following keys:
-
-- `node` is a `Hash` with keys: `url`, `username`, `password`
-- `path` is the sub-path inside the node, as configured in Faspex
-
-### Email notification on transfer
-
-Like for any transfer, a notification can be sent by email using options: `notify_to` and `notify_template`.
-
-Example:
-
-```shell
-ascli faspex package send --delivery-info=@json:'{"title":"test pkg 1","recipients":["aspera.user1@gmail.com"]}' ~/Documents/Samples/200KB.1 --notify-to=aspera.user1@gmail.com --notify-template=@ruby:'%Q{From: <%=from_name%> <<%=from_email%>>\nTo: <<%=to%>>\nSubject: Package sent: <%=ts["tags"]["aspera"]["faspex"]["metadata"]["_pkg_name"]%> files received\n\nTo user: <%=ts["tags"]["aspera"]["faspex"]["recipients"].first["email"]%>}'
-```
-
-In this example the notification template is directly provided on command line.
-Package information placed in the message are directly taken from the tags in transfer spec.
-The template can be placed in a file using modifier: `@file:`
-
-### Operations on dropbox
-
-Example:
-
-```shell
-ascli faspex v4 dropbox create @json:'{"dropbox":{"e_wg_name":"test1","e_wg_desc":"test1"}}'
-ascli faspex v4 dropbox list
-ascli faspex v4 dropbox delete 36
-```
-
-### Remote sources
-
-Faspex lacks an API to list the contents of a remote source (available in web UI).
-To work around this, the Node API is used, for this it is required to set option: `storage` that links a storage name to a node configuration and sub path.
-
-Example:
-
-```yaml
-my_faspex_conf:
-  url: https://10.25.0.3/aspera/faspex
-  username: admin
-  password: MyUserPassword
-  storage:
-    my_storage:
-      node: "@preset:my_faspex_node"
-      path: /mydir
-my_faspex_node:
-  url: https://10.25.0.3:9092
-  username: node_faspex
-  password: MyNodePassword
-```
-
-In this example, a Faspex storage named `my_storage` exists in Faspex, and is located
-under the docroot in `/mydir` (this must be the same as configured in Faspex).
-The node configuration name is `my_faspex_node` here.
-
-> [!NOTE]
-> The v4 API provides an API for nodes and shares.
-
-### Automated package download (cargo)
-
-It is possible to tell `ascli` to download newly received packages, much like the official cargo client, or drive.
-See the [same section](#receive-new-packages-only-cargo) in the Aspera on Cloud plugin:
-
-```shell
-ascli faspex packages recv ALL --once-only=yes --lock-port=12345
-```
-
-### Tested commands for `faspex`
-
-> [!NOTE]
-> Add `ascli faspex` in front of the following commands:
-
-```shell
-address_book
-dropbox list --recipient='*my_dbx'
-health
-login_methods
-me
-package list --query.max=5
-package receive <id> --recipient='*my_dbx' --to-folder=.
-package receive <id> --recipient='*my_wkg' --to-folder=.
-package receive <id> --to-folder=.
-package receive <id> --to-folder=. --box=sent
-package receive ALL --once-only=yes --to-folder=. --query.max=10
-package send --delivery-info=@json:'{"title":"package title","recipients":["my_email_internal","my_username"]}' test_file.bin
-package send --delivery-info=@json:'{"title":"package title","recipients":["my_email_internal"]}' --remote-source=%name:my_src sample_source.txt
-package send --delivery-info=@json:'{"title":"package title","recipients":[*my_dbx]}' test_file.bin
-package send --delivery-info=@json:'{"title":"package title","recipients":[*my_wkg]}' test_file.bin
-package send --link=https://app.example.com/send_to_dropbox_path --delivery-info.title='package title' test_file.bin
-package send --link=https://app.example.com/send_to_user_path --delivery-info.title='package title' test_file.bin
-source info %name:my_src --storage=@preset:faspex4_storage
-source list
-source node %name:my_src br / --storage=@preset:faspex4_storage
-v4 dmembership list
-v4 dropbox list
-v4 metadata_profile list
-v4 user list
-v4 wmembership list
-v4 workgroup list
-```
-
 ## Plugin: `shares`: IBM Aspera Shares v1
 
 Aspera Shares supports the **Node API** for the file transfer part.
@@ -9555,9 +9625,17 @@ case "$*" in *trev*) tmout=10m ;; *) tmout=30m ;; esac
 
 - `trevents` : only recently uploaded files will be tested (transfer events)
 - `events` : only recently uploaded files will be tested (file events: not working)
-- `scan` : recursively scan all files under the access key&apos;s **storage root**
+- `scan [path]` : generate previews for a file or recursively scan a folder. The default path is the access key&apos;s **storage root**. A file or folder can also be selected with `%id:<file_id>`.
 - `test` : test using a local file
 
+Use `--filter` with `scan`, `events`, or `trevents` to select files by name. It accepts a glob string, a regular expression using `@re:`, or a Proc using `@ruby:`. For example:
+
+```shell
+ascli preview scan /videos --filter='*.mp4'
+ascli preview scan %id:<file_id>
+ascli preview scan /videos --filter='@ruby:->(f){f["name"].end_with?(".mp4")}'
+```
+
 Once candidate are selected, a preview is always generated if it does not exist already, else if a preview already exist, it will be generated using one of three values for the `overwrite` option:
 
 - `always` : preview is always generated, even if it already exists and is newer than original
@@ -9575,8 +9653,6 @@ ascli preview scan --skip-folders=@json:'["/not_here"]'
 
 The option `folder_reset_cache` forces the node service to refresh folder contents using various methods.
 
-When scanning the option `query` has the same behavior as for the `node access_keys do self find` command.
-
 See the following section for details.
 
 ### Preview File types
@@ -9636,8 +9712,8 @@ Nevertheless, `ascli` may or may not have direct file system access to the acces
 ```shell
 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=aspera" => nil} --ts.target_rate_kbps=1000000
-scan --skip-types=office --log-level=info --skip-folder=/special/folder
+scan %id:1 --skip-types=office --log-level=info --root-url=aspera: --ts.target_rate_kbps=1000000
+scan --skip-types=office --log-level=info --skip-folders=/special/folder
 show /etc/hosts --base=test
 show my_docx --base=test
 show my_mpg --base=test --video-png-conv=animated
@@ -9650,21 +9726,27 @@ test my_dcm --base=test --mimemagic=yes
 test my_jpg_unk --base=test --mimemagic=yes
 test my_mpg mp4 --base=test --video-conversion=clips
 test my_mpg mp4 --base=test --video-conversion=reencode
-test my_mxf mp4 --base=test --video-conversion=blend --query=@json:'{"text":true,"double":true}'
+test my_mxf mp4 --base=test --video-conversion=blend --query.text=true --query.double=true
 trevents --once-only=yes --skip-types=office --log-level=info
 ```
 
 ## Plugin: `mcp`: Model Context Protocol server
 
 > [!WARNING]
-> This plugin is **experimental**. The interface, options, and behaviour may change in future releases without notice.
+> This plugin is **experimental**.
+> The interface, options, and behavior may change in future releases without notice.
 
 The `mcp` plugin starts a [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server that exposes `ascli` to AI assistants and LLM-based tools.
 The server registers a single tool, `execute_ascli_command`, which executes any `ascli` command in-process and returns the result as text.
 
-> [!NOTE]
-> The `mcp` gem is required.
-> Install it with: `gem install mcp`
+> [!IMPORTANT]
+> The `mcp` and `rack` gems are required.
+> Check section [Installing Optional Gems](#installing-optional-gems)
+> Install them with the following command:
+
+```shell
+gem install mcp rack
+```
 
 ### Usage
 
@@ -9696,7 +9778,7 @@ The `server` command accepts an optional [Hash](#extended-value-syntax) argument
 | `max_line_bytes` | `integer` | 4194304 (4 MiB) | Maximum JSON frame size in bytes |
 
 > [!NOTE]
-> **`stdio` transport and server description** — The MCP protocol does not carry a `description` field in the `initialize` handshake.
+> **`stdio` transport and server description** - The MCP protocol does not carry a `description` field in the `initialize` handshake.
 > For `stdio` servers, AI clients (Claude Desktop, VS Code, Bob, …) cannot retrieve the description automatically.
 > Add a `"description"` field directly in the client's `mcpServers` configuration to display it in the UI.
 
@@ -9713,7 +9795,7 @@ The `server` command accepts an optional [Hash](#extended-value-syntax) argument
 | `max_sessions` | `integer` | - | Maximum number of concurrent sessions |
 
 > [!NOTE]
-> **HTTP transport discovery endpoint** — When using `http` transport, the server exposes a `GET /` endpoint that returns a JSON object with `name`, `version`, and `description` fields.
+> **HTTP transport discovery endpoint** - When using `http` transport, the server exposes a `GET /` endpoint that returns a JSON object with `name`, `version`, and `description` fields.
 > AI clients that support this convention (such as Bob) automatically read the description from this endpoint and display it in their MCP server list without any manual configuration.
 
 ### Examples
@@ -9738,12 +9820,60 @@ ascli mcp server @: instructions="Aspera transfer automation" protocol_version=2
 
 ### MCP client configuration
 
-To register `ascli` as an MCP server in an AI client (e.g. Claude Desktop, VS Code, Bob), add the following to the client's MCP configuration file:
+#### Streamable HTTP transport
+
+Start the server in a separate terminal first:
+
+```shell
+ascli mcp server @: transport=http port=3000
+```
+
+Then register it in the AI client's MCP configuration file.
+
+For [**IBM Bob**](https://bob.ibm.com/docs/ide/configuration/mcp/mcp-in-bob), add to `.bob/mcp.json` in your project (or `~/.bob/mcp.json` for global configuration):
+
+```json
+{
+  "mcpServers": {
+    "ascli": {
+      "type": "streamable-http",
+      "url": "http://localhost:3000/mcp"
+    }
+  }
+}
+```
+
+For other clients (Claude Desktop, VS Code, …):
 
 ```json
 {
   "mcpServers": {
     "ascli": {
+      "type": "http",
+      "url": "http://localhost:3000/mcp"
+    }
+  }
+}
+```
+
+> [!NOTE]
+> With `http` transport, the client connects to a running server process.
+> The server must be started and kept running independently before the AI client tries to connect.
+
+#### `stdio` transport
+
+The client launches `ascli` directly as a subprocess.
+Add the following to the AI client's MCP configuration file.
+
+##### IBM Bob `stdio`
+
+For [**IBM Bob**](https://bob.ibm.com/docs/ide/configuration/mcp/mcp-in-bob), add to `.bob/mcp.json` in your project (or `~/.bob/mcp.json` for global configuration):
+
+```json
+{
+  "mcpServers": {
+    "ascli": {
+      "type": "stdio",
       "command": "/path/to/bin/ascli",
       "args": ["mcp", "server"],
       "description": "Aspera CLI MCP server"
@@ -9752,23 +9882,45 @@ To register `ascli` as an MCP server in an AI client (e.g. Claude Desktop, VS Co
 }
 ```
 
-> [!NOTE]
-> **Development mode** — if the `ascli` gem is not installed and you are running directly from the source tree, Ruby will not find the `lib/` directory automatically.
-> Add the `RUBYLIB` environment variable pointing to the `lib/` directory of the project:
->
-> ```json
-> {
->   "mcpServers": {
->     "ascli": {
->       "command": "/path/to/aspera-cli/bin/ascli",
->       "args": ["mcp", "server"],
->       "env": {
->         "RUBYLIB": "/path/to/aspera-cli/lib"
->       }
->     }
->   }
-> }
-> ```
+For other clients (Claude Desktop, VS Code, …), the configuration is identical.
+
+##### Claude Desktop `stdio`
+
+Find the configuration file as specified in [Claude Desktop Documentation](https://modelcontextprotocol.io/docs/2026-07-28/develop/connect-local-servers).
+
+place this section in `mcpServers`:
+
+```json
+{
+  "mcpServers": {
+    "ascli": {
+      "command": "ascli",
+      "args": ["mcp", "server"]
+    }
+  },
+...
+}
+```
+
+##### Development mode for `stdio`
+
+If the `ascli` gem is not installed and you are running directly from the source tree, Ruby will not find the `lib/` directory automatically.
+Add the `RUBYLIB` environment variable pointing to the `lib/` directory of the project:
+
+```json
+{
+  "mcpServers": {
+    "ascli": {
+      "type": "stdio",
+      "command": "/path/to/aspera-cli/bin/ascli",
+      "args": ["mcp", "server"],
+      "env": {
+        "RUBYLIB": "/path/to/aspera-cli/lib"
+      }
+    }
+  }
+}
+```
 
 ### Tested commands for `mcp`
 
@@ -9789,6 +9941,74 @@ It covers tool visibility, self-discovery, Hash schema introspection, option lis
 documentation retrieval, live transfer tasks, truncation handling, error handling, and
 credential safety.
 
+### MCP usage patterns for AI
+
+> [!TIP]
+> This section is for AI assistants using the MCP server. Follow these patterns to avoid
+> common first-call failures and unnecessary retries.
+
+#### Session bootstrap
+
+Always start a session with two discovery calls before doing anything else:
+
+```
+["config", "preset", "list"]
+["config", "preset", "show", "default"]
+```
+
+The second call returns the `plugin → preset_name` mapping so you know which credentials
+are active for each plugin.
+
+#### Command discovery
+
+Always use `["config", "commands"]` to enumerate every available command and its syntax.
+Never guess command names from training data — names like `shared_folders` vs
+`shared_inboxes` are easily confused.
+
+#### Schema introspection for Hash arguments
+
+Whenever a command syntax shows a `<data>` argument, call `help` **before** the real call:
+
+```json
+["<plugin>", "<cmd>", ..., "help"]
+```
+
+This returns a table of field names, types, and descriptions. Never infer field names from
+server error messages.
+
+#### Async transfers and cross-call status tracking
+
+The `direct` agent keeps transfer state in-memory. A job started in one MCP call **cannot**
+be monitored in a subsequent call — the in-memory agent is gone between calls.
+
+Use the `transferd` agent when you need to check transfer status in a later call:
+
+```json
+["server", "upload", "--transfer=transferd", "--to-folder=/dst", "/local/file"]
+```
+
+The `desktop` agent is also unaffected because it runs in an external process.
+
+#### Workspace context for AoC
+
+`aoc files` and `aoc packages` commands require a workspace context. If no default
+workspace is configured in the preset, always add `--workspace=NAME`:
+
+```
+["aoc", "files", "ls", "/", "--workspace=MyWorkspace"]
+```
+
+List available workspaces with `["aoc", "user", "workspaces", "list"]`.
+
+#### Admin operations and privilege checks
+
+Before calling any `admin` sub-command, verify that the active preset has admin rights.
+`access_denied` typically means the wrong preset is active, not a syntax error. Check with:
+
+```
+["config", "preset", "show", "<preset_name>"]
+```
+
 ## Operational Utilities
 
 This section covers the specialized modules and utilities used to integrate `ascli` into your broader operational infrastructure.
@@ -10323,14 +10543,14 @@ This can also be used with other folder-based applications: Aspera on Cloud, Sha
 #### Example: Unidirectional synchronization (download) from Aspera on Cloud Files
 
 ```shell
-ascli aoc files download . --to-folder=. --lock-port=12345 --progress-bar=no --display=data --ts=@json:'{"resume_policy":"sparse_csum","target_rate_kbps":50000,"exclude_newer_than":-8,"delete_before_transfer":true}'
+ascli aoc files download . --to-folder=. --lock-port=12345 --progress-bar=no --out.level=data --ts=@json:'{"resume_policy":"sparse_csum","target_rate_kbps":50000,"exclude_newer_than":-8,"delete_before_transfer":true}'
 ```
 
 > [!NOTE]
 > Option `delete_before_transfer` will delete files locally, if they are not present on remote side.
 
 > [!NOTE]
-> Options `progress` and `display` limit output for headless operation (for example, cron job)
+> Options `progress` and `--out.level` limit output for headless operation (for example, cron job)
 
 ### Health check and Nagios
 
@@ -10745,7 +10965,7 @@ Enjoy a coffee on me:
 ```shell
 ascli config coffee
 ascli config coffee --ui=text
-ascli config coffee --ui=text --image.text=true
+ascli config coffee --ui=text --out.img.text=true
 ```
 
 ### References