We wrote our hosting platform to have an expansive yet easy to use API, and we use this API from within the Civo.com website. This brings the benefit of being able to write other clients to manage your instances, networks, firewalls, etc from maybe a mobile app, your own custom scripts or in this case from the terminal in Linux or MacOS.

Installation

Download the latest release from Absolute Devops' GitHub page and unzip it at the command line. We'll use release v0.11.0 in this guide, but the same instructions should apply to all future releases.

wget -c https://github.com/absolutedevops/civo/releases/download/v0.11.0/civo-v0.11.0.zip
unzip civo-v0.11.0.zip

You then need to move the binary for your choice of platform to somewhere on your path. Assuming that echo $PATH shows /usr/local/bin we'll put it in there and make it executable:

mv macos/civo /usr/local/bin/
chmod +x /usr/local/bin/macos

At this point we can verify it works by running:

Version 0.11.0 of the Civo command line client for interacting with the Civo API for cloud instances.

Usage:
  civo [command]

Available Commands:
  apikey      List all API Keys
  domain      List all DNS domains
  firewall    List all firewalls
  help        Help about any command
  instance    List all instances
  network     List all networks
  quota       List the current account apikey's quota
  region      List regions
  size        List sizes
  snapshot    List all snapshots
  sshkey      List uploaded SSH keys
  template    List all templates

Use "civo [command] --help" for more information about a command.

Connecting to your account

The first thing you need to do is connect your CLI client to your Civo.com account. The way you do this is through the API keys command. This holds true for all commands, but to get documentation for a command (from the list shown above) you just run the command with --help at the end. For example:

$ civo apikey --help
List the API Keys you've saved for accessing the Civo API

Usage:
  civo apikey [flags]
  civo apikey [command]

Aliases:
  apikey, apikeys


Available Commands:
  current     Change your current API Key
  remove      Remove an API Key
  save        Save an API Key

Use "civo apikey [command] --help" for more information about a command.

So this shows you without any subcommands you can just run it to list the API keys you've saved. Let's try that:

$ civo apikey
+------+---------+---------+
| Name | API Key | Current |
+------+---------+---------+
+------+---------+---------+

To connect your account you need to save an API key for the command line client to use. To do this, first get your API key by visiting our API Documentation and save it to the client using the civo apikey save command:

$ civo apikey save --help
When you've been given an API key for use against a Civo cloud API, you can save the API Key here to be able to use it within this client

Usage:
  civo apikey save [flags]

Aliases:
  save, register, store


Flags:
  -k, --key string    The API key supplied for use against a Civo cloud
  -n, --name string   The name to use for this API Key (can be an abbreviation)
$ civo apikey save --key ABCDEF0123456789ABCDEF0123456789 --name example
Saved API Key example and set it as the default API Key because it's your first API Key
$ civo apikeys
+---------+----------------------------------+---------+
|  Name   |            API Key               | Current |
+---------+----------------------------------+---------+
| example | ABCDEF0123456789ABCDEF0123456789 | <=====  |
+---------+----------------------------------+---------+

Listing, creating and deleting instances

You can probably guess how to look up the help for the instances command now, but let's just do it again (for the future commands I won't keep showing the output of help, I'll leave that as an exercise for the reader):

$ civo instances --help
List the instances for the current account

Usage:
  civo instance [flags]
  civo instance [command]

Aliases:
  instance, instances


Available Commands:
  create      Create a new instance
  destroy     Destroy an instance
  firewall    Firewall an instance
  reboot      Reboot an instance
  rebuild     Rebuild an instance
  restore     Restore an instance
  tags        Re-tag an instance
  upgrade     Upgrade an instance

Flags:
  -f, --full-ids      Return full IDs for instances
  -t, --tags string   Only return instances with these tags (AND not OR)

Use "civo instance [command] --help" for more information about a command.

So we have a create command which will launch a new instance for us. The --help command lists the flags we can pass in:

  -f, --firewall string       The firewall ID or name from 'civo firewalls' (default "default")
  -u, --initial-user string   The default user to create (default "civo")
  -n, --name string           Name of the instance; lowercase, hyphen separated. If you don't specify one, a random one will be used.
  -w, --network string        The network ID or name from 'civo networks' (default "Default")
  -p, --public-ip             Should a public IP address be allocated (default true)
  -r, --region string         The region from 'civo regions'
  -s, --size string           The size from 'civo sizes' (default "g1.small")
  -k, --ssh-key-id string     The SSH key ID from 'civo sshkeys' (default "default")
  -g, --tags string           A space-separated list of tags to use
  -t, --template string       The template from 'civo templates' (default "ubuntu-16.04")

These parameters are hopefully obvious, and they explain where to get the values from ifyou don't know them. It also gives you an example of how to create an instance. The simplest thing we can do to run an instance is:

$ civo instance create --name test1.example.com --network 35e293ed-0a41-46e7-82f1-ba41c0c83cd8

In the future it will automatically choose your default network, but for now you must specify a network ID from civo networks --full-ids (we've used a dummy 35e293ed-0a41-46e7-82f1-ba41c0c83cd8).

You can check on the status with:

$ civo instances
+----------+-------------------+----------+--------------+--------------+----------+------+------------------+----------+------+
|    ID    |       Name        |   Size   |   Template   | IP Addresses |  Status  | User |     Password     | Firewall | Tags |
+----------+-------------------+----------+--------------+--------------+----------+------+------------------+----------+------+
| 71ab9e07 | test1.example.com | g1.small | ubuntu-16.04 |              | BUILDING | civo | PASSWORD_HERE    | default  |      |
+----------+-------------------+----------+--------------+--------------+----------+------+------------------+----------+------+

And eventually it will change to ACTIVE and list the public IP address. You can then connect with the username and password shown (as we didn't specify an SSH key).

To destroy the instance you can just call:

$ civo instances destroy --id=71ab9e07
Destroying instance with ID 71ab9e07-4d5d-4df5-6772-95f51f3ecfcd

An extra neat tip

Rather than take you through the rest of the CLI, I thought I'd use the last minute I have of writing time to describe something cool.

If you wanted to launch 10 machines all with the same software installed on them, how would you do it? Manually SSHiing into each server, copying and pasting commands is the wrong answer, by the way. The best ways would probably involve Chef, Ansible or Puppet (or something similar). However, there's another way.

You can create custom private templates in Civo using the civo template set of commands. One of the parameters to that is --cloud-init-file which you can use to uplaod a cloud-init file to configure the instance on first boot. I'll leave it as an exercise (for now) on how to do this, but as another tip, you'll need a base OS --image-id as well for your custom template, you need to find them from another call...