Getting Started

The Ascend CLI gives users the ability to work with the platform in a shell based environment. Users can query the platform, integrate with source control, automate pipeline creation, and more!

Installation & Usage

Requirements: Python 3.8+ to Python 3.10+

Setup a virtual environment

It is recommended that you use some sort of python virtual environment. This is one example of how to use venv.

python3 -m venv .venv
source .venv/bin/activate

pip install the ascend-io-cli

Within your virtual environment, you install the ascend-io-cli package directly via pip.

pip install ascend-io-cli

Authentication

There are a few options for authenticating the CLI with your target Ascend environment. The recommended way to authenticate is to create a developer key and then use a credentials file located in the ~/.ascend (shell) or $USER_HOME\.ascend (windows) directory. There will be a separate key for each environment. For example, the file contents should look like this if you have access to cloud.ascend.io and impact.ascend.io environments. ~/.ascend/credentials should contain:

[cloud]
ascend_access_key_id=your_key_id_for_cloud
ascend_secret_access_key=your_secret_key_for_cloud

[impact]
ascend_access_key_id=your_key_id_for_impact
ascend_secret_access_key=your_secret_key_for_impact

🚧

Credential File Format

Ensure that your credentials file is saved with a UTF-8 encoding! Some text editors, such as Notepad.exe on Windows, may save files in an incompatible encoding.

The CLI will automatically load the key and secret key that matches the hostname for the environment you are working with. Keep your secrets file safe!

📘

Authenticating CI/CD Platforms

For CI/CD platforms like jenkins, github, .circleci, and others, the best practice is to create environment variables from the secret store. The CLI will prioritize these values over any other authentication materials source.

Shell

export ASCEND_ACCESS_KEY_ID=access_key_value
export ASCEND_SECRET_ACCESS_KEY=secret_key_value

Help System

The CLI includes a help system that gives information about how each command works. For example, try:

ascend --help
ascend list --help
ascend list data-services --help

Platform Target (--hostname)

The CLI can target one Ascend environment at a time. The target environment is set by either passing --hostname in the command or by using the static configuration method. supports several types of output. The --hostname value must exist in the credentials file otherwise the CLI will complain about authentication. For example, try this out:

# make sure the hostname matches what you put into the credentials file
ascend --hostname impact.ascend.io list data-services

Configuration Help

Typing --hostname for every command can be repetitive. You can tell the CLI to default to a hostname you specify:

ascend config show
ascend config set hostname cloud.ascend.io
ascend config show
ascend config list
ascend config --help

Formatting Output

The CLI supports several types of output. The default output is json. For example, try a table output:

ascend --output table list data-services

See ascend --help for all of the formatting options

Advanced Usage

Scripting with the Ascend CLI is simple and easy.

• Output from all commands comes back through stdout.
• Log messages and/or error messages will return via stderr.
• The CLI will return 0 for successful commands.

The default output is json which makes scripting easy.

For example, using jq

jq is a popular scripting tool for manipulating json in a shell environment. Learn about it here. It is easy to install in almost all environments.

Here are some examples of how to use jq with the CLI. Your shell will allow you to do very similar things in many different ways. These are just to get you started.

Get just the data service id

ascend list data-services | jq -r '.[].id'

Delete data services with name starting with sandbox

while read s; do
  ascend delete data-service $s
done < <(ascend list data-services | jq -r '.[]|select(.name | startswith("sandbox"))|.id')