PLEASE NOTE: We have updated the tool and API, and consequently this article is now out of date. Please see this see this guide for the current version of the CLI.
-----------------------------------------------------------------------
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 Civo's 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...
