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

The optimizer options can be set at either the study level and also overwritten at optimize step level. Since a study is an Akamas resource this can be done by using the update command described on the 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:

Updating the safety mode

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

Updating the workload strategy

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

Updating the safety factor

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

Updating the exploration factor

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

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'

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 detail 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:

Notice: users without administrative privileges can update only their own password, while administrators can perform this action on any profile.

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 an example of updating interactively the password for a user:

$ 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).

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 alias or shortcuts for many resources.

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

   component            [comp, co, components, cmp]
   system               [systems, sys, sy]
   component-type       [ctype, comp-type, ct, component-types]
   optimization-pack    [optimization-packs, op, opt-pack, opack]
   metric               [metr, metrics, me]
   parameter            [parameters, pa, param, par]
   study                [st, studies, sty]
   workflow             [wf, wkfl, workflows, wo]
   telemetry-instance   [ti, tel-instance, telemetry-instances, tel-inst]
   telemetry-provider   [telemetry-providers, tel-prov, tp, tel-provider]
   kpi                  [kpis]
   workspace            [workspaces, ws]
   trial                [tr, trials]
   user                 [us, users]
   license              [licenses, lic]
   experiment           [experiments, exp]
   log                  [logs]
   step                 [steps]

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

akamas list alias

Build command

This command builds the Akamas resource described in the provided YAML file.

akamas build <resource-type> <resource-file>

Create command

Create the Akamas resource described in the provided YAML file.

akamas create <resource-type> <resource-file> [<parent-resource-id>|<parent-resource-name>]

Delete command

Delete an Akamas resource, identified by UUID or name.

akamas delete [options] <resource-type> <resource-id|resource-name> [<parent-resource-id>|<parent-resource-name>]

with the following options:

List command

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

akamas list [flags] <resource-type> <resource-id|resource-name> [<parent-resource-id>|<parent-resource-name>]

with the following options:

Describe command

Describe an Akamas resource with all its fields.

akamas describe [flags] <resource-type> <resource-type> <resource-id|resource-name> [<parent-resource-id>|<parent-resource-name>]

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.

akamas update <resource-type> <resource-id|resource-name>

with the following options:

Install command

Install a License or an Optimization Pack

akamas install <resource-type> <file>

with the following options:

Uninstall command

Uninstall a License or an Optimization Pack

akamas uninstall <resource-type> <id>

with the following options:

Start command

Start the execution of a Study.

akamas start study <id>|<name>

Stop command

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

akamas stop study <id>|<name>

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:

akamas export study <UUID>|"<NAME>" [FILENAME]

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 be restarted 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:

akamas import study FILENAME

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.

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:

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

Login

Login credentials can be passed as an argument to Akamas CLI:

akamas login -u <user> -p <password> -w <workspace>

• If the user, password, or organization are not specified as parameters, they will be asked via a prompt. Beware that passing the password as an argument makes it visible in the command line history. Therefore it should always be typed by the CLI 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.

The fill reference for the Akamas login command is.

akamas login [-u|--user USERNAME] [-p|--password PASSWORD] [-w|--workspace WORKSPACE] [-o|--organization ORGANIZATION]

If one of the environmental variables is specified, the corresponding parameter will not be asked to the user. Workspace and Organization are not needed for login, they will not be asked even if not specified.

Logout

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

akamas logout

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

Resources