Civo Command-Line Client

Introduction

Civo CLI is a tool to manage your Civo.com account from the terminal. The Civo web control panel has a user-friendly interface for managing your account, but in case you want to automate or run scripts on your account, or have multiple complex services, the command-line interface outlined here will be useful. This guide will cover the set-up and usage of the Civo CLI tool with examples.

STATUS: This project is currently under active development and maintenance.

Table of contents

• Introduction
• Global Options
• Set-Up
• Version/Updating CLI
• Docker Usage
• API Keys
• Instances
• Kubernetes clusters
• Kubernetes applications
• Domains and Domain Records
• Firewalls
• Networks
• Database Backup and Restore
• Object Stores
• Object Store Credentials
• Load Balancers
• Quota
• Sizes
• SSH Keys
• Disk Images
• Volumes
• Resource Snapshots
• Teams
• Permissions
• Region
• Enabling shell autocompletion
• Contributing
• License

Set-up

Civo CLI is built with Go and distributed as binary files, available for multiple operating systems and downloadable from https://github.com/civo/cli/releases.

Installing on macOS

If you have a Mac, you can install it using Homebrew:

brew tap civo/tools
brew install civo

or if you prefer you can run this in the console:

curl -sL https://civo.com/get | sh

Installing on Windows

Civo CLI is available to download on windows via Chocolatey and Scoop

For installing via Chocolatey you need Chocolatey package manager installed on your PC.

• run the following command after confirming Chocolatey on your PC

choco install civo-cli

and it will install Civo CLI on your PC.

For installing via Scoop you need Scoop installed as a package manager, then:

• add the extras bucket with

scoop bucket add extras

• install civo with

scoop install civo

You will also, of course, need a Civo account, for which you can register here.

Installing on Linux

For Linux Civo CLI can be installed by various methods.

• Install via the direct shell script:

curl -sL https://civo.com/get | sh

• Install via the brew package manager, as shown in the above instructions for MacOS.

• Install via wget, specifying the release version you want.

Note that the version in the example below may not be the latest. Specify the version based on the latest available if you are using this method.

wget https://github.com/civo/cli/releases/download/v1.0.40/civo-1.0.40-linux-amd64.tar.gz
tar -xvf civo-1.0.40-linux-amd64.tar.gz
chmod +x civo
mv ./civo /usr/local/bin/

• You can also build the binary, but make sure you have go installed,

git clone https://github.com/civo/cli.git
cd cli
make
cd ..
cp -r cli $HOME
export PATH="$HOME/cli:$PATH"

With this, we have installed the Civo CLI successfully. Check it is working by running any of the following commands.

Note: For the first time when you are running, make sure you set your current region. Check Region for more information.

Running the Civo CLI tool and getting help

To use the tool, simply run civo with your chosen options. You can find context-sensitive help for commands and their options by invoking the help or -h command: civo help, civo instance help, civo instance create help and so on. The main components of Civo CLI are outlined in the following sections.

Version/Updating CLI

Every user receives a reminder to update the CLI once in 24 hours as well as notified to update the CLI version in case of any error. Run civo update to update the CLI to the latest version.

Docker Usage

Civo's CLI utility can also run within a Docker container, if you prefer to keep your base OS clean.

To run, you generally will want to map the API key for persistence.

touch $HOME/.civo.json
docker run -it --rm -v $HOME/.civo.json:/.civo.json civo/cli:latest

You can also use the Kubernetes options of the CLI. Kubectl is included inside our image, to use it you just need to mount the configuration in the container.

touch $HOME/.civo.json
mkdir $HOME/.kube/
touch $HOME/.kube/config
docker run -it --rm -v $HOME/.civo.json:/.civo.json -v $HOME/.kube/config:/root/.kube/config civo/cli:latest

To make usage easier, an alias is recommended. Here's an example how to set one to the same command as would be used if installed directly on the system, and using the Docker image:

Ubuntu etc:

alias civo="docker run -it --rm -v $HOME/.civo.json:/.civo.json civo/cli:latest"
# Maybe put the above line in ~/.bash_profile or ~/.zshrc
civo sshkey list
civo instance list
civo instance create --size g2.xsmall
civo k8s list

For Fedora users:

alias civo="docker run -it --rm -v $HOME/.civo.json:/.civo.json:Z -v $HOME/.kube/config:$HOME/.kube/config:Z civo/cli:latest"

Here's an example how to set an alias and get started with Kubernetes.

alias civo="docker run -it --rm -v $HOME/.civo.json:/.civo.json -v $HOME/.kube/config:$HOME/.kube/config civo/cli:latest"
# Maybe put the above line in ~/.bash_profile or ~/.zshrc
civo sshkey list
civo instance list
civo instance create --size g2.xsmall
civo k8s list

Global Options

The civo cli have multiple global options, that you can use, like this:

      --config string   config file (default is $HOME/.civo.json)
  -f, --fields string   output fields for custom format output (use -h to determine fields)
  -h, --help            help for civo
  -o, --output string   output format (json/human/custom) (default "human")
      --pretty          Print pretty the json output
      --region string   Choose the region to connect to, if you use this option it will use it over the default region
  -y, --yes             Automatic yes to prompts; assume "yes" as answer to all prompts and run non-interactive

API Keys

Introduction

In order to use the command-line tool, you will need to authenticate yourself to the Civo API using a special key. You can find an automatically-generated API key or regenerate a new key at https://www.civo.com/api. The CLI have a global env variable call CIVO_TOKEN if this is set, the CLI will use this token instead of the one in the config file. This is useful for scripting situations or CI/CD pipelines. When you set the CIVO_TOKEN you will see a new apikey entry with the name tempKey in the civo apikey list command.

Adding a current API Key to your account

You can add the API Key to the CLI tool through the API Keys command. civo apikey add apikey_name apikey such as:

$ civo apikey add Demo_Test_Key DAb75oyqVeaE7BI6Aa74FaRSP0E2tMZXkDWLC9wNQdcpGfH51r
  Saved the API Key Demo_Test_Key as DAb75oyqVeaE7BI6Aa74FaRSP0E2tMZXkDWLC9wNQdcpGfH51r

As you can have multiple API keys stored to handle multiple accounts, you will need to tell which key the tool should use to authenticate with civo apikey current [apikey_name]. This sets your chosen API key as the default key to use for any subsequent commands:

$ civo apikey current Demo_Test_Key
  Set the default API Key to be Demo_Test_Key

By default, the Civo account credentials API Key along with other settings like region will be saved in a file called .civo.json in the user home directory. The default location of the file can be changed using the environment variable CIVO_CONFIG.

Managing and listing API keys

You can list all stored API keys in your configuration by invoking civo apikey list or remove one by name by using civo apikey remove apikey_name.

To see the secret key you can use civo apikey show which will show only the default key, to see others just use civo apikey show NAME

civo apikey list
+--------------+---------+
| Name         | Default |
+--------------+---------+
| my_username  | <=====  |
+--------------+---------+

civo apikey show my_username
+-------------+------------+
| Name        | Key        |
+-------------+------------+
| my_username | secret_key |
+-------------+------------+

Instances

Introduction

An instance is a virtual server running on the Civo cloud platform. They can be of variable size and you can run any number of them up to your quota on your account.

Creating an instance

You can create an instance by running civo instance create with a hostname parameter, as well as any options you provide:

Options:
  -t, --diskimage string     the instance's disk image name (from 'civo diskimage ls' command)
  -l, --firewall string      the instance's firewall you can use the Name or the ID
  -h, --help                 help for create
  -s, --hostname string      the instance's hostname
  -u, --initialuser string   the instance's initial user
  -r, --network string       the instance's network you can use the Name or the ID
  -p, --publicip string      This should be either "none" or "create" (default "create")
  -i, --size string          the instance's size (from 'civo instance size' command)
  -k, --sshkey string        the instance's ssh key you can use the Name or the ID
  -g, --tags string          the instance's tags
  -w, --wait                 wait until the instance's is ready
  --allowe