This section describes all the commands provided by the Akamas Command Line Interface (CLI):

• Administration commands to manage the Akamas installation

• User and Workspace management commands to manage user and workspaces

• Authentication commands to perform login and logout operations

• Resource management commands to manage all the Akamas resources

• Optimizer option commands to update the Akamas optimizer options

The Akamas CLI provides a command-line interaction with the Akamas platform, thus enabling an infrastructure-as-code user experience to manage the end-to-end optimization lifecycle.

Notice: the Akamas CLI allows performing all the operations that you can do on the UI and more. In particular, the CLI has to be used for all modification operations on the platform, such as the creation and deletion of Akamas resources.

Read here below to use the built-in help to get started with Akamas commands.

Akamas resources

The following table describes all the Akamas' resources and their parent resources.

Built-in help

Akamas CLI provides built-in help, which is one of the few commands that do not require any authentication.

By issuing the following command:

akamas

you get something like the following:

Usage: akamas [OPTIONS] COMMAND [ARGS]...

  A command line interface for Akamas.

Options:
  --version  Show the version and exit.
  --help     Show this message and exit.

Commands:
  build      Build a resource.
  create     Create a resource
  delete     Delete a resource
  describe   Show details of a specific resource
  export     Export a resource
  finish     Terminate the execution of a resource
  import     Restore a resource
  init       Initializes resources and other entities
  install    Install a resource
  list       List resource instances
  log        Show Akamas logs
  login      Login into Akamas
  logout     Logout from Akamas
  set        Set a resource.
  start      Start an execution of a resource
  status     Show the status of Akamas services
  uninstall  Uninstall a resource
  update     Update a resource
  whoami     Show logged user, current workspace and configured api address

Except for the , all Akamas commands representing Akamas operation require authentication.

Login

The CLI supports two different methods to authenticate with the Akamas server:

• direct login: performs the authentication using the username and password provided directly to the CLI

• oauth2: performs the authentication redirecting the user to Akamas' login page

By default, the CLI authenticates using the direct login unless the user provides the argument --method direct|oauth2 or with the akamas set config --method direct|oauth2 command.

Direct login

Local users (not linked to any external identity provider) can authenticate by providing the credentials as arguments to Akamas CLI:

• When the user or password are not provided as arguments, the CLI will prompt for their value. Be aware that passing the password as an argument may store it in the terminal history, so is advised to provide it through the secure prompt.

• If the workspace is specified and the user has access to it, it will be set as the default workspace for the session.

• If the login is successful, a message like the following will be printed: <username> logged in. Welcome."

• If the login fails because the credentials are wrong or the user is not authorized to access, the error message "Login failed: Invalid user credentials" will be printed.

Oauth2 login

All Akamas users can authenticate through the login page provided by the UI by running the following command:

The CLI will provide you with a link to the login page of the configured Akamas instance, similar to the following:

Open the browser on the provided link and authenticate using your local user or any configured identity provider. Once successfully authenticated, the UI will provide you with a code: paste it into the CLI prompt to complete the login process.

Reference

The full reference for the Akamas login command is.

If one of the environmental variables is specified, the corresponding parameter will not be asked to the user. Workspace is not needed for login.

Logout

When logged in, this command will log out the current user

On success the message "Logout successful." will be printed.

This page describes all commands that allow to be managed with their options (see also available for all commands).

General information

Common options

The following table describes the common options available for all commands:

Akamas aliases

The Akamas CLI allows using a set of aliases or shortcuts for many resources.

Any resource can be specified using either the singular or plural form. Furthermore, the shortcuts listed below are available:

You can print the list of available aliases with the following command

Build command

This command builds either a new optimization pack or a new scaffolding hierarchy.

Build optimization pack

In this case, you supply a folder with a specific hierarchy: the needed folders are metrics, component-types and parameters, and each of them contains a set of yaml resource files listing the supported resources. Then the command akamas build optimization-pack FOLDER_NAME creates a full JSON file with all the optimization pack contents inside it.

Build scaffolding

In this case, you supply two folders: one for variables, named variables and one for templates named templates. The variables folder must contain one yaml file for each desired output set and the templates folder should hold all generic templates that can contain variable parameters specified in the variables file.

For example, the variables folder could contain two files named test.yaml and prod.yaml. The contents of these files are:

Then suppose that the template folder contains some YAML files and one of them the is following file named template-study.yaml:

Create command

Create the Akamas resource described in the provided YAML file.

Create by file/folder

You can also omit the resource type from the create command and use the -f flag instead to create most of the resources with a YAML file in a single command. The supported resources are component, system, optimization-pack, study, workflow, telemetry-instance and telemetry-provider. To use this feature, it's required to add the kind key inside each YAML file. Also, the system key must be added when the resource is required to be attached to a system (applies to telemetry instances and system components).

For example, to create a new telemetry instance, you should add the following to your YAML file:

Then you can use the akamas create -f <filename.yaml> command instead of akamas create telemetry-instance <filename.yaml> SYSTEM_NAME.

Similarly, to create a new telemetry-provider (which does not need the system attribute), you just need to specify the kind to your YAML file:

This also works for optimization packs. For standard optimization packs provided by akamas, you need to write a YAML file such as:

If you want to install a custom optimization pack, you can also supply a JSON file. In this case, there is no need to specify the kind attribute.

Finally, if you supply a folder to the command akamas create, it will process all files inside this folder and create all the requested resources. You can, for example, use one of the output folders created by the command akamas build scaffold. Let's assume we have a folder named scaffold that contains the following files:

the following command will process all of the files above and (if correct) create all resources described inside of them:

Delete command

Delete an Akamas resource, identified by UUID or name.

with the following options:

Delete entity command

All resources created with the command akamas create -f <folder> can also be deleted by using the opposite command akamas delete -f <folder>. The only difference is that the command akamas delete -f has an additional flag --complete. When supplied, it deletes all supported objects including optimization packs and telemetry providers. When the --complete flag is missing, however, optimization packs and telemetry providers are not deleted.

List command

List the resources for the selected type with their id, name, and description. Additional resource-specific fields can be shown.

with the following options:

Describe command

Describe an Akamas resource with all its fields.

with the following options:

Notice that this command does not support the resource type System.

Update command

Update an Akamas resource, identified by UUID or name.

with the following options:

Update experiment command

Update an experiment, identified by the ID of the study and the experiment.

with the following options:

Install command

Install a License or an Optimization Pack

with the following options:

Uninstall command

Uninstall a License or an Optimization Pack

with the following options:

Start command

Start the execution of a Study.

Stop command

Stop the execution of a Study. Once stopped, the execution cannot be resumed.

Export command

To export a study, the study name or the study UUID can be used from the command line.

An optional filename can be specified, with a relative or absolute path:

The exported information will be saved in tar.gz format.

The following entities are exported:

• The Study

• The Steps of the Study

• The Experiments of the Study

• The Trials of the Study

• The Workflow to which the Study refers

• The Timeseries collected during the study run

• The System to which the Study refers

• The Component related to the Study's System

• The ComponentType of each Component

• The Metrics definitions of each ComponentTypes

• The Parameters definitions of each ComponentTypes

Notice: this operation can require a long time, depending on the quantity of data to be collected. During this time the CLI will wait for Akamas to send the exported package. Do not interrupt the CLI during this phase, as otherwise, the process will need to restart from the beginning.

Import command

Notice: please make sure that you have installed the latest versions of the optimization packs before starting the import: this way, the import procedure will bind the studies to the latest optimization packs version (i.e., the installed ones) instead of importing the (possibly) old ones from the source system.

Use the following command to import a study into an existing Akamas instance:

Where FILENAME refers to the file of a previously exported study.

When imported, the following entities will have a new UUID:

• Study

• Workflow

• System

• Component

• ComponentType

• Metrics

• Parameters

In case a resource that is being imported has the same name as an existing one, the existing entity will not be deleted. The existing entity (with its UUID) will be used instead of the imported one.

All steps, experiments, and trials will maintain the same id and, therefore, the same execution order as the original exported study.

Notice: this operation can require a long time. If the CLI shows a timeout error or if the operation is interrupted, the import will continue on the Akamas server.

The optimizer options can be customized at the study level only. Since a study is an Akamas resource this can be done by using the update command described on the Resource management commands page.

This page provides a quick reference for the update commands that can be used to dynamically change the options that drive how the Akamas optimizer works for live optimization studies.

Updating the online mode

The following command can be used to update the online mode of live optimization studies:

akamas update study <STUDY_NAME_OR_ID> --online-mode [RECOMMEND|FULLY_AUTONOMOUS]

Updating the safety mode

The following command can be used to update the safety mode of live optimization studies:

akamas update study <STUDY_NAME_OR_ID> --safety [GLOBAL|LOCAL]

Updating the workload strategy

The following command can be used to update the workload strategy of live optimization studies:

akamas update study <STUDY_NAME_OR_ID> --workload-strategy [MAXIMIN|MEDIAN|LAST|MOST_VIOLATED]

Updating the safety factor

The following command can be used to update the safety factor of live optimization studies:

akamas update study <STUDY_NAME_OR_ID> --safety-factor <VALUE>

Updating the exploration factor

The following command can be used to update the exploration factor of live optimization studies:

akamas update study <STUDY_NAME_OR_ID> --exploration-factor <VALUE>

This page describes all commands that allow users and workspaces to be managed with their options (see also common options available for all commands).

Notice: an Akamas workspace (user) is an Akamas resource (see list of Akamas resources) so you can also refer to resource management commands.

Create workspace

The create workspace command allows defining a new workspace:

akamas create workspace NAME

The following snippet shows an example:

akamas create  workspace 'New Workspace'

After the workspace has been created you can add users to the workspace with the following command:

akamas update user <user> -w 'New Workspace' W

See #update-a-user-profile section for further details

Update workspace

The update workspace command allows updating the workspace name:

akamas update workspace [OPTIONS] IDENTIFIER

with the following options:

The following snippet shows an example:

akamas update workspace 'New Workspace' --name 'New Name'

Delete workspace

The delete workspace command allows deleting a workspace:

akamas delete workspace [OPTIONS] IDENTIFIER

with the following options:

The following snippet shows an example:

akamas delete workspace 'New Workspace'

List users

The list users command returns the list of the available users.

akamas list users

The following snippet shows an example:

$ akamas list users

                 Id                    Username   First Name   Last Name   Workspaces       User Type
=======================================================================================================
66778cc3-4b01-4f3e-8921-c279600c8e07   akamas     -            -           -              Administrator
ae8bfe02-e32d-480b-92ed-30a8d8e835ef   newuser    new          user        Default W      User
                                                                           Workspace1 R

Create user

The create user command allows defining a new user and assigning it to one or more workspaces.

akamas create user [OPTIONS]

with the following options

The default policy requires the password to satisfy the following rules:

• Include one or more uppercase characters (A-Z)

• Include one or more special characters (~!@#$%^&*_-+=`|\(){}[]:;"'<>,.?/)

The username and password can be either provided interactively or as command arguments.

The following snippet shows the process of creating a new user interactively:

$ akamas create user

Username: newuser
Password:
Repeat for confirmation:
User first name: John
User last name: Doe
Email: john.doe@akamas.io

The same action can be performed using the command options:

$ akamas create user -u newuser -p P455w0rd

Describe user

The describe user command returns the details of a valid user matching the provided username or ID:

akamas describe user IDENTIFIER

Notice: users without administrative privileges can only describe their profiles, while administrators can inspect any profile.

The following snippet shows an example:

akamas describe user newuser

# Id         | a81fd6e5-aedc-4b74-b6d2-40650441935b
# Username   | newuser
# First Name | new
# Last Name  | user
# Email      | newuser@akamas.io
# Workspaces | - Default R
#            | - Workspace1 W
# User Type  | User

Update user

The update user command allows updating the user profile attributes for the user matching the username or ID:

akamas update user [OPTIONS] IDENTIFIER

with the following options:

The following snippet shows an example of updating the email of a user:

akamas update user --email 'new.email@akamas.io' newuser

This command is also used to grant or revoke access to workspaces and administrative privileges to users.

The following snippet shows an example of updating the user’s workspace access privileges, adding write privileges on Workspace 1, and revoking access on Default:

akamas update user -w 'Workspace 1' W -r Default newuser

Update password

The update password command updates the password for the user matching the username or ID:

akamas update password [OPTIONS] IDENTIFIER

with the following options:

The default policy requires the password to satisfy the following rules:

• Include one or more uppercase characters (A-Z)

• Include one or more special characters (~!@#$%^&*_-+=`|\(){}[]:;"'<>,.?/)

The password can be either provided interactively or as command arguments.

The following snippet shows the prompts to update the user password:

akamas update password newuser

# New password:
# Repeat for confirmation:

The same action can be performed using the command options:

akamas update password -p P455w0rd newuser

Delete user

The delete user command removes the user with the provided username or id:

akamas delete user IDENTIFIER

with the following options:

The following snippet shows an example of deleting interactively a user:

akamas delete user newuser

Confirm deletion of newuser [y/N]: y

This page describes all commands that allow Akamas resources to be managed with their options (see also common options available for all commands).

Install License command

An Akamas license is an Akamas resource (see list of Akamas resources) so you can use the following command (see install command) to install a license in an Akamas instance:

akamas install license licenkse.ak

Uninstall License command

An Akamas license is an Akamas resource (see list of Akamas resources) so you can use the following command (see uninstall command) to remove a license from the Akamas installation:

akamas uninstall license <license-id>

Status command

Print the status of the Akamas instance.

akamas status [-d]

with the following options:

Log command

Print the logs of the Akamas services.

akamas status [-d]

with the following options:

Initialize Akamas configuration

Initialize the CLI’s configuration file, either interactively or through the provided options.

akamas init config [options]

with the following options:

Set Akamas configuration

Set a value in the CLI’s configuration file

akamas set config [options]

with the following options: