Skip to content

Quick Start🔗

This section walks you through your first interaction with ascli on Linux.

Prerequisites🔗

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 ascli is 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 ascli package:
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 ascli as you do, with your configuration. Give it the file llms.txt, located at the root of the gem and of the GitHub repository. It tells the AI what ascli does 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 folder skills/ascli of 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🔗