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: Specifyaocto 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,
ascliuses a pre-registered global client ID. To create and use an organization-specific integration, give the option--use-generic-client=noof pluginaocto the wizard command. -
Direct Plugin Targeting: To limit detection to the
aocplugin 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
CookieRequest 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.
Public and private links🔗
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
laurentin 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 eventsquery: 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.
Files with type link🔗
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_idused 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
noderesource 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:
- 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
- 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_optionis--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_optionis@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_folderis not specified or is an emptyHash, packages are downloaded directly into the folder defined byto_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=yeskeeps memory of any downloaded package in persistency files located in the configuration folder--lock-port=12345ensures 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
Example: Public and Private short links🔗
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_folderormy_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 commandfiles 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:
ascliis the command executed by the shell-Porg1loads options for presetorg1(URL and credentials)aocuses the Aspera on Cloud pluginfiles 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=jsonformats the output as JSON (instead of the default text table)--out.level=datadisplays only the result, removing other information such as workspace name|pipes the standard output of the first command into the second one-Porg2 aocuses the Aspera on Cloud plugin and loads credentials fororg2files upload <SOURCE_FILE> --to-folder=<DEST_FOLDER>uploads the file<SOURCE_FILE>(located in<SOURCE_FOLDER>oforg1) to<DEST_FOLDER>inorg2--transfer=@json:@stdin:reads the Node API information from standard input (JSON) and uses it as parameters of the transfer agent--transfer.agent=nodeselects thenodetransfer agent: the source node oforg1pushes the file toorg2
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