Highlights:
asclias a tool for AI assistants:mcp serveris 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 withhelp, development guides of Orchestrator and Aspera on Cloud Automation read by section); new filellms.txt(also as an agent skill) that tells an AI how to drive IBM Aspera products withascli.- Analysis of
ascplogs, local (config ascp logs) or on a server (server logs): statistics, sessions, diagnostics with recommendations. - Named secret stores for
vault, new typeskeeperandsecret_service, HashiCorp AppRole and token file, secrets inspected without their value. - Web login without local port (
--ui.web_auth=paste), SAML web authentication forshares(--auth=web). - New plugin
transferd: Transfer Daemon as a service. Export and import of Aspera on Cloud Automation workflows. Many neworchestratorcommands. 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): whatasclidoes with IBM Aspera products, and how to discover commands, arguments and options, on the command line or throughmcp server. Same content as an agent skill in folderskills/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 keyweb_authof optionui. 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 runsascli(e.g. jump server). Ifascliis also installed on the workstation, it displays a commandascli 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
ed25519are supported without additional gem. Gembcrypt_pbkdfis only needed for OpenSSH keys protected by a passphrase.
- New file
config:- New command
ascp logs: analysis ofascplog files (ascp4.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 recommendedascpoptions oraspera.confparameters),health(Nagios format), multi-session transfers, rates per period, errors by peer, files, licenses, and parsedrecordsfor--out.query. Accepts gzip files, folders and the standard input (-). New optionascp_logs: thresholds of diagnostics,timezone,health_minutes. ascp errors: optional argumentsessionlists error codes found in logs, with category and the corresponding error of the management port.vault: optionvaultdeclares 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 commandsvault stores,check,overviewandfield <label>: they inspect stores and secrets without showing values. The former single-store form of optionvaultis deprecated, and converted when the configuration file is loaded (a backup is saved).@file:in optionsvaultandvault_passwordis restricted by optionsecurity(refused by default inmcp server).vaulttypefile: parameterpassword(value, or@file:<path>) replaces optionvault_password.vaulttype HashiCorp:tokenaccepts@file:<path>(read again when modified, e.g. by Vault Agent). New parametersapprole,namespaceandca_file.vault: new typeskeeper(Keeper Secrets Manager, optional gemkeeper_secrets_manager) andsecret_service(Linux Secret Service: GNOME Keyring, KWallet, KeePassXC, withsecret-tool).wizardadds_comment: "wizard: <application>"to the preset it creates.- Asynchronous transfer jobs (
list,status,cleanup) are managed byagents jobs.config transferis deprecated. transferd(install,list) andascp installare deprecated, use the new plugintransferd.preset setmerges into the configuration at three levels (see Breaking Changes below).preset update,initializeandunsetare deprecated, and show the command to use.
- New command
transferd: new plugin for the Transfer Daemon.install [version]andlist.installdoes nothing if the version is already installed.infoandtransfers show|cancel <transfer_id>for a running daemon (options--url,--api-key,--ca-file; requires gemgrpc).service(spec,install,configure,status,uninstall,use,versions): runtransferdas asystemdservice, with its configuration validated, and SDK versions side by side (usefor rollback). New global option--dry-runshows the actions without change.
server: new commandlogs: same analysis asconfig ascp logs, on the log files of the server, read over SSH (size limited by keyremote_max_sizeof optionascp_logs, default 256 MB).aoc:automationis no longer beta. New commandsautomation workflows details,export,importandduplicate.- 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) orpaste. It requires a patch of Shares, provided indocs/sharesuntil it is part of a Shares release (see manual).node:asperabrowseropens the new Aspera Browser web application (optionasperabrowserurl), 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 (statsofworkorders,workstepsandqueues), andcontrol(engine, monitor and workers). workflows check_importdetects more problems that make a workflow unusable (steps that never start, loops, invalid links or lookups).workflows developmentandplugins specare read by section (toc,full,section <anchor>), so that an AI assistant reads only what it needs.
- New commands:
connect: IBM Aspera Connect will be deprecated in 2027: the transfer agentconnectdisplays 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: referencessecret://<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.sealandunseal: new parametersencrypt:andreverse:.- New token creator
Aspera::OAuth::SharesWeb(grant_method: :shares_web). - Transfer agents: new optional method
transfer_cancel. Agenttransferd: parametersapi_keyandca_filefor an existing daemon, methodsinfoandcreate_client, new fields intransfer_status, readertransfer_id.
- New class
- 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.mdanddocs/ASSURANCE_CASE.md(security requirements, threat model). Code review requirements inCONTRIBUTING.md. - Each source file has an SPDX copyright and license header.
Issues Fixed
- Security:
mcp server(security levelhigh): a client could execute code, or write a file where it chooses, through some options (notify_template,fpac,uikeycommand,outkeyfile,output,pid_file,home,plugin_folder,sdk_url,locations_url), the folderpluginsof the configuration folder,config plugins createandfaspex5 postprocessing. They are now available only at levellow, on the command line and in presets. At levelsmediumandhigh,config preset setrefuses them,config commandsdoes not list refused commands, and local files are written only in the new keywritable_pathsof optionsecurity(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 createrefuses a plugin name that is not made of lowercase letters, digits and underscores.
ascli:--out.selectwith a dot-path key (e.g.directory_user.type) selected no item with formatsjson,jsonpp,yamlandruby. 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
Hashoption in dot notation (e.g.--ui.foo=1) gave an extraunprocessed valueserror. - 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_parser2.13.2, with whichjson_schemerfails to load.
config:preset updatesaved all the options of the command line in the preset, also those placed beforeupdate(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 keyssh-rsa, the only one offered by the demo server, so thatserver browseand other file operations work. To fix a preset created by an earlier version: recreate it, or add--ssh-options=@json:'{"host_key":["ssh-rsa"]}'.vaulttypefile: the vault keeps its owner, group and mode when it is changed by another user, e.g. root.vaulttype HashiCorp: responses of Vault failed withwrong number of argumentswith gemjson3.
aoc:automation instances showdid not return. It now accepts the numeric identifier or the UUID.packages receivewith optionpackage_folder: two fields (e.g.{"fld":["name","id"]}) gave<name>.idinstead of<name>.<id>, and withseqoroptthe existence of the folder was checked in the current folder instead ofto_folder.
faspex5: web authentication (--auth=web) failed when HTTP basic authentication is enabled on the API client: optionclient_secretis now sent.orchestrator: authentication with optionapikeywas rejected (HTTP 401): the API requiresusernamewith the API key. Optionusernameis now required withapikey.node:- Browsing a folder with
--query.per_pageor--query.pagefailed when API v4 is not used. telemetry: an integer value of keyinterval(e.g.0, as documented) was refused. Same for keysspawn_timeout_secandspawn_delay_secoftransfer_info(agentdirect), andfont_ratioof optionout(keyimg).access_keys do <id> showandthumbnailask the node not to use its cache.
- Browsing a folder with
preview:eventsgenerated no preview: it now generates previews of new and modified files (optionfilterapplies), and deletes the previews of deleted files.- Option
skip_formatfailed withFrozenError. - An existing preview is also detected with the preview of the file (
files/<id>/preview), when the information of the file has nopreview.
- library: agent
transferd:transfer_statusno 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 isunknowninstead ofrunning. Calls have a timeout: keytimeoutofagent_params, default 10 seconds.- A process that attaches to an external daemon for each transfer (e.g. Orchestrator) accumulated
at_exithandlers.
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-ssh8,marcel2. orchestrator:- Command
workstepis renamedworksteps(e.g.worksteps status), consistent withworkorders. workflows development: documentauthoringis replaced byguide(the Aspera Orchestrator Development Guide, which includes the Workflow Authoring Guide):workflows development authoring tocis nowworkflows development guide toc, andworkflows development templates customrubyis nowworkflows development templates section customruby.plugins specis nowplugins spec toc, andplugins spec <plugin> [section]is nowplugins spec show <plugin> [section].
- Command
config: arguments given in a fixed order are replaced by aHash, usually given with@:(itemskey=valuein any order):detect <url> [<plugin>]is nowdetect @: url=<url> plugin=<plugin>.urlis still asked if not given.wizard <url> [<plugin> [<preset>]]is nowwizard @: url=<url> plugin=<plugin> preset=<preset>.urlis still asked if not given. Options--overrideand--defaultare replaced by keysoverrideanddefaultof theHash. Options of the plugin (--username,--password,--private-key,--client-id,--use-generic-client...) are unchanged. Option--key-pathis removed: give the key itself with--private-key=@file:<path>. The wizard still uses the default key, or generates one, if--private-keyis empty.preset lookup --url=<url> --username=<user>is nowpreset lookup @: url=<url> username=<user>. Options--urland--usernameare no longer used by this command.preset setmerges 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 presetp1),set <name> <Hash>(parameters of a preset, e.g.set p1 @: url=https://example.com username=bob), orset <name> <param> <value>(unchanged). Options of the command line are not saved in the preset. Commandsupdate,initializeandunsetare deprecated, and show the command to use:update <name> --url=...isset <name> @: url=...(it now saves only the options placed afterupdate),initialize <name> <Hash>isdelete <name>thenset <name> <Hash>,unset <name> <param>isset <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:SecretHideris nowSecret::Hider,SecretStrengthis nowSecret::Strength,Keychainis nowSecret::Store.Secret::Store::Factory.createtakes only the parameters of the store, andFactory::LISTis replaced byFactory.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 |