CLI User Guide

The app-pilvio-pro tool allows you to manage resources (such as VMs and vdisks) at a location on the command line. It is available for Linux, Windows and OS X operating systems (x86-64 only).

Installation

To install app-pilvio-pro you can download the latest CLI for your platform from the Downloads section.

Alternatively, you can download the CLI binary using curl

jwt=<YOUR JWT TOKEN>
curl -X GET "https://app.pilvio.pro/api/1/utilities/cli?platform=linux" -H  "accept: application/zip" -H "Authorization: Bearer $jwt" --output app-pilvio-pro.zip --output app-pilvio-pro.zip

After downloading, unpack the archive. Unpacking the archive will yield the app-pilvio-pro binary (NB: app-pilvio-pro.exe on Windows).

On linux-based systems, add the nessesary permissions to the binary chmod +x app-pilvio-pro.

Adding tab completion

To load completions use this command:

$ ./app-pilvio-pro completion --help

Bash

$ source <(app-pilvio-pro completion bash)

# To load completions for each session, execute once:
# Linux:
$ app-pilvio-pro completion bash > /etc/bash_completion.d/app-pilvio-pro
# macOS:
$ app-pilvio-pro completion bash > /usr/local/etc/bash_completion.d/app-pilvio-pro

Zsh

# If shell completion is not already enabled in your environment,
# you will need to enable it.  You can execute the following once:

$ echo "autoload -U compinit; compinit" >> ~/.zshrc

# To load completions for each session, execute once:
$ app-pilvio-pro completion zsh > "${fpath[1]}/_app-pilvio-pro"

# You will need to start a new shell for this setup to take effect.

Fish

$ app-pilvio-pro completion fish | source

# To load completions for each session, execute once:
$ app-pilvio-pro completion fish > ~/.config/fish/completions/app-pilvio-pro.fish

PowerShell

PS> app-pilvio-pro completion powershell | Out-String | Invoke-Expression

# To load completions for every new session, run:
PS> app-pilvio-pro completion powershell > app-pilvio-pro.ps1
# and source this file from your PowerShell profile.

Usage

./app-pilvio-pro completion [bash|zsh|fish|powershell]
[...]

Updating the CLI

The CLI checks for the availability of updates automatically and will notify the user if a new version is available:

$ ./app-pilvio-pro version --json

{
"app_name": "app-pilvio-pro",
"branch": "HEAD",
"build_date": "2021-04-15T09:53:58Z",
"build_host": "app-pilvio-pro-builder-mds9t",
"version": {
"cli_version": "0.2.0-dirty",
"api_version": "2021-04-15T09:53:58Z-unknown"
},
"api_hash": "b3086d6d4baa39f55969dda0136f766de7d49a4932f1659bbb04347f6a54dee1",
"default_update_location": "https://app.pilvio.pro/api/1/utilities/cli?platform=windows",
"api_url": "app.pilvio.pro/api/1"
}

Alternatively, there's also an explicit check for the latest version available:

$ ./app-pilvio-pro update show

This command here will perform an update:

$ ./app-pilvio-pro update install

Documentation

The CLI is self-documenting: any app-pilvio-pro command line accepts a --help flag providing information about its arguments and flags.

Automation

To support automation (scripting), app-pilvio-pro command lines accept a --json flag which provides output in JSON format to stdout to ease further processing.

Configuration

To avoid having to specify the authentication token to connect to the app-pilvio-pro API on each command line, the CLI stores this information in a configuration file (default directory on Linux: $HOME/.config/app-pilvio-pro, can be overridden with the --config flag). Modification of the configuration database also happens through the CLI.

Authentication using JWT

Authentication is achieved by using JWT tokens. To access a valid JWT token

Go to the Pilvio.pro portal.
Click APIS in the navigation drawer on the left side of the page.
Click Copy JWT to copy the JWT token, you can also click the downward-facing arrow icon to display the JWT token.

To configure the JWT token in app-pilvio-pro

Linux

$ echo $JWT | ./app-pilvio-pro config auth-token update

Windows

$ .\app-pilvio-pro.exe config auth-token update

The JWT is refreshed automatically behind the scenes when the CLI is in use. Conversely, if the CLI hasn't been used for a while the JWT can expire and a new one needs to be obtained and configured.

Examples

Listing locations

To get a list of the available locations for a customer

Linux

$ ./app-pilvio-pro customers list-customer-locations --customer-id [string]

Payload:
    {
    "currency": "USD",
    "locations": [
        {
        "location": "be-loc-dc01-001",
        "resources": {
            "mu": 0,
            "nu": 0,
            ...
        }
    ]
    }

Windows

$ .\app-pilvio-pro.exe customers list-customer-locations --customer-id [string]

Payload:
    {
    "currency": "USD",
    "locations": [
        {
        "location": "be-loc-dc01-001",
        "resources": {
            "mu": 0,
            "nu": 0,
            ...
        }
    ]
    }

Listing locations using locations list-locations command is only available for Pilvio.pro admins.

Listing customers

Pilvio.pro admins can get a list of all their customers

Linux

$ ./app-pilvio-pro customers list-customers

Payload:
    {
    "result": [
        {
        "customer_id": "customer_1",
        "name": "customer-cloud",
        "contact_name": "test",
        "email": "test@example.com",
        "billable": true,
        "status": "Active",
        "deleted_timestamp": 0,
        "deleted": false
        }
    ]
    }

Windows

$ .\app-pilvio-pro.exe customers list-customers

Payload:
    {
    "result": [
        {
        "customer_id": "customer_1",
        "name": "customer-cloud",
        "contact_name": "test",
        "email": "test@example.com",
        "billable": true,
        "status": "Active",
        "deleted_timestamp": 0,
        "deleted": false
        }
    ]
    }

For an API alternative, you can use GET 'https://app.pilvio.pro/api/1/customers?include_deleted=false&only_deleted=false'. To learn more about API endpoints in Pilvio.pro check API documentation.

Creating cloudspaces

To create a cloudspace

Linux

$ ./app-pilvio-pro customers create-cloudspace --customer-id=<CUSTOMER_ID> --payload.name=<CLOUDSPACE_NAME> --payload.location=<LOCATION_NAME> --payload.firewall.private=true

Payload:
    {
    "cloudspaceid": YmUtZzgtMzozODA1Ng
    }

Windows

$ .\app-pilvio-pro.exe customers create-cloudspace --customer-id=<CUSTOMER_ID> --payload.name=<CLOUDSPACE_NAME> --payload.location=<LOCATION_NAME> --payload.firewall.private=true

Payload:
    {
    "cloudspaceid": YmUtZzgtMzozODA1Ng
    }

Arguments

CUSTOMER_ID: Replace this argument with your customer ID.
CLOUDSPACE_NAME: Specify the name you want to give your new cloudspace.
LOCATION_NAME: Specify the location you want to associate your cloudspace with.

payload.firewall.private=true sets the new cloudspace as a private cloudspace.

Result

The new Cloudspace ID is returned.

Creating VMs

To create a virtual machine

Linux

$ ./app-pilvio-pro customers create-virtual-machine --cloudspace-id=<CLOUDSPACE_ID> --customer-id=<CUSTOMER_ID> --disk-size 8192 --memory 1024 --vcpus 1 --name f_Vm --description "linux vm" --os-type Linux --timeout=2m --os-name "Ubuntu server 16.04"

Windows

$ .\app-pilvio-pro.exe customers create-virtual-machine --cloudspace-id=<CLOUDSPACE_ID> --customer-id=<CUSTOMER_ID> --disk-size 8192 --memory 1024 --vcpus 1 --name f_Vm --description "linux vm" --os-type Linux --timeout=2m --os-name "Ubuntu server 16.04"

The API call will return the ID of the created VM

    Payload:
        {
        "vmid": 59106
        }

Arguments

CUSTOMER_ID: Replace this argument with your customer ID.
CLOUDSPACE_ID: Specify the ID of the cloudspace you want the new virtual machine to belong to.
Specify the rest of the configurations you need for the new virtual machine.

Result

The new virtual machine ID is returned.

Note: The timeout is increased to 2 minutes (where the default value is 30 sec) as this operation might take a while.

Listing VMs

To list the virtual machines in a certain cloudspace

Linux

$ ./app-pilvio-pro customers list-cloudspace-virtual-machines --customer-id=<CUSTOMER_ID> --cloudspace-id=<CLOUDSPACE_ID>

Windows

$ .\app-pilvio-pro.exe customers list-cloudspace-virtual-machines --customer-id=<CUSTOMER_ID> --cloudspace-id=<CLOUDSPACE_ID>

    Payload:
      result:
      - appliance: false
        creationtime: 1.619083789e+09
        disks:
        - 81165
        imageid: 8053
        memory: 1024
        name: f_Vm
        networkinterfaces:
        - devicename: ve6e2-10296
          ipaddress: [192.168.103.254]
            macaddress: 52:54:00:00:ee:ee
            networkid: 66198
          referenceid: 9ddab987-c8d7-42d6-83fe-e99d164ebc22
          stackid: 0
          status: HALTED
          storage: 8192
          updatetime: 1.61908379e+09
          vcpus: 1
          vmid: 59106

Arguments

CUSTOMER_ID: Replace this argument with your customer ID.
CLOUDSPACE_ID: Specify the cloudspace ID.

Result

A list of the virtual machines and their properties is returned.

Deleting VMs

To delete a virtual machine

Linux

$ ./app-pilvio-pro customers delete-virtual-machine --customer-id=<CUSTOMER_ID> --cloudspace-id=<CLOUDSPACE_ID> --vmid=<VM_ID>

Windows

$ .\app-pilvio-pro.exe customers delete-virtual-machine --customer-id=<CUSTOMER_ID> --cloudspace-id=<CLOUDSPACE_ID> --vmid=<VM_ID>

Arguments

CUSTOMER_ID: Replace this argument with your customer ID.
CLOUDSPACE_ID: Specify the cloudspace ID.
VM_ID: Replace this argument with the ID of the virtual machine you want to delete.

Result

The specified virtual machine is deleted.