GIG CLI Quickstart Guide

You are here:
< All Topics


The gig tool allows you to manage resources (such as VMs and vdisks) in a G8 on the command line. It is available for Linux, Windows and OS X operating systems (x86-64 only). To achieve support for multiple platforms it consists of a platform specific frontend binary that drives a backend in a Docker container, so a working Docker installation is prerequisite to using the gig CLI. Please refer to for more information on how to install Docker on your platform.


First Installation

Download the latest zip archive for your platform. Unpacking the archive will yield the gig binary (NB: gig.exe on Windows). Example for Linux:

$ wget -q
$ unzip  
  inflating: gig

Download Locations


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

$ ./gig version --json
time=2020-05-07T12:55:17+02:00 level=info msg=checking \\ for updates
time=2020-05-07T12:55:17+02:00 level=info msg=fetching
time=2020-05-07T12:55:18+02:00 level=info msg=local version: 0.0.8, remote version: 0.0.9
a more recent version 0.0.9 is available - run gig update install [VERSION] to update
    "app_name": "gig",
    "branch": "HEAD",
    "date": "2020-03-10T14:37:56Z",
    "host": "9220ad80ceb7",
    "version": "0.0.8",
    "default_docker_image": "gigtech/gig-cli:0.0.8",
    "default_update_location": "

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

$ ./gig update show
time=2020-05-07T12:56:59+02:00 level=info msg=fetching

Note that your version might be different from the version above

The gig update install command will perform an update:

$ ./gig update install 0.0.9
time=2020-05-07T12:57:08+02:00 level=info msg=fetching
time=2020-05-07T12:57:09+02:00 level=info msg=fetching archive -> /tmp/, digest 312a5a0065e90a98721ef13f31f8f9c6f5d8046e2ccc512f538988e2a2a6908a
time=2020-05-07T12:57:09+02:00 level=info msg=fetching
time=2020-05-07T12:57:11+02:00 level=info msg=downloaded and verified
time=2020-05-07T12:57:11+02:00 level=info msg=renaming old binary /tmp/linux/gig -> /tmp/linux/gig.bak
time=2020-05-07T12:57:11+02:00 level=info msg=renaming new binary /tmp/gig.209547419 -> /tmp/linux/gig
time=2020-05-07T12:57:11+02:00 level=info msg=removing old binary /tmp/linux/gig.bak
old version: 0.0.8, new version: 0.0.9


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


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


To avoid having to specify the address and credentials for a G8 on each command line, the CLI stores this information in a configuration file (default directory on Linux: $HOME/.config/gig, can be overridden with the --config flag). First, the credentials to be used with a G8 have to be added:


$ ./gig config credentials add <NAME OF CREDENTIALS>  <USER ID> <SECRET>


NAME OF CREDENTIALS: This could be any name for your credentials. Will be used as a reference to your key and secret of this specific configuration. Example: my-demo-creds
USER ID: This is your Client ID which can be retrieved from account settings. Example: SBvtarbgRzPBpsNqeVNbgRe9-_Lg
SECRET: This is your secret which can be retrieved from account settings. Example: UU3JKQxl8B3k97ZAUGha-3k97an

Shell Tip: use -- before USER ID and SECRET if either begin with "-". This will tell the shell to interpret the - as part of the string and not a flag for the cli tool

Example command
$ ./gig config credentials add my-demo-creds -- "-CvtarbgRzPBpsNqeVNbgRe9-_Lg" "UU3JKQxl8B3k97ZAUGha-3k97an"

These credentials are used to fetch JWTs from which are then used for authentication with the G8.
Once the credentials are added, the G8 environment can be configured:


$ ./gig config environment add <NAME OF YOUR G8> <G8 URL> <CREDENTIALS>


NAME OF YOUR G8: This can be any name of your choice to reference your G8 in your commands. Example: my-g8
G8 URL: Url of your G8. Example:
CREDENTIALS: This is one of your credentials you have added in the previous step. Example: my-demo-creds

Example command
$ ./gig config environment add my-g8  my-demo-creds


Certain jobs such as a VM import can take a long time and might leave resources in an incomplete state, e.g. if the client machine is powercycled during a VM import. To address these problems, the CLI uses the concept of a task: tasks that previously did not finish can either be aborted (NB: not while a task is still running!) or, if supported by the task (such as the VM import), be resumed. tasks that did not run to completion can be inspected:


$ ./gig task show --json
    task_id: e23eca4e-1b44-4cd5-abfe-50ab6f53f6e4,
    date: 2020-03-24T15:27:14.590751203+01:00,


It can then be aborted (= any resources created in the G8 will be cleaned up) or resumed using the task_id:

./gig task abort e23eca4e-1b44-4cd5-abfe-50ab6f53f6e4 

Importing VMs

The gig tool allows to import VM images that were exported to the the Open Virtualization Format (OVF) into a cloudspace in a G8:


./gig import vm <NAME OF YOUR G8> <ACCOUNT>  <CLOUDSPACE> <path/to/your/ova/file> --image-type <TYPE> --memory <MEMORY SIZE> --vcpus <VCPUs> --json


NAME OF YOUR G8: Name of an already added G8 via the config environment command explained earlier. Example: my-g8
ACCOUNT: name of an account that already exists on your G8 to be used in the creation of the VM. Example: my-account
CLOUDSPACE: name of an existing cloudspace on your G8. This is where gigcli will create your VM. Example: my-cloudspace
TYPE: Type of your image used for the VM. Has to be either Linux, Unix, BSD, Windows, Darwin or Other. (Required for versions 0.0.12 and later)
MEMORY SIZE: Memory size of your VM in MiB. (Optional)
VCPUs: Number of vcpus for your VM. (Optional)

Example command
$ ./gig import vm ch-g8  "my-account" my-cloudspace ~/Downloads/myvm.ova --image-type Linux --memory 64 --vcpus 1 --json

Individual settings such as VM name, memory, number of CPUs can be overridden via command line flags.

Table of Contents