github IBM/aspera-cli v4.29.1
Aspera CLI v4.29.1

one hour ago

New Features

  • New option poll: repeats a read-only command and displays its result (each time it changes, each time, or the last one), until a JMESPath condition on the result is true, or a number of runs or a time is reached, e.g. orchestrator workorders status <ID> --poll=@json:'{"interval":10,"max":30,"until":"status == `Complete`"}'. Parameters interval, max, timeout, until, show, errors (fail or retry). Refused on a command that is not marked read-only (e.g. faspex5 packages send), with options once_only and notify_to, and in MCP server mode. Read-only: commands named list, show, status, info, health, ls, browse and find (except preview show: it generates a preview file), and others, e.g. orchestrator workflows workorders, server du, node ssync state.

  • config: new command skill: displays the agent skill (same content as llms.txt), for an AI that does not install skills, in a shell or through mcp server.

  • mcp server: the default instructions tell the AI to read the Aspera on Cloud Automation Development Guide before writing a workflow (sections to start with, for example package-transfer for action "Send a package"), and point to config skill for general guidance. The agent skill and llms.txt give the same starting sections.

  • Chocolatey package aspera-cli: installs the Windows portable package (Ruby, gems and ascp included, checked with its SHA-256) instead of Ruby and the gem, and adds only ascli to the PATH. It is built, tested and published by the release workflow.

  • Hidden input (passwords, code or URL pasted after a web login): a mark shows the state, without revealing the length: 🔑 while the input is empty, … once something is typed or pasted (*** and ... without Unicode). Ctrl-U erases the input, e.g. to paste again. --ui.hidden_silent=yes reads without mark (no feedback, as before). A terminal without raw mode (error Inappropriate ioctl for device) reads the line as is. An input that is checked while typed or pasted (the code displayed by Shares for --auth=web with --ui.web_auth=paste) shows ✓ (green) if valid, else ✗ (red) (valid and invalid without Unicode), and is asked again if Enter is pressed while it is not valid.

  • Web login without local port (--ui.web_auth=paste): the page that shows the code after config web_login tells how long it is valid (15 minutes). Same for the page of the Shares patch for --auth=web (docs/shares), which also tells how long the session token is valid (24 hours, from the constant of Shares).

  • OAuth: new key token_refresh_max_age of option http_options: a cached token obtained since more than this duration (seconds) is refreshed before use (default: 0, no limit). With an ascli command run more often than the lifetime of the refresh token (e.g. every 12 hours), it keeps a session alive without new login, e.g. with Shares whose token and refresh token both expire after 24 hours: --http-options=@json:'{"token_cache_max_age":"1d","token_refresh_max_age":"12h"}'.

  • http_options: durations (timeouts, retry_sleep, token_*, jwt_*) accept a string, e.g. 30s, 12h, 1d, 1h 30m, in addition to a number of seconds. Keys jwt_accepted_offset_sec and jwt_expiry_offset_sec are documented.

  • Plugins: the manual has a section "Writing a plugin" for a plugin loaded with option plugin_folder: file and class names, files of the gem to require, options, commands, actions, results, REST client, with an example.

  • Plugins: an unexpected error in a plugin (e.g. Other(NoMethodError)) also logs its location in the plugin (file and line) at level info.

  • Plugins: modules OauthWebOptions (client_id, client_secret, redirect_uri) and OauthJwtOptions (private_key, passphrase) give the options of Oauth: a plugin of the OAuth web flow only adds them with use_options OauthWebOptions. Options of the existing plugins do not change.

  • OAuth: parameter token_field accepts a dot-separated path of a nested field of the token answer, e.g. authed_user.access_token (user token of Slack OAuth v2). A plain field name is read as before.

  • OAuth: parameters path_authorize and path_token accept an absolute URL (http or https), used as is, e.g. a token created on another host than the authorization page. The token cache still depends on base_url only: no new login for existing configurations.

  • transferd install, transferd list: the request for the list of SDK archives (option locations_url) includes the version of ascli in the HTTP header Referer.

  • transferd install: the list of SDK archives is no longer read when the requested version is already installed, and is read once per installation instead of twice.

  • REST: a raw body is sent as is when no content_type is given: a String (e.g. binary data), or an IO (e.g. a file) streamed from its current position, without loading it in memory, and sent again from the same position on retry. Its type is in headers (Content-Type). It was ignored, so a binary body needed content_type: Mime::TEXT and a Content-Type header.

Issues Fixed

  • Linux single executable, Linux and Windows portable packages, container image: Ruby 4.0.10 instead of 4.0.9, which has vulnerabilities in Regexp and String (Ruby security release of 2026-11-18). With the gem, ascli runs on the Ruby of the system: update it to 4.0.10, 3.4.13 or 3.3.14.
  • Option security, mcp server: extended value @zlib: was accepted at levels medium and high: a client could send a small value that decompresses to gigabytes (e.g. @zlib:@zlib:<DATA>), and exhaust the memory of the system. It is now refused at these levels, as @ruby:, @uri: and @env:. It is not limited at level low. Reported by visionx7.
  • orchestrator workflows import and check_import: a workflow package (.wkf) was decompressed in memory without limit for the local check, so a small package could exhaust the memory (e.g. 1 MB for 1 GiB). A package whose files exceed 256 MiB once decompressed is now reported (issue package.too_large) and not decompressed: the size is read in the archive before each file.
  • Node API bearer token (e.g. option password of plugin node, or a token in cache): it was decompressed without limit, so a small token could exhaust the memory. The decoded token is now limited to 64 KiB, checked while decompressing.
  • Option security, mcp server: orchestrator workflows check_import read any local file at levels medium and high, and its issues show parts of the content. It now reads the file as @file:: only in allowed_paths at level medium, refused at level high. workflows import sends the file, as a transfer: not restricted.
  • config ascp info: key log was always - (ascp is run with -L- to read its paths). It is now where ascp logs without option -L: <logging><directory> of aspera.conf, else ~/Library/Logs/Aspera on macOS, var\log of the product (or the folder of ascp) on Windows, syslog on Linux and Unix.
  • Logs (--log-level=trace1, trace2): the value of a secret option given on command line (e.g. --password=<PASSWORD>, --vault.password=<PASSWORD>) was shown in clear in the logs of the command line, of unprocessed options, and of the evaluation of the option. It is now declared as a secret when the command line is read, by option name, as is a structured value with a secret key (e.g. --vault=@json:'{"password":"<PASSWORD>"}'), and a short value (less than 8 characters) is hidden too in these logs.
  • Option dry_run was ignored by all commands except transferd service, e.g. server download transferred files. A transfer command now does not transfer, and its result is the final transfer spec (secrets hidden). Commands that change something before the transfer (aoc packages send, faspex5 packages send: the package is created first), sync commands and preview generation are refused with option dry_run, before any change.
  • Option show_config: after the configuration, the error unprocessed values was displayed (exit code 2) when the command had arguments, e.g. server browse / --show-config. Arguments of the command, not executed, are not reported anymore, unknown options still are.
  • Logs (--log-level=debug): the value of a secret option given in an environment variable (e.g. ASCLI_PASSWORD, ASCLI_VAULT_PASSWORD) was shown in clear in the dump of environment values, and that of a secret option given on command line to config preset update (e.g. --password=<PASSWORD>) in the log of the option. Values of options from environment, presets and command line that are not declared yet are now hidden, by option name, as those of declared options.
  • OAuth: an opaque token (not a JWT, e.g. Shares) was used until rejected by the server: its refresh token, if it expires at the same time, could no longer be used. The expiration given at creation (expires_in) is now kept in cache (expires_at), and the token is refreshed before it expires (token_refresh_threshold).
  • orchestrator workflows find_constraints: the optional workflow ID was required ("Missing argument: add_as_revision"): an optional argument of type identifier was always mandatory. orchestrator workflows import_with_constraints: add_as_revision accepts null (new workflow).
  • Extended value @extend: followed by a single extended value, e.g. @json:@extend:@file:<PATH>: the text on the right was taken as is (unexpected character: '@file:...') instead of being decoded first, as other decoders. It is now decoded, then its embedded values (e.g. "@vault:<LABEL>.<FIELD>@" in a JSON file) are evaluated. With a closing @ (@extend:@file:<PATH>@) the content is still inserted as is, not evaluated again.
  • mcp server: when the optional gem mcp is not installed, the error was uninitialized constant Cli instead of the message telling to install it.
  • Vault 1Password (op): creating a secret (e.g. config vault create, config preset secure) failed with invalid JSON in piped input, because op item create reads an item template on its standard input when it is not a terminal. The fields are now given to op in a JSON template on its standard input, so the secret is no longer on its command line.
  • Wizard: an existing default preset for the plugin was replaced without error when override=yes was not given: the check (A default configuration already exists) never applied.
  • Display of an image as text in a terminal that does not report its size (0 x 0, e.g. a pseudo-terminal) or without console: the image was scaled to nothing or failed (Cannot decode picture.). The default size 24 x 80 is now used.
  • Display of an image as text without the optional gem rmagick: an image that ChunkyPNG does not decode (e.g. JPEG) failed with cannot load such file -- rmagick, instead of being displayed with the iTerm2 inline image protocol (if supported by the terminal) or failing with Cannot decode picture..

Breaking Changes

Server Versions

Tested with Ruby 4.0.9 on osx-arm64.

Plugin Product Version
aoc IBM Aspera on Cloud SaaS
console IBM Aspera Console 3.4.11
faspex5 IBM Aspera Faspex 5.0.19
faspio IBM Aspera faspio Gateway 1.3.7
httpgw IBM Aspera HTTP Gateway 2.3.4
node IBM Aspera High-Speed Transfer Server (Node API) 4.4.9.3472
orchestrator IBM Aspera Orchestrator 4.1.6.2036-00000
server IBM Aspera High-Speed Transfer Server (SSH) 4.4.9.3472
shares IBM Aspera Shares 1.11.5

Transfer Agent Versions

Agent Product Version
connect IBM Aspera Connect 4.2.16
desktop IBM Aspera for Desktop 1.1.2
direct IBM Aspera ascp 4.4.8.2592
httpgw IBM Aspera HTTP Gateway 2.3.4
node IBM Aspera High-Speed Transfer Server (Node API) 4.4.9.3472
transferd IBM Aspera Transfer Daemon 1.1.9

Don't miss a new aspera-cli release

NewReleases is sending notifications on new releases.