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

{% code lineNumbers="true" %}

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

{% endcode %}

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 the Akamas resource described in the provided YAML file.

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

## 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> <resource-file> [<parent-resource-id>|<parent-resource-name>]
```

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

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

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

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