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

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.