Using the CLI

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


To install on Mac OS X:

brew tap bigstepinc/homebrew-repo
brew install metalcloud-cli

To install on any CentOS/Redhat Linux distribution:

$ sudo rpm -i

To install on any Debian/Ubuntu distributions:

curl -sLO && sudo dpkg -i metalcloud-cli_1.0.3_linux_amd64.deb

To install on Windows: Binaries are available here:

To install using go get (this should also work on Windows):

go get

Getting the API key

In the Metalcloud’s Infrastructure Editor go to the upper left corner and click on your email. Then go to Settings > API & SDKs > API credentials

Copy the api key. It should be of the form :

Configure credentials as environment variables:

export METALCLOUD_API_KEY="<your key>"
export METALCLOUD_USER_EMAIL="<your email>"
export METALCLOUD_DATACENTER="uk-reading"

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

Apply support

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