# Resource management commands

This page describes all commands that allow [Akamas resources](#clireference-operations) to be managed with their options (see also [common options](#clireference-commonoptions) available for all commands).

| Command                              | Description                               |
| ------------------------------------ | ----------------------------------------- |
| [build](#clireference-build)         | build a resource from a file or directory |
| [create](#clireference-create)       | create a resource from a file             |
| [delete](#clireference-delete)       | delete a resource                         |
| [list](#clireference-list)           | list a set of resources                   |
| [describe](#clireference-describe)   | describe a resource                       |
| [update](#clireference-update)       | update a resource                         |
| [install](#clireference-install)     | install a resource from a file            |
| [uninstall](#clireference-uninstall) | uninstall a resource                      |
| [start](#clireference-start)         | start a study                             |
| [stop](#clireference-finish)         | stop a study                              |
| [export](#export-command)            | export a study                            |
| [import](#import-command)            | import a study                            |

## General information <a href="#clireference-commonoptions" id="clireference-commonoptions"></a>

### Common options <a href="#clireference-commonoptions" id="clireference-commonoptions"></a>

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

| Option      | Short option | Type   | Description                                                                                                                      |
| ----------- | ------------ | ------ | -------------------------------------------------------------------------------------------------------------------------------- |
| --debug     | -d           | Flag   | Print detailed information in case of errors                                                                                     |
| --workspace | -w           | String | Overrides the workspace defined in the configuration file when interacting with resources such as systems, workflows and studies |
| --help      |              | Flag   | Print command line help                                                                                                          |

### Akamas aliases <a href="#clireference-akamasaliases" id="clireference-akamasaliases"></a>

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:

```
   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

```bash
akamas list alias
```

## Build command <a href="#clireference-build" id="clireference-build"></a>

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

```bash
# build optimization pack
akamas build optimization-pack <folder-with-resource-files>

# build scaffolding
akamas build scaffold <folder-with-resource-files>
```

### 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.

{% hint style="info" %}
This command is available since version 2.8.0 of the CLI
{% endhint %}

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

{% code title="test.yaml" %}

```yaml
study:
  name: my study

k8s:
  namespace: online-boutique
  deployment: adservice
  container: server

k8s_deployment: test
```

{% endcode %}

{% code title="prod.yaml" %}

```yaml
study:
  name: Production study

k8s:
  namespace: online-boutique-prod
  deployment: adservice-prod
  container: server-prod

k8s_deployment: prod
```

{% endcode %}

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

{% code title="template-study.yaml" %}

```yaml
kind: study

name: {{ study.name }}
system: {{ k8s.deployment }}
workflow: {{ k8s.deployment }}

goal:
  name: Cost
  objective: minimize
  function:
    formula: (({{ k8s.container }}.container_cpu_limit)/1000)*29 + (((({{ k8s.container }}.container_memory_limit)/1024)/1024)/1024)*3
```

{% endcode %}

When launching the command `akamas build scaffold SCAFFOLDING_DIR_NAME/`, a new folder `output`is created inside `SCAFFOLDING_DIR_NAME` along with two sub-folders `test` and `prod`. Each sub-folder now contains the templates rendered with the values set in the `variables` files. The [`akamas create entity`](#create-entity-command) command makes it easier to create bulk entities.

## Create command <a href="#clireference-create" id="clireference-create"></a>

Create the Akamas resource described in the provided YAML file.

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

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

```yaml
kind: telemetry-instance
system: SYSTEM_NAME
```

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:

```yaml
kind: telemetry-provider
```

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

```yaml
kind: optimization-pack
name: OPTIMIZATION_PACK_NAME
```

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:

```
component.yaml
opt_pack.yaml
provider.yaml
study.yaml
system.yaml
telemetry_instance.yaml
workflow.yaml
```

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

```bash
akamas create -f scaffold/
```

## Delete command <a href="#clireference-delete" id="clireference-delete"></a>

Delete an Akamas resource, identified by UUID or name.

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

with the following options:

| Option  | Short option | Type | Description                           |
| ------- | ------------ | ---- | ------------------------------------- |
| --force | -f           | Flag | Force the deletion of the resource(s) |

### Delete entity command

Similarly to the create command, you can use the flag `-f` to delete the supplied resources. See the section [Create by file/folder](#create-by-file-folder) command for instructions on the supported resources and the additional required fields.

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 <a href="#clireference-list" id="clireference-list"></a>

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

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

with the following options:

| Option                            | Short option    | Type   | Values                                            | Default | Description                                        |
| --------------------------------- | --------------- | ------ | ------------------------------------------------- | ------- | -------------------------------------------------- |
| --no-pagination                   | -no-pag         | Flag   |                                                   |         | Show all resources without pagination              |
| --use-seconds                     | -u-s            | Flag   |                                                   |         | If durations should be output in seconds           |
| <p>--sort-asc,<br>--sort-desc</p> | -s-asc, -s-desc | Flag   |                                                   |         | Sort items by creation time                        |
| --output                          | -o              | Choice | <ul><li>table</li><li>json</li><li>yaml</li></ul> | table   | Switch the output to table (default), json or yaml |

## Describe command <a href="#clireference-describe" id="clireference-describe"></a>

Describe an Akamas resource with all its fields.

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

with the following options:

| Option   | Short option | Type   | Values                                            | Default | Description                                        |
| -------- | ------------ | ------ | ------------------------------------------------- | ------- | -------------------------------------------------- |
| --output | -o           | Choice | <ul><li>table</li><li>json</li><li>yaml</li></ul> | table   | Switch the output to table (default), json or yaml |

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

## Update command <a href="#clireference-update" id="clireference-update"></a>

Update an Akamas resource, identified by UUID or name.

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

with the following options:

| Option   | Short option | Type   | Values                                            | Default | Description                                        |
| -------- | ------------ | ------ | ------------------------------------------------- | ------- | -------------------------------------------------- |
| --output | -o           | Choice | <ul><li>table</li><li>json</li><li>yaml</li></ul> | table   | Switch the output to table (default), json or yaml |

### Update experiment command <a href="#clireference-install" id="clireference-install"></a>

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

```bash
akamas update experiment <study-id|study-name> <experiment-id>
```

with the following options:

<table><thead><tr><th width="165">Option</th><th width="175">Type</th><th>Values</th><th>Description</th></tr></thead><tbody><tr><td>--approve-configuration</td><td>Flag</td><td></td><td>Approve a waiting experiment.</td></tr><tr><td>--parameter</td><td>String</td><td>list of key-value pairs</td><td>Updated the experiment's configuration with the values provided in the key-value pairs.</td></tr></tbody></table>

## Install command <a href="#clireference-install" id="clireference-install"></a>

Install a License or an Optimization Pack

```bash
akamas install <resource-type> <file>
```

with the following options:

| Option  | Short option | Type | Description                            |
| ------- | ------------ | ---- | -------------------------------------- |
| --force | -f           | Flag | Force the installation of the resource |

## Uninstall command <a href="#clireference-uninstall" id="clireference-uninstall"></a>

Uninstall a License or an Optimization Pack

```bash
akamas uninstall <resource-type> <id>
```

with the following options:

| Option  | Short option | Type | Description                         |
| ------- | ------------ | ---- | ----------------------------------- |
| --force | -f           | Flag | Force the uninstall of the resource |

## Start command <a href="#clireference-start" id="clireference-start"></a>

Start the execution of a Study.

```bash
akamas start study <id|name>
```

## Stop command <a href="#clireference-finish" id="clireference-finish"></a>

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

```bash
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:

```bash
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 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:

```bash
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.