Skip to main content

Installing the command line interface supctl

The Avassa system provides a command line interface supctl. This instruction defines how to install and configure the command line interface.

Open the menu top right in Control Tower

User menu

Before performing the steps below cdto a directory where you would like to install the command line. You can add that directory to your path.

Select "Install supctl (Avassa command line)" which will result in the following dialogue. (Note, the actual URL and profile name will differ) Install supctl

Copy and paste that command sequence in your shell. It performs the following (skip reading if you are not interested, just start using supctl).

  1. downloads the supctl tool using curl from your environment. If you read the url you recognize your domain and environment name
  2. makes supctl executable
  3. runs a supctl command that generates a shell tab completion file
  4. creates a profile in subctl, profiles are useful to be able to switch between logins
  5. performs an oidc login to control tower, lauch the prompted url in your Control Tower browser window
note

OIDC user refers to the user that was created when you first registered for an Avassa account. That user is authenticated using an OIDC provider. You can also create local users in Control Tower, these are called local users.

You will get back a URL that you will need to paste into your browser in order to proceed, something like this:

Complete the login via your OIDC provider. Launch browser to:

  https://login.avassa.com/authorize?client_id=JVX9fZLU8fvsRZxuZ3uuGUuh1zPps1Ng&response_type=code&redirect_uri=https%3A%2F%2Fapi.cloud.demo.avassa.net%2Fcontrol-tower%2Foidc-callback&scope=openid+profile&state=YTAxNjRmN2YtYjc0Yi00ZWM2LTk5HGAtMWRkZTgzYjJhNDczOnByb2QudW1jLmF2YXNzYS5kZXY%3D&nonce=86f78035-ce6a-4a70-88f3-7b3d3a0b82f3

Once you have successfully authenticated you will see something like this:

Success! You are authenticated.
{
  "token": "46beba6a-4ab9-4b66-9d43-39d424c1581d",
  "expires-in": 2764800,
  "accessor": "6584cf72-7474-40ee-8d4e-1455c1f142f8",
  "creation-time": "2021-08-23T13:47:24.024953Z"
}

But don't worry; supctl saved the necessary information in your new profile (more about profiles later) so you do not have to memorize any of the above.

If you later would login as another user, you can get guidance by picking the Login command for supctl menu item

supctl login

Dependencies​

Running supctl is supported on the following operating systems:

  • Linux
  • macOS

In addition to that most of the functionality is expected to work under WSL on Windows.

You need Python 3 (and the websockets package) to run supctl. The minimum supported versions are:

  • Python 3.11, although most of the functionality works in older versions of Python too
  • websockets package version 10.0

In most cases Python is already installed on your operating system. If it isn't, here are some examples on how you would install it on your operating system:

sudo apt install python3
sudo apt install python3-websockets

If you are using bash or zsh, supctl offers tab-completion. To activate tab completion run:

source <(./supctl completion)

You need bash version 5+ for this to work (bash --version). Unfortunately the bash installed in macOS is old and does not support tab completion.

If you use zsh, and in case you get an error: command not found: compdef, please add the following to your $HOME/.zshrc:

autoload -Uz compinit
compinit

source <(supctl completion)

Adding supctl to your default PATH​

Instead of always typing ./supctl you can download supctl to a directory that you add to your path. Assume you downloaded the tool to ~/bin you can then add this to your path:

export PATH=${PATH}:~/bin

Working with profiles​

When you need to interact with more than one Control Tower, or want to interact with the same Control Tower using different users, profiles come in handy. A profile stores any current token information and the address of the Control Tower, so once you have logged in with a profile you do not need to provide any additional options to indicate the hostname of the Control Tower etc.

Listing profiles​

Use the profile list command. The currently active profile is indicated.

supctl profile list
api.dev.umc.avassa.dev (active)
joe

Switching profiles​

supctl profile switch joe
The active profile is now joe

Creating a new profile​

supctl profile create kim@dev
kim@dev created, it is now the active profile

If there are no profiles configured, one will automatically be created when you connect to a Control Tower. The host name will be used as the profile name.

Learning more on using supctl

You can follow the tutorial on supctl to learn how to use the command line interface to do specific Avassa tasks.