Skip to main content

Civo CLI

Overview

The Civo CLI is a command-line interface that allows you to create, manage and delete resources such as Kubernetes clusters and instances through the Civo API programmatically through your terminal. The Civo web dashboard has a user-friendly interface for managing your account, and if you want to automate or run scripts on your account, or have multiple complex services, the command-line interface outlined here will be useful.

Civo CLI is open-source.

Installation

The quickest way to get the latest release of Civo CLI is to run the installation script:

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

MacOS Homebrew

On a Mac, Civo CLI can be installed using the brew package manager:

brew tap civo/tools
brew install civo

You should then be able to run civo and receive the initial help message and continue to the Setting up section below.

Windows

Civo CLI is available to download on Windows via Chocolatey and Scoop.

For installing via the Chocolatey package manager, run the following command:

choco install civo-cli

For installing via Scoop, you will need to first add the extras bucket and then install the CLI itself:

scoop bucket add extras
scoop install civo

You should then be able to run civo and receive the initial help message and continue to the Setting up section below.

Linux

On Linux, Civo CLI can be installed by various methods.

If you use the brew package manager, you can use it as shown in the MacOS section above.

You can also install by downloading the specific release version (detailed on the GitHub releases page) using wget:

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/

Or you can build the CLI from the original source if 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"

Setting up

Add an API key to Civo CLI

You will need to associate an API key from your account to Civo CLI in order to authenticate you to the Civo API. You can do this by running the command civo apikey save. The command will prompt you for a memorable name (in this case docs-demo) and to paste in the API key of your choice. This will not be displayed for security reasons.

$ civo apikey save
Enter a nice name for this account/API Key: docs-demo
Enter the API key:
Saved the API Key docs-demo

Set your current region

Civo operates multiple regions. To avoid having to specify the region you want each time, you can set the current region to match the one you most commonly work in.

You can choose your region from the listing of the available regions:

civo region ls

You can then set the current region to that of your choice by specifying the code of the region in the command:

$ civo region use LON1
The default region was set to (London 1) LON1

You can now use the CLI to create and manage Civo resources. See resource-specific documentation for specific guidance.

To find the full list of available commands, run civo help or a specific subcommand without an operation, such as civo kubernetes. This will output command-specific options.

Updating

Civo CLI is under active development. You can update the version of Civo CLI you are running with the civo update command:

$ civo update
[================================================] 100%
Updated to v1.0.40

Commands and help

The categories of commands available on Civo CLI are listed by running civo:

$ civo
civo is a CLI library for managing cloud resources such
as instances and Kubernetes clusters at Civo.com.

Usage:
civo [flags]
civo [command]

Available Commands:
apikey Manage API keys used to access your Civo account
completion Generates bash completion scripts
database Manage Civo Database
diskimage Details of Civo disk images
domain Details of Civo domains
firewall Details of Civo firewalls
help Help about any command
instance Details of Civo instances
ip Details of Civo reserved IPs
kfcluster Manage Civo Kubeflow Clusters
kubernetes Details of Civo Kubernetes clusters
loadbalancer Details of Civo Load Balancer
network Details of Civo networks
objectstore Civo Object Store/Bucket management commands
permissions List available permissions
quota Show quota
region Details of Civo regions
size Details of Civo instance sizes
sshkey Details of Civo SSH keys
teams Manage teams in Civo
update Update the cli to the last version
version Version will output the current build information
volume Details of Civo volumes

Flags:
--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
-v, --version Print the version of the CLI
-y, --yes Automatic yes to prompts; assume "yes" as answer to all prompts and run non-interactively

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

You can also get help for a command by running civo [command] --help. This works for all command categories and subcommands, e.g.:

$ civo kubernetes create --help
Create a new Kubernetes cluster

Usage:
civo kubernetes create [flags]

Aliases:
create, new, add

Examples:
civo kubernetes create CLUSTER_NAME [flags]

Notes:
* The '--create-firewall' will open the ports 80,443 and 6443 in the firewall if '--firewall-rules' is not used.
* The '--create-firewall' and '--existing-firewall' flags are mutually exclusive. You can't use them together.
* The '--firewall-rules' flag need to be used with '--create-firewall'.
* The '--firewall-rules' flag can accept:
* You can pass 'all' to open all ports.
* An optional end port using 'start_port-end_port' format (e.g. 8000-8100)
* An optional CIDR notation (e.g. 0.0.0.0/0)
* When no CIDR notation is provided, the port will get 0.0.0.0/0 (open to public) as default CIDR notation
* When a CIDR notation is provided without slash and number segment, it will default to /32
* Within a rule, you can use comma separator for multiple ports to have same CIDR notation
* To separate between rules, you can use semicolon symbol and wrap everything in double quotes (see below)
So the following would all be valid:
* "80,443,6443:0.0.0.0/0;8080:1.2.3.4" (open 80,443,6443 to public and 8080 just for 1.2.3.4/32)
* "80,443,6443;6000-6500:4.4.4.4/24" (open 80,443,6443 to public and 6000 to 6500 just for 4.4.4.4/24)


Flags:
-a, --applications string optional, use names shown by running 'civo kubernetes applications ls'
--cluster-type string optional, possible options: k3s,talos. (default "k3s")
-p, --cni-plugin string optional, possible options: flannel,cilium. (default "flannel")
-c, --create-firewall optional, create a firewall for the cluster with all open ports
-e, --existing-firewall string optional, ID of existing firewall to use
-u, --firewall-rules string optional, can be used if the --create-firewall flag is set, semicolon-separated list of ports to open (default "default")
-h, --help help for create
-m, --merge merge the config with existing kubeconfig if it already exists.
-t, --network string the name of the network to use in the creation (default "default")
-n, --nodes int the number of nodes to create (the master also acts as a node). (default 3)
-r, --remove-applications string optional, remove default application names shown by running 'civo kubernetes applications ls'
--save save the config
-s, --size civo size list -s kubernetes the size of nodes to create. You can list available kubernetes sizes by civo size list -s kubernetes (default "g4s.kube.medium")
--switch switch context to newly-created cluster
-v, --version string the k3s version to use on the cluster. Defaults to the latest. Example - 'civo k3s create --version 1.21.2+k3s1' (default "latest")
-w, --wait a simple flag (e.g. --wait) that will cause the CLI to spin and wait for the cluster to be ACTIVE

Global Flags:
--config string config file (default is $HOME/.civo.json)
-f, --fields string output fields for custom format output (use -h to determine fields)
-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-interactively