Introduction🔗
Overview🔗
The IBM Aspera Command Line Interface (ascli) is an enterprise-grade tool that provides comprehensive command-line access to IBM Aspera's suite of high-speed file transfer products and services.
Designed for automation, scripting, and integration scenarios, ascli enables organizations to leverage Aspera's FASP technology within their existing workflows and DevOps pipelines.
Tip
For any question about ascli (behavior, options), or to build a command line, give this manual to an AI assistant as a reference and ask it.
See Leveraging AI Assistance.
Key Features🔗
Multi-Product Integration : Unified interface supporting Aspera on Cloud, Faspex 5, Shares, Node API, Console, Orchestrator, and High-Speed Transfer Server (HSTS).
Flexible Authentication : Support for OAuth 2.0, JWT, Basic Authentication, and SSH key-based authentication across different Aspera products.
Transfer Automation : High-speed FASP transfers with multiple agent support (Direct, Connect, Node, HTTP Gateway, Transfer Daemon).
Configuration Management : Persistent configuration presets, environment variables, and flexible option handling for streamlined operations.
Developer Friendly : Comprehensive logging, debugging capabilities, and API exploration tools for development and troubleshooting.
Target Audience🔗
This manual is intended for:
- System Administrators managing Aspera infrastructure
- DevOps Engineers integrating Aspera into CI/CD pipelines
- Developers building automation scripts and workflows
- IT Professionals performing file transfer operations
Document Structure🔗
This manual is organized into the following sections:
- Quick Start - Getting started with basic operations
- Installation - Setup procedures for various platforms
- Command Line Interface - Syntax, options, configuration, transfers, and usage patterns
- Plugin sections (one per product: AoC, ATS, HSTS, Faspex 5, and so on) - Product-specific operations and examples
- Operational Utilities - Sync, hot folders, health checks, email notifications
- Common problems - Common issues and solutions
- About - History and references
When to use and when not to use🔗
Note
If you are scripting or automating transfers from the command line, ascli is the right choice.
If you are developing an application, prefer the APIs or SDKs instead.
ascli is designed for command-line interaction with IBM Aspera products, enabling users to execute remote commands and perform high-performance file transfers.
It supports both interactive terminal operations (for example, maintenance tasks on VT100-compatible terminals) and scripting use cases (for example, batch jobs via shell scripts or cron).
Internally, ascli integrates several components:
- A configuration file (
config.yaml) for persistent settings - Advanced command-line options (see Extended Value)
- REST API calls, including OAuth (like
curl) - Aspera's
ascpfor high-speed file transfers
For programmatic integration with languages such as C/C++, Go, Python, NodeJS, and others, it is recommended to use the Aspera APIs directly. These include:
- REST APIs for products like Aspera on Cloud (AoC), Faspex 5, and Node
- The Transfer Daemon with gRPC interfaces and language-specific stubs (C/C++, Python, .NET/C#, Java, Go, Ruby, Rust, and so on)
These APIs are generally more suitable for long-term development and maintenance. Example implementations can be found at: https://github.com/laurent-martin/aspera-api-examples.
For scripting and ad hoc command-line tasks, ascli is ideal.
It is developer-friendly and well-suited for testing and learning Aspera APIs (see Logging, Debugging).
ascli or ascp?🔗
ascp is the low-level command-line utility that implements the FASP protocol and is used for actual data transfers.
Every Aspera transfer involves an ascp process on both the client and server sides.
ascli is not an alternative transfer engine: it starts ascp (directly or through another transfer agent), so transfer performance is identical.
Other low-level command line tools are included with Aspera transfer products, and ascli is a front end for them too:
async: the IBM Aspera Sync utility, to synchronize folders (see IBM Aspera Sync).ascp4: an alternate transfer engine, selected with transfer spec parameteruse_ascp4.ascp4will be deprecated: useascpunless one of its specific features is needed.
Used directly, ascp is limited to sending and receiving files:
- Connection parameters (address, ports, user, credentials) must be provided on each command line: there are no connection profiles.
- The remote server cannot be browsed: remote paths must be known in advance.
- With Aspera applications (AoC, Faspex, Shares, Node API), the transfer address and token must first be obtained through the application's REST API.
- Multi-session requires starting and monitoring one
ascpprocess per session (option-C). - On interruption,
ascpexits with an error: data already at destination is skipped on the next run (option-k), but restarting is up to the caller.
ascli adds:
- Configuration presets, with secrets protected in a vault (see Option Preset and Secret Vault)
- Detection of the Aspera application from its URL, and automatic retrieval of transfer parameters and tokens (see Wizard)
- Remote file browsing and management: list, create folder, rename, copy, delete, checksum
- Built-in multi-session, with an aggregated progress bar (see Multi-session transfer)
- Automatic resume on retry-able errors, with increasing delay and token renewal (see Agent: Direct)
- Choice of transfer agents: Direct, Node, Connect, HTTP Gateway, Transfer Daemon
- Structured output (table, JSON, YAML, CSV) for scripting (see Output)
All ascp options remain available, either through transfer spec parameters (listed with config ascp spec), or by passing ascp arguments directly when using the direct agent (via ascp_args in option transfer).
Using ascp directly remains relevant when:
asclicannot be installed:ascpis included with every Aspera transfer product.- The need is limited to simple transfers with an HSTS using SSH credentials.
To use ascp directly as a command line, refer to the IBM Aspera documentation of either Desktop Client, Endpoint or Transfer Server - each of which includes a dedicated section on ascp.
Notations, Shell, Examples🔗
Examples of command-line operations are shown using a shell such as: bash (Linux) or zsh (macOS).
Using Windows PowerShell or cmd is also possible.
Command line examples listed in sections titled Tested commands for _plugin_name_ are verified during version validation.
Command line arguments formatted as <NAME> in examples represent user-provided values, not literal values.
ascli is an API Client toward the remote Aspera application Server (Faspex, HSTS, and so on).
Some commands will start an Aspera transfer (for example, upload).
The transfer is not implemented directly in ascli; rather, ascli uses one of the external Aspera Transfer Clients called Transfer Agents.
Note
A Transfer Agent is a client for the remote Transfer Server (HSTS/HSTE).
It can be local, or remote.
For example, a remote Aspera Transfer Server may be used as a transfer agent through its Node API, using option --transfer=node.