Using the CLI#

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



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:

$ sudo rpm -i

To install on any Debian/Ubuntu distributions:

curl -skL $(curl -s | grep -i browser_download_url  | grep "$(dpkg --print-architecture)" | grep deb | head -n 1 | cut -d'"' -f4) -o metalcloud-cli.deb && sudo dpkg -i metalcloud-cli.deb

To install on Windows: Binaries are available here: Download and unzip the executable and simply execute.

To install using go get:

go get

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:

export METALCLOUD_API_KEY="<your key>" # example value: "1:e5fa44f2b31c1fb553b6021e7360d07d5d91ff5e"
export METALCLOUD_ENDPOINT="<your api endpoint>" # example value: ""
export METALCLOUD_USER_EMAIL="<your email>" # example value: "[email protected]"

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

metalcloud-cli infrastructure create --label test --return-id
metalcloud-cli infrastructure list
| ID    | LABEL                                   | OWNER                         | REL.      | STATUS    | CREATED             | UPDATED             |
| 12345 | complex-demo                            | [email protected]                   | 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):

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:

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:

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

To view the current status of the infrastructure

metalcloud-cli infrastructure get --id 12345
Infrastructures I have access to (as [email protected])
| 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

The kubernetes-style ‘apply’ functionality#

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

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

metalcloud-cli infra ls

Using label instead of IDs#

Most commands also take a label instead of an id as a parameter. For example:

metalcloud-cli infra show --id complex-demo


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

Admin commands#

To enable admin commands set the following environment variable:

export METALCLOUD_ADMIN="true"

Debugging information#

To enable debugging information in the output set the following environment variable:


Building the CLI#

The build process is automated by travis. Just push into the repository using the appropriate tag:

Use git tag to get the last tag:

git tag

Push new changes with new tag:

git add .
git commit -m "commit comment"
git tag v1.0.1
git push --tags

A coverage report is generated automatically at each build by coverall. There is a lower limit to the coverage currently set at 20%.

It is a good idea to update the master branch as well (with no tag):

git push

Updating the SDK#

To update the SDK update go.mod file then regenerate the interfaces used for testing. Ifacemaker is needed

go get ifacemaker
go generate

If new objects are added in the SDK helpers/fix_package.go will need to be updated.