aspera-cli 4.22.0 → 4.23.0

data/README.md

@@ -1,22 +1,21 @@
 # Command Line Interface for IBM Aspera products
 <!--
 DO NOT EDIT: THIS FILE IS GENERATED, edit docs/README.erb.md, for details, read docs/README.md
-
-markdownlint-disable MD033 MD003 MD053
-cspell:ignore Serban Antipolis
 PANDOC_META_BEGIN
-subtitle: "ascli 4.22.0.pre"
+subtitle: "ascli 4.23.0"
 author: "Laurent MARTIN"
 PANDOC_META_END
 -->
 
+<!-- xmarkdownlint-disable MD033 MD003 MD053 -->
+
 [![Gem Version](https://badge.fury.io/rb/aspera-cli.svg)](https://badge.fury.io/rb/aspera-cli)
 [![unit tests](https://github.com/IBM/aspera-cli/actions/workflows/test.yml/badge.svg?branch=main)](https://github.com/IBM/aspera-cli/actions)
 [![CII Best Practices](https://bestpractices.coreinfrastructure.org/projects/5861/badge)](https://bestpractices.coreinfrastructure.org/projects/5861)
 
 ## Introduction
 
-Version : 4.22.0.pre
+Version : 4.23.0
 
 Laurent/2016-2025
 
@@ -67,10 +66,10 @@ It is designed for:
 - `curl` (for REST calls)
 - Aspera transfer (`ascp`)
 
-If the need is to perform operations programmatically in languages such as: C, Go, Python, NodeJS, ... then it is better to directly use [Aspera APIs](https://ibm.biz/aspera_api)
+If the need is to perform operations programmatically in languages such as: C/C++, Go, Python, NodeJS, ... then it is better to directly use [Aspera APIs](https://ibm.biz/aspera_api)
 
 - Product APIs (REST) : e.g. AoC, Faspex, node
-- Transfer SDK : with gRPC interface and language stubs (C, C++, Python, .NET/C#, java, Go, Ruby, Rust, etc...)
+- Transfer SDK : with gRPC interface and language stubs (C/C++, Python, .NET/C#, java, Go, Ruby, Rust, etc...)
 
 Using APIs (application REST API and transfer SDK) will prove to be easier to develop and maintain.
 Code examples here: <https://github.com/laurent-martin/aspera-api-examples>
@@ -101,14 +100,14 @@ Command line arguments beginning with `my_` in examples, e.g. `my_param_value`,
 Some commands will start an Aspera transfer (e.g. `upload`).
 The transfer is not directly implemented in `ascli`, rather `ascli` uses one of the external Aspera Transfer Clients called **[Transfer Agents](#transfer-clients-agents)**.
 
-> **Note:** A **[Transfer Agent](#transfer-clients-agents)** is a client for the remote Transfer Server (HSTS).
+> **Note:** A **[Transfer Agent](#transfer-clients-agents)** is a client for the remote Transfer Server (HSTS/HSTE).
 A **[Transfer Agent](#transfer-clients-agents)** can be local or remote...
-For example a remote Aspera Server may be used as a transfer agent (using Node API).
+For example a remote Aspera Transfer Server may be used as a transfer agent (using Node API).
 i.e. using option `--transfer=node`
 
 ## Quick Start
 
-This section guides you from installation, first use and advanced use.
+This section guides you from installation to first use and advanced use.
 
 First, follow section: [Installation](#installation) (Ruby, Gem, FASP) to start using `ascli`.
 
@@ -116,7 +115,7 @@ Once the gem is installed, `ascli` shall be accessible:
 
 ```console
 $ ascli --version
-4.22.0.pre
+4.23.0
 ```
 
 ### First use
@@ -202,7 +201,7 @@ complete
 
 Get familiar with configuration, options, commands : [Command Line Interface](#command-line-interface).
 
-Then, follow the section relative to the product you want to interact with (Aspera on Cloud, Faspex, ...) : [Application Plugins](plugins)
+Then, follow the section relative to the product you want to interact with (Aspera on Cloud, Faspex, ...) : [Application Plugins](#plugins)
 
 ## Installation
 
@@ -230,7 +229,10 @@ A package with pre-installed Ruby, gem and `ascp` may also be provided.
 It is planned to provide `ascli` as a single platform-dependent executable.
 [Beta releases can be found here](https://ibm.biz/aspera-cli-exe).
 
-**Note:** This is a Beta feature. On Linux, the executable requires a minimum GLIBC version. Installation of `ascp` is still required separately. Refer to [Install `ascp`](#installation-of-ascp-through-transferd).
+**Note:** This is a Beta feature.
+On Linux, the executable requires a minimum GLIBC version.
+Installation of `ascp` is still required separately.
+Refer to [Install `ascp`](#installation-of-ascp-through-transferd).
 
 On Linux, check the minimum required GLIBC on this site: [repology.org](https://repology.org/project/glibc/versions), or check your GLIBC version with `ldd`:
 
@@ -242,7 +244,7 @@ ldd --version | head -n1
 ldd (GNU libc) 2.34
 ```
 
-Check an executable's (`ascli`, `ascp`) minimum required GLIBC version:
+Check an executable's (e.g. `/bin/bash`, `ascli`, `ascp`) minimum required GLIBC version:
 
 ```bash
 objdump -p /bin/bash | sed -n 's/^.*GLIBC_//p' | sort -V | tail -n1
@@ -252,9 +254,9 @@ objdump -p /bin/bash | sed -n 's/^.*GLIBC_//p' | sort -V | tail -n1
 2.34
 ```
 
-> **Note:** if `objdump` is not available, then use `strings` or `grep -z 'GLIBC_'|tr \\0 \\n`
+> **Note:** If `objdump` is not available, then use `strings` or `grep -z 'GLIBC_'|tr \\0 \\n`
 
-The required GLIBC version for `ascp` can be found in the [Release Notes of HSTS](https://www.ibm.com/docs/en/ahts) or [here](https://eudemo.asperademo.com/download/sdk.html).
+The required GLIBC version for `ascp` can be found in the [Release Notes of HSTS](https://www.ibm.com/docs/en/ahts) or [in this page](https://eudemo.asperademo.com/download/sdk.html).
 
 ### Ruby
 
@@ -558,7 +560,7 @@ gem install bigdecimal -v '~> 3.1.9'
 Once you have Ruby and rights to install gems, install the `aspera-cli` gem and its dependencies:
 
 ```bash
-gem install aspera-cli --pre
+gem install aspera-cli
 ```
 
 To upgrade to the latest version:
@@ -607,10 +609,7 @@ This can be installed either be installing an Aspera transfer software or using
 
 #### Installation of `ascp` through `transferd`
 
-The easiest option to install `ascp` is through the use of the IBM Aspera Transfer Daemon.
-
-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).
-
+The easiest option to install `ascp` is through the use of the IBM Aspera Transfer Daemon (`transferd`).
 Install using `ascli` for the current platform with:
 
 ```bash
@@ -623,14 +622,18 @@ or
 ascli config transferd install
 ```
 
-The installation of the transfer binary follows those steps:
+The installation of the transfer binaries follows those steps:
 
-- Check the value of option `sdk_url`: if the value is the default value `DEF`, then the procedure follows, else it specified a URL where to take the archive from.
-- The location of archives is retrieved from the URL specified by option `locations_url` whose default value is <https://ibm.biz/sdk_location>
-- The archive for the current system architecture (CPU and OS) is selected and downloaded.
+- Check the value of option `sdk_url`: if the value is the default value `DEF`, then the procedure follows, else it specifies directly the URL where to take the archive from.
+- Download the YAML file from the URL specified by option `locations_url` whose default value is <https://ibm.biz/sdk_location>. This file provides the list of supported OS, CPU and versions of the Aspera Transfer Daemon.
+- Select the archive for the current system architecture (CPU and OS) is selected and downloaded. An alternate version can be specified as position argument, e.g. `1.1.3`.
+- By default, the archive is extracted to `$HOME/.aspera/sdk`, this can be changed by setting the `sdk_folder` option.
 
-The option `locations_url` can be set to override the URL where the list of versions is located, in case of air-gap environment or for testing.
-Option `sdk_url` can be set to specify a direct location for the transfer binaries.
+| Option          | Default | Description |
+|-----------------|---------|-------------|
+| `sdk_url`       | `DEF`   | URL to download the Aspera Transfer SDK archive. `DEF` means: select from available archives. |
+| `locations_url` | `https://ibm.biz/sdk_location` | URL to get download URLs of Aspera Transfer Daemon from IBM official repository. |
+| `sdk_folder`    | `$HOME/.aspera/sdk` | Folder where the SDK archive is extracted. |
 
 Available Transfer Daemon versions available from `locations_url` can be listed with: `ascli config transferd list`
 
@@ -652,7 +655,7 @@ To download it, pipe to `config download`:
 ascli config transferd list --select=@json:'{"platform":"osx-arm64","version":"1.1.3"}' --fields=url | ascli config download @stdin:
 ```
 
-If installation from a local file preferred instead of fetching from internet: one can specify the location of the SDK file with option `sdk_url`:
+If installation from a local file preferred (airgap installation) instead of fetching from internet: one can specify the location of the SDK file with option `sdk_url`:
 
 ```bash
 ascli config ascp install --sdk-url=file:///macos-arm64-1.1.3-c6c7a2a.zip
@@ -660,6 +663,8 @@ ascli config ascp 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.
 
+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).
+
 #### Installation of `ascp` through other component
 
 If the embedded method is not used, the following packages are also suitable:
@@ -685,7 +690,7 @@ Refer to section: [Transfer Agents](#transfer-clients-agents)
 
 #### Gem files and dependencies
 
-The sample script: [examples/build_package.sh](examples/build_package.sh) can be used to download all necessary gems and dependencies in a `tar.gz`.
+The sample script: [windows/build_package.sh](windows/build_package.sh) can be used to download all necessary gems and dependencies in a `tar.gz`.
 
 ```console
 $ ./build_package.sh aspera-cli 4.18.0
@@ -769,7 +774,7 @@ gem install --force --local *.gem
 ascli config ascp install --sdk-url=file:///sdk.zip
 ```
 
-> **Note:** An example of installation script is provided: [docs/install.bat](docs/install.bat)
+> **Note:** An example of installation script is provided: [windows/install.bat](windows/install.bat)
 
 ### Container
 
@@ -810,7 +815,7 @@ That is simple, but there are limitations:
 
 #### Container: Details
 
-The container image is built from this [Dockerfile](Dockerfile.tmpl.erb).
+The container image is built from this [Dockerfile](container/Dockerfile.tmpl.erb).
 The entry point is `ascli` and the default command is `help`.
 
 The container can be executed for individual commands like this: (add `ascli` commands and options at the end of the command line, e.g. `-v` to display the version)
@@ -832,7 +837,7 @@ ascli -v
 ```
 
 ```text
-4.22.0.pre
+4.23.0
 ```
 
 In order to keep persistency of configuration on the host, you should specify your user's configuration folder as a volume for the container.
@@ -877,9 +882,9 @@ asclish
 
 #### Container: Sample start script
 
-A convenience sample script is also provided: download the script [`dascli`](../examples/dascli) from [the GIT repo](https://raw.githubusercontent.com/IBM/aspera-cli/main/examples/dascli) :
+A convenience sample script is also provided: download the script [`dascli`](../container/dascli) from [the GIT repo](https://raw.githubusercontent.com/IBM/aspera-cli/main/container/dascli) :
 
-> **Note:** If you have installed `ascli`, the script `dascli` can also be found: `cp $(ascli config gem path)/../examples/dascli ascli`
+> **Note:** If you have installed `ascli`, the script `dascli` can also be found: `cp $(ascli config gem path)/../container/dascli ascli`
 
 Some environment variables can be set for this script to adapt its behavior:
 
@@ -899,7 +904,7 @@ To add local storage as a volume, you can use the env var `docker_args`:
 Example of use:
 
 ```bash
-curl -o ascli https://raw.githubusercontent.com/IBM/aspera-cli/main/examples/dascli
+curl -o ascli https://raw.githubusercontent.com/IBM/aspera-cli/main/container/dascli
 chmod a+x ascli
 export xferdir=$HOME/xferdir
 mkdir -p $xferdir
@@ -2170,7 +2175,7 @@ preset set default shares conf_name
 preset show conf_name
 preset unset conf_name param
 preset update conf_name --p1=v1 --p2=v2
-proxy_check --fpac=@file:examples/proxy.pac https://eudemo.asperademo.com --proxy-credentials=@list:,user,pass
+proxy_check --fpac=@file:proxy.pac https://eudemo.asperademo.com --proxy-credentials=@list:,user,pass
 pubkey @file:my_key
 remote_certificate chain https://node.example.com/path
 remote_certificate name https://node.example.com/path
@@ -2298,9 +2303,9 @@ The wizard is a command that asks the user for information and creates an [Optio
 
 It takes three optional arguments:
 
-- the URL of the application, else it will ask for it
-- the plugin name: it limits detection to a given plugin, else it will try to detect known plugins from the URL
-- the preset name: it will create a new [Option Preset](#option-preset) with this name, else it will use specific information to generate a unique preset name.
+- The URL of the application, else it will ask for it;
+- The plugin name: it limits detection to a given plugin, else it will try to detect known plugins from the URL
+- The preset name: it will create a new [Option Preset](#option-preset) with this name, else it will use specific information to generate a unique preset name.
 
 Special options are also available to the wizard:
 
@@ -3919,7 +3924,7 @@ ascli server upload "faux:///mydir?file=testfile&count=1000&size=1" --to-folder=
 ```text
 ascli -h
 NAME
-        ascli -- a command line tool for Aspera Applications (v4.22.0.pre)
+        ascli -- a command line tool for Aspera Applications (v4.23.0)
 
 SYNOPSIS
         ascli COMMANDS [OPTIONS] [ARGS]
@@ -3990,21 +3995,21 @@ OPTIONS: global
         --default=ENUM               Wizard: set as default configuration for specified plugin (also: update): no, [yes]
         --test-mode=ENUM             Wizard: skip private key check step: [no], yes
         --key-path=VALUE             Wizard: path to private key for JWT
-        --ascp-path=VALUE            Path to ascp
-        --use-product=VALUE          Use ascp from specified product
-        --sdk-url=VALUE              URL to get Aspera Transfer Daemon
-        --locations-url=VALUE        URL to get locations of Aspera Transfer Daemon
-        --sdk-folder=VALUE           SDK folder path
+        --ascp-path=VALUE            Ascp: Path to ascp
+        --use-product=VALUE          Ascp: Use ascp from specified product
+        --sdk-url=VALUE              Ascp: URL to get Aspera Transfer Executables
+        --locations-url=VALUE        Ascp: URL to get locations of Aspera Transfer Daemon
+        --sdk-folder=VALUE           Ascp: SDK folder path
         --progress-bar=ENUM          Display progress bar: [no], yes
-        --smtp=VALUE                 SMTP configuration (Hash)
-        --notify-to=VALUE            Email recipient for notification of transfers
-        --notify-template=VALUE      Email ERB template for notification of transfers
-        --insecure=ENUM              Do not validate any HTTPS certificate: [no], yes
-        --ignore-certificate=VALUE   Do not validate HTTPS certificate for these URLs (Array)
-        --silent-insecure=ENUM       Issue a warning if certificate is ignored: no, [yes]
-        --cert-stores=VALUE          List of folder with trusted certificates (Array, String)
-        --http-options=VALUE         Options for HTTP/S socket (Hash)
-        --http-proxy=VALUE           URL for HTTP proxy with optional credentials (String)
+        --smtp=VALUE                 Email: SMTP configuration (Hash)
+        --notify-to=VALUE            Email: Recipient for notification of transfers
+        --notify-template=VALUE      Email: ERB template for notification of transfers
+        --insecure=ENUM              HTTP/S: Do not validate any certificate: [no], yes
+        --ignore-certificate=VALUE   HTTP/S: Do not validate certificate for these URLs (Array)
+        --silent-insecure=ENUM       HTTP/S: Issue a warning if certificate is ignored: no, [yes]
+        --cert-stores=VALUE          HTTP/S: List of folder with trusted certificates (Array, String)
+        --http-options=VALUE         HTTP/S: Options for HTTP/S socket (Hash)
+        --http-proxy=VALUE           HTTP/S: URL for proxy with optional credentials (String)
         --cache-tokens=ENUM          Save and reuse OAuth tokens: no, [yes]
         --fpac=VALUE                 Proxy auto configuration script
         --proxy-credentials=VALUE    HTTP proxy credentials for fpac: user, password (Array)
@@ -4187,6 +4192,7 @@ OPTIONS:
         --workspace=VALUE            Name of workspace (String, NilClass)
         --new-user-option=VALUE      New user creation option for unknown package recipients (Hash)
         --validate-metadata=ENUM     Validate shared inbox metadata: no, [yes]
+        --package-folder=VALUE       Field of package to use as folder name, or @none: (String, NilClass)
 
 
 COMMAND: server
@@ -5133,7 +5139,7 @@ In this case:
   - Specify the source folder as first item in the list
   - followed by the list of file names.
 
-### Packages
+### Packages app
 
 The web-mail-like application.
 
@@ -5142,7 +5148,7 @@ The web-mail-like application.
 General syntax:
 
 ```bash
-ascli aoc packages send [package extended value] [other parameters such as file list and transfer parameters]
+ascli aoc packages send [package extended value] [other parameters such as options and file list]
 ```
 
 Package creation parameter are sent as **Command Parameter**.
@@ -5166,30 +5172,13 @@ If a user recipient (email) is not already registered and the workspace allows e
 - if the option `new_user_option` is `@json:{"package_contact":true}` (default), then a public link is sent and the external user does not need to create an account
 - if the option `new_user_option` is `@json:{}`, then external users are invited to join the workspace
 
-#### List packages
-
-By default, when using `aoc packages list` or `aoc packages receive ALL`, the following `query` is performed:
-
-| Query parameter            | Value   |
-|----------------------------|---------|
-| `archived`                 | `false` |
-| `has_content`              | `true`  |
-| `received`                 | `true`  |
-| `completed`                | `true`  |
-| `workspace_id`             | Set based on current workspace |
-| `dropbox_id`               | Set according to `dropbox_name`, if provided |
-| `exclude_dropbox_packages` | `true` unless `dropbox_id` is provided |
-
-Parameters provided using option `query` override this query.
-To remove a parameter, set it to `null`.
-
-#### Example: Send a package with one file to two users, using their email
+##### Example: Send a package with one file to two users, using their email
 
 ```bash
 ascli aoc packages send @json:'{"name":"my title","note":"my note","recipients":["someuser@example.com","other@example.com"]}' my_file.dat
 ```
 
-#### Example: Send a package to a shared inbox with metadata
+##### Example: Send a package to a shared inbox with metadata
 
 ```bash
 ascli aoc packages send --workspace="my ws" @json:'{"name":"my pack title","recipients":["Shared Inbox With Meta"],"metadata":{"Project Id":"123","Type":"Opt2","CheckThose":["Check1","Check2"],"Optional Date":"2021-01-13T15:02:00.000Z"}}' ~/Documents/Samples/200KB.1
@@ -5201,45 +5190,7 @@ It is also possible to use identifiers and API parameters:
 ascli aoc packages send --workspace="my ws" @json:'{"name":"my pack title","recipients":[{"type":"dropbox","id":"12345"}],"metadata":[{"input_type":"single-text","name":"Project Id","values":["123"]},{"input_type":"single-dropdown","name":"Type","values":["Opt2"]},{"input_type":"multiple-checkbox","name":"CheckThose","values":["Check1","Check2"]},{"input_type":"date","name":"Optional Date","values":["2021-01-13T15:02:00.000Z"]}]}' ~/Documents/Samples/200KB.1
 ```
 
-#### Example: List packages in a given shared inbox
-
-When user packages are listed, the following query is used:
-
-```json
-{"archived":false,"exclude_dropbox_packages":true,"has_content":true,"received":true}
-```
-
-To list packages in a shared inbox, the query has to be specified with the shared inbox by name or its identifier.
-Additional parameters can be specified, as supported by the API (to find out available filters, consult the API definition, or use the web interface in developer mode).
-The current workspace is added unless specified in the query.
-
-> **Note:** By default, `exclude_dropbox_packages` is set to `true` for user packages, and to false for shared inbox packages. This can be overridden in the query.
-
-Using shared inbox name:
-
-```bash
-ascli aoc packages list --query=@json:'{"dropbox_name":"My Shared Inbox","archived":false,"received":true,"has_content":true,"exclude_dropbox_packages":false,"include_draft":false,"sort":"-received_at"}'
-```
-
-Using shared inbox identifier: first retrieve the ID of the shared inbox, and then list packages with the appropriate filter.
-
-```bash
-shared_box_id=$(ascli aoc packages shared_inboxes show --name='My Shared Inbox' --format=csv --display=data --fields=id)
-```
-
-```bash
-ascli aoc packages list --query=@json:'{"dropbox_id":"'$shared_box_id'","archived":false,"received":true,"has_content":true,"exclude_dropbox_packages":false,"include_draft":false,"sort":"-received_at"}'
-```
-
-#### Example: Receive all packages from a given shared inbox
-
-```bash
-ascli aoc packages recv ALL --workspace=_workspace_ --once-only=yes --lock-port=12345 --query=@json:'{"dropbox_name":"_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}'
-```
-
-To list packages that would be downloaded, without actually downloading them, replace `recv ALL` with `list` (keep options `once_only` and `query`)
-
-#### Example: Send a package with files from the Files app
+##### Example: Send a package with files from the Files app
 
 Find files in Files app:
 
@@ -5264,7 +5215,35 @@ Let's send a package with the file `10M.dat` from subfolder /src_folder in a pac
 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=node --transfer-info=@json:@stdin:
 ```
 
-#### Receive new packages only (Cargo)
+#### Receive packages
+
+The command to receive one or multiple packages is:
+
+```bash
+ascli aoc packages recv <package id> [<file> ...]
+```
+
+Where `<package id>` is the identifier of the package to receive or `ALL` to receive all packages matching the query.
+Option `once_only` is supported, see below.
+
+To download only some files from the package, just add the path of the files on the command line: `[<file> ...]`, see option `sources`.
+By default, all files in the package are downloaded, i.e. `.` is used as the file list.
+
+Option `package_folder` defines the attribute of folder used as destination sub folder in the `to_folder` path (see description earlier).
+The default value is `@none:` : package files will be downloaded directly inside the folder specified by option `to_folder`.
+The option `package_folder` can be set to the name of **any** attributes of the package.
+Notably, `id` or `name` can be used.
+Using option `--package-folder=id` ensures that every downloaded package is placed in a subfolder named after its unique ID.
+
+##### Example: Receive all packages from a given shared inbox
+
+```bash
+ascli aoc packages recv ALL --workspace=_workspace_ --once-only=yes --lock-port=12345 --query=@json:'{"dropbox_name":"_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}'
+```
+
+To list packages that would be downloaded, without actually downloading them, replace `recv ALL` with `list` (keep options `once_only` and `query`)
+
+##### Receive new packages only (Cargo)
 
 It is possible to automatically download new packages, like using Aspera Cargo:
 
@@ -5278,7 +5257,7 @@ ascli aoc packages recv ALL --once-only=yes --lock-port=12345
 
 Typically, one would execute this command on a regular basis, using the method of your choice: see [Scheduler](#scheduler).
 
-### Example: Content of a received Package
+##### Example: Content of a received Package
 
 Some `node` operations are available for a package, such as `browse` and `find`.
 
@@ -5288,9 +5267,7 @@ To list the content of a package, use command `packages browse <package id> <fol
 ascli aoc package browse my5CnbeWng /
 ```
 
-To list recursively, use command `find`.
-
-To download only some files listed in the package, just add the path of the files on the command line.
+Use command `find` to list recursively.
 
 For advanced users, it's also possible to pipe node information for the package and use node operations:
 
@@ -5298,7 +5275,54 @@ For advanced users, it's also possible to pipe node information for the package
 ascli aoc package node_info <package ID here> / --format=json --show-secrets=yes --display=data | ascli node -N --preset=@json:@stdin: access_key do self browse /
 ```
 
-### Files
+#### List packages
+
+By default, when using `aoc packages list` or `aoc packages receive ALL`, the following `query` is performed:
+
+| Query parameter            | Value   |
+|----------------------------|---------|
+| `archived`                 | `false` |
+| `has_content`              | `true`  |
+| `received`                 | `true`  |
+| `completed`                | `true`  |
+| `workspace_id`             | Set based on current workspace. |
+| `dropbox_id`               | Set according to `dropbox_name`, if provided. |
+| `exclude_dropbox_packages` | `true` unless `dropbox_id` is provided. |
+
+Parameters provided using option `query` override this query.
+To remove a parameter, set it to `null`.
+
+##### Example: List packages in a given shared inbox
+
+When user packages are listed, the following query is used:
+
+```json
+{"archived":false,"exclude_dropbox_packages":true,"has_content":true,"received":true}
+```
+
+To list packages in a shared inbox, the query has to be specified with the shared inbox by name or its identifier.
+Additional parameters can be specified, as supported by the API (to find out available filters, consult the API definition, or use the web interface in developer mode).
+The current workspace is added unless specified in the query.
+
+> **Note:** By default, `exclude_dropbox_packages` is set to `true` for user packages, and to false for shared inbox packages. This can be overridden in the query.
+
+Using shared inbox name:
+
+```bash
+ascli aoc packages list --query=@json:'{"dropbox_name":"My Shared Inbox","archived":false,"received":true,"has_content":true,"exclude_dropbox_packages":false,"include_draft":false,"sort":"-received_at"}'
+```
+
+Using shared inbox identifier: first retrieve the ID of the shared inbox, and then list packages with the appropriate filter.
+
+```bash
+shared_box_id=$(ascli aoc packages shared_inboxes show --name='My Shared Inbox' --format=csv --display=data --fields=id)
+```
+
+```bash
+ascli aoc packages list --query=@json:'{"dropbox_id":"'$shared_box_id'","archived":false,"received":true,"has_content":true,"exclude_dropbox_packages":false,"include_draft":false,"sort":"-received_at"}'
+```
+
+### Files app
 
 The Files application presents a **Home** folder to users in a given workspace.
 Files located here are either user's files, or shared folders.
@@ -5348,42 +5372,46 @@ The basic payload (last argument at creation usually specified with `@json:`) is
 ```
 
 `ascli` expects the same payload for creation.
-`ascli` automatically populates this payload like this:
-
-- `file_id` : the ID of the folder to share whose path is specified in the command line
-- `access_levels` : are set by default to full access.
-- `tags` : are set with expected values for AoC: username who creates, and workspace in which the shared folder is created.
-- `access_type` and `access_id` : need to be set by the user, or using special key as follows.
-
-To change `access_levels`, just provide the list of levels in the `@json:` payload.
+`ascli` automatically populates some payload fields and provides convenient additional fields that generate native fields:
 
-In order to declare/create the shared folder in the workspace, a special value for `access_id` is used: `ASPERA_ACCESS_KEY_ADMIN_WS_[workspace ID]]`. This is conveniently set by `ascli` using an empty string for the pseudo key `with`. In order to share a folder with a different, special tags are set, but this is conveniently done by `ascli` using the `as` key.
+<!-- markdownlint-disable MD033 -->
+| Field           | Type     | Description |
+|-----------------|----------|-------------|
+| `file_id`       | Native<br/>Auto     | ID of the folder to share, as specified in the command line by path. |
+| `access_levels` | Native<br/>Optional | List of access levels to set for the shared folder. Defaults to full access. |
+| `tags`          | Native<br/>Auto     | Set with expected values for AoC: username who creates, and workspace in which the shared folder is created. |
+| `access_type`   | Native<br/>Required | Type of access, such as `user`, `group`, or `workspace`. Can be set with parameter `with`. |
+| `access_id`     | Native<br/>Required | ID of the user, group, or workspace (see `with`) |
+| `with`          | `ascli`           | Recipient of shared folder. Can be a username, a group name, or a workspace name. `ascli` will resolve the name to the proper type and ID in fields `access_type` and `access_id`. If the value is the empty string, then it declares the shared folder in the workspace (first action to do, see below). |
+| `link_name`     |  `ascli`          | Name of the link file created in the user's home folder for private links. |
+| `as`            |  `ascli`          | Name of the link file created in the user's home folder for admin shared folders. |
+<!-- markdownlint-enable MD033 -->
 
-The following optional additional helper keys are supported by `ascli`:
+In order to declare/create the shared folder in the workspace, a special value for `access_id` is used: `ASPERA_ACCESS_KEY_ADMIN_WS_[workspace ID]]`.
+This is conveniently set by `ascli` using an empty string for the pseudo key `with`.
+In order to share a folder with a different, special tags are set, but this is conveniently done by `ascli` using the `as` key.
 
-- `with` : Recipient of shared folder. Can be a username, a group name, or a workspace name. `ascli` will resolve the name to the proper type and ID in fields `access_type` and `access_id`. If the value is the empty string, then it declares the shared folder in the workspace (first action to do, see below).
-- `link_name` : The name of the link file created in the user's home folder for private links.
-- `as` : The name of the link file created in the user's home folder for admin shared folders.
-
-- List permissions on a shared folder as user
+##### Example: List permissions on a shared folder
 
 ```bash
 ascli aoc files perm /shared_folder_test1 list
 ```
 
-- Share a personal folder with other users
+##### Example: Share a personal folder with other users
 
 ```bash
 ascli aoc files perm /shared_folder_test1 create @json:'{"with":"laurent"}'
 ```
 
-- Revoke shared access
+##### Example: Revoke shared access
 
 ```bash
 ascli aoc files perm /shared_folder_test1 delete 6161
 ```
 
-Public and Private short links can be managed with command:
+##### Example: Public and Private short links
+
+They can be managed with commands:
 
 ```bash
 ascli aoc files short_link _path_here_ private create
@@ -5392,17 +5420,63 @@ ascli aoc files short_link _path_here_ public list
 ascli aoc files short_link public delete _id_
 ```
 
-- Create an admin shared folder and shared with a user or group or workspace
+##### Example: Create a workspace shared folder
+
+First, identify the node ID where the shared folder will be created.
+
+To use the default node for workspace `my ws`, use the command:
+
+```bash
+ascli aoc admin workspace show %name:'my ws' --fields=node_id
+```
+
+Alternatively (longer):
+
+```bash
+ascli aoc admin workspace list --select=@json:'{"name":"my ws"}' --fields=node_id
+```
+
+Or select manually from the list of nodes:
+
+```bash
+ascli aoc admin node list --fields=id,name
+```
+
+In the following commands, replace:
+
+- `1234` with the node ID
+- `my ws` with the workspace name
+- `folder_on_node` with the name of the folder on the node
+
+The node can also be conveniently identified using the **percent selector** instead of numerical ID: `%name:"my node"`.
+
+If the shared folder does not exist, then create it:
 
 ```bash
 ascli aoc admin node do 1234 mkdir folder_on_node
+```
+
+Create the shared folder in workspace `my ws` (set `with` to empty string, or do not specify it).
+Optionally use `as` to set the name of the shared folder if different from the folder name on the node.
+For other options, refer to the previous section on shared folders.
+
+```bash
 ascli aoc admin node do 1234 perm folder_on_node create @json:'{"with":"","as":"folder_for_users"}' --workspace="my ws"
-ascli aoc admin node do 1234 perm folder_on_node create @json:'{"with":"john@example.com","as":"folder_for_users"}' --workspace="my ws"
-ascli aoc admin node do 1234 perm folder_on_node create @json:'{"with":"group 1","as":"folder_for_users"}' --workspace="my ws"
-ascli aoc admin node do 1234 perm folder_on_node create @json:'{"with":"my ws","as":"folder_for_users"}' --workspace="my ws"
 ```
 
-> **Note:** The node can be conveniently identified using the **percent selector** instead of numerical ID.
+To share with a user, group, or workspace, use the `with` parameter:
+
+```bash
+ascli aoc admin node do 1234 perm folder_on_node create @json:'{"with":"john@example.com","as":"folder_for_one_user"}' --workspace="my ws"
+```
+
+```bash
+ascli aoc admin node do 1234 perm folder_on_node create @json:'{"with":"group 1","as":"folder_for_a_group"}' --workspace="my ws"
+```
+
+```bash
+ascli aoc admin node do 1234 perm folder_on_node create @json:'{"with":"my ws","as":"folder_for_all_workspace"}' --workspace="my ws"
+```
 
 #### Cross Organization transfers
 
@@ -5561,7 +5635,7 @@ packages receive ALL --once-only=yes --to-folder=. --lock-port=12345
 packages receive ALL --once-only=yes --to-folder=. --lock-port=12345 --query=@json:'{"dropbox_name":"my_shared_inbox_name","archived":false,"received":true,"has_content":true,"exclude_dropbox_packages":false,"include_draft":false}' --ts=@json:'{"resume_policy":"sparse_csum","target_rate_kbps":50000}'
 packages receive INIT --once-only=yes --query=@json:'{"dropbox_name":"my_shared_inbox_name"}'
 packages receive package_id3 --to-folder=.
-packages receive package_id3 --to-folder=. /
+packages receive package_id3 --to-folder=. / --package-folder=name
 packages send --workspace=my_workspace_shared_inbox --validate-metadata=yes @json:'{"name":"$(notdir test) PACKAGE_TITLE_BASE","recipients":["my_shared_inbox_meta"],"metadata":[{"input_type":"single-text","name":"Project Id","values":["123"]},{"input_type":"single-dropdown","name":"Type","values":["Opt2"]},{"input_type":"multiple-checkbox","name":"CheckThose","values":["Check1","Check2"]},{"input_type":"date","name":"Optional Date","values":["2021-01-13T15:02:00.000Z"]}]}' test_file.bin
 packages send --workspace=my_workspace_shared_inbox --validate-metadata=yes @json:'{"name":"$(notdir test) PACKAGE_TITLE_BASE","recipients":["my_shared_inbox_meta"],"metadata":{"Project Id":"456","Type":"Opt2","CheckThose":["Check1","Check2"],"Optional Date":"2021-01-13T15:02:00.000Z"}}' test_file.bin
 packages send --workspace=my_workspace_shared_inbox --validate-metadata=yes @json:'{"name":"$(notdir test) PACKAGE_TITLE_BASE","recipients":["my_shared_inbox_meta"],"metadata":{"Type":"Opt2","CheckThose":["Check1","Check2"],"Optional Date":"2021-01-13T15:02:00.000Z"}}' test_file.bin
@@ -5575,6 +5649,7 @@ packages shared_inboxes show %name:my_shared_inbox_name
 remind --username=my_user_email
 servers
 tier_restrictions
+user contacts list
 user pref modify @json:'{"default_language":"en-us"}'
 user pref show
 user profile modify @json:'{"name":"dummy change"}'
@@ -6267,7 +6342,7 @@ ascli node access_key modify %id:self @ruby:'{token_verification_key: File.read(
   ascli node bearer_token @file:./myorgkey.pem @json:'{"user_id":"'$my_user_id'","_validity":3600}' --output=bearer.txt
   ```
 
-> **Note:** The Bearer token can also be created using command `asnodeadmin` on HSTS. Refer to the [HSTS manual](https://www.ibm.com/docs/en/ahts): `Bearer tokens` section. Code for token generation is provided in [lib/aspera/api/node.rb](lib/aspera/api/node.rb)
+> **Note:** The Bearer token can also be created using command `asnodeadmin` on HSTS. Refer to the [HSTS manual](https://www.ibm.com/docs/en/ahts): `Bearer tokens` section. Code for token generation is provided in [`lib/aspera/api/node.rb`](lib/aspera/api/node.rb)
 
 #### Bearer token: User side
 
@@ -6369,22 +6444,27 @@ watch_folder list
 
 ### Open Telemetry
 
-The Node plugin supports Open Telemetry (OTel) for monitoring and tracing.
+The `node` plugin supports Open Telemetry (OTel) for monitoring and tracing.
+
+> **Note:** This is an experimental feature and currently only available for the `node` plugin and Instana backend.
 
-`ascli` can poll the Node API for transfer events and send them to an OTel collector.
+`ascli` polls the Node API for transfer events and sends them to an OTel collector.
 
 The command expects the following parameters provided as a `Hash` positional parameter:
 
-| Parameter   | Type     | Default |  Description                    |
-|-------------|----------|---------|---------------------------------|
-| `url`       | `String` | -       | URL of the Instana backend.     |
-| `apikey`    | `String` | -       | Token for the OTel collector.   |
-| `interval`  | `Float`  | 10      | Polling interval in seconds.    |
+| Parameter   | Type     | Default |  Description                                      |
+|-------------|----------|---------|---------------------------------------------------|
+| `url`       | `String` | -       | URL of the Instana HTTPS backend for OTel.        |
+| `key`       | `String` | -       | Agent key for the backend.                        |
+| `interval`  | `Float`  | 10      | Polling interval in seconds. `0` for single shot. |
 
-For convenience, those parameters can be provided in a preset, e.g. `otel_default`.
+To retrieve OTel backend information: Go to the Instana web interface, **More** &rarr; **Agents** &rarr; **Docker** and identify the agent endpoint and key, e.g. `endpoint=ingress-blue-saas.instana.io`.
+Identify the region and the endpoint URL will be `https://otlp-[region]-saas.instana.io`, i.e. replace `ingress` with `otlp`.
+
+For convenience, those parameters can be provided in a preset, e.g. named `otel_default`.
 
 ```bash
-ascli config preset init otel_default @json:'{"url":"https://otlp-orange-saas.instana.io:4318","apikey":"*********","interval":1.1}'
+ascli config preset init otel_default @json:'{"url":"https://otlp-orange-saas.instana.io:4318","key":"*********","interval":1.1}'
 ```
 
 Then it is invoked like this (assuming a default node is configured):
@@ -6393,6 +6473,12 @@ Then it is invoked like this (assuming a default node is configured):
 ascli node telemetry @preset:otel_default
 ```
 
+In Instana, create a custom Dashboard to visualize the OTel data:
+
+- Add Widget: Histogram
+- Data Source: Infrastructure and Platforms
+- Metric: search `transfer`
+
 ## Plugin: `faspex5`: IBM Aspera Faspex v5
 
 IBM Aspera's newer self-managed application.
@@ -7496,7 +7582,7 @@ If you use a value different from `16777216`, then specify it using option `max_
 
 `ascli` requires the following external tools available in the `PATH`:
 
-- **ImageMagick** v7+: `magick` `composite`
+- **ImageMagick** v7+: `magick` (for tools: `convert` and `composite`)
 - **OptiPNG** : `optipng`
 - **FFmpeg** : `ffmpeg` `ffprobe`
 - **LibreOffice** : `unoconv`
@@ -7523,6 +7609,19 @@ Prefer ImageMagick version >=7.
 
 More info on ImageMagick at <https://imagemagick.org/>
 
+If your OS has only ImageMagick v6, then you can create a script called `magick` and add it to your `PATH`:
+
+```bash
+#!/bin/bash
+exec "$@"
+```
+
+make it executable:
+
+```bash
+chmod a+x /usr/local/bin/magick
+```
+
 #### Video: FFmpeg
 
 The easiest method is to download and install the latest released version of `ffmpeg` with static libraries from [https://johnvansickle.com/ffmpeg/](https://johnvansickle.com/ffmpeg/)
@@ -7745,6 +7844,7 @@ check --skip-types=office
 events --once-only=yes --skip-types=office --log-level=info
 scan --scan-id=1 --skip-types=office --log-level=info --file-access=remote --ts=@json:'{"target_rate_kbps":1000000}'
 scan --skip-types=office --log-level=info
+show --base=test /etc/hosts
 show --base=test my_docx
 show --base=test my_mpg --video-png-conv=animated
 show --base=test my_mpg --video-png-conv=fixed