Skip to content

Plugin: aoc: IBM Aspera on Cloud🔗

The aoc plugin enables integration with IBM Aspera on Cloud. Because the Aspera on Cloud API requires OAuth 2.0 for authentication, HTTP Basic authentication is not supported.

Note

This plugin is also used for Aspera Enterprise Web Apps (AEWA).

AoC configuration: Using Wizard🔗

ascli includes an interactive configuration wizard to simplify the OAuth setup. While manual configuration is possible, using the wizard is the recommended method for most deployments.

Prerequisites🔗

To complete the setup, you must have:

  • The URL or organization name of your Aspera on Cloud instance:

  • _your_organization_

  • _your_organization_.ibmaspera.com
  • https://_your_organization_.ibmaspera.com

  • User Credentials: Access to the Aspera on Cloud web interface to update your Public Key.

Wizard Invocation🔗

The wizard accepts an optional argument, a Hash with keys:

  • url: The organization name or the full FQDN.

  • plugin: Specify aoc to bypass automatic application detection.

  • preset: Name of the preset to create.

If the URL is omitted, the wizard will prompt for it interactively.

Example: Standard Configuration🔗

During the process, the wizard generates or identifies a PEM-formatted Public Key. You must copy this key (including the BEGIN and END headers) and paste it into the Public Key field in the Aspera on Cloud UI. Once saved in the UI, return to the terminal and press Enter.

Info

In the following example, replace https://<ORG_NAME>.ibmaspera.com with your actual organization URL. (User) represents the user menu on the top right of the page.

$ ascli config wizard
Using: Aspera on Cloud at https://<ORG_NAME>.ibmaspera.com
Private RSA key, e.g. @file:<path> (leave empty to generate):
option: private_key>
Using existing key:
/home/john/.aspera/ascli/<PKEY_NAME>.pem
Please Log in as user john@example.com at: https://<ORG_NAME>.ibmaspera.com
Navigate to: (User) → Account Settings → Profile → Public Key
Check or update the value to (including BEGIN/END lines):
-----BEGIN PUBLIC KEY-----
MIICIjANBg....
....
....kCAwEAAQ==
-----END PUBLIC KEY-----
Once updated or validated, press [Enter].

Using global client_id.
Preparing preset: aoc<ORG_NAME>ibmaspera_com_john_example_com
Setting config preset as default for aoc
You can test with:
ascli aoc user profile show
Saving config file.

Advanced Options🔗

  • Custom Client Identification: By default, ascli uses a pre-registered global client ID. To create and use an organization-specific integration, give the option --use-generic-client=no of plugin aoc to the wizard command.

  • Direct Plugin Targeting: To limit detection to the aoc plugin and skip discovery, provide both the URL and plugin name:

ascli config wizard @: url=<ORG_NAME> plugin=aoc

Verifying the Configuration🔗

Upon successful completion, the wizard creates a configuration preset and assigns it as the default for the aoc plugin.

To verify the current configuration presets, execute:

ascli config preset list

To test the connection and display your profile information:

ascli aoc user profile show

AoC configuration: Using manual setup🔗

Note

If you used the wizard (recommended): skip this section.

AoC manual configuration: Details🔗

IBM Aspera on Cloud (AoC) supports several OAuth 2.0 authentication mechanisms to secure API interactions. The method used is determined by the auth option.

Supported Authentication Methods:

Method auth Description
JSON Web Token jwt Recommended. Uses a private RSA key for secure, headless authentication.
Ideal for automation and scripts.
Web-based web Redirects the user to a browser for interactive login.
Suitable for manual operations on local workstations.
URL Token - Facilitates authentication for external users via public link tokens.

ascli automatically manages the lifecycle of Bearer tokens. Once a token is generated, it is cached in the local configuration folder (option cache_tokens). The tool reuses valid tokens and automatically triggers a refresh or regeneration when they expire, according to the expiration policy defined by the AoC administrator.

API Client Registration🔗

Note

If you use the pre-registered client_id and client_secret, skip this and do not set them in next section.

You can use a specific OAuth API client_id. The first step is to declare ascli in Aspera on Cloud using the admin interface.

(AoC documentation: Registering an API Client).

To register with web-based authentication (auth=web):

  • Open a web browser, log in to your instance: for example, https://<ORG_NAME>.ibmaspera.com/ (use your actual AoC instance URL)
  • Go to (Apps) → Admin → Organization → Integrations
  • Click Create New
  • Client Name: ascli
  • Redirect URIs: http://localhost:12345
  • Origins: localhost
  • Uncheck Prompt users to allow client to access
  • Leave the JWT part for now
  • Save

Note

For web based authentication, ascli listens on a local port (for example, specified by the redirect_uri parameter, in this example: 12345), and the browser will provide the OAuth code there. See Web login flow. For ascli, HTTP is required, and 12345 is the default port. The host of redirect_uri shall be loopback: localhost, an address of 127.0.0.0/8, or [::1].

Once the client is registered, a Client ID and Secret are created; these values are used in the next step.

Configuration for Aspera on Cloud🔗

If you did not use the wizard, you can also manually create an Option Preset for ascli in its configuration file.

Create an Option Preset called <AOC_ORG> using ask for interactive input (client info from previous step):

ascli config preset ask <AOC_ORG> url client_id client_secret
option: url> https://<ORG_NAME>.ibmaspera.com/
option: client_id> <CLIENT_ID>
option: client_secret> <CLIENT_SECRET>
updated: <AOC_ORG>

Note

In above example, replace https://<ORG_NAME>.ibmaspera.com with your actual AoC URL.

(This can also be done in one line using the command config preset update <AOC_ORG> --url=...)

Define this Option Preset as default configuration for the aoc plugin:

ascli config preset set default aoc <AOC_ORG>

Note

Default auth method is web and default redirect_uri is http://localhost:12345. Leave those default values.

Authentication with private key🔗

For browser-less, private key-based authentication, use the following steps.

To use JSON Web Token (JWT) for Aspera on Cloud API client authentication, a private/public key pair must be used.

API Client JWT activation🔗

If you are not using the built-in client_id and secret, JWT needs to be authorized in Aspera on Cloud. This can be done in two ways:

  • Graphically

  • Open a web browser, log in to your instance: https://<ORG_NAME>.ibmaspera.com/ (Use your actual AoC instance URL)

  • Go to Apps → Admin → Organization → Integrations
  • Click the previously created application
  • Select tab: JSON Web Token Auth
  • Modify options if necessary, for instance: activate both options in section Settings
  • Save

  • Using command line

ascli aoc admin client list
Items: 4/4
╭────────────┬─────────────────────╮
│ id         │ name                │
╞════════════╪═════════════════════╡
│ oXPUyJ7JpQ │ ALM                 │
│ <ID> │ web_client         │
│ TDNl2bLZqw │ jwt_client          │
│ VTh92i5OfQ │ iPaaS               │
╰────────────┴─────────────────────╯
ascli aoc admin client modify <ID> @json:'{"jwt_grant_enabled":true,"explicit_authorization_required":false}'
modified

User key registration🔗

The public key must be assigned to your user. This can be done in two ways as follows.

Graphically🔗

Open the previously generated public key located here: $HOME/.aspera/ascli/<PKEY_NAME>.pub

  • Open a web browser, log in to your instance: https://<ORG_NAME>.ibmaspera.com/ (Use your actual AoC instance URL)
  • Click the user icon (top right)
  • Select Account Settings
  • Paste the Public Key PEM value in the Public Key section
  • Click Submit

Using command line🔗

ascli aoc admin user list
╭─────────┬────────────────┬────────────────────╮
│ id      │ name           │ email              │
╞═════════╪════════════════╪════════════════════╡
│ 1234567 │ John Doe       │ john@example.com   │
│ 7654321 │ Alice Saprich  │ alice@example.com  │
│ 1234321 │ Sponge Bob     │ bob@example.com    │
╰─────────┴────────────────┴────────────────────╯
ascli aoc user profile modify @: public_key=@file:~/.aspera/ascli/<PKEY_NAME>.pub
modified

Tip

The ascli aoc user profile show command can be used to verify modifications.

Option Preset modification for JWT🔗

To activate default use of JWT authentication for ascli using the Option Preset, do the following:

  • Change auth method to JWT
  • Provide location of private key
  • Provide username to login as (OAuth subject)

Execute:

ascli config preset update <AOC_ORG> --auth=jwt --private-key=@val:@file:~/.aspera/ascli/<PKEY_NAME> --username=someuser@example.com

Note

The private key argument represents the actual PEM string. To read the content from a file, use the @file: prefix. But if the @file: argument is used as is, it will read the file and set in the configuration file. So, to keep the @file: tag in the configuration file, the @val: prefix is added.

After this last step, commands do not require web login anymore.

AoC bootstrap authentication🔗

For quick access using an existing browser session, use --auth=boot.

  • Open a Web browser and log in to your AoC instance
  • Open the browser developer tools
  • In Network, select any request to api.ibmaspera.com.
  • In Headers, right-click the Cookie Request Header and select Copy Value

Alternatively:

  • Go to the Application tab → Cookies
  • Copy the full cookie string, all values on one line, separated by "; " (semi-colon + space).

For a simpler use, configure a preset with the url option, and optionally username. (If the username is not provided, then the subject from the token is used, else both must match.)

Use the cookie string as the value of option password; an environment variable is convenient, as the value is temporary anyway:

export ASCLI_PASSWORD="...; aoc.token=...; aoc.refresh=...; ..."

ascli aoc user profile show --auth=boot

Note

The cookie string contains aoc.token (bearer JWT, mandatory) and aoc.refresh (refresh token, optional). Only those two are used. On first use, the tokens are cached locally. Subsequent calls reuse the cache and refresh automatically: the password option is used only to get the username unless the option username is already provided.

AoC gives the possibility to generate public links for both the Files and Packages modules. Public links embed the authorization of access. Provide the public link using option url alone.

In addition, the Files application supports private links. Private links require the user to authenticate. So, provide the same options as for regular authentication, and provide the private link using option url.

A user may not be part of any workspace, but still have access to shared folders (using private links). In that case, it is possible to list those shared folders by using a value for option workspace equal to @none: or @json:null or @ruby:nil.

AoC: First Use🔗

Once client has been registered and Option Preset created: ascli can be used:

ascli aoc files browse /
Current Workspace: Default Workspace (default)
empty

Calling AoC APIs from command line🔗

The command ascli aoc bearer_token can be used to generate an OAuth token suitable to call any AoC API. This can be useful when a command is not yet available. The token is a secret: it is hidden in the output, unless option --out.secrets=yes is used.

Example:

curl -s -H "Authorization: $(ascli aoc bearer_token --out.secrets=yes)" 'https://api.ibmaspera.com/api/v1/group_memberships?embed[]=dropbox&embed[]=workspace'|jq -r '.[]|(.workspace.name + " -> " + .dropbox.name)'

It is also possible to get the bearer token for node, as user or as admin using:

ascli aoc files bearer_token_node /
ascli aoc admin node bearer_token <NODE_ID>

Administration🔗

The admin command allows several administrative tasks (and requires admin privilege).

It allows actions (create, update, delete) on resources: users, groups, nodes, workspaces, and so on, with the admin <RESOURCE_TYPE> commands.

Listing resources🔗

The command aoc admin <TYPE> list lists all entities of given type. It uses paging and multiple requests if necessary.

The option query can be optionally used. It expects a Hash using Extended Value syntax. For a single filter key, the dot-path option form is the most direct (for example, --query.sort=name). For multiple keys or values copied from API documentation, --query=@json:{...} is more suitable. Values are directly sent to the API call and used as a filter on server side.

The following parameters are supported:

Parameter Source Description
q Native A filter on name of resource.
(case-insensitive, matches if value is contained in name)
sort Native Name of fields to sort results, prefix with - for reverse order.
page Native Do not use.
Managed by ascli.
per_page Native Do not use.
Managed by ascli.
max ascli Maximum number of items to retrieve.
pmax ascli Maximum number of pages to request.
other Native Other specific parameters depending on resource type.

Note

Both max and pmax are processed by ascli (see option --query). ascli will return all values using paging if not provided. page and per_page are normally added by ascli to build successive API calls to get all values if there are more than 1000 (AoC allows a maximum page size of 1000). Other parameters depend on the type of resource (refer to AoC API) and are directly sent as parameters to the GET request on API.

Tip

Use --query=help to display the full list of supported query parameters for any list command. For example: ascli aoc admin user list --query=help

Tip

Options --out.query and --out.select can also be used to further refine selection, refer to Filtering results.

Examples:

  • List users with laurent in name:
ascli aoc admin user list --query.q=laurent
  • List users who logged in before a date:
ascli aoc admin user list --query.q='last_login_at:<2018-05-28'
  • List external users and sort in reverse alphabetical order using name:
ascli aoc admin user list --query=@json:'{"member_of_any_workspace":false,"sort":"-name"}'

Selecting a resource🔗

Resources are identified by a unique id and a unique name (case-insensitive).

To execute an action on a specific resource, select it using one of those methods:

  • recommended: give the ID directly on the command line after the action: aoc admin node show 123
  • Give another unique field, such as the name, using the percent selector after the action: aoc admin node show %name:abc

Creating a resource🔗

New resources (users, groups, workspaces, and so on) can be created using a command like:

ascli aoc admin <RESOURCE_TYPE> create @json:'{<...parameters...>}'

Some API endpoints are described in IBM API Hub. Not all endpoints are documented there.

Nevertheless, it is possible to infer the structure of the creation payload by dumping an existing resource and using the same parameters for creation.

ascli aoc admin group show 12345 --format=json
{"created_at":"2018-07-24T21:46:39.000Z","description":null,"id":"12345","manager":false,"name":"A8Demo WS1","owner":false,"queued_operation_count":0,"running_operation_count":0,"stopped_operation_count":0,"updated_at":"2018-07-24T21:46:39.000Z","saml_group":false,"saml_group_dn":null,"system_group":true,"system_group_type":"workspace_members"}

Remove the parameters that are set by the system (id, created_at, updated_at), and optional ones.

And then craft your command:

ascli aoc admin group create @json:'{"wrong":"param"}'

If the command returns an error, for example:

ERRR Rest: found unpermitted parameter: :wrong
code: unpermitted_parameters
request_id: 2a487dbc-bc5c-41ab-86c8-3b9972dfd4c4
api.ibmaspera.com 422 Unprocessable Entity

Remove the offending parameters and try again.

Note

Some properties that are shown in the web UI, such as membership, are not listed directly in the resource, but instead another resource is created to link a user and its group: group_membership

Access Key secrets🔗

To access some administrative actions on nodes (in fact, access keys), the associated secret may be required. The secret is provided using the secret option. For example, in a command like:

ascli aoc admin node do <NODE_ID> v3 info

It is also possible to store secrets in the secret vault and then automatically find the related secret using the config finder.

Activity🔗

The activity app can be queried with:

ascli aoc admin analytics transfers

It supports filters and can send notifications using option notify_to. A template is defined using option notify_template:

mytemplate.erb:

From: <%=from_name%> <<%=from_email%>>
To: <<%=ev['user_email']%>>
Subject: <%=ev['files_completed']%> files received

Dear <%=ev[:user_email.to_s]%>,
We received <%=ev['files_completed']%> files for a total of <%=ev['transferred_bytes']%> bytes, starting with file:
<%=ev['content']%>

Thank you.

The environment provided contains the following additional variable:

  • ev : all details on the transfer event

Example:

ascli aoc admin analytics transfers --once-only=yes --lock-port=12345 --query=@json:'{"status":"completed","direction":"receive"}' --notify-to=active --notify-template=@file:mytemplate.erb

Options:

  • once_only: keep track of the last date it was called, so that the next call gets only new events
  • query: filter (on API call)
  • notify_to, notify_template: send an email as specified by the template; the template can be placed in a file with the @file: modifier.

Note

This must not be executed in less than 5 minutes because the analytics interface accepts only a period of time between 5 minutes and 6 months. The period is [date of previous execution]..[now].

Using ATS🔗

See the section Examples of ATS and substitute command ats with aoc admin ats.

Aspera on Cloud Shared folders are implemented through a special type of file: link. A link is the equivalent of a symbolic link on a file system: it points to another folder (not file).

Listing a link (as the last element of the path) shows information on the link itself, not the content of the folder it points to. To list the target folder content, add a / at the end of the path.

Example:

ascli aoc files browse the_link
Current Workspace: Default (default)
╭──────────┬──────┬────────────────┬──────┬──────────────────────┬──────────────╮
│ name     │ type │ recursive_size │ size │ modified_time        │ access_level │
╞══════════╪══════╪════════════════╪══════╪══════════════════════╪══════════════╡
│ the_link │ link │                │      │ 2021-04-28T09:17:14Z │ edit         │
╰──────────┴──────┴────────────────┴──────┴──────────────────────┴──────────────╯
ascli aoc files browse the_link/
Current Workspace: Default (default)
╭─────────────┬──────┬────────────────┬──────┬──────────────────────┬──────────────╮
│ name        │ type │ recursive_size │ size │ modified_time        │ access_level │
╞═════════════╪══════╪════════════════╪══════╪══════════════════════╪══════════════╡
│ file_inside │ file │                │      │ 2021-04-26T09:00:00Z │ edit         │
╰─────────────┴──────┴────────────────┴──────┴──────────────────────┴──────────────╯

Example: Bulk creation of users🔗

ascli aoc admin user create --bulk=yes @json:'[{"email":"dummyuser1@example.com"},{"email":"dummyuser2@example.com"}]'
╭───────┬─────────╮
│ id    │ status  │
╞═══════╪═════════╡
│ 98398 │ created │
│ 98399 │ created │
╰───────┴─────────╯

Example: Find with filter and delete🔗

ascli aoc admin user list --query.q=dummyuser --fields=id,email
╭───────┬────────────────────────╮
│ id    │ email                  │
╞═══════╪════════════════════════╡
│ 98398 │ dummyuser1@example.com │
│ 98399 │ dummyuser2@example.com │
╰───────┴────────────────────────╯
ascli aoc admin user list --query.q=dummyuser --fields=id --out.level=data --format=csv | ascli aoc admin user delete @lines:@stdin: --bulk=yes
╭───────┬─────────╮
│ id    │ status  │
╞═══════╪═════════╡
│ 98398 │ deleted │
│ 98399 │ deleted │
╰───────┴─────────╯

Example: Find deactivated users for more than 2 years🔗

ascli aoc admin user list --query=@ruby:'{"deactivated"=>true,"q"=>"last_login_at:<#{(DateTime.now.to_time.utc-2*365*86400).iso8601}"}'

To delete them use the same method as before.

Example: Display current user's workspaces🔗

ascli aoc user workspaces list
╭────────┬─────────────────────────╮
│ id     │ name                    │
╞════════╪═════════════════════════╡
│ 45073  │ Engineering             │
│ 145222 │ Marketing               │
│ 149207 │ Sales                   │
│ 149699 │ Secret Project          │
╰────────┴─────────────────────────╯

User client settings🔗

The aoc user settings sub-command manages persistent client-side settings stored server-side in AoC.

ascli aoc user settings list
ascli aoc user settings show <ID>
ascli aoc user settings modify <ID> @json:'{"value":"..."}'

Note

The AoC API endpoint client_settings filters entries by two implicit criteria:

  • User identity: derived from the OAuth bearer token (the authenticated user).
  • Application identity: derived from the client_id used during authentication.

This means that settings stored by one client application (for example, the AoC web UI) are not visible to another (for example, ascli using a different client_id). By default, ascli uses the pre-registered global client_id (see option --use-generic-client of plugin aoc).

Example: Create a sub access key in a node🔗

Creation of a sub-access key is like creation of an access key, with the following differences: authentication to the Node API is made with an access key (the master access key), and only the path parameter is provided, relative to the storage root of the master key (id and secret are optional).

ascli aoc admin node do %name:'<NODE_NAME>' v3 access_keys create @: storage.path=/folder1

Example: Display transfer events (ops/transfer)🔗

ascli aoc admin node do <NODE_ID> v3 transfer list --query.q='*' --query.max=5

Examples of query:

{"q":"type(file_upload OR file_delete OR file_download OR file_rename OR folder_create OR folder_delete OR folder_share OR folder_share_via_public_link)","sort":"-date"}
{"tag":"aspera.files.package_id=LA8OU3p8w"}

Example: Display node events (events)🔗

ascli aoc admin node do <NODE_ID> v3 events

Example: Display members of a workspace🔗

ascli aoc admin workspace_membership list --fields=member_type,manager,member.email --query=@json:'{"embed":"member","inherited":false,"workspace_id":11363,"sort":"name"}'
╭─────────────┬─────────┬──────────────────────────╮
│ member_type │ manager │ member.email             │
╞═════════════╪═════════╪══════════════════════════╡
│ user        │ true    │ john.curtis@email.com    │
│ user        │ false   │ someuser@example.com     │
│ user        │ false   │ jean.dupont@me.com       │
│ user        │ false   │ another.user@example.com │
│ group       │ false   │                          │
│ user        │ false   │ aspera.user@gmail.com    │
╰─────────────┴─────────┴──────────────────────────╯

Other query parameters:

{"workspace_membership_through":true,"include_indirect":true}

Example: Add all members of a workspace to another workspace🔗

a- Get ID of first workspace

WS1='First Workspace'
WS1ID=$(ascli aoc admin workspace list --query=@json:'{"q":"'"$WS1"'"}' --select=@json:'{"name":"'"$WS1"'"}' --fields=id --format=csv)

b- Get ID of second workspace

WS2='Second Workspace'
WS2ID=$(ascli aoc admin workspace list --query=@json:'{"q":"'"$WS2"'"}' --select=@json:'{"name":"'"$WS2"'"}' --fields=id --format=csv)

c- Extract membership information

ascli aoc admin workspace_membership list --fields=manager,member_id,member_type,workspace_id --query=@json:'{"workspace_id":'"$WS1ID"'}' --format=jsonpp --out.file=ws1_members.json

d- Convert to creation data for second workspace:

grep -Eve '(direct|effective_manager|_count|storage|"id")' ws1_members.json|sed '/workspace_id/ s/"'"$WS1ID"'"/"'"$WS2ID"'"/g' > ws2_members.json

Or, using jq:

jq '[.[] | {member_type,member_id,workspace_id,manager,workspace_id:"'"$WS2ID"'"}]' ws1_members.json > ws2_members.json

e- Add members to second workspace

ascli aoc admin workspace_membership create --bulk=yes @json:@file:ws2_members.json

Example: Get users who did not log in since a date🔗

ascli aoc admin user list --fields=email --query=@json:'{"q":"last_login_at:<2018-05-28"}'
╭──────────────────────────╮
│ email                    │
╞══════════════════════════╡
│ John.curtis@acme.com     │
│ Jean.Dupont@tropfort.com │
╰──────────────────────────╯

Example: List Limited users🔗

ascli aoc admin user list --fields=email --select=@json:'{"member_of_any_workspace":false}'

Example: Create a group, add to workspace and add user to group🔗

  • Create the group and take note of id
ascli aoc admin group create @json:'{"name":"group 1","description":"<DESCRIPTION>"}'

Group: <GROUP_ID>

  • Get the workspace ID
ascli aoc admin workspace show %name:"<WORKSPACE_NAME>" --fields=id

Or (similar, but may return several entries, as it is a simple search):

ascli aoc admin workspace list --query.q="<WORKSPACE_NAME>" --fields=id

Workspace:

  • Add group to workspace
ascli aoc admin workspace_membership create @json:'{"workspace_id":<WORKSPACE_ID>,"member_type":"group","member_id":<GROUP_ID>}'
  • Get a user's ID
ascli aoc admin user list --query=@json:'{"q":"manu.macron@example.com"}' --fields=id --format=csv --out.level=data

User:

  • Add user to group
ascli aoc admin group_membership create @json:'{"group_id":<GROUP_ID>,"member_type":"user","member_id":<USER_ID>}'

Example: Perform a multi Gbps transfer between two remote shared folders🔗

In this example, a user has access to a workspace where two shared folders are located on different sites, for example, different cloud regions.

First, set up the environment (skip if already done), see AoC configuration: Using Wizard:

ascli config wizard @: url=https://sedemo.ibmaspera.com plugin=aoc preset=aoc_sedemo --username=someuser@example.com

This creates the option preset aoc_sedemo to allow seamless command line access and sets it as default for Aspera on Cloud.

Then, create two shared folders located in two regions, in your files home, in a workspace.

Then, transfer between those:

ascli -Paoc_sedemo aoc files transfer push 'IBM Cloud SJ' --to-folder='AWS Singapore' 100GB.file --ts=@json:'{"target_rate_kbps":1000000,"multi_session":10,"multi_session_threshold":1}'

Example: Delete all registration keys🔗

ascli aoc admin client_registration_token list --fields=id --format=csv|ascli aoc admin client_registration_token delete @lines:@stdin: --bulk=yes
╭─────┬─────────╮
│ id  │ status  │
╞═════╪═════════╡
│ 99  │ deleted │
│ 100 │ deleted │
│ 101 │ deleted │
│ 102 │ deleted │
╰─────┴─────────╯

Example: Create a tethered Node🔗

Follow these steps to configure a new HSTS and link it to your existing Aspera on Cloud (AoC) organization.

  • Retrieve the Organization Public Key

First, obtain the organization's public key. This key is used to verify bearer tokens generated by your organization. This key remains constant for the lifetime of your Organization.

ascli aoc admin organization show --fields=oauth_token_verification_key --out.secrets=yes --out.file=mypubkey.pem

It can also be retrieved from an existing node:

ascli aoc admin node do %name:'<NODE_NAME>' v3 access_keys show self --fields=token_verification_key --out.secrets=yes --out.file=mypubkey.pem
  • Create an Access Key on the Self-Managed HSTS

Create the local credentials on your High-Speed Transfer Server (HSTS).

Tip

In this command, "master node credentials" allowing access key creation are used. The id and secret parameters are optional. If you omit them, you must add --out.secrets=yes to the command. Record the generated secret immediately; it cannot be retrieved later, only reset.

ascli node access_keys create @: id=<ACCESS_KEY_ID> secret=<SECRET> storage.type=local storage.path=/data/aoc token_verification_key=@file:mypubkey.pem
  • Register the Node in AoC

Now, register the physical server as a node object within the Aspera on Cloud administration interface.

ascli aoc admin node create @: url=https://aspera.example.com access_key=<ACCESS_KEY_ID> name=testnode1
  • Configure Access Key Permissions

Assign the necessary permissions to the root file ID for your new access key. This ensures the system and node owner have the correct authorization.

Tip

The following two commands are executed using access key credentials. If the node is configured for admin user, then add options: --username=<ACCESS_KEY_ID> --password=<SECRET>.

ascli node access_keys do self permission / create @: access_type=user access_id='F4 System'
ascli node access_keys do self permission / create @: access_type=user access_id=NODE_OWNER
  • Optional next steps

To register an Aspera Event Journal (AEJ) as described in the HSTS manual, refer to:

Example: Create registration key to register a tethered node🔗

The following command will create and display a secret token to register a self-managed Aspera Transfer Server:

ascli aoc admin client_registration_token create @json:'{"data":{"name":"laurentnode","client_subject_scopes":["alee","aejd"],"client_subject_enabled":true}}' --fields=token --out.secrets=yes

Example: Create an ATS Node🔗

AoC nodes are composed of two related entities:

  • An access key created on the Transfer Server (HSTS/ATS)
  • A node resource in the AoC application.

The web UI allows creation of both entities in one shot. For more flexibility, ascli allows this in two separate steps.

Note

When selecting Use existing access key in the web UI, this skips access key creation (first step).

So, for example, the creation of a node using ATS in IBM Cloud looks like (see other example in this manual):

  • Create the access key on ATS

The creation options are the ones of ATS API, refer to the section on ATS for more details and examples.

ascli aoc admin ats access_key create @json:'{"storage":{"type":"ibm-s3","bucket":"mybucket","credentials":{"access_key_id":"<ACCESS_KEY_ID>","secret_access_key":"<SECRET>"},"path":"/"}}' --cloud=softlayer --region=eu-de

Once executed, the access key id and secret, randomly generated by the Node API, are displayed.

Note

Once returned by the API, the secret will not be available anymore, so store it securely. ATS secrets can only be reset by asking IBM support.

  • Create the AoC node resource

First, retrieve the ATS node address:

ascli aoc admin ats cluster show --cloud=softlayer --region=eu-de --fields=transfer_setup_url --format=csv

Then use the returned address for the url key to create the AoC Node resource:

ascli aoc admin node create @json:'{"name":"myname","access_key":"<ACCESS_KEY>","ats_access_key":true,"ats_storage_type":"ibm-s3","url":"https://ats-sl-fra-all.aspera.io"}'

Creation of a node with a self-managed node is similar, but the command aoc admin ats access_key create is replaced with node access_keys create on the private node itself.

Example: Deactivate an application in a workspace🔗

This is a two-step procedure:

  1. Find the application ID in the workspace:
ascli aoc admin workspace show <WORKSPACE_ID> --query.include_aspera_apps=true --fields=packages_app.id

Or, alternatively:

ascli aoc admin application instance list --query.aspera_app_type=packages --query.workspace_id=<WORKSPACE_ID> --fields=id --out.level=data

This displays the .

  1. Deactivate the application:
ascli aoc admin application instance packages modify <APP_ID> @: enabled=false inherit_organization_app_settings=false

List of files to transfer🔗

Source files are provided as a list with the sources option. By default, the list of files is provided on the command line. See File list.

Packages app🔗

The Aspera on Cloud Packages app lets you assemble copies of any number of files and folders into a digital "package" and send the package to others, pretty much like a web-mail application.

Note

All aoc packages commands operate in a workspace context. The workspace is inferred automatically when a default workspace is configured in the application. If no default is set, provide one explicitly with --workspace=NAME. List available workspaces with ascli aoc user workspaces list.

Send a Package🔗

General syntax:

ascli aoc packages send <PACKAGE_EXTENDED_VALUE> <OPTIONS> <FILE_LIST>

Package creation parameters are sent as a Command Parameter. See the AoC package creation API, or display an existing package in JSON to list attributes.

List allowed shared inbox destinations with:

ascli aoc packages shared_inboxes list

Use fields: recipients and/or bcc_recipients to provide the list of recipients: user or shared inbox:

  • Provide either IDs as expected by API: "recipients":[{"type":"dropbox","id":"<SHBOX_ID>"}]
  • or names only: "recipients":["The Dest"].

ascli will resolve the list of email addresses and dropbox names to the expected type/ID list, based on case-insensitive partial match.

If a user recipient (email) is not already registered and the workspace allows external users, then the package is sent to an external user, and:

  • If the option new_user_option is --new-user-option.package_contact=true (default), then a public link is sent and the external user does not need to create an account.
  • If the option new_user_option is @json:{}, then external users are invited to join the workspace.

Example: Send a package with one file to two users, using their email🔗

ascli aoc packages send @json:'{"name":"<TITLE>","note":"<NOTE>","recipients":["someuser@example.com","other@example.com"]}' <FILE_PATH>

Example: Send a package to a shared inbox with metadata🔗

ascli aoc packages send --workspace="<WORKSPACE_NAME>" @json:'{"name":"<TITLE>","recipients":["Shared Inbox With Meta"],"metadata":{"Project Id":"123","Type":"Opt2","CheckThose":["Check1","Check2"],"Optional Date":"2021-01-13T15:02:00.000Z"}}' ~/Documents/Samples/200KB.1

It is also possible to use identifiers and API parameters. For example, sending to a shared inbox by ID with metadata:

ascli aoc packages send --workspace="<WORKSPACE_NAME>" @json:'{"name":"<TITLE>","recipients":[{"type":"dropbox","id":"12345"}],"metadata":[{"input_type":"single-text","name":"Project Id","values":["123"]},{"input_type":"single-dropdown","name":"Type","values":["Opt2"]},{"input_type":"multiple-checkbox","name":"CheckThose","values":["Check1","Check2"]},{"input_type":"date","name":"Optional Date","values":["2021-01-13T15:02:00.000Z"]}]}' ~/Documents/Samples/200KB.1

Example: Send a package with files from the Files app🔗

Find files in Files app:

ascli aoc files browse /src_folder
╭──────────────┬──────┬────────────────┬──────────────┬──────────────────────┬──────────────╮
│ name         │ type │ recursive_size │ size         │ modified_time        │ access_level │
╞══════════════╪══════╪════════════════╪══════════════╪══════════════════════╪══════════════╡
│ sample_video │ link │                │              │ 2020-11-29T22:49:09Z │ edit         │
│ 100G         │ file │                │ 107374182400 │ 2021-04-21T18:19:25Z │ edit         │
│ 10M.dat      │ file │                │ 10485760     │ 2021-05-18T08:22:39Z │ edit         │
│ Test.pdf     │ file │                │ 1265103      │ 2022-06-16T12:49:55Z │ edit         │
╰──────────────┴──────┴────────────────┴──────────────┴──────────────────────┴──────────────╯

To send a package with the file 10M.dat from subfolder /src_folder:

ascli aoc files node_info /src_folder --format=json --out.level=data --out.secrets=yes | ascli aoc packages send @json:'{"name":"test","recipients":["someuser@example.com"]}' 10M.dat --transfer=@json:@stdin: --transfer.agent=node

Receive packages🔗

The command to receive one or multiple packages is:

ascli aoc packages recv <PACKAGE_ID> [<FILE> ...]

Where <PACKAGE_ID> is the identifier of the package to receive or ALL to receive all packages matching the query. Option once_only is supported, see below.

To download only some files from the package, add the path of the files on the command line: [<FILE> ...], see option sources. By default, all files in the package are downloaded, that is, . is used as the file list.

Option package_folder🔗

The package_folder option (Hash) controls how downloaded packages are organized into subfolders under the path specified by to_folder.

  • If package_folder is not specified or is an empty Hash, packages are downloaded directly into the folder defined by to_folder.
  • If specified, packages are stored in dynamically generated subfolders.

Supported Fields:

Field Type Description
fld Array[String] List of package fields (up to 2) used to build the subfolder name. Field values are joined with ..
Example: ["name", "id"].
inf Bool If true, creates a <ID>.info.json sidecar file inside the folder containing package metadata.
Default: false.
opt Bool If false (default), all fields in fld are always used. If true, the first field is used unless the folder already exists.
Default: false.
seq Bool If true, appends an incrementing number to the folder name when a conflict occurs.
Default: false.

Examples:

  • {"fld":["id"]}
  • The subfolder name is the unique package ID.
  • Downloading the same package (same ID) multiple times places it in the same folder.
  • {"fld":["name"]}
  • The subfolder name is the package name.
  • If multiple packages share the same name, their contents are downloaded into the same folder.
  • {"fld":["name","id"]}
  • The subfolder name is <NAME>.<ID>.
  • This guarantees uniqueness when package names are identical.
  • {"fld":["name","id"],"opt":true}
  • The subfolder name is initially the package name.
  • If a folder with that name already exists, the name and ID (<NAME>.<ID>) are used instead.
  • {"fld":["name"],"seq":true,"opt":true}
  • The subfolder name is the package name if it does not already exist.
  • If it exists, a sequence number is appended (for example, <NAME>.1, <NAME>.2, and so on).
  • Downloading the same package multiple times results in different folders when a conflict occurs.

Example: Receive all packages from a given shared inbox🔗

ascli aoc packages recv ALL --workspace=_workspace_ --once-only=yes --lock-port=12345 --query=@json:'{"dropbox_name":"_shared_inbox_name_","archived":false,"received":true,"has_content":true,"exclude_dropbox_packages":false,"include_draft":false}' --ts=@json:'{"resume_policy":"sparse_csum","target_rate_kbps":50000}'

To list packages that would be downloaded, without downloading them, replace recv ALL with list (keep options once_only and query).

Receive new packages only (Cargo)🔗

It is possible to automatically download new packages, like using Aspera Cargo:

ascli aoc packages recv ALL --once-only=yes --lock-port=12345
  • ALL (case-sensitive) will download all packages
  • --once-only=yes keeps memory of any downloaded package in persistency files located in the configuration folder
  • --lock-port=12345 ensures that only one instance is started at the same time, to avoid running two downloads in parallel

Typically, one would execute this command on a regular basis, using the method of your choice: see Scheduler.

Example: Content of a received Package🔗

Some node operations are available for a package, such as browse and find.

To list the content of a package, use command packages browse <PACKAGE_ID> <FOLDER>. Example:

ascli aoc packages browse xx5CnbeWng /

Use command find to list recursively.

For advanced users, it is also possible to pipe node information for the package and use node operations:

ascli aoc packages node_info <PACKAGE_ID> / --format=json --out.secrets=yes --out.level=data | ascli node -N --preset=@json:@stdin: access_keys do self browse /

List packages🔗

By default, when using aoc packages list or aoc packages receive ALL, the following query is performed:

Query parameter Value
archived false
has_content true
received true
completed true
workspace_id Set based on current workspace.
dropbox_id Set according to dropbox_name, if provided.
exclude_dropbox_packages true unless dropbox_id is provided.

Parameters provided using option query override this query. To remove a parameter, set it to null.

Example: List packages in a given shared inbox🔗

When user packages are listed, the following query is used:

{"archived":false,"exclude_dropbox_packages":true,"has_content":true,"received":true}

To list packages in a shared inbox, the query has to be specified with the shared inbox by name or its identifier. Additional parameters can be specified, as supported by the API (to find out available filters, consult the API definition, or use the web interface in developer mode). The current workspace is added unless specified in the query.

Note

By default, exclude_dropbox_packages is set to true for user packages, and to false for shared inbox packages. This can be overridden in the query.

Using shared inbox name:

ascli aoc packages list --query=@json:'{"dropbox_name":"My Shared Inbox","archived":false,"received":true,"has_content":true,"exclude_dropbox_packages":false,"include_draft":false,"sort":"-received_at"}'

Using shared inbox identifier: first retrieve the ID of the shared inbox, and then list packages with the appropriate filter.

shared_box_id=$(ascli aoc packages shared_inboxes show %name:'My Shared Inbox' --format=csv --out.level=data --fields=id)
ascli aoc packages list --query=@json:'{"dropbox_id":"'$shared_box_id'","archived":false,"received":true,"has_content":true,"exclude_dropbox_packages":false,"include_draft":false,"sort":"-received_at"}'

Files app🔗

The Files application presents a Home folder to users in a given workspace. Files located here are either user's files, or shared folders.

Note

All aoc files commands operate in a workspace context. The workspace is inferred automatically when a default workspace is configured in the application. If no default is set, provide one explicitly with --workspace=NAME. List available workspaces with ascli aoc user workspaces list. All commands under files are the same as under access_keys do self for plugin node, that is, gen4/access key operations.

Download Files🔗

The general download command is:

ascli aoc files download <SOURCE_FOLDER_PATH> <SOURCE_FILENAME_1> ...

That is, the first argument is the source folder, and the following arguments are the source file names in this folder.

If a single file or folder is to be downloaded, then a single argument can be provided.

ascli aoc files download <SINGLE_FILE_PATH>

Shared folders🔗

In Aspera on Cloud (AoC), Shared Folders allow users to collaborate on content via Private or Public links.

  • Private links: Require the collaborator to log in to access the folder.
  • Public links: Include a passcode that allows access without an account or login.

Management Scopes🔗

Shared folders can be managed through two primary administrative scopes:

  • User Shared Folders: Users share personal folders with others in the same workspace using aoc files permission.
  • Admin Shared Folders: Administrators share folders from any node in a workspace using aoc admin node do <NODE_ID> permission.

Technically, shared folders are managed as permissions on a specific node. When a permission is created, AoC generates a link in the recipient's home folder to that shared folder.

Permission Payloads🔗

When creating a Shared Folder, ascli expects a Hash payload (typically passed via @json: or @:) similar to the one used at API level.

API-level Payload Example:

{
  "file_id": "50",
  "access_levels": ["list","read","write","delete","mkdir","rename","preview"],
  "access_type": "user",
  "access_id": "john@example.com",
  "tags": {...}
}

Field Mapping & Helper Fields:

ascli automatically populates (Auto) several native fields and provides helper fields to simplify the process:

Field Type Description
file_id Native
Auto
The ID of the folder, automatically resolved from the path provided in the command.
access_levels Native
Optional
List of access levels to set for the shared folder.
Defaults to full access.
tags Native
Auto
Set with expected values for AoC: username who creates, and workspace in which the shared folder is created.
access_type Native
Required
Type of access, such as user, group, or workspace.
Can be set with parameter with.
access_id Native
Required
ID of the user, group, or workspace (see with)
with ascli Recipient of shared folder. Can be a username, a group name, or a workspace name.
ascli will resolve the name to the proper type and ID in fields access_type and access_id.
If the value is the empty string, then it declares the shared folder in the workspace (first action to do, see below).
link_name ascli Name of the link file created in the user's home folder for private links.
as ascli Name of the link file created in the user's home folder for admin shared folders.

To declare or create the shared folder in the workspace, a special value for access_id is used: ASPERA_ACCESS_KEY_ADMIN_WS_[workspace ID], with an access_type of user. This is conveniently set by ascli using an empty string for field with. To share a folder with a different user, special tags are set, but this is conveniently done by ascli using the as field.

User Shared Folders🔗

Personal shared folders, created by users in a workspace, follow the syntax:

ascli aoc files permission --workspace=<WORKSPACE_NAME> <PATH_TO_FOLDER> ...

Note

The workspace is identified by name, and folder by path, relative to the user's home. To use an identifier instead, one can use the percent selector, like %id:<WS_ID>.

Admin Shared Folders🔗

Admin shared folders, created by administrators in a workspace, follow the syntax:

ascli aoc admin node do <NODE_ID> permission --workspace=<WORKSPACE_NAME> <PATH_TO_FOLDER>

Tip

The node is identified by identifier. To use a name instead, one can use the percent selector, like %name:"<NODE_NAME>". The folder is identified by its path; a file ID can be specified instead, with %id:123. If the ID is left blank: %id:, then it means *, that is, "all".

Example: List permissions on a user shared folder🔗

ascli aoc files permission /shared_folder_test1 list

Example: Share a personal folder with other users🔗

ascli aoc files permission /shared_folder_test1 create @json:'{"with":"laurent"}'

Example: Revoke shared access🔗

ascli aoc files permission /shared_folder_test1 delete 6161

They can be managed with commands:

ascli aoc files short_link <PATH_TO_FOLDER> private create
ascli aoc files short_link <PATH_TO_FOLDER> private list
ascli aoc files short_link <PATH_TO_FOLDER> public create @json:'{...}'
ascli aoc files short_link <PATH_TO_FOLDER> public list
ascli aoc files short_link <PATH_TO_FOLDER> public delete <ID>
ascli aoc files short_link <PATH_TO_FOLDER> public modify <ID> @json:'{...}'

Only public short links can be modified. An optional payload can be provided at creation, for example to protect with a password, set an expiry date or set the access level.

A password can be provided on create and modify for public links:

{"password":"<PASSWORD>"}

To remove a password:

{"password_enabled":false}

By default, access level is set to edit. Change the default access level by providing the parameter: access_levels in payload. access_levels can be:

  • A single String: one of the shortcuts: edit, preview, download, upload.
  • An Array: any custom combination of: delete, list, mkdir, preview, read, rename, write.

For example:

{"access_levels":"upload"}
{"access_levels":["list","rename"]}

An expiration date can be set with parameter expires_at, using ISO 8601 format. For example, 2025-08-29T08:10:31.000Z. If only a date is provided, for example: 2025-08-29, it will be set to midnight UTC of that date, that is, 2025-08-29T00:00:00.000Z.

Example: Create a workspace admin shared folder🔗

First, identify the node ID where the shared folder will be created.

To get the node ID of the default node for workspace <WORKSPACE_NAME>, use the command:

ascli aoc admin workspace show %name:'<WORKSPACE_NAME>' --fields=node_id

Tip

This syntax first lists workspaces using API selector q, and then performs an exact match on the specified field: name.

Alternatively:

ascli aoc admin workspace list --select.name="<WORKSPACE_NAME>" --fields=node_id

Tip

This syntax lists all workspaces, and then performs an exact match on the specified field: name.

Alternatively:

ascli aoc admin workspace list --query.q="<WORKSPACE_NAME>" --fields=node_id

Tip

This syntax first lists workspaces using API selector q. It may return several items as the query is case insensitive and made on several fields as substring.

Or select a node identifier manually from the list of nodes:

ascli aoc admin node list --fields=id,name

In the following commands, replace:

  • <NODE_ID> with the node ID, or with %name:<NODE_NAME>.
  • <WORKSPACE_NAME> with the workspace name, or with %id:<WORKSPACE_ID>.
  • <FOLDER_PATH> with the path of the folder to share on the node (for example, /my_folder or my_folder). It can also be a folder deeper than level 1.

If the shared folder does not exist, then create it:

ascli aoc admin node do <NODE_ID> mkdir <FOLDER_PATH>

Create the shared folder in workspace <WORKSPACE_NAME> (set with to empty string, or do not specify it). Optionally, use as to set the name of the shared folder if different from the folder name on the node. For other options, refer to the previous section on shared folders.

ascli aoc admin node do <NODE_ID> permission <FOLDER_PATH> create @json:'{"with":"","as":"folder_for_users"}' --workspace="<WORKSPACE_NAME>"

Note

The previous command only declares the shared folder in the workspace, but does not share it with anybody.

To share with a user, group, or workspace, use the with parameter with the name of a resource to share with (non-empty value). The "with" parameter will perform a lookup, and set fields access_type and access_id accordingly. The native fields access_type and access_id can also be used, instead of with.

ascli aoc admin node do <NODE_ID> permission <FOLDER_PATH> create @json:'{"with":"john@example.com","as":"folder_for_one_user"}' --workspace="<WORKSPACE_NAME>"
ascli aoc admin node do <NODE_ID> permission <FOLDER_PATH> create @json:'{"with":"group 1","as":"folder_for_a_group"}' --workspace="<WORKSPACE_NAME>"
ascli aoc admin node do <NODE_ID> permission <FOLDER_PATH> create @json:'{"with":"<WORKSPACE_NAME>","as":"folder_for_all_workspace"}' --workspace="<WORKSPACE_NAME>"

Note

In the previous commands, field as is optional.

Example: List all workspace admin shared folders in a workspace🔗

ascli aoc admin workspace shared_folder %name:'<WORKSPACE_NAME>' list
╭───────┬───────────┬─────────┬─────────┬───────────┬──────────────────────────────────────╮
│ id    │ node_name │ node_id │ file_id │ file.path │ tags.aspera.files.workspace.share_as │
╞═══════╪═══════════╪═════════╪═════════╪═══════════╪══════════════════════════════════════╡
│ 198   │ eudemo    │ 8666    │ 2465    │ /project1 │                                      │
│ 785   │ eudemo    │ 8666    │ 9       │ /folder2  │ project2                             │
│ 4788  │ eudemo    │ 8666    │ 3691    │ /backup   │                                      │
╰───────┴───────────┴─────────┴─────────┴───────────┴──────────────────────────────────────╯

To list members:

ascli aoc admin workspace shared_folder %name:'<WORKSPACE_NAME>' member 198 list
╭─────────────┬──────────────────────────────────┬──────────────┬──────────────────────╮
│ access_type │ access_id                        │ access_level │ last_updated_at      │
╞═════════════╪══════════════════════════════════╪══════════════╪══════════════════════╡
│ user        │ ASPERA_ACCESS_KEY_ADMIN_WS_45071 │ edit         │ 2020-11-29T22:48:49Z │
│ group       │ 160270                           │ edit         │ 2024-05-13T15:58:02Z │
╰─────────────┴──────────────────────────────────┴──────────────┴──────────────────────╯

If you have the node ID of the shared folder, then it is equivalent to:

ascli aoc admin node do 8666 permission /project1 list --query=@json:'{"tag":"aspera.files.workspace.id=<WORKSPACE_ID>"}'

Example: List all workspace admin shared folders on a node🔗

First get the workspace identifier:

ascli aoc admin workspace list --select=@json:'{"name":"<WORKSPACE_NAME>"}' --fields=id
<WORKSPACE_ID>

Then, identify the node ID on which to list, see previous section.

Finally, list all shared folders, as permissions:

ascli aoc admin node do <NODE_ID> permission %id: list --query=@json:'{"access_type":"user","access_id":"ASPERA_ACCESS_KEY_ADMIN_WS_<WORKSPACE_ID>"}'

Note

See Node API: GET /permissions for all query options. The folder identifier is left empty %id:, to apply to all folders.

Cross Organization transfers🔗

It is possible to transfer files directly between organizations without having to first download locally and then upload...

Although optional, the creation of Option Preset is recommended to avoid placing all parameters in the command line.

Procedure to send a file from org1 to org2:

  • Get access to Organization 1 and create an Option Preset, for example org1 (for instance, using the Wizard)
  • Check that access works and locate the source folder <SOURCE_FOLDER> and the file <SOURCE_FILE> in it, for example, using command files browse
  • Get access to Organization 2 and create an Option Preset, for example org2
  • Check that access works and locate the destination folder <DEST_FOLDER>
  • Execute the following:
ascli -Porg1 aoc files node_info <SOURCE_FOLDER> --format=json --out.level=data --out.secrets=yes | ascli -Porg2 aoc files upload <SOURCE_FILE> --to-folder=<DEST_FOLDER> --transfer=@json:@stdin: --transfer.agent=node

Explanation:

  • ascli is the command executed by the shell
  • -Porg1 loads options for preset org1 (URL and credentials)
  • aoc uses the Aspera on Cloud plugin
  • files node_info <SOURCE_FOLDER> generates transfer information for the source folder: Node API URL, credentials and root file ID, suitable for the next command
  • --format=json formats the output as JSON (instead of the default text table)
  • --out.level=data displays only the result, removing other information such as workspace name
  • | pipes the standard output of the first command into the second one
  • -Porg2 aoc uses the Aspera on Cloud plugin and loads credentials for org2
  • files upload <SOURCE_FILE> --to-folder=<DEST_FOLDER> uploads the file <SOURCE_FILE> (located in <SOURCE_FOLDER> of org1) to <DEST_FOLDER> in org2
  • --transfer=@json:@stdin: reads the Node API information from standard input (JSON) and uses it as parameters of the transfer agent
  • --transfer.agent=node selects the node transfer agent: the source node of org1 pushes the file to org2

Find Files🔗

The command aoc files find allows searching for files in a given workspace.

It works also on node resource:

ascli aoc admin node do %name:'<NODE_NAME>' find ...

For instructions, refer to section find for plugin node.

Tested commands for aoc🔗

Note

Add ascli aoc in front of the following commands:

admin analytics application_events
admin analytics files organization '' <ID>
admin analytics transfers organization --query=@json:'{"status":"completed","direction":"receive","limit":2}' --notify-to=my_email_external --notify-template=@ruby:'%Q{From: <%=from_name%> <<%=from_email%>>\nTo: <<%=to%>>\nSubject: <%=ev["files_completed"]%> files received\n\n<%=ev.to_yaml%>}'
admin analytics transfers users --once-only=yes
admin application instance list
admin application instance list --query.aspera_app_type=files
admin application instance list --query.organization_apps=true
admin application membership list
admin application types
admin ats access_key create --cloud=aws --region=my_region @json:'{"id":"ak_aws_aoc","name":"my test key AWS","storage":{"type":"aws_s3","bucket":"my_bucket","credentials":{"access_key_id":"<ACCESS_KEY>","secret_access_key":"<SECRET_KEY>"},"path":"/"}}'
admin ats access_key create --cloud=softlayer --region=my_region @: id=ak1ibmcloud secret=<SECRET> 'name="my test key"' storage.type=ibm-s3 storage.bucket=my_bucket storage.credentials.access_key_id=<ACCESS_KEY> storage.credentials.secret_access_key=<SECRET_KEY> storage.path=/
admin ats access_key delete ak1ibmcloud
admin ats access_key list --fields=name,id
admin ats access_key node ak1ibmcloud --secret=<SECRET> browse /
admin ats cluster clouds
admin ats cluster list
admin ats cluster show --cloud=aws --region=eu-west-1
admin ats cluster show 1f412ae7-869a-445c-9c05-02ad16813be2
admin auth_providers list
admin bearer_token --out.level=data --out.secrets=yes
admin client list
admin client_access_key list
admin client_registration_token create @json:'{"data":{"name":"test_client_reg1","client_subject_scopes":["alee","aejd"],"client_subject_enabled":true}}'
admin client_registration_token delete <ID>
admin client_registration_token list
admin configuration_policy list
admin configuration_policy show <ID>
admin contact list
admin dropbox list
admin dropbox_membership list
admin group list
admin group_membership list --fields=ALL --query=@json:'{"page":1,"per_page":50,"embed":"member","inherited":false,"workspace_id":11363,"sort":"name"}'
admin kms_profile list
admin network_policy list
admin network_policy show <ID>
admin node bearer_token %name:my_node_name user:all
admin node do %name:my_node_name --secret=<AK_SECRET> browse /
admin node do %name:my_node_name --secret=<AK_SECRET> browse /folder_sub --node-api.cache=false
admin node do %name:my_node_name --secret=<AK_SECRET> delete /folder1
admin node do %name:my_node_name --secret=<AK_SECRET> delete /folder_sub
admin node do %name:my_node_name --secret=<AK_SECRET> mkdir /folder1
admin node do %name:my_node_name --secret=<AK_SECRET> mkdir /folder_sub
admin node do %name:my_node_name --secret=<AK_SECRET> v3 access_key create @json:'{"id":"test-sub-1","storage":{"path":"/folder_sub"}}'
admin node do %name:my_node_name --secret=<AK_SECRET> v3 access_key delete test-sub-1
admin node do %name:my_node_name --secret=<AK_SECRET> v3 events
admin node do %name:my_node_name delete test_shared_folder
admin node do %name:my_node_name mkdir test_shared_folder
admin node do %name:my_node_name perm test_shared_folder create @json:'{"with":"","as":"other_name_shared"}' --workspace=my_workspace_shared_inbox
admin node do %name:my_node_name perm test_shared_folder create @json:'{"with":"my_user_email","as":"other_name_shared"}' --workspace=my_workspace_shared_inbox
admin node do %name:my_node_name perm test_shared_folder create @json:'{"with":"my_user_group","as":"other_name_shared"}' --workspace=my_workspace_shared_inbox
admin node list
admin operation list
admin organization show
admin package list --http-options.read_timeout=120.0
admin saml_configuration list
admin self show
admin short_link list
admin subscription account
admin subscription usage
admin subscription usage MONTH
admin user list
admin user list --out.query='[?ats_admin].{name: name, email: email}'
admin user modify %name:my_user_email @: deactivated=false
admin user notifications %name:my_user_email show
admin user preferences %name:my_user_email show
admin workspace dropbox %name:my_other_workspace list
admin workspace list
admin workspace shared_folder %name:my_other_workspace list
admin workspace shared_folder %name:my_other_workspace member <ID> list
admin workspace_membership list
admin workspace_membership list --fields=ALL --query=@json:'{"page":1,"per_page":50,"embed":"member","inherited":false,"workspace_id":11363,"sort":"name"}'
automation workflow action <ID> create @: name=toto
automation workflow create @: name=test_workflow
automation workflow delete <ID>
automation workflow details <ID>
automation workflow export <ID>
automation workflow list
automation workflow list --query.show_org_workflows=@val:true
automation workflow list --select.name=test_workflow --fields=id
bearer_token --out.level=data --out.secrets=yes
files bearer /
files bearer_token_node / --cache-tokens=no
files browse /
files browse / --url=<PRIVATE_LINK_SHARED_FOLDER>
files browse / --url=<PUBLIC_LINK_FOLDER_NO_PASS>
files browse / --url=<PUBLIC_LINK_FOLDER_WITH_PASS> --password=<PUBLIC_LINK_FOLDER_PASSWORD>
files browse my_remote_file
files browse my_remote_folder
files browse my_remote_folder/
files cat test-dst/test_file.bin
files delete /test-src
files download --to-folder=. test-dst/test_file.bin test-dst/test_file.bin
files download --transfer.agent=connect test-dst/test_file.bin
files download --transfer.agent=desktop test-dst/test_file.bin
files find /sample_video
files find /sample_video '\.partial$'
files find /sample_video @ruby:'->(f){f["type"].eql?("file")}'
files mkdir /test-src
files modify /some_folder @: mount_point=false
files permission my_test_folder list
files rename /some_folder test-dst
files short_link /test-dst private create
files short_link /test-dst private list
files short_link /test-dst public create @: access_levels.0=mkdir access_levels.1=write --fields=id
files short_link /test-dst public modify <AOC_SHORT_LINK_PUB_CREATE> @: access_levels=edit
files show %id:<ID>
files show /
files show test-dst/test_file.bin
files sync admin status /data/local_sync
files sync pull /test-dst --to-folder=/data/local_sync @json:'{"reset":true,"transport":{"target_rate":my_bps}}'
files thumbnail my_test_folder/video_file.mpg
files thumbnail my_test_folder/video_file.mpg --query.text=true --query.double=true
files transfer push /test-src --to-folder=/test-dst test_file.bin
files upload --to-folder=/ test_file.bin --url=<PUBLIC_LINK_FOLDER_NO_PASS>
files upload --to-folder=/test-src test_file.bin
files upload --to-folder=/test-src test_file.bin test_file.bin
files v3 info
gateway @: url=https://localhost:12347/aspera/faspex
organization
organization --format=image --fields=background_image_url --ui=text
organization --url=<PUBLIC_LINK_RECV_FROM_AOC_USER>
packages browse <ID> /
packages list
packages list --query=@json:'{"dropbox_name":"my_shared_inbox_name","sort":"-received_at","archived":false,"received":true,"has_content":true,"exclude_dropbox_packages":false}'
packages receive <ID> --to-folder=.
packages receive <ID> --to-folder=. /
packages receive ALL --once-only=yes --to-folder=. --query.max=5 --lock-port=50101 --package-folder.fld.0=name --package-folder.fld.1=id --package-folder.opt=true
packages receive ALL --once-only=yes --to-folder=. --query.max=5 --lock-port=50101 --query=@json:'{"dropbox_name":"my_shared_inbox_name","archived":false,"received":true,"has_content":true,"exclude_dropbox_packages":false,"include_draft":false}' --ts=@json:'{"resume_policy":"sparse_csum","target_rate_kbps":50000}'
packages receive INIT --once-only=yes --query.dropbox_name=my_shared_inbox_name
packages send --workspace=my_workspace_shared_inbox --validate-metadata=yes @json:'{"name":"package title","recipients":["my_shared_inbox_meta"],"metadata":[{"input_type":"single-text","name":"Project Id","values":["123"]},{"input_type":"single-dropdown","name":"Type","values":["Opt2"]},{"input_type":"multiple-checkbox","name":"CheckThose","values":["Check1","Check2"]},{"input_type":"date","name":"Optional Date","values":["2021-01-13T15:02:00.000Z"]}]}' test_file.bin
packages send --workspace=my_workspace_shared_inbox --validate-metadata=yes @json:'{"name":"package title","recipients":["my_shared_inbox_meta"],"metadata":{"Project Id":"456","Type":"Opt2","CheckThose":["Check1","Check2"],"Optional Date":"2021-01-13T15:02:00.000Z"}}' test_file.bin
packages send --workspace=my_workspace_shared_inbox @json:'{"name":"package title","recipients":["my_shared_inbox_name"]}' test_file.bin
packages send @: 'name=package title' END test_file.bin --url=<PUBLIC_LINK_SEND_AOC_USER> --password=<PUBLIC_LINK_SEND_USE_PASS>
packages send @: 'name=package title' END test_file.bin --url=<PUBLIC_LINK_SEND_SHARED_INBOX>
packages send @: 'name=package title' recipients.0=my_username 'note=some notes' END test_file.bin
packages send @json:'{"name":"package title","recipients":["my_email_external"]}' --new-user-option.package_contact=true test_file.bin
packages shared_inboxes list
packages shared_inboxes short_link public %name:my_shared_inbox_name create --fields=id
packages shared_inboxes short_link public %name:my_shared_inbox_name delete <AOC_SHARED_INBOX_SHORT_LINK_CREATE>
packages shared_inboxes short_link public %name:my_shared_inbox_name list
packages shared_inboxes short_link public %name:my_shared_inbox_name modify <AOC_SHARED_INBOX_SHORT_LINK_CREATE> @: password=<PUBLIC_LINK_FOLDER_PASSWORD>
packages shared_inboxes short_link public %name:my_shared_inbox_name show <AOC_SHARED_INBOX_SHORT_LINK_CREATE>
packages shared_inboxes show %name:my_shared_inbox_name
packages show '%name:package title'
remind --username=my_user_email --url=https://aoc.example.com/path
servers --url=https://aoc.example.com/path
tier_restrictions
user contacts list
user pref modify @: default_language=en-us
user pref show
user profile modify @: 'name=dummy change'
user profile show
user workspaces current
user workspaces list