Quick Start🔗
This section walks you through your first interaction with ascli on Linux.
Prerequisites🔗
-
Get the
asclibinary for Linux (.tgz) in the release section of the GitHub repository. -
Decompress the archive to get the executable:
mkdir -p $HOME/bin
tar -C $HOME/bin -zxvf ascli-4.29.0.pre-linux-x86_64.tgz
export PATH=$PATH:$HOME/bin
Note
For other operating systems, complete the Installation section (Ruby, Gem, FASP) to get ascli set up on your system.
- Once installed, confirm
ascliis accessible by checking its version:
ascli -v
4.29.0.pre
- Install the Aspera transfer runtime (tested version), as it is not included in the
asclipackage:
ascli transferd install
Option A - Test with the Aspera Demo Server🔗
- Run the following command to initialize the demo environment:
ascli config initdemo
- Check the configuration:
ascli config preset overview
- Browse the remote file system:
ascli server browse /
╭────────────┬──────┬───────────┬───────┬───────────────────────────┬───────────────────────╮
│ zmode │ zuid │ zgid │ size │ mtime │ name │
╞════════════╪══════╪═══════════╪═══════╪═══════════════════════════╪═══════════════════════╡
│ dr-xr-xr-x │ xfer │ demousers │ 4096 │ 2014-11-05 16:01:56 +0100 │ aspera-test-dir-large │
│ drwxrwxr-x │ xfer │ demousers │ 94208 │ 2025-03-31 11:27:33 +0200 │ Upload │
│ dr-xr-xr-x │ xfer │ demousers │ 4096 │ 2014-11-05 16:01:56 +0100 │ aspera-test-dir-small │
│ dr-xr-xr-x │ xfer │ demousers │ 4096 │ 2014-11-05 16:01:56 +0100 │ aspera-test-dir-tiny │
╰────────────┴──────┴───────────┴───────┴───────────────────────────┴───────────────────────╯
- Download a file:
ascli server download /aspera-test-dir-small/10MB.1
Time: 00:00:02 ====================================== 100% 100 Mbps Time: 00:00:00
complete
Option B - Test with Your Own HSTS🔗
To use ascli with a server of your own, it is recommended to save its connection details as an Option Preset.
This avoids repeating credentials on every command.
The steps below create a preset, set it as the default for the server plugin, browse a remote directory, and download a file:
- Create a preset with your server's connection details:
ascli config preset update <SERVER_PRESET_NAME> --url=ssh://hsts.example.com:33001 --username=<USERNAME> --password=<PASSWORD>
INFO Saving config file: /home/john/.aspera/ascli/config.yaml
Updated: <SERVER_PRESET_NAME>
- Set the preset as the default for the server plugin:
ascli config preset set default server <SERVER_PRESET_NAME>
INFO Updated: default: server <- <SERVER_PRESET_NAME>
INFO Saving config file: /home/john/.aspera/ascli/config.yaml
- Once your preset is set, follow the same browse and download steps as in Option A.
Option C - Test with Aspera on Cloud🔗
If you'd prefer to test against Aspera on Cloud, skip ahead to the AoC Wizard section.
Leveraging AI Assistance🔗
You can significantly accelerate your workflow by using an AI assistant with ascli.
There are three ways, the first one is the simplest:
- The AI executes commands in a shell (coding agents): nothing to set up, and no limitation: the AI uses
asclias you do, with your configuration. Give it the filellms.txt, located at the root of the gem and of the GitHub repository. It tells the AI whatasclidoes with IBM Aspera products, and how to discover commands, arguments and options (config commands,help,config options,config documentation). With an AI client that supports agent skills, install the skill instead: the AI loads it by itself when a request is about IBM Aspera. The skill is the folderskills/ascliof the gem (and of the GitHub repository): copy it to the skills folder of the AI client, for example:
cp -R "$(gem contents aspera-cli | grep 'skills/ascli/SKILL.md$' | xargs dirname)" ~/.claude/skills/
-
The AI executes commands through MCP: for an AI client without a shell, start the MCP server and register it in the AI client. The AI discovers commands and their arguments by itself, and executes them. By default, the server restricts what the AI can do (see Security), and the AI never sees secrets.
-
The AI generates commands that you execute (chat assistant that cannot execute commands): it cannot read the documentation through
ascli, so provide it as context, as described below.
In the first two ways, the AI reads the documentation by itself, one section at a time, with ascli config documentation: there is no need to provide the manual.
Recommended Workflow for a chat assistant:
-
Contextualize: Download the project manual (this manual in Markdown format,
docs/README.md) from the GitHub repository. -
Upload: Attach the file to your AI assistant's prompt to ensure it uses specific, up-to-date syntax.
-
Inquire: Use a detailed prompt that specifies your requirements and environment.
Tip
Specify your environment.
Quoting rules and syntax vary significantly between shells.
Always mention if you are using bash, PowerShell 5 or 7, or Windows CMD.
Example Prompt:
Use only the attached ascli manual (it matches the version I use).
Generate a command to send a package via Aspera on Cloud using the Bash shell.
Set a custom title and note.
Define specific recipients.
Cap the transfer speed at 300Mbps.
By providing the documentation as a direct reference, you reduce "hallucinations" and receive accurate, executable commands in seconds.
Next Steps🔗
-
Learn the CLI: Read Command Line Interface to understand configuration, options, and commands.
-
Explore plugins: Jump to the section for the relevant product, for example: Aspera on Cloud, HSTS, Faspex 5.