aspera-cli 4.27.3 → 4.27.4

data/docs/README.md

@@ -11,7 +11,7 @@ EDITING GUIDELINES (developers and AI):
 DO NOT EDIT: THIS FILE IS GENERATED, edit docs/README.erb.md.
 PANDOC_DEFAULTS_BEGIN
 metadata:
-  subtitle: "ascli 4.27.3"
+  subtitle: "ascli 4.27.4"
   author: "Laurent Martin"
 PANDOC_DEFAULTS_END
 -->
@@ -145,7 +145,7 @@ This section walks you through your first interaction with `ascli` on Linux.
 
 ```shell
 mkdir -p $HOME/bin
-tar -C $HOME/bin -zxvf ascli-4.27.3-linux-x86_64.tgz
+tar -C $HOME/bin -zxvf ascli-4.27.4-linux-x86_64.tgz
 export PATH=$PATH:$HOME/bin
 ```
 
@@ -159,7 +159,7 @@ ascli -v
 ```
 
 ```text
-4.27.3
+4.27.4
 ```
 
 - Install the Aspera transfer runtime (tested version), as it is not included in the `ascli` package:
@@ -294,6 +294,9 @@ There are several ways to install `ascli`:
 - As a [single file executable](#single-file-executable)
 
   This method is simple, but only a limited number of platforms are supported.
+- On Linux, as a [portable package](#linux-portable-package)
+
+  This method is simple on Linux: extract and run, without root access. It includes Ruby, gems and `ascp`.
 - On Windows, as a [portable package](#windows-portable-package)
 
   This method is the simplest on Windows: extract and run. It includes Ruby, gems and `ascp`.
@@ -316,20 +319,20 @@ This executable includes the Ruby runtime and gems, but not the transfer SDK.
 #### Installing the single file executable
 
 > [!NOTE]
-> Replace `<VERSION>` and `<PLATFORM>` with the values of the downloaded archive, for example: `linux-x86_64`.
-> The archive contains a single file: the executable `ascli`.
+> Replace `<VERSION>` and `<PLATFORM>` with the values of the downloaded archive, for example: `linux-x86_64-glibc2.28-ocran`.
+> The archive contains the executable `ascli` and its `README.ascli.md`.
 > Installation of `ascp` is still required separately.
 > See [Install `ascp`](#installing-ascp-through-transferd).
 
 ```shell
-tar zxvf ascli-<VERSION>-<PLATFORM>.tgz
+tar zxvf aspera-cli-<VERSION>-<PLATFORM>.tgz
 ./ascli config transferd install
 ```
 
 #### Linux: Checking the GLIBC version
 
 > [!WARNING]
-> On Linux, the executable requires a minimum GLIBC version, specified in the executable name on the download site.
+> On Linux, the executable requires a minimum GLIBC version, specified in the archive name on the download site (for example: `glibc2.28`).
 > If the minimum version is not met, then executables (`ascp`, `transferd`) will exit with error.
 
 On Linux, you can check your system's GLIBC version on this site: [repology.org](https://repology.org/project/glibc/versions), or check your GLIBC version with `ldd`:
@@ -357,9 +360,40 @@ objdump -p /bin/bash | sed -n 's/^.*GLIBC_//p' | sort -V | tail -n1
 
 The required GLIBC version for `ascp` can be found in the [Release Notes of HSTS](https://www.ibm.com/docs/en/ahts) or [on this page](https://eudemo.asperademo.com/download/sdk.html).
 
+### Linux: Portable package
+
+A ready-to-use archive for Linux (x86_64) is available in the [Releases](https://github.com/IBM/aspera-cli/releases): `aspera-cli-<VERSION>-linux-x86_64-glibc2.28-portable.tgz`.
+
+It contains the Ruby runtime with the shared libraries it needs, the aspera-cli gem with its dependencies, and the Aspera Transfer SDK (`ascp`).
+No installation step, no root access, and no internet access are required.
+The GLIBC of the system must be at least the version in the archive name, see [Checking the GLIBC version](#linux-checking-the-glibc-version).
+
+1. Extract the archive, for example in `~/.local/share`, and check that `ascli` runs:
+
+   ```shell
+   tar -xzf aspera-cli-<VERSION>-linux-x86_64-glibc2.28-portable.tgz -C ~/.local/share
+   ~/.local/share/aspera-cli-<VERSION>-linux-x86_64-glibc2.28-portable/ascli -v
+   ```
+
+2. Optionally, place a symbolic link to the launcher in a folder of the `PATH`.
+   Then, `ascli` can be used from any folder:
+
+   ```shell
+   ln -s ~/.local/share/aspera-cli-<VERSION>-linux-x86_64-glibc2.28-portable/ascli ~/.local/bin/ascli
+   ascli -v
+   ```
+
+> [!NOTE]
+> The launcher `ascli` uses the `ascp` located in folder `sdk` of the package, unless environment variable `ASCLI_SDK_FOLDER` is set.
+> So, `ascli config transferd install` is not needed.
+
+The configuration is stored in the [main folder](#main-configuration-and-persistency-folder), like for other installation methods.
+To upgrade, extract the new version, and update the symbolic link.
+To uninstall, delete the folder, and the symbolic link if it was created.
+
 ### Windows: Portable package
 
-A ready-to-use ZIP archive for Windows (x64) is available in the [Releases](https://github.com/IBM/aspera-cli/releases): `aspera-cli-<VERSION>-windows-amd64-portable.zip`.
+A ready-to-use ZIP archive for Windows (x64) is available in the [Releases](https://github.com/IBM/aspera-cli/releases): `aspera-cli-<VERSION>-windows-x86_64-portable.zip`.
 
 It contains the Ruby runtime, the aspera-cli gem with its dependencies, and the Aspera Transfer SDK (`ascp`).
 No installation step, no administrator rights, and no internet access are required.
@@ -933,11 +967,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.3 --no-document --install-dir temp_folder
+gem install aspera-cli:4.27.4 --no-document --install-dir temp_folder
 find temp_folder
-mv temp_folder/cache aspera-cli-4.27.3-gems
+mv temp_folder/cache aspera-cli-4.27.4-gems
 rm -fr temp_folder
-tar zcvf aspera-cli-4.27.3-gems.tgz aspera-cli-4.27.3-gems
+tar zcvf aspera-cli-4.27.4-gems.tgz aspera-cli-4.27.4-gems
 ```
 
 #### Unix-like: Alternative installation using `rvm`
@@ -1073,7 +1107,7 @@ ascli -v
 ```
 
 ```text
-4.27.3
+4.27.4
 ```
 
 To persist the configuration on the host, specify your user's configuration folder as a volume for the container.
@@ -1267,6 +1301,7 @@ ascli config echo '@ruby:[OpenSSL::X509::DEFAULT_CERT_DIR,OpenSSL::X509::DEFAULT
 
 Certificates are checked against the [Ruby default certificate store](https://ruby-doc.org/stdlib-3.0.3/libdoc/openssl/rdoc/OpenSSL/X509/Store.html) `OpenSSL::X509::DEFAULT_CERT_FILE` and `OpenSSL::X509::DEFAULT_CERT_DIR`, which are typically the ones of `openssl` on Unix-like systems (Linux, macOS, and so on).
 Ruby's default values can be overridden using env vars: `SSL_CERT_FILE` and `SSL_CERT_DIR`.
+If neither these env vars are set nor the default locations exist (for example, a single executable built on another Linux distribution), `ascli` sets `SSL_CERT_FILE` to the first system CA bundle found: `/etc/ssl/certs/ca-certificates.crt`, `/etc/pki/tls/certs/ca-bundle.crt`, `/etc/ssl/ca-bundle.pem`, `/etc/ssl/cert.pem`.
 
 To get certificate validation, the CA certificate bundle must be up-to-date.
 Check this repository on how to update the system's CA certificate bundle: [https://github.com/millermatt/osca](https://github.com/millermatt/osca).
@@ -1740,6 +1775,8 @@ Depending on action, the output will contain:
 | `status`        | A message. |
 | `other_struct`  | A complex structure that cannot be displayed as an array. |
 
+With a structured format (`json`, `jsonpp`, `yaml`, `ruby`), the output is always valid in this format: a status is a string, an empty list is `[]`, and no result is `null`.
+
 #### Enhanced display of special values
 
 Special values are highlighted as follows in `format=table`:
@@ -3908,6 +3945,8 @@ For `direct` and `httpgw`, the transfer runs as a Ruby thread inside the `ascli`
 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.
 
+Parameters of the agent are persisted, except secrets (e.g. `password` of agent `node`): `config transfer status` takes them from the current `transfer` option, if it is for the same agent (e.g. same option on command line, or in a preset).
+
 > [!NOTE]
 > **`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.
@@ -3934,7 +3973,7 @@ The `transfer` option accepts the following optional parameters to control multi
 | `file_list` | `Bool` | If `true`, source paths are written to a temp file passed to `ascp` via `--file-list` or `--file-pair-list`.<br/>If `false`, source paths are placed directly on the `ascp` command line.<br/>Default: `true`. |
 | `monitor` | `Bool` | Enable use of the `ascp` management port for transfer monitoring.<br/>Default: `true`. |
 | `multi_incr_udp` | `Bool` | Multi session - Increment UDP port for each session.<br/>If `true`, each session uses a different UDP port starting at `fasp_port` (default: 33001).<br/>If `false`, all sessions use the same `fasp_port` (or `ascp` default).<br/>Default: `true` on Windows, `false` on other platforms. |
-| `quiet` | `Bool` | Suppress the `ascp` progress bar display.<br/>Default: `true`. |
+| `quiet` | `Bool` | Suppress the `ascp` progress bar display.<br/>If `false`, the progress bar of option `progress_bar` is not displayed, unless that option is set.<br/>Default: `true`. |
 | `resume.iter_max` | `Integer` | Maximum number of retry attempts on error.<br/>Default: `7`. |
 | `resume.sleep_factor` | `Integer` | Multiplier applied to sleep duration between consecutive retry attempts.<br/>Default: `2`. |
 | `resume.sleep_initial` | `Integer` | Initial sleep duration (in seconds) before first retry.<br/>Default: `2`. |
@@ -3952,18 +3991,18 @@ Sleep between iterations is given by the following formula where `iter_index` is
 min( sleep_max, sleep_initial * sleep_factor ^ iter_index )
 ```
 
-To display the native progress bar of `ascp`, use:
+By default, the progress bar of `ascli` is displayed (see [Transfer progress bar](#transfer-progress-bar)): it aggregates all sessions of a multi-session transfer.
+
+To display the native progress bar of `ascp` instead, set parameter `quiet` to `false`:
 
 ```shell
---progress-bar=no --transfer.quiet=false
+--transfer.quiet=false
 ```
 
-To skip usage of management port (which disables custom progress bar), set option `monitor` to `false`.
-In that case, use the native progress bar:
+In that case, the progress bar of `ascli` is not displayed, unless option `progress_bar` is set.
+For multi-session transfers, each `ascp` process displays its own progress bar.
 
-```shell
---transfer.monitor=false --transfer.quiet=false
-```
+To skip usage of management port (which disables the progress bar of `ascli`), set option `monitor` to `false`.
 
 By default, Ruby's root CA store is used to validate any HTTPS endpoint used by `ascp` (for example, WSS).
 To use a custom certificate store, use the `trusted_certs` option of direct agent's option `transfer`.
@@ -4727,10 +4766,20 @@ Example: parameter to download a Faspex package and decrypt on the fly
 
 ### Transfer progress bar
 
-File transfer operations are monitored, and a progress bar is displayed on the terminal if option `progress_bar` (`Bool`) is set to `yes` (default if the output is a terminal).
+File transfer operations are monitored, and a progress bar is displayed on the standard error if option `progress_bar` (`Bool`) is set to `yes` (default if the standard error is a terminal).
+So, the progress bar is displayed even if the output of the command is redirected to a file.
 
 The same progress bar is used for any type of transfer: using `ascp`, server to server, using HTTPS, and so on.
 
+It shows the elapsed time, the percentage, the rate in megabits per second (`Mbps`, 1,000,000 bits per second, averaged over the last 5 seconds) and the estimated remaining time.
+As long as the total size is not known (for example, when the job size is not pre-calculated), the transferred size is shown instead of the percentage.
+For multi-session transfers, sessions are aggregated, and the number of running sessions is shown in brackets.
+Files already at destination (resumed transfer) count in the progress, but not in the rate.
+If the transfer fails, the progress bar stops at the reached progress, and shows `failed`.
+Log lines are displayed above the progress bar.
+
+Agent `direct` can display the native progress bar of `ascp` instead (see [`direct`](#agent-direct)).
+
 ### Scheduler
 
 `ascli` does not include a built-in scheduler.
@@ -5150,13 +5199,13 @@ Key query parameters:
   Place only the bare filename(s) in the file list, and pass the `file:` URI as the source prefix so that the query parameters apply uniformly to every entry:
 
   ```shell
-  ascli server upload growing --to-folder=/Upload --ts.source_root='file:///?grow=120' --progress-bar=no --transfer.quiet=false
+  ascli server upload growing --to-folder=/Upload --ts.source_root='file:///?grow=120' --transfer.quiet=false
   ```
 
 - **URI directly on the command line with `file_list=false`**
 
   ```shell
-  ascli server upload 'file:///./growing?grow=120' --to-folder=/Upload --transfer.file_list=false --transfer.quiet=false --progress-bar=no
+  ascli server upload 'file:///./growing?grow=120' --to-folder=/Upload --transfer.file_list=false --transfer.quiet=false
   ```
 
 ### Usage
@@ -5164,7 +5213,7 @@ Key query parameters:
 ```text
 ascli -h
 NAME
-        ascli -- a command line tool for Aspera Applications (v4.27.3)
+        ascli -- a command line tool for Aspera Applications (v4.27.4)
 
 SYNOPSIS
         ascli [GLOBAL_OPTIONS] <command> [OPTIONS] [ARGS]
@@ -5243,9 +5292,6 @@ OPTIONS: global
     --cache-tokens=yes|no          Save and reuse OAuth tokens
     --expand-mounts=yes|no         Commands: list commands of sub-trees provided by another plugin
 -N, --no-default                   Do not load default configuration for plugin
-    --query=HASH                   Additional filter for for some commands (list/delete)
-    --bulk=yes|no                  Bulk operation (only some)
-    --bfail=yes|no                 Bulk operation error handling
     --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
@@ -5255,6 +5301,9 @@ OPTIONS: global
     --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
+    --query=HASH                   Additional filter for for some commands (list/delete)
+    --bulk=yes|no                  Bulk operation (only some)
+    --bfail=yes|no                 Bulk operation error handling
     --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)
@@ -7370,6 +7419,8 @@ admin subscription usage
 admin subscription usage MONTH
 admin user list
 admin user modify %name:my_user_email @: deactivated=false
+admin user notifications %name:my_user_email show
+admin user preferences %name:my_user_email show
 admin workspace dropbox %name:my_other_workspace list
 admin workspace list
 admin workspace shared_folder %name:my_other_workspace list
@@ -7386,9 +7437,9 @@ bearer_token --out.level=data
 files bearer /
 files bearer_token_node / --cache-tokens=no
 files browse /
-files browse / --url=my_private_link
+files browse / --url=my_private_link_shared_folder
 files browse / --url=my_public_link_folder_no_pass
-files browse / --url=my_public_link_folder_pass --password=my_public_link_password
+files browse / --url=my_public_link_folder_with_pass --password=my_public_link_folder_password
 files browse my_remote_file
 files browse my_remote_folder
 files browse my_remote_folder/
@@ -7440,6 +7491,11 @@ packages send @: 'name=package title' END test_file.bin --url=my_public_link_sen
 packages send @: 'name=package title' recipients.0=my_username 'note=some notes' END test_file.bin
 packages send @json:'{"name":"package title","recipients":["my_email_external"]}' --new-user-option.package_contact=true test_file.bin
 packages shared_inboxes list
+packages shared_inboxes short_link public %name:my_shared_inbox_name create --fields=id
+packages shared_inboxes short_link public %name:my_shared_inbox_name delete <aoc_shared_inbox_short_link_create>
+packages shared_inboxes short_link public %name:my_shared_inbox_name list
+packages shared_inboxes short_link public %name:my_shared_inbox_name modify <aoc_shared_inbox_short_link_create> @: password=my_public_link_folder_password
+packages shared_inboxes short_link public %name:my_shared_inbox_name show <aoc_shared_inbox_short_link_create>
 packages shared_inboxes show %name:my_shared_inbox_name
 packages show '%name:package title'
 remind --username=my_user_email --url=https://aoc.example.com/path
@@ -7665,10 +7721,11 @@ upload 'faux:///test.bin?1k' --to-folder=my_upload_folder
 upload --sources=@ts --transfer.ascp_args=@list:,--file-list,file_list.txt --to-folder=my_inside_folder
 upload --sources=@ts --transfer.ascp_args=@list:,--file-pair-list,file_pair_list.txt
 upload --sources=@ts --ts=@json:'{"paths":[{"source":"test_file.bin","destination":"my_inside_folder/other_name_4"}]}' --transfer.agent=transferd
-upload --src-type=pair --sources=@json:'["test_file.bin","my_inside_folder/other_name_3"]' --transfer.quiet=false --progress=no
+upload --src-type=pair --sources=@json:'["test_file.bin","my_inside_folder/other_name_3"]' --transfer.quiet=false
 upload --src-type=pair test_file.bin my_inside_folder/other_name_2 --notify-to=my_email_external '--transfer.ascp_args=@list: -l 100m'
 upload --src-type=pair test_file.bin my_upload_folder/other_name_5 --ts=@json:'{"cipher":"aes-192-gcm","content_protection":"encrypt","content_protection_password":"my_secret_here","cookie":"biscuit","create_dir":true,"delete_before_transfer":false,"delete_source":false,"exclude_newer_than":"-1","exclude_older_than":"-10000","fasp_port":33001,"http_fallback":false,"multi_session":0,"overwrite":"diff+older","precalculate_job_size":true,"preserve_access_time":true,"preserve_creation_time":true,"rate_policy":"fair","resume_policy":"sparse_csum"}'
 upload --to-folder=my_upload_folder/target_hot --lock-port=50101 --transfer.ascp_args=@list:,--remove-after-transfer,--remove-empty-directories,--exclude-newer-than=-8,--src-base,hot_folder hot_folder
+upload /test_file.bin --to-folder=my_upload_folder --transfer.agent=node --transfer.url=http://localhost:12348 --transfer.username=sim --transfer.password=sim
 upload test_file.bin --to-folder=my_inside_folder --ts=@json:'{"multi_session":3,"multi_session_threshold":1,"resume_policy":"none","target_rate_kbps":100000}' --transfer=@json:'{"spawn_delay_sec":2.5,"multi_incr_udp":false}' --progress-bar=yes
 ```
 
@@ -8230,6 +8287,8 @@ ascli node -N --url=https://... --password="Bearer $(cat bearer.txt)" --root-id=
 > Add `ascli node` in front of the following commands:
 
 ```shell
+--url=http://localhost:12348 --username=sim --password=sim browse / --fields=path --format=csv --select=@json:'{"basename":"test_file.bin"}'
+--url=http://localhost:12348 --username=sim --password=sim transfer list --fields=status
 --url=https://tst.example.com/path --password='Bearer <nd_bearer_token>' --root-id=<id> access_key do self browse /
 access_key create @json:'{"id":"my_username","secret":"my_password_here","storage":{"type":"local","path":"/"}}'
 access_key delete my_username
@@ -8274,6 +8333,7 @@ central session list
 delete @list:,my_upload_folder/a_folder,my_upload_folder/tdlink,my_upload_folder/a_file
 delete my_upload_folder/test_file.bin
 download my_upload_folder/test_file.bin --to-folder=.
+emulator @json:'{"url":"http://localhost:12348","username":"sim","password":"sim","docroot":"/data"}'
 health
 info --fpac='function FindProxyForURL(url,host){return "DIRECT"}'
 license
@@ -8356,6 +8416,79 @@ In Instana, create a custom Dashboard to visualize the OTel data:
 - Data Source: Infrastructure and Platforms
 - Metric: search `transfer`
 
+### Node emulator
+
+> [!NOTE]
+> This is not a feature for production.
+> It's provided for testing only.
+
+The command `emulator` starts a local web server that answers a subset of the Node API, and executes transfers with the Transfer Daemon (`transferd`).
+It allows testing, without HSTS, the [Node API agent](#agent-node-api) (`--transfer.agent=node`) and the `node` commands `info`, `browse`, `transfer list|show|modify|cancel`.
+
+The Transfer Daemon and the gem `grpc` must be installed (see [Agent: Transfer Daemon](#agent-transfer-daemon)).
+The emulator starts its own `transferd`, and stops it on exit.
+
+It takes an optional `Hash` argument with the following parameters:
+
+| Field | Type | Description |
+|---------------|---------|----------------------------------------------------------------------------------|
+| `cert` | `String` | Path to the TLS certificate file. Accepted formats: PEM (`.pem`) or PKCS12 (`.p12` / `.pfx`).<br/>Example: `/path/to/cert.pem`. |
+| `chain` | `String` | Path to the PEM certificate chain file (appended as extra chain certificates).<br/>Example: `/path/to/chain.pem`. |
+| `docroot` | `String` | Local folder of the node files. Paths of `/files/browse` and local paths of transfers (sources of `send`, destination of `receive`) are relative to it, and confined in it. Defaults to the current working directory.<br/>Example: `/data/aspera`. |
+| `key` | `String` | Path to the PEM private key file, or the PKCS12 passphrase when `cert` is a `.p12`/`.pfx` file.<br/>Example: `/path/to/key.pem`. |
+| `password` | `String` | Password expected from clients in HTTP Basic authentication, for the above `username`.<br/>Example: `my_password`. |
+| `retention_sec` | `Integer` | Time in seconds a transfer stays in the list of transfers after it ended (completed, failed or canceled, and no more retried).<br/>Default: `86400`. |
+| `url` | `String` | Address and port the emulator listens on. Use `https://` with `cert`/`key` for TLS.<br/>Default: `http://localhost:8080`. |
+| `username` | `String` | Username expected from clients in HTTP Basic authentication. Set together with `password`. When not set, requests are accepted without authentication.<br/>Example: `node_user`. |
+
+For details on `url` and HTTPS, see [Web service](#web-service).
+
+Like on a real node, the files of the emulator are in its `docroot`: paths of `browse`, and local paths of transfers, are relative to it.
+Local paths are the sources of an upload (`send`), and the destination of a download (`receive`).
+Paths leading out of the `docroot` are rejected.
+
+Start the emulator, it runs until interrupted:
+
+```shell
+ascli node emulator @json:'{"url":"http://localhost:12348","username":"sim","password":"sim","docroot":"/data"}'
+```
+
+Then, in another terminal, use it as a node, for example, to list the files in `/data`:
+
+```shell
+ascli node --url=http://localhost:12348 --username=sim --password=sim browse /
+```
+
+Or as the transfer agent, for example, to upload the file `/data/my_file.dat` to a transfer server:
+
+```shell
+ascli server upload /my_file.dat --transfer.agent=node --transfer.url=http://localhost:12348 --transfer.username=sim --transfer.password=sim
+```
+
+The transfer is executed by `transferd`, and its status is available on the emulator:
+
+```shell
+ascli node --url=http://localhost:12348 --username=sim --password=sim transfer list
+```
+
+Supported endpoints:
+
+| Verb     | Path                  | Action                                                                                            |
+|----------|-----------------------|---------------------------------------------------------------------------------------------------|
+| `GET`    | `/info`               | Node information, version and license from `transferd`.                                           |
+| `GET`    | `/ops/transfers`      | List transfers. Query parameters: `active_only`, `direction`, `count`.                            |
+| `POST`   | `/ops/transfers`      | Start a transfer with `transferd`.                                                                |
+| `GET`    | `/ops/transfers/{id}` | Transfer information, with sessions and files.                                                    |
+| `PUT`    | `/ops/transfers/{id}` | Modify `target_rate_kbps`, `min_rate_kbps` or `rate_policy`, or cancel with `status`: `canceled`. |
+| `CANCEL` | `/ops/transfers/{id}` | Cancel a transfer.                                                                                |
+| `POST`   | `/files/browse`       | List a folder of the `docroot`.                                                                   |
+
+Limitations:
+
+- Only transfers started through the emulator are known. They are kept in memory, and lost when the emulator stops. Ended transfers are removed from the list after `retention_sec` (default: one day).
+- Only Basic authentication is supported: when `username` and `password` are set, bearer tokens and access keys are rejected. When they are not set, all requests are accepted.
+- Not supported: `files/upload_setup` and `files/download_setup` (so, `node upload|download` on the emulator), `ops/transfers/bandwidth`, pause and resume of transfers, query parameters `iteration_token` and `tag`.
+
 ## Plugin: `faspex5`: IBM Aspera Faspex v5
 
 Faspex 5 is IBM Aspera's newer self-managed application.
@@ -8598,6 +8731,7 @@ gateway @: url=https://localhost:12346/aspera/faspex
 health --url=https://f5.example.com/path
 invitation list
 invitations create @: email_address=aspera.user1+u@gmail.com
+packages browse --url=my_public_link_recv_fr_user /
 packages browse <id> --query.recursive=true
 packages delete <id>
 packages list --box=ALL
@@ -8607,11 +8741,14 @@ packages list --box=outbox --fields=DEF,sender.email,recipients.0.recipient_type
 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 --url=my_public_link_recv_fr_user --to-folder=.
+packages receive --url=my_public_link_recv_fr_user ALL --to-folder=.
 packages receive <id> --to-folder=. --ts.content_protection_password=my_secret_here
+packages receive <id> <f5_pack_first_file> --to-folder=. --ts.content_protection_password=my_secret_here
 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 --url=my_public_link_send_to_user @json:'{"title":"test title"}' 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
@@ -9114,19 +9251,24 @@ Example: Create a Node: Attributes are like API:
 | `timeout`    |          | `30s`   |
 | `open_timeout` |        | `10s`   |
 
-Example: Create a share and list user permissions on it.
+Example: Create a share, grant access to a user and list user permissions on it.
 
 ```shell
 ascli shares admin share create @json:'{"node_id":1,"name":"test1","directory":"test1","create_directory":true}'
 
-share_id=$(ascli shares admin share list --select=@json:'{"name":"test1"}' --fields=id --out.level=data)
+user_id=$(ascli shares admin user all show %username:john@example.com --fields=id --out.level=data)
 
-ascli shares admin share user_permissions $share_id list
+ascli shares admin share user_permissions %name:test1 create @json:'{"user_id":'$user_id',"browse_permission":true,"download_permission":true,"upload_permission":true}'
+
+ascli shares admin share user_permissions %name:test1 list
 ```
 
+Share permissions (`user_permissions`, `group_permissions`) are identified by the user or group identifier: e.g. `show %username:john@example.com`.
+Permissions not specified on creation take their default value.
+Available permissions: `browse_permission`, `download_permission`, `upload_permission`, `mkdir_permission`, `delete_permission`, `rename_permission`, `content_availability_permission`, `manage_permission`.
+
 > [!NOTE]
-> The Shares API provides read-only access to share permissions (`user_permissions`, `group_permissions`): only `list` and `show` are available.
-> Permissions are granted in the Shares web UI.
+> Permissions of a user or group on all shares (`user all share_permissions`, `group all share_permissions`) are read-only: only `list` and `show` are available.
 
 ### Tested commands for `shares`
 
@@ -9138,6 +9280,7 @@ admin group all list
 admin node list
 admin share list --fields=DEF,-status,status_message
 admin share user_permissions %name:my_share list
+admin share user_permissions %name:my_share modify %username:my_username @json:'{"browse_permission":true}'
 admin transfer_settings modify @: min_connect_version=3.6.1
 admin transfer_settings show --format=json
 admin user all app_authorizations %username:my_username modify @: app_login=true
@@ -9195,6 +9338,18 @@ transfer smart sub my_smart_id @: source.paths.0=my_smart_file source_type=user_
 
 ## Plugin: `orchestrator`: IBM Aspera Orchestrator
 
+### Authentication
+
+The Orchestrator plugin supports different credentials and authentication styles configured via `--auth_style`:
+
+- **Username / Password** (`--username` and `--password`):
+  - `--auth_style=token` (default): Exchanges credentials for a JWT Bearer token via `/api/login`.
+  - `--auth_style=basic`: Standard HTTP Basic Authentication.
+  - `--auth_style=query`: Passes credentials in URL query parameters (`?login=...&password=...`).
+- **API Key** (`--apikey`):
+  - `--auth_style=token` (default): Exchanges the API key for a JWT Bearer token via `/api/login`.
+  - `--auth_style=query`: Passes the API key in URL query parameter (`?apikey=...`).
+
 ### Start a workflow
 
 Command `workflows start` creates a work order:
@@ -9231,16 +9386,19 @@ ascli orchestrator workflows start 1234 @json:'{"Param":"world !"}' @json:'{"ste
 > Add `ascli orchestrator` in front of the following commands:
 
 ```shell
+--auth_style=query workflow list
+--auth_style=token workflow list
 health
 info
 monitors
-plugins
+plugins list
 processes
 workflow details my_workflow_id
 workflow export my_workflow_id
 workflow inputs my_workflow_id
 workflow list
 workflow outputs my_workflow_id
+workflow start my_sleep_workflow_id --fields=work_order.id
 workflow start my_workflow_id @: 'Param=world !'
 workflow start my_workflow_id @: 'Param=world !' END @: step=ResultStep variable=Complete_status_message
 workflow status ALL
@@ -9251,8 +9409,9 @@ workorder cancel <id>
 workorder output <id>
 workorder reset <id>
 workorder status <id>
-workstep cancel 1
-workstep status 1
+workorder status <orch_wf_start_sleep> --fields=status_details
+workstep cancel <id>
+workstep status <id>
 ```
 
 ## Plugin: `cos`: IBM Cloud Object Storage
@@ -9630,9 +9789,32 @@ This shall list the contents of the storage root of the access key.
 
 ### Options for generated files
 
-When generating preview files, some options are provided by default.
-Some values for the options can be modified on command line.
-For video preview, the whole set of options can be overridden with option `reencode_ffmpeg`: it is a `Hash` with two keys: `in` and `out`, each is an `Array` of strings with the native options to `ffmpeg`.
+When generating preview files, the following options can be modified on command line (or in a preset):
+
+| Field | Type | Description |
+|---------------------|---------|----------------------------------------------------------------------------------|
+| `blend_fps` | `Integer` | MP4 video preview (`blend`): frames per second.<br/>Default: `15`. |
+| `blend_keyframes` | `Integer` | MP4 video preview (`blend`): number of key frames.<br/>Default: `30`. |
+| `blend_pauseframes` | `Integer` | MP4 video preview (`blend`): number of pause frames (repetitions of each key frame).<br/>Default: `3`. |
+| `blend_transframes` | `Integer` | MP4 video preview (`blend`): number of transition frames between key frames.<br/>Default: `5`. |
+| `clips_count` | `Integer` | MP4 video preview (`clips`): number of clips.<br/>Default: `5`. |
+| `clips_length` | `Integer` | Video: length (in seconds) of each clip of MP4 video preview (`clips`), and of `animated` PNG thumbnail.<br/>Default: `5`. |
+| `max_size` | `Integer` | Maximum size (in bytes) of a preview file: a warning is logged if exceeded.<br/>Default: `16777216`. |
+| `office_conversion` | `String` | PNG thumbnail of office document: conversion tool.<br/>Allowed values: `soffice`, `unoconv`.<br/>Default: `soffice`. |
+| `reencode_ffmpeg.in` | `Array` | Input options. |
+| `reencode_ffmpeg.out` | `Array` | Output options. |
+| `reencode_ffmpeg` | `Hash` | MP4 video preview (`reencode`): `ffmpeg` options replacing the default ones.<br/>Default: `{}`. |
+| `thumb_img_size` | `Integer` | PNG thumbnail of image, PDF, office document or text: size (in pixels).<br/>Default: `800`. |
+| `thumb_text_font` | `String` | PNG thumbnail of text: font name, as listed by `magick identify -list font`.<br/>Default: `Courier`. |
+| `thumb_vid_fraction` | `Number` | PNG thumbnail of video (`fixed`): position of the snapshot, as a fraction of the video duration.<br/>Default: `0.1`. |
+| `thumb_vid_scale` | `String` | PNG thumbnail of video: frame size, as `ffmpeg` scale filter argument.<br/>Default: `-1:min(ih,100)`. |
+| `video_codec` | `String` | MP4 video preview (`reencode`): `ffmpeg` video codec, e.g. `libx264`, `h264_videotoolbox`, `h264_nvenc`. Default: first available H.264 encoder. |
+| `video_conversion` | `String` | MP4 video preview: generation method. `reencode`: re-encode the beginning of the video, `blend`: key frames with transitions, `clips`: concatenation of short clips.<br/>Allowed values: `reencode`, `blend`, `clips`.<br/>Default: `reencode`. |
+| `video_png_conv` | `String` | PNG thumbnail of video: generation method. `fixed`: single frame, `animated`: animated PNG.<br/>Allowed values: `fixed`, `animated`.<br/>Default: `fixed`. |
+| `video_scale` | `String` | MP4 video preview: frame size, as `ffmpeg` scale filter argument.<br/>Default: `min(iw,360):-2`. |
+| `video_start_sec` | `Integer` | Video: start offset (in seconds) of MP4 video preview and of `animated` PNG thumbnail.<br/>Default: `10`. |
+
+For video preview with method `reencode`, the whole set of `ffmpeg` options can be overridden with option `reencode_ffmpeg`: it is a `Hash` with two keys: `in` and `out`, each is an `Array` with the native options to `ffmpeg`.
 
 ### Execution
 

data/lib/aspera/agent/base.rb

@@ -23,14 +23,19 @@ module Aspera
       end
 
       # Wait for all sessions to terminate and return a typed Transfer::Result.
+      # Notifies the end of transfer to the progress bar (agents do not).
       # @return [Transfer::Result::Success, Transfer::Result::Error]
       def wait_for_completion
+        success = false
         statuses = wait_for_transfers_completion
-        @progress&.reset
         Aspera.assert_type(statuses, Array)
         Aspera.assert(statuses.none? { |i| !i.eql?(:success) && !i.is_a?(StandardError) }) { "bad statuses content: #{statuses}" }
         errors = statuses.reject { |i| i.eql?(:success) }
-        return errors.empty? ? Transfer::Result.success : Transfer::Result.error(errors.first)
+        success = errors.empty?
+        return success ? Transfer::Result.success : Transfer::Result.error(errors.first)
+      ensure
+        # Also when the agent raises an exception
+        notify_progress(:end, info: success)
       end
 
       # Return the job_id of the last transfer submitted by this agent.

data/lib/aspera/agent/connect.rb

@@ -160,19 +160,15 @@ module Aspera
                 end
               when 'completed'
                 notify_progress(:session_end, session_id: @transfer_id)
-                notify_progress(:end)
                 break
               when 'failed'
                 notify_progress(:session_end, session_id: @transfer_id)
-                notify_progress(:end)
                 raise Transfer::Error, transfer['error_desc']
               when 'cancelled'
                 notify_progress(:session_end, session_id: @transfer_id)
-                notify_progress(:end)
                 raise Transfer::Error, 'Transfer cancelled by user'
               else
                 notify_progress(:session_end, session_id: @transfer_id)
-                notify_progress(:end)
                 raise Transfer::Error, "unknown status: #{transfer['status']}: #{transfer['error_desc']}"
               end
             end

data/lib/aspera/agent/desktop.rb

@@ -121,19 +121,15 @@ module Aspera
               end
             when 'completed'
               notify_progress(:session_end, session_id: @transfer_id)
-              notify_progress(:end)
               break
             when 'failed'
               notify_progress(:session_end, session_id: @transfer_id)
-              notify_progress(:end)
               raise Transfer::Error, transfer['error_desc']
             when 'cancelled'
               notify_progress(:session_end, session_id: @transfer_id)
-              notify_progress(:end)
               raise Transfer::Error, 'Transfer cancelled by user'
             else
               notify_progress(:session_end, session_id: @transfer_id)
-              notify_progress(:end)
               raise Transfer::Error, "unknown status: #{transfer['status']}: #{transfer['error_desc']}"
             end
             sleep(1)