# Using the CLI

This tool allows the manipulation of all Metal Cloud elements via the command line.

![metalcloud-cli](/assets/metalcloud-cli-animated.gif)

## Installation

To install on Mac OS X:
```
brew tap metalsoft-io/homebrew-repo
brew install metalcloud-cli
```

To install on any CentOS/Redhat Linux distribution use the latest release for your platform:
[https://github.com/metalsoft-io/metalcloud-cli/releases/latest](https://github.com/metalsoft-io/metalcloud-cli/releases/latest)

```
$ sudo rpm -i https://github.com/metalsoft-io/metalcloud-cli/releases/download/v2.5.13/metalcloud-cli_2.5.13_linux_amd64.rpm
```

To install on any Debian/Ubuntu distributions:
```
curl -sLO https://github.com/metalsoft-io/metalcloud-cli/releases/download/v2.5.13/metalcloud-cli_2.5.13_linux_amd64.deb && sudo dpkg -i metalcloud-cli_2.5.13_linux_amd64.deb
```

To install on Windows:
Binaries are available [here](https://github.com/metalsoft-io/metalcloud-cli/releases/latest):
Download and unzip the executable and simply execute. 

To install using `go get`:
```bash
go get github.com/metalsoft-io/metalcloud-cli
```

## Getting the API key

In the Metalsoft Web UI click on the user icon at the top right corner. Then go to **API credentials** > **APY key**

Copy the api key. Its format should be `<number>:<letters>`.

Copy the endpoint. Its format should be `https://api.environment.hostname`.

Configure credentials as environment variables:
```bash
export METALCLOUD_API_KEY="<your key>" # example value: "1:e5fa44f2b31c1fb553b6021e7360d07d5d91ff5e"
export METALCLOUD_ENDPOINT="<your api endpoint>" # example value: "https://api.demo.metalsoft.io"
export METALCLOUD_USER_EMAIL="<your email>" # example value: "user@metalsoft.io"
export METALCLOUD_INSECURE_SKIP_VERIFY=false #defaults to false
export METALCLOUD_TIMEOUT_SECONDS=300 #defaults to 300 if not set
```

## Getting a list of supported commands

Use `metalcloud-cli help` for a list of supported commands.


## Getting started

To create an infrastructure, in the default datacenter, configured via the `METALCLOUD_DATACENTER` environment variable):
```bash
metalcloud-cli infrastructure create --label test --return-id
```

```bash
metalcloud-cli infrastructure list
+-------+-----------------------------------------+-------------------------------+-----------+-----------+---------------------+---------------------+
| ID    | LABEL                                   | OWNER                         | REL.      | STATUS    | CREATED             | UPDATED             |
+-------+-----------------------------------------+-------------------------------+-----------+-----------+---------------------+---------------------+
| 12345 | complex-demo                            | d.d@sdd.com                   | OWNER     | active    | 2019-03-28T15:23:08Z| 2019-03-28T15:23:08Z|
+-------+-----------------------------------------+-------------------------------+-----------+-----------+---------------------+---------------------+
```

To create an instance array in that infrastructure, get the ID of the infrastructure from above (12345):

```bash
metalcloud-cli instance-array create --infra 12345 --label master --proc 1 --proc-core-count 8 --ram 16
```

To view the id of the previously created drive array:

```bash
metalcloud-cli instance-array list --infra 12345
+-------+---------------------+---------------------+-----------+
| ID    | LABEL               | STATUS              | INST_CNT  |
+-------+---------------------+---------------------+-----------+
| 54321 | master              | ordered             | 1         |
+-------+---------------------+---------------------+-----------+
Total: 1 Instance Arrays
```

To create a drive array and attach it to the previous instance array:

```bash
metalcloud-cli drive-array create --infra 12345 --label master-da --ia 54321
```

To view the current status of the infrastructure

```bash
metalcloud-cli infrastructure get --id 12345
Infrastructures I have access to (as test@test.com)
+-------+----------------+-------------------------------+-----------------------------------------------------------------------+-----------+
| ID    | OBJECT_TYPE    | LABEL                         | DETAILS                                                               | STATUS    |
+-------+----------------+-------------------------------+-----------------------------------------------------------------------+-----------+
| 36791 | InstanceArray  | master                        | 1 instances (16 RAM, 8 cores, 1 disks)                                | ordered   |
| 47398 | DriveArray     | master-da                     | 1 drives - 40.0 GB iscsi_ssd (volume_template:0) attached to: 36791   | ordered   |
+-------+----------------+-------------------------------+-----------------------------------------------------------------------+-----------+
Total: 2 elements
```


## Kubernetes-style Apply support

Apply creates or updates a resource from a file. The supported format is yaml.

```bash
metalcloud-cli apply -f resources.yaml
```

The type of the requested resource needs to be specified using the field *kind*.

```
cat resources.yaml

kind: InstanceArray
apiVersion: 1.0
label: my-instance-array

---

kind: Secret
apiVersion: 1.0
name: my-secret

```

The objects and their fields can be found in the [SDK documentation](https://godoc.org/github.com/metalsoft-io/metal-cloud-sdk-go). The fields will be in the format specified in the yaml tag. For example `SubnetPool` object has a field named `subnet_pool_prefix_human_readable` in JSON format. In the YAML file used as input for this command, the field should be called `prefix`. 

## Condensed format

The CLI also provides a "condensed format" for most of it's commands:
* instance=array = ia
* drive-array = da
* infrastructure = infra
* list = ls
* delete = rm
...

This allows commands such as:
```bash
metalcloud-cli infra ls
```

## Using label instead of IDs

Most commands also take a label instead of an id as a parameter. For example:
```bash
metalcloud-cli infra show --id complex-demo
```


## Permissions

Some commands depend on various permissions. For instance you cannot access another user's infrastructure unless you are a delegate of it.