gem-hunter
Language: Go
Our Command Line Interface (CLI) for interacting with your Civo resources
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.
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.
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 | shCivo CLI is available to download on windows via Chocolatey and Scoop
For installing via Chocolatey you need Chocolatey package manager installed 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:
scoop bucket add extras
scoop install civo
You will also, of course, need a Civo account, for which you can register here.
For Linux Civo CLI can be installed by various methods.
curl -sL https://civo.com/get | shInstall 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/
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.
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.
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.
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
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
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.
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.
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 | +-------------+------------+
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.
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 --allowed-ips <ip1,ip2,...> Specifies a comma-separated list of IP addresses that the instance is allowed to use (for IP/MAC spoofing protection, the allowed_ips need to be within the network subnet that the instance is attached to). --network-bandwidth-limit <limit_mbps> Sets the network bandwidth limit for the instance in Mbps. Use 0 for unlimited.
Example usage:
$ civo instance create --hostname=api-demo.test --size g4s.small --diskimage=ubuntu-noble --initialuser=demo-user --allowed-ips 192.168.1.100,192.168.1.101 --network-bandwidth-limit 100
The instance api-demo.test has been created
$ civo instance show api-demo.test
ID : 112f2407-fb89-443e-bd0e-5ddabc4682c6
Hostname : api-demo.test
Status : ACTIVE
Size : g4s.small
Cpu Cores : 1
Ram : 2048
SSD disk : 25
Region : LON1
Network ID : 28244c7d-b1b9-48cf-9727-aebb3493aaac
Disk image ID : ubuntu-noble
Snapshot ID :
Initial User : demo-user
Initial Password : demo-user
SSH Key :
Firewall ID : c9e14ae8-b8eb-4bae-a687-9da4637233da
Tags :
Created At : Mon, 01 Jan 0001 00:00:00 UTC # Note: This is a placeholder date
Private IP : 192.168.1.7
Public IP : 74.220.21.246
Allowed IPs : 192.168.1.100, 192.168.1.101
Network Bandwidth Limit : 100 Mbps
----------------------------- NOTES -----------------------------You will be able to see the instance's details by running civo instance show api-demo.test as above.
The civo instance show command displays detailed information about a specific instance.
Usage:
civo instance show <INSTANCE_ID_OR_HOSTNAME>
If you wish to use a custom format, the available fields are:
* id
* hostname
* status
* size
* cpu_cores
* ram_mb
* disk_gb
* region
* network_id
* diskimage_id
* initial_user
* initial_password
* ssh_key
* firewall_id
* tags
* created_at
* private_ip
* public_ip
* notes
* script
* reverse_dns
* allowed_ips
* network_bandwidth_limit
The output for civo instance show now includes:
You can view the Disk images by running civo diskimage ls
$ civo diskimage ls +--------------------------------------+----------------------+----------------+-----------+--------------+ | ID | Name | Version | State | Distribution | +--------------------------------------+----------------------+----------------+-----------+--------------+ | a4204155-a876-43fa-b4d6-ea2af8774560 | debian-10 | 10 | available | debian | +--------------------------------------+----------------------+----------------+-----------+--------------+ | 25fbbd96-d5ec-4d08-9c75-a5e154dabf9b | debian-11 | 11 | available | debian | +--------------------------------------+----------------------+----------------+-----------+--------------+ | 887f05e7-e3b0-49b5-9ab9-6f35848e1e56 | debian-12 | 12 | available | debian | +--------------------------------------+----------------------+----------------+-----------+--------------+ | 9b661c46-ac4f-46e1-9f3d-aaacde9b4fec | debian-9 | 9 | available | debian | +--------------------------------------+----------------------+----------------+-----------+--------------+ | d0e47b5e-b9af-4386-9902-2ded1018dd29 | rocky-10 | 10 | available | rocky | +--------------------------------------+----------------------+----------------+-----------+--------------+ | d052a966-385d-4018-931e-3637fe97cd13 | rocky-9 | 9 | available | rocky | +--------------------------------------+----------------------+----------------+-----------+--------------+ | 170db96f-8458-44aa-83ca-0c31fb81a835 | rocky-9-1 | 9.1 | available | rocky | +--------------------------------------+----------------------+----------------+-----------+--------------+ | 21613daa-a66b-44fc-87f5-b6db566d8f91 | ubuntu-cuda11-8 | 22.04-cuda11-8 | available | ubuntu | +--------------------------------------+----------------------+----------------+-----------+--------------+ | 13232803-0928-4634-9ab8-476bff29ef1b | ubuntu-cuda12-2 | 22.04-cuda12-2 | available | ubuntu | +--------------------------------------+----------------------+----------------+-----------+--------------+ | ece39039-56ac-4bf6-8b39-78bd895d8385 | ubuntu-cuda12-6 | 24.04-cuda12-6 | available | ubuntu | +--------------------------------------+----------------------+----------------+-----------+--------------+ | 8d7e4997-f97d-43c8-9936-8329bbbcc6cf | ubuntu-cuda12-8 | 24.04-cuda12-8 | available | ubuntu | +--------------------------------------+----------------------+----------------+-----------+--------------+ | 0b346fc3-2d7e-4be7-8881-34787417f7ff | ubuntu-cuda12-9 | 24.04-cuda12-9 | available | ubuntu | +--------------------------------------+----------------------+----------------+-----------+--------------+ | d927ad2f-5073-4ed6-b2eb-b8e61aef29a8 | ubuntu-focal | 20.04 | available | ubuntu | +--------------------------------------+----------------------+----------------+-----------+--------------+ | eda67ea0-4282-4945-9b7b-d3e1cba1d987 | ubuntu-jammy | 22.04 | available | ubuntu | +--------------------------------------+----------------------+----------------+-----------+--------------+ | d2c2c728-512d-4087-906a-8486fcf4a1c7 | ubuntu-noble | 24.04 | available | ubuntu | +--------------------------------------+----------------------+----------------+-----------+--------------+
You can view the instance sizes list by running civo size ls
$ civo size ls +--------------------+--------------------------------+------------+-----+---------+-----+ | Name | Description | Type | CPU | RAM | SSD | +--------------------+--------------------------------+------------+-----+---------+-----+ | g3.xsmall | Extra Small | Instance | 1 | 1024 | 25 | +--------------------+--------------------------------+------------+-----+---------+-----+ | g3.small | Small | Instance | 1 | 2048 | 25 | +--------------------+--------------------------------+------------+-----+---------+-----+ | g3.medium | Medium | Instance | 2 | 4096 | 50 | +--------------------+--------------------------------+------------+-----+---------+-----+ | g3.large | Large | Instance | 4 | 8192 | 100 | +--------------------+--------------------------------+------------+-----+---------+-----+ | g3.xlarge | Extra Large | Instance | 6 | 16384 | 150 | +--------------------+--------------------------------+------------+-----+---------+-----+ | g3.2xlarge | 2X Large | Instance | 8 | 32768 | 200 | +--------------------+--------------------------------+------------+-----+---------+-----+ | g4s.kube.xsmall | Extra Small - Standard | Kubernetes | 1 | 1024 | 30 | +--------------------+--------------------------------+------------+-----+---------+-----+ | g4s.kube.small | Small - Standard | Kubernetes | 1 | 2048 | 40 | +--------------------+--------------------------------+------------+-----+---------+-----+ | g4s.kube.medium | Medium - Standard | Kubernetes | 2 | 4096 | 50 | +--------------------+--------------------------------+------------+-----+---------+-----+ | g4s.kube.large | Large - Standard | Kubernetes | 4 | 8192 | 60 | +--------------------+--------------------------------+------------+-----+---------+-----+ | g4p.kube.small | Small - Performance | Kubernetes | 4 | 16384 | 60 | +--------------------+--------------------------------+------------+-----+---------+-----+ | g4p.kube.medium | Medium - Performance | Kubernetes | 8 | 32768 | 80 | +--------------------+--------------------------------+------------+-----+---------+-----+ | g4p.kube.large | Large - Performance | Kubernetes | 16 | 65536 | 120 | +--------------------+--------------------------------+------------+-----+---------+-----+ | g4p.kube.xlarge | Extra Large - Performance | Kubernetes | 32 | 131072 | 180 | +--------------------+--------------------------------+------------+-----+---------+-----+ | g4c.kube.small | Small - CPU optimized | Kubernetes | 8 | 16384 | 60 | +--------------------+--------------------------------+------------+-----+---------+-----+ | g4c.kube.medium | Medium - CPU optimized | Kubernetes | 16 | 32768 | 80 | +--------------------+--------------------------------+------------+-----+---------+-----+ | g4c.kube.large | Large - CPU optimized | Kubernetes | 32 | 65536 | 120 | +--------------------+--------------------------------+------------+-----+---------+-----+ | g4c.kube.xlarge | Extra Large - CPU optimized | Kubernetes | 64 | 131072 | 180 | +--------------------+--------------------------------+------------+-----+---------+-----+ | g4m.kube.small | Small - RAM optimized | Kubernetes | 2 | 16384 | 60 | +--------------------+--------------------------------+------------+-----+---------+-----+ | g4m.kube.medium | Medium - RAM optimized | Kubernetes | 4 | 32768 | 80 | +--------------------+--------------------------------+------------+-----+---------+-----+ | g4m.kube.large | Large - RAM optimized | Kubernetes | 8 | 65536 | 120 | +--------------------+--------------------------------+------------+-----+---------+-----+ | g4m.kube.xlarge | Extra Large - RAM optimized | Kubernetes | 16 | 131072 | 180 | +--------------------+--------------------------------+------------+-----+---------+-----+ | g3.db.xsmall | Extra Small | Database | 1 | 2048 | 20 | +--------------------+--------------------------------+------------+-----+---------+-----+ | g3.db.small | Small | Database | 2 | 4096 | 40 | +--------------------+--------------------------------+------------+-----+---------+-----+ | g3.db.medium | Medium | Database | 4 | 8192 | 80 | +--------------------+--------------------------------+------------+-----+---------+-----+ | g3.db.large | Large | Database | 6 | 16384 | 160 | +--------------------+--------------------------------+------------+-----+---------+-----+ | g3.db.xlarge | Extra Large | Database | 8 | 32768 | 320 | +--------------------+--------------------------------+------------+-----+---------+-----+ | g3.db.2xlarge | Double Extra Large | Database | 10 | 65536 | 640 | +--------------------+--------------------------------+------------+-----+---------+-----+ | g3.kf.small | Small - CPU optimized | KfCluster | 4 | 16384 | 60 | +--------------------+--------------------------------+------------+-----+---------+-----+ | g3.kf.medium | Medium - CPU optimized | KfCluster | 8 | 32768 | 80 | +--------------------+--------------------------------+------------+-----+---------+-----+ | g3.kf.large | Large - CPU optimized | KfCluster | 16 | 65536 | 120 | +--------------------+--------------------------------+------------+-----+---------+-----+ | g3.kf.xlarge | Extra Large - CPU optimized | KfCluster | 32 | 131072 | 180 | +--------------------+--------------------------------+------------+-----+---------+-----+ | g4s.xsmall | xSmall - Standard | Instance | 1 | 1024 | 25 | +--------------------+--------------------------------+------------+-----+---------+-----+ | g4s.small | Small - Standard | Instance | 1 | 2048 | 25 | +--------------------+--------------------------------+------------+-----+---------+-----+ | g4s.medium | Medium - Standard | Instance | 2 | 4096 | 50 | +--------------------+--------------------------------+------------+-----+---------+-----+ | g4s.large | Large - Standard | Instance | 4 | 8192 | 100 | +--------------------+--------------------------------+------------+-----+---------+-----+ | g4s.xlarge | Extra Large - Standard | Instance | 6 | 16384 | 150 | +--------------------+--------------------------------+------------+-----+---------+-----+ | g4s.2xlarge | 2X Large - Standard | Instance | 8 | 32768 | 200 | +--------------------+--------------------------------+------------+-----+---------+-----+ | g4g.kube.small | Small - Nvidia A100 80GB | Kubernetes | 12 | 131072 | 100 | +--------------------+--------------------------------+------------+-----+---------+-----+ | g4g.kube.medium | Medium - Nvidia A100 80GB | Kubernetes | 24 | 262144 | 100 | +--------------------+--------------------------------+------------+-----+---------+-----+ | g4g.kube.large | Large - Nvidia A100 80GB | Kubernetes | 48 | 524288 | 100 | +--------------------+--------------------------------+------------+-----+---------+-----+ | g4g.kube.xlarge | Extra Large - Nvidia A100 80GB | Kubernetes | 96 | 1048576 | 100 | +--------------------+--------------------------------+------------+-----+---------+-----+ | g4g.small | Small - Nvidia A100 80GB | Instance | 12 | 131072 | 200 | +--------------------+--------------------------------+------------+-----+---------+-----+ | g4g.medium | Medium - Nvidia A100 80GB | Instance | 24 | 262144 | 200 | +--------------------+--------------------------------+------------+-----+---------+-----+ | g4g.large | Large - Nvidia A100 80GB | Instance | 48 | 524288 | 400 | +--------------------+--------------------------------+------------+-----+---------+-----+ | g4g.xlarge | Extra Large - Nvidia A100 80GB | Instance | 96 | 1048576 | 400 | +--------------------+--------------------------------+------------+-----+---------+-----+ | g4g.40.small | Small - Nvidia A100 40GB | Instance | 8 | 65536 | 200 | +--------------------+--------------------------------+------------+-----+---------+-----+ | g4g.40.medium | Medium - Nvidia A100 40GB | Instance | 16 | 131072 | 400 | +--------------------+--------------------------------+------------+-----+---------+-----+ | g4g.40.large | Large - Nvidia A100 40GB | Instance | 32 | 262133 | 400 | +--------------------+--------------------------------+------------+-----+---------+-----+ | g4g.40.xlarge | Extra Large - Nvidia A100 40GB | Instance | 64 | 524288 | 400 | +--------------------+--------------------------------+------------+-----+---------+-----+ | g4g.40.kube.small | Small - Nvidia A100 40GB | Kubernetes | 8 | 65536 | 200 | +--------------------+--------------------------------+------------+-----+---------+-----+ | g4g.40.kube.medium | Medium - Nvidia A100 40GB | Kubernetes | 16 | 131072 | 400 | +--------------------+--------------------------------+------------+-----+---------+-----+ | g4g.40.kube.large | Large - Nvidia A100 40GB | Kubernetes | 32 | 262133 | 400 | +--------------------+--------------------------------+------------+-----+---------+-----+ | g4g.40.kube.xlarge | Extra Large - Nvidia A100 40GB | Kubernetes | 64 | 524288 | 400 | +--------------------+--------------------------------+------------+-----+---------+-----+ | an.g1.l40s.x1 | Small - Nvidia L40S 40GB | Instance | 12 | 131072 | 200 | +--------------------+--------------------------------+------------+-----+---------+-----+ | an.g1.l40s.x2 | Medium - Nvidia L40S 40GB | Instance | 24 | 262133 | 200 | +--------------------+--------------------------------+------------+-----+---------+-----+ | an.g1.l40s.x4 | Large - Nvidia L40S 40GB | Instance | 48 | 524288 | 400 | +--------------------+--------------------------------+------------+-----+---------+-----+ | an.g1.l40s.x8 | Extra Large - Nvidia L40S 40GB | Instance | 96 | 1048576 | 400 | +--------------------+--------------------------------+------------+-----+---------+-----+ | an.g1.l40s.kube.x1 | Small - Nvidia L40S 40GB | Kubernetes | 12 | 131072 | 200 | +--------------------+--------------------------------+------------+-----+---------+-----+ | an.g1.l40s.kube.x2 | Medium - Nvidia L40S 40GB | Kubernetes | 24 | 262133 | 200 | +--------------------+--------------------------------+------------+-----+---------+-----+ | an.g1.l40s.kube.x4 | Large - Nvidia L40S 40GB | Kubernetes | 48 | 524288 | 400 | +--------------------+--------------------------------+------------+-----+---------+-----+ | an.g1.l40s.kube.x8 | Extra Large - Nvidia L40S 40GB | Kubernetes | 96 | 1048576 | 400 | +--------------------+--------------------------------+------------+-----+---------+-----+
Snapshots allow you to create point-in-time copies of your instances. You can use these snapshots to create new instances or restore an existing instance to a previous state.
To create a snapshot of an instance:
$ civo instance snapshot create INSTANCE_NAME [flags]
Flags:
-n, --name string The name of the snapshot (default: auto-generated)
-d, --description string Description for the snapshotTo view all available snapshots for a specific instance:
$ civo instance snapshot list INSTANCE_NAME/ID
To restore an instance from a snapshot:
$ civo instance snapshot restore INSTANCE_NAME/ID SNAPSHOT_NAME/ID [flags] Flags: -d, --description string New description for the restored instance --hostname string New hostname for the restored instance (optional) --private-ipv4 string New private IPv4 address for the restored instance (optional) --overwrite-existing Overwrite an existing instance if it shares the same IP or hostname (defaults to false)
Example:
$ civo instance snapshot restore my-instance-id snap-123 --hostname restored-instance-new-name --overwrite-existing
To update the name or description of an instance snapshot:
$ civo instance snapshot update INSTANCE_NAME/ID SNAPSHOT_NAME/ID [flags] Flags: -n, --name string New name for the snapshot -d, --description string New description for the snapshot
Example:
$ civo instance snapshot update my-instance my-snapshot --name new-snapshot-name --description "Updated snapshot description"To delete a snapshot:
$ civo instance snapshot remove INSTANCE_NAME/ID SNAPSHOT_NAME/ID
You can view the default user's password for an instance by running civo instance password ID/hostname
$ civo instance password api-demo.test The instance api-demo.test (112f2407-fb89-443e-bd0e-5ddabc4682c6) has the password BrbXNW2RUYLe (and user demo-user)
You can also run this command with the option -o and -f to get only the password output, useful for scripting situations:
$ civo instance password api-demo.test -o custom -f Password BrbXNW2RUYLe
If an instance has a public IP address configured, you can display it using civo instance public-ip ID/hostname:
$ civo instance public-ip api-demo.test -o custom -f public_ip # Corrected from 'show' to 'public-ip'
74.220.21.246The above example uses -o and -f to display only the IP address in the output.
Instances can make use of separately-configured firewalls. By default, an instance is created with default all port open firewall rules set. If you want to secure your instances more, so you will need to configure some rules (see Firewalls for more information). Once you have configured the rules you can check it by running civo firewall ls
$ civo firewall ls +--------------------------------------+------------------------------------+---------+-------------+-----------------+ | ID | Name | Network | Total rules | Total Instances | +--------------------------------------+------------------------------------+---------+-------------+-----------------+ | c9e14ae8-b8eb-4bae-a687-9da4637233da | Default (all open) | Default | 3 | 0 | | f79db64d-41f0-4be0-ae80-ce4499164319 | Kubernetes cluster: Dem