Learn about the Ascend CLI
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
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 install ascend-io-cli
There are a few options for authenticating the CLI with your target Ascend environment. The recommended way to authenticate is to 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
~/.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.
export ASCEND_ACCESS_KEY_ID=access_key_value export ASCEND_SECRET_ACCESS_KEY=secret_key_value
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
--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
The CLI supports several types of output. The default output is
json. For example, try a table output:
ascend --output table list data-services
ascend --help for all of the formatting options
Scripting with the Ascend CLI is simple and easy.
- Output from all commands comes back through
- Log messages and/or error messages will return via
- The CLI will return
0for successful commands.
The default output is
json which makes scripting easy.
For example, using
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')
Updated about 2 months ago