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

one hour ago

Highlights:

  • ascli as a tool for AI assistants: mcp server is hardened (the AI client can neither execute code nor write files where it chooses) and no longer experimental; commands describe themselves (schema of structured arguments with help, development guides of Orchestrator and Aspera on Cloud Automation read by section); new file llms.txt (also as an agent skill) that tells an AI how to drive IBM Aspera products with ascli.
  • Analysis of ascp logs, local (config ascp logs) or on a server (server logs): statistics, sessions, diagnostics with recommendations.
  • Named secret stores for vault, new types keeper and secret_service, HashiCorp AppRole and token file, secrets inspected without their value.
  • Web login without local port (--ui.web_auth=paste), SAML web authentication for shares (--auth=web).
  • New plugin transferd: Transfer Daemon as a service. Export and import of Aspera on Cloud Automation workflows. Many new orchestrator commands. Improved shell completion.
  • Project: OpenSSF Best Practices silver badge, test coverage 96.6%.

This version has several breaking changes: read the Breaking Changes section below before upgrading and validate production workflows before deployment. In particular: Ruby 3.3 or later is required, config wizard, config detect and config preset lookup take their arguments as a Hash (@: url=...), and some orchestrator commands are renamed.

New Features

  • ascli:
    • New file llms.txt (in the gem and in the repository): what ascli does with IBM Aspera products, and how to discover commands, arguments and options, on the command line or through mcp server. Same content as an agent skill in folder skills/ascli. The repository is also a Claude Code plugin marketplace: /plugin marketplace add IBM/aspera-cli, then /plugin install ascli@aspera-cli.
    • Web authentication (--auth=web): new key web_auth of option ui. With --ui.web_auth=paste, no local port is opened: after login, the user pastes in the terminal the URL the browser was redirected to. It allows SSO when the browser cannot reach the host that runs ascli (e.g. jump server). If ascli is also installed on the workstation, it displays a command ascli config web_login <code> to run there instead. Default: port (unchanged).
    • Improved shell completion: structures, extended values, local files and folders, presets (with their _comment), transfer jobs and --query.
    • SSH keys of type ed25519 are supported without additional gem. Gem bcrypt_pbkdf is only needed for OpenSSH keys protected by a passphrase.
  • config:
    • New command ascp logs: analysis of ascp log files (ascp 4.0 and later), of client and server (joined by session). Sub-commands: statistics, sessions (with context columns: product, transport, authentication, proxy, FIPS), diagnostics (severity, category, hint and recommended ascp options or aspera.conf parameters), health (Nagios format), multi-session transfers, rates per period, errors by peer, files, licenses, and parsed records for --out.query. Accepts gzip files, folders and the standard input (-). New option ascp_logs: thresholds of diagnostics, timezone, health_minutes.
    • ascp errors: optional argument session lists error codes found in logs, with category and the corresponding error of the management port.
    • vault: option vault declares several named stores: {"default":"<name>","cache_ttl":60,"stores":{"<name>":{"type":...}}}. A secret can be read from any store with @vault://<store>/<path>[?<options>][#<field>]; @vault:<label>.<field> uses the default store. New commands vault stores, check, overview and field <label>: they inspect stores and secrets without showing values. The former single-store form of option vault is deprecated, and converted when the configuration file is loaded (a backup is saved). @file: in options vault and vault_password is restricted by option security (refused by default in mcp server).
    • vault type file: parameter password (value, or @file:<path>) replaces option vault_password.
    • vault type HashiCorp: token accepts @file:<path> (read again when modified, e.g. by Vault Agent). New parameters approle, namespace and ca_file.
    • vault: new types keeper (Keeper Secrets Manager, optional gem keeper_secrets_manager) and secret_service (Linux Secret Service: GNOME Keyring, KWallet, KeePassXC, with secret-tool).
    • wizard adds _comment: "wizard: <application>" to the preset it creates.
    • Asynchronous transfer jobs (list, status, cleanup) are managed by agents jobs. config transfer is deprecated.
    • transferd (install, list) and ascp install are deprecated, use the new plugin transferd.
    • preset set merges into the configuration at three levels (see Breaking Changes below). preset update, initialize and unset are deprecated, and show the command to use.
  • transferd: new plugin for the Transfer Daemon.
    • install [version] and list. install does nothing if the version is already installed.
    • info and transfers show|cancel <transfer_id> for a running daemon (options --url, --api-key, --ca-file; requires gem grpc).
    • service (spec, install, configure, status, uninstall, use, versions): run transferd as a systemd service, with its configuration validated, and SDK versions side by side (use for rollback). New global option --dry-run shows the actions without change.
  • server: new command logs: same analysis as config ascp logs, on the log files of the server, read over SSH (size limited by key remote_max_size of option ascp_logs, default 256 MB).
  • aoc:
    • automation is no longer beta. New commands automation workflows details, export, import and duplicate.
    • New command automation guide (toc, full, section <anchor>): the Aspera on Cloud Automation Development Guide.
  • faspex5: web authentication (--auth=web) uses PKCE (S256), checked by Faspex 5.0.16 and later. Nothing to change in the configuration.
  • shares: new option --auth=web: SAML authentication with the web browser, with --ui.web_auth=port (default) or paste. It requires a patch of Shares, provided in docs/shares until it is part of a Shares release (see manual).
  • node: asperabrowser opens the new Aspera Browser web application (option asperabrowserurl), as the former one is no longer available. The node credentials are given in the fragment of the URL, which the browser does not send to the web server.
  • orchestrator:
    • New commands: tasks, alerts list, queues, pools, plugins (reload, enable, import), workflows (parents, steps, test_step, test_status), portlets, users create, workorders delete, workorders worksteps, worksteps reset, monitors activate|deactivate, statistics (stats of workorders, worksteps and queues), and control (engine, monitor and workers).
    • workflows check_import detects more problems that make a workflow unusable (steps that never start, loops, invalid links or lookups).
    • workflows development and plugins spec are read by section (toc, full, section <anchor>), so that an AI assistant reads only what it needs.
  • connect: IBM Aspera Connect will be deprecated in 2027: the transfer agent connect displays a warning that recommends IBM Aspera for Desktop (--transfer=desktop).
  • mcp: no longer experimental: the plugin follows the same compatibility rules as other plugins.
  • library:
    • New class Aspera::Secret::Resolver: references secret://<store>/<path>[?<options>][#<field>] to secrets of named stores, read when used, with a cache. It can also write secrets (writable: true) and inspect stores and references without reading values.
    • Aspera::Log#logger= sends logs to the logger of the application.
    • Aspera::SealedHash.seal and unseal: new parameters encrypt: and reverse:.
    • New token creator Aspera::OAuth::SharesWeb (grant_method: :shares_web).
    • Transfer agents: new optional method transfer_cancel. Agent transferd: parameters api_key and ca_file for an existing daemon, methods info and create_client, new fields in transfer_status, reader transfer_id.
  • project:
    • OpenSSF Best Practices: silver badge (https://www.bestpractices.dev/projects/5861).
    • Test coverage: 96.6% of lines (was 85%), badge in README.md. Branch coverage is also measured.
    • New GOVERNANCE.md and docs/ASSURANCE_CASE.md (security requirements, threat model). Code review requirements in CONTRIBUTING.md.
    • Each source file has an SPDX copyright and license header.

Issues Fixed

  • Security:
    • mcp server (security level high): a client could execute code, or write a file where it chooses, through some options (notify_template, fpac, ui key command, out key file, output, pid_file, home, plugin_folder, sdk_url, locations_url), the folder plugins of the configuration folder, config plugins create and faspex5 postprocessing. They are now available only at level low, on the command line and in presets. At levels medium and high, config preset set refuses them, config commands does not list refused commands, and local files are written only in the new key writable_paths of option security (none by default).
    • config transferd install, config ascp install: a file or a link of the SDK archive cannot be written outside of the installation folder. Reported by @thesmartshadow.
    • config plugins create refuses a plugin name that is not made of lowercase letters, digits and underscores.
  • ascli:
    • --out.select with a dot-path key (e.g. directory_user.type) selected no item with formats json, jsonpp, yaml and ruby. Matching no item displayed a table with headings only, instead of <empty>.
    • An argument without = collected by @: is reported as a bad argument, instead of an assertion failure. Errors of extended values name their modifier (e.g. @file:).
    • @extend: no longer evaluates again the values it inserts (e.g. read by @env: or @file:).
    • An unknown key of a Hash option in dot notation (e.g. --ui.foo=1) gave an extra unprocessed values error.
    • When the renewal of an expired OAuth token fails, the error of the renewal is reported, instead of the original authorization error.
    • In debug logs, a command argument that contains a single quote was quoted wrongly.
    • Gem dependency: excludes regexp_parser 2.13.2, with which json_schemer fails to load.
  • config:
    • preset update saved all the options of the command line in the preset, also those placed before update (e.g. --home, --log-level, --format).
    • preset set: the value is evaluated once: @val:@file:<path> stores @file:<path>, as documented, not the content of the file. The result of an evaluation is no longer evaluated again.
    • initdemo: the demo server preset allows the SSH host key ssh-rsa, the only one offered by the demo server, so that server browse and other file operations work. To fix a preset created by an earlier version: recreate it, or add --ssh-options=@json:'{"host_key":["ssh-rsa"]}'.
    • vault type file: the vault keeps its owner, group and mode when it is changed by another user, e.g. root.
    • vault type HashiCorp: responses of Vault failed with wrong number of arguments with gem json 3.
  • aoc:
    • automation instances show did not return. It now accepts the numeric identifier or the UUID.
    • packages receive with option package_folder: two fields (e.g. {"fld":["name","id"]}) gave <name>.id instead of <name>.<id>, and with seq or opt the existence of the folder was checked in the current folder instead of to_folder.
  • faspex5: web authentication (--auth=web) failed when HTTP basic authentication is enabled on the API client: option client_secret is now sent.
  • orchestrator: authentication with option apikey was rejected (HTTP 401): the API requires username with the API key. Option username is now required with apikey.
  • node:
    • Browsing a folder with --query.per_page or --query.page failed when API v4 is not used.
    • telemetry: an integer value of key interval (e.g. 0, as documented) was refused. Same for keys spawn_timeout_sec and spawn_delay_sec of transfer_info (agent direct), and font_ratio of option out (key img).
    • access_keys do <id> show and thumbnail ask the node not to use its cache.
  • preview:
    • events generated no preview: it now generates previews of new and modified files (option filter applies), and deletes the previews of deleted files.
    • Option skip_format failed with FrozenError.
    • An existing preview is also detected with the preview of the file (files/<id>/preview), when the information of the file has no preview.
  • library: agent transferd:
    • transfer_status no longer blocks on an ended transfer. When the daemon cannot be reached, does not answer in time, or does not know the transfer, the status is unknown instead of running. Calls have a timeout: key timeout of agent_params, default 10 seconds.
    • A process that attaches to an external daemon for each transfer (e.g. Orchestrator) accumulated at_exit handlers.

Breaking Changes

  • Ruby 3.3 or later is required (3.2 reached end of life in March 2026). Future minimum is 3.4. Policy: a Ruby version is supported until 6 months after its end of official support. Gem dependencies: net-ssh 8, marcel 2.
  • orchestrator:
    • Command workstep is renamed worksteps (e.g. worksteps status), consistent with workorders.
    • workflows development: document authoring is replaced by guide (the Aspera Orchestrator Development Guide, which includes the Workflow Authoring Guide): workflows development authoring toc is now workflows development guide toc, and workflows development templates customruby is now workflows development templates section customruby.
    • plugins spec is now plugins spec toc, and plugins spec <plugin> [section] is now plugins spec show <plugin> [section].
  • config: arguments given in a fixed order are replaced by a Hash, usually given with @: (items key=value in any order):
    • detect <url> [<plugin>] is now detect @: url=<url> plugin=<plugin>. url is still asked if not given.
    • wizard <url> [<plugin> [<preset>]] is now wizard @: url=<url> plugin=<plugin> preset=<preset>. url is still asked if not given. Options --override and --default are replaced by keys override and default of the Hash. Options of the plugin (--username, --password, --private-key, --client-id, --use-generic-client...) are unchanged. Option --key-path is removed: give the key itself with --private-key=@file:<path>. The wizard still uses the default key, or generates one, if --private-key is empty.
    • preset lookup --url=<url> --username=<user> is now preset lookup @: url=<url> username=<user>. Options --url and --username are no longer used by this command.
    • preset set merges into the configuration (JSON Merge Patch: deep merge, @none: removes a key) at one of three levels: set <Hash> (presets by name, e.g. set @: p1.url=https://example.com default.server=p1, set @: p1=@none: deletes preset p1), set <name> <Hash> (parameters of a preset, e.g. set p1 @: url=https://example.com username=bob), or set <name> <param> <value> (unchanged). Options of the command line are not saved in the preset. Commands update, initialize and unset are deprecated, and show the command to use: update <name> --url=... is set <name> @: url=... (it now saves only the options placed after update), initialize <name> <Hash> is delete <name> then set <name> <Hash>, unset <name> <param> is set <name> <param> @none:.
  • config completion: completion scripts saved in a file must be saved again (see manual). Keys of an option are proposed with a trailing = or ..
  • library: Modules about secrets are in Aspera::Secret: SecretHider is now Secret::Hider, SecretStrength is now Secret::Strength, Keychain is now Secret::Store. Secret::Store::Factory.create takes only the parameters of the store, and Factory::LIST is replaced by Factory.types.

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.