{"id":18469958,"url":"https://github.com/civo/cli-rubygem","last_synced_at":"2025-04-08T10:32:56.730Z","repository":{"id":70907662,"uuid":"171666301","full_name":"civo/cli-rubygem","owner":"civo","description":"Command line interface for interacting with Civo's cloud API","archived":false,"fork":false,"pushed_at":"2020-06-16T11:17:44.000Z","size":204,"stargazers_count":15,"open_issues_count":9,"forks_count":4,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-03-23T11:33:15.255Z","etag":null,"topics":["civo-api","cli","cloud","ruby","rubygem"],"latest_commit_sha":null,"homepage":"https://www.civo.com","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/civo.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-02-20T12:08:29.000Z","updated_at":"2021-10-02T18:07:22.000Z","dependencies_parsed_at":null,"dependency_job_id":"66073c04-a113-4db9-b577-9a8ca6488901","html_url":"https://github.com/civo/cli-rubygem","commit_stats":null,"previous_names":[],"tags_count":21,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/civo%2Fcli-rubygem","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/civo%2Fcli-rubygem/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/civo%2Fcli-rubygem/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/civo%2Fcli-rubygem/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/civo","download_url":"https://codeload.github.com/civo/cli-rubygem/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247824309,"owners_count":21002248,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["civo-api","cli","cloud","ruby","rubygem"],"created_at":"2024-11-06T10:12:14.556Z","updated_at":"2025-04-08T10:32:56.722Z","avatar_url":"https://github.com/civo.png","language":"Ruby","readme":"# Civo Command-Line Client\n\n## Introduction\nCivo CLI is a tool to manage your [Civo.com](https://www.civo.com) account from the terminal. The [Civo web control panel](https://www.civo.com/account/) 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.\n\n**STATUS:** This project is currently under active development and maintenance.\n\n## Table of contents\n- [Introduction](#introduction)\n- [Set-Up](#set-up)\n- [Docker Usage](#docker-usage)\n- [API Keys](#api-keys)\n- [Instances](#instances)\n- [Kubernetes clusters](#kubernetes-clusters)\n- [Kubernetes applications](#kubernetes-applications)\n- [Domains and Domain Records](#domains-and-domain-records)\n- [Firewalls](#firewalls)\n- [Networks](#networks)\n- [Load Balancers](#load-balancers)\n- [Quota](#quota)\n- [Sizes](#sizes)\n- [Snapshots](#snapshots)\n- [SSH Keys](#ssh-keys)\n- [Templates](#templates)\n- [Volumes](#volumes)\n- [Development](#development)\n- [Contributing](#contributing)\n- [License](#license)\n\n## Set-up\nCivo CLI is built with Ruby and distributed as a Gem. If you have Ruby (2.0.0 or later) installed, you can simply run `gem install civo_cli` in your terminal to get the gem and its dependencies.\n\nYou may need to use `sudo` if you get an error about `You don't have write permissions` when installing the gem. The syntax is `sudo gem install civo_cli`.\n\nIf you need to install Ruby, follow the installation instructions appropriate for your operating system, and return to this guide after you have successfully installed the gem.\n\n - [Microsoft Windows](https://rubyinstaller.org/)\n - [Mac OS](https://www.ruby-lang.org/en/documentation/installation/#homebrew)\n - [UNIX/Linux](https://www.ruby-lang.org/en/documentation/installation/#package-management-systems)\n\n\nYou will also, of course, need a Civo account, for which you can [register here](https://www.civo.com/signup).\n\nTo run the tool, simply run `civo` with your chosen options. You can find context-sensitive help for commands and their options by invoking the `help` command:\n`civo help`,\n`civo instance help`,\n`civo instance help create`\nand so on. The main components of Civo CLI are outlined in the following sections.\n\n## Docker Usage\nCivo's CLI utilty can also run within a Docker container, which avoids the need to maintain a Ruby environment on the main system.\n\nTo run, you generally will want to map the API key for persistence.\n\n```\ntouch $HOME/.civo.json\ndocker run -it --rm -v $HOME/.civo.json:/home/user/.civo.json civo/cli:latest\n```\n\nTo 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:\n\n```\nalias civo=\"docker run -it --rm -v $HOME/.civo.json:/home/user/.civo.json civo/cli:latest\"\n# Maybe put the above line in ~/.bash_profile or ~/.zshrc\ncivo sshkey list\ncivo instance list\ncivo instance create --size g2.xsmall\ncivo k8s list\n```\n\n## API Keys\n#### Introduction\nIn 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](https://www.civo.com/api).\n\n#### Adding a current API Key to your account\nYou can add the API Key to the CLI tool through the API Keys command.\n`civo apikey add apikey_name apikey` such as:\n\n```\n$ civo apikey add Demo_Test_Key DAb75oyqVeaE7BI6Aa74FaRSP0E2tMZXkDWLC9wNQdcpGfH51r\n       Saved the API Key DAb75oyqVeaE7BI6Aa74FaRSP0E2tMZXkDWLC9wNQdcpGfH51r as Demo_Test_Key\n```\nAs 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:\n```\n$ civo apikey current Demo_Test_Key\n  The current API Key is now Demo_Test_Key\n```\n#### Managing and listing API keys\nYou 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`.\n\n## Instances\n#### Introduction\nAn 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.\n\n#### Creating an instance\nYou can create an instance by running `civo instance create` with a hostname parameter, as well as any options you provide:\n\n* `hostname` is a fully qualified domain name that should be set as the instance's hostname. The client will generate a random name if not provided.\n* `size` -  The size of instance to create, from the current list of sizes (e.g. g2.small) available at [`civo sizes`](#sizes). Defaults to `g2.small`.\n* `template` -  The OS template UUID to use, from the available list at [`civo templates`](#templates) Defaults to Ubuntu 18.04 if no `template` value or `snapshot` provided.\n* `snapshot` - The snapshot UUID to use, from snapshots you have saved on your account. Only required if `template` ID not provided.\n* `region` - The region code identifier to have your instance built in. Optional; will be assigned randomly if not provided.\n* `public_ip` - this should be either `none`, `create` or `from`. If `from` is specified then the `move_ip_from`parameter should also be specified (and contain the ID of the instance that will be releasing its IP). As aliases, `true` will be treated the same as `create` and `false` will be treated the same as `none`. If `create` or `true` is specified it will automatically allocate an initial public IP address, rather than having to add the first one later. Optional; default is `create`.\n* `initial_user` - The name of the initial user created on the server. If not provided, will default to the template's `default_username` and fallback to `civo`.\n* `ssh_key_id` - The ID of an already  [uploaded SSH public key](#ssh-keys)  to use for login to the default user. Optional; if one isn't provided a random password will be set and returned in the  `initial_password`  field.\n* `tags` - A space-separated list of tags in `'quotation marks'` to be used freely as required. Optional.\n* `wait` - a simple flag (e.g. `--wait`) that will cause the CLI to spin and wait for the instance to be `ACTIVE`.\n\nExample usage:\n```\n$ civo instance create --name=api-demo.test --size g2.small --template=811a8dfb-8202-49ad-b1ef-1e6320b20497 --initial_user=demo-user\n Created instance api-demo.test\n\n$ civo instance show api-demo.test\n                ID : 715f95d1-3cee-4a3c-8759-f9b49eec34c4\n          Hostname : api-demo.test\n              Tags :\n              Size : Small - 2GB RAM, 1 CPU Core, 25GB SSD Disk\n            Status : ACTIVE\n        Private IP : 10.250.199.4\n         Public IP : 172.31.2.164 =\u003e 91.211.152.100\n           Network : Default (10.250.199.0/24)\n          Firewall :  (rules: )\n            Region : lon1\n      Initial User : api-demouser\n      OpenStack ID : 7c89f7de-2b29-4178-a2e5-55bdaa5c4c21\n       Template ID : 811a8dfb-8202-49ad-b1ef-1e6320b20497\n       Snapshot ID :\n\n----------------------------- NOTES -----------------------------\n\n\n```\n\nYou will be able to see the instance's details by running `civo instance show api-demo.test` as above.\n\n#### Viewing the Default User Password For an Instance\nYou can view the default user's password for an instance by running `civo instance password ID/hostname`\n```\n$ civo instance password api-demo.test\nThe password for user civo on api-demo.test is 5OaGxNhaN11pLeWB\n```\nYou can also run this command with the option `-q` to get only the password output, useful for scripting situations:\n```\n$ civo instance password -q api-demo.test\n5OaGxNhaN11pLeWB\n```\n\n#### Viewing Instance Public IP Address\nIf an instance has a public IP address configured, you can display it using `civo instance ip_address ID/hostname`:\n```\n$ civo instance ip_address -q api-demo.test\n91.211.152.100\n```\nThe above example uses `-q` to display only the IP address in the output.\n\n#### Setting Firewalls\nInstances can make use of separately-configured firewalls. By default, an instance is created with no firewall rules set, so you will need to configure some rules (see [Firewalls](#firewalls) for more information).\n\nTo associate a firewall with an instance, use the command `civo instance firewall ID/hostname firewall_id`. For example:\n```\n$ civo instance firewall api-demo.test firewall_1\nSet api-demo.test to use firewall firewall_1\n```\n\n#### Listing Instances\nYou can list all instances associated with a particular API key by running `civo instance list`.\n\n#### Moving a Public IP Between Instances\nGiven two instances, one with a public IP and one without, you can move the public IP by `civo instance move_ip instance ip_address`:\n```\n$ civo instance move_ip cli-private-ip-demo.test 123.234.123.255`\n Moved public IP 123.234.123.255 to instance cli-private-ip-demo.test\n```\n#### Rebooting/Restarting Instances\nA user can reboot an instance at any time, for example to fix a crashed piece of software. Simply run `civo instance reboot instanceID/hostname`. You will see a confirmation message:\n```\n$ civo instance reboot api-demo.test\n Rebooting api-demo.test. Use 'civo instance show api-demo.test' to see the current status.\n```\n\nIf you prefer a soft reboot, you can run `civo instance soft_reboot instanceID/hostname` instead.\n\n#### Removing Instances\nYou can use a command to remove an instance from your account. This is immediate, so use with caution! Any snapshots taken of the instance, as well as any mapped storage, will remain.\nUsage: `civo instance remove instanceID/hostname`. For example:\n```\n$ civo instance remove api-demo.test\n Removing instance api-demo.test\n```\n#### Stopping (Shutting Down) and Starting Instances\nYou can shut down an instance at any time by running `civo instance stop instanceID/hostname`:\n\n```\n$ civo instance stop api-demo.test\n Stopping api-demo.test. Use 'civo instance show api-demo.test' to see the current status.\n```\nAny shut-down instance on your account can be powered back up with `civo instance start instanceID/hostname`:\n```\n$ civo instance start api-demo.test\n Starting api-demo.test. Use 'civo instance show api-demo.test' to see the current status.\n```\n#### (Re)Tagging an Instance\nTags can be useful in distinguishing and managing your instances. You can retag an instance using `civo instance tags instanceID/hostname 'tag1 tag2 tag3...'` as follows:\n```\n$ civo instance tags api-demo.test 'ubuntu demo web'\n Updated tags on api-demo.test. Use 'civo instance show api-demo.test' to see the current tags.'\n$ civo instance show api-demo.test\n                ID : 715f95d1-3cee-4a3c-8759-f9b49eec34c4\n          Hostname : api-demo.test\n              Tags : ubuntu, demo, web\n              Size : Small - 2GB RAM, 1 CPU Core, 25GB SSD Disk\n            Status : ACTIVE\n        Private IP : 10.250.199.4\n         Public IP : 172.31.2.164 =\u003e 91.211.152.100\n           Network : Default (10.250.199.0/24)\n          Firewall :  (rules: )\n            Region : lon1\n      Initial User : api-demouser\n      OpenStack ID : 7c89f7de-2b29-4178-a2e5-55bdaa5c4c21\n       Template ID : 811a8dfb-8202-49ad-b1ef-1e6320b20497\n       Snapshot ID :\n\n----------------------------- NOTES -----------------------------\n```\n#### Updating Instance Information\nIn case you need to rename an instance or add notes, you can do so with the `instance update` command as follows:\n```\n$ civo instance update api-demo.test --name api-demo-renamed.test --notes 'Hello, world!'\n Instance 715f95d1-3cee-4a3c-8759-f9b49eec34c4 now named api-demo-renamed.test\n Instance 715f95d1-3cee-4a3c-8759-f9b49eec34c4 notes are now: Hello, world!\n$ civo instance show api-demo-renamed.test\n                ID : 715f95d1-3cee-4a3c-8759-f9b49eec34c4\n          Hostname : api-demo-renamed.test\n              Tags : ubuntu, demo, web\n              Size : Small - 2GB RAM, 1 CPU Core, 25GB SSD Disk\n            Status : ACTIVE\n        Private IP : 10.250.199.4\n         Public IP : 172.31.2.164 =\u003e 91.211.152.100\n           Network : Default (10.250.199.0/24)\n          Firewall :  (rules: )\n            Region : lon1\n      Initial User : api-demouser\n      OpenStack ID : 7c89f7de-2b29-4178-a2e5-55bdaa5c4c21\n       Template ID : 811a8dfb-8202-49ad-b1ef-1e6320b20497\n       Snapshot ID :\n\n----------------------------- NOTES -----------------------------\n\nHello, world!\n```\nYou can leave out either the ``--name`` or `--notes` switch if you only want to update one of the fields.\n\n#### Upgrading (Resizing) an Instance\nProvided you have room in your Civo quota, you can upgrade any instance up in size. You can upgrade an instance by using `civo instance upgrade instanceID/hostname new_size` where `new_size` is from the list of sizes at `civo sizes`:\n```\n$ civo instance upgrade api-demo-renamed.test g2.medium\n Resizing api-demo-renamed.test to g2.medium. Use 'civo instance show api-demo-renamed.test' to see the current status.\n\n$ civo instance show api-demo-renamed.test\n                ID : 715f95d1-3cee-4a3c-8759-f9b49eec34c4\n          Hostname : api-demo-renamed.test\n              Tags : ubuntu, demo, web\n              Size : Medium - 4GB RAM, 2 CPU Cores, 50GB SSD Disk\n            Status : ACTIVE\n        Private IP : 10.250.199.4\n         Public IP : 172.31.2.164 =\u003e 91.211.152.100\n           Network : Default (10.250.199.0/24)\n          Firewall :  (rules: )\n            Region : lon1\n      Initial User : api-demouser\n  Initial Password : [randomly-assigned-password-here]\n      OpenStack ID : 7c89f7de-2b29-4178-a2e5-55bdaa5c4c21\n       Template ID : 811a8dfb-8202-49ad-b1ef-1e6320b20497\n       Snapshot ID :\n\n----------------------------- NOTES -----------------------------\n\nHello, world!\n```\nPlease note that resizing can take a few minutes.\n\n## Kubernetes clusters\n#### Introduction\n*IMPORTANT:* Kubernetes is in closed-access only at the moment, during testing. The endpoints here will be rejected unless you are one of the closed set of users that can launch them.\n\n#### List clusters\nTo see your created clusters, simply call `civo kubernetes list`:\n\n```\n$ civo kubernetes list\n+--------------------------------------+------+---------+-----------+--------+\n| ID                                   | Name | # Nodes | Size      | Status |\n+--------------------------------------+------+---------+-----------+--------+\n| f13e3f64-d657-40dd-8449-c42c6e341208 | test | 3       | g2.medium | ACTIVE |\n+--------------------------------------+------+---------+-----------+--------+\n```\n\n#### Create a cluster\nYou can create a cluster by running `civo kubernetes create` with a cluster name parameter, as well as any options you provide:\n\n* `size` -  The size of nodes to create, from the current list of sizes  available at [`civo sizes`](#sizes). Defaults to `g2.medium`.\n* `nodes` -  The number of nodes to create (the master also acts as a node).\n* `version` - the `k3s` version to use on the cluster. Defaults to the latest.\n* `wait` - a simple flag (e.g. `--wait`) that will cause the CLI to spin and wait for the cluster to be `ACTIVE`.\n* `save` - a flag used in conjunction with `--wait` (i.e. `--wait --save`) to save the configuration to your local `~/.kube/config` file.\n\n```\n$ civo kubernetes create my-first-cluster\nCreated Kubernetes cluster my-first-cluster\n```\n\n#### Scaling the cluster\nYou can change the total number of nodes in the cluster (obviously 1 is the minimum) live while the cluster is running. It takes the name of the cluster (or the ID) and a parameter of `--nodes` which is the new number of nodes to run\n\n```\ncivo kubernetes scale my-first-cluster --nodes=4\nKubernetes cluster my-first-cluster will now have 4 nodes\n```\n\n#### Viewing or Saving the cluster configuration\nTo output a cluster's configuration information, you can invoke `civo kubernetes config cluster-name`. This will output the `kubeconfig` file to the screen.\n\nYou can save a cluster's configuration to your local `~/.kube/config` file. This requires `kubectl` to be installed. Usage:\n```\ncivo kubernetes config -s my-first-cluster\nSaved config to ~/.kube/config\n```\n\nIf you already have a `~/.kube/config` file, any cluster configuration that is saved will be merged to the file, allowing you to switch contexts at will.\n\n#### Renaming the cluster\nAlthough the name isn't used anywhere except for in the list of clusters (e.g. it's not in any way written in to the cluster), if you wish to rename a cluster you can do so with:\n\n```\ncivo kubernetes rename my-first-cluster --name=\"Production\"\nKubernetes cluster my-first-cluster is now named Production\n```\n\n#### Starting a cluster without default applications\nBy default, `traefik` is bundled in with `k3s` to act as the ingress controller. If you want to set up a cluster without `traefik`, you can use the `remove-applications` option in the creation command to start a cluster without it:\n\n```\ncivo kubernetes create --remove-applications=traefik --nodes=2 --wait --save\n```\n\n#### Removing the cluster\nIf you're completely finished with a cluster you can delete it with:\n\n```\ncivo kubernetes remove my-first-cluster\nRemoving Kubernetes cluster my-first-cluster\n```\n\n## Kubernetes Applications\n#### Introduction\nYou can install applications from the [Applications Marketplace](https://github.com/civo/kubernetes-marketplace/) through the command-line interface. The installation depends on whether you are creating a new cluster or adding applications to an existing cluster.\n\n#### Listing Available Applications\nTo get an up-to-date list of available applications on the Marketplace, run `civo apps list`. At the time of writing, the list looked like this:\n```\n+---------------------+------------+--------------+-----------------+--------------+\n| Name                | Version    | Category     | Plans           | Dependencies |\n+---------------------+------------+--------------+-----------------+--------------+\n| cert-manager        | v0.10.0    | architecture | Not applicable  | Helm         |\n| Helm                | 2.14.3     | management   | Not applicable  |              |\n| Linkerd             | 2.5.0      | architecture | Not applicable  |              |\n| Longhorn            | 0.5.0      | storage      | Not applicable  |              |\n| Maesh               | Latest     | architecture | Not applicable  | Helm         |\n| MariaDB             | 10.4.7     | database     | 5GB, 10GB, 20GB | Longhorn     |\n| metrics-server      | Latest     | architecture | Not applicable  | Helm         |\n| MinIO               | 2019-08-29 | storage      | 5GB, 10GB, 20GB | Longhorn     |\n| MongoDB             | 4.2.0      | database     | 5GB, 10GB, 20GB | Longhorn     |\n| OpenFaaS            | 0.18.0     | architecture | Not applicable  | Helm         |\n| PostgreSQL          | 11.5       | database     | 5GB, 10GB, 20GB | Longhorn     |\n| prometheus-operator | 0.32.0     | monitoring   | Not applicable  | Helm         |\n| Redis               | 3.2        | database     | Not applicable  |              |\n| Traefik             | (default)  | architecture | Not applicable  |              |\n+---------------------+------------+--------------+-----------------+--------------+\n```\n\n\n#### Installing Applications Onto a New Cluster\nTo specify applications to install onto a new cluster, list them at cluster creation by specifying their `name` from the list above:\n```\n$ civo kubernetes create apps-demo-cluster --nodes=2 --applications=Redis,Linkerd\nCreated Kubernetes cluster apps-demo-cluster.\n```\nNow, if you take a look at the cluster's details, you will see the newly-installed applications listed:\n```\n$ civo kubernetes show apps-demo\n                ID : 1199efbe-e2a5-4d25-a32f-0b7aa50082b2\n              Name : apps-demo-cluster\n           # Nodes : 2\n              Size : g2.medium\n            Status : ACTIVE\n           Version : 0.8.1\n      API Endpoint : https://[Cluster-IP]:6443\n      DNS A record : 1199efbe-e2a5-4d25-a32f-0b7aa50082b2.k8s.civo.com\n\nNodes:\n+------------------+----------------+--------+\n| Name             | IP             | Status |\n+------------------+----------------+--------+\n| kube-master-1e91 |      (IP)      | ACTIVE |\n| kube-node-e678   |      (IP)      | ACTIVE |\n+------------------+----------------+--------+\n\nInstalled marketplace applications:\n+---------+-----------+-----------+--------------+\n| Name    | Version   | Installed | Category     |\n+---------+-----------+-----------+--------------+\n| Traefik | (default) | Yes       | architecture |\n| Linkerd | 2.5.0     | Yes       | architecture |\n| Redis   | 3.2       | Yes       | database     |\n+---------+-----------+-----------+--------------+\n```\n\n#### Installing Applications to an Existing Cluster\nIf you want to add a new application to an existing cluster, you can do so by running the `civo applications` command specifying the cluster and the app(s) you wish to add:\n```\n$ civo applications add Longhorn --cluster=apps-demo\nAdded Longhorn 0.5.0 to Kubernetes cluster apps-demo-cluster\n```\n\n#### Installing Applications That Require Plans\nSome applications, specifically database apps, require a storage plan that you can specify at installation time from the list of plan options. If you do not provide a plan for an application that requires one, the CLI will notify you and suggest a default size:\n```\n$ civo applications add mariadb --cluster=apps-demo\nYou requested to add MariaDB but didn't select a plan. Please choose one... (5GB, 10GB, 20GB) [5GB]: 10GB\nThank you, next time you could use \"MariaDB:10GB\" to choose automatically\nAdded MariaDB 10.4.7 to Kubernetes cluster apps-demo-cluster\n```\n\n## Domains and Domain Records\n#### Introduction\nWe host reverse DNS for all instances automatically. If you'd like to manage forward (normal) DNS for your domains, you can do that for free within your account.\n\nThis section is effectively split in to two parts: 1) Managing domain names themselves, and 2) Managing records within those domain names.\n\nWe don't offer registration of domains names, this is purely for hosting the DNS. If you're looking to buy a domain name, we recommend  [LCN.com](https://www.lcn.com/)  for their excellent friendly support and very competitive prices.\n#### Set Up a New Domain\nAny user can add a domain name (that has been registered elsewhere) to be managed by Civo.com. You should adjust the nameservers of your domain (through your registrar) to point to  `ns0.civo.com`  and  `ns1.civo.com`.\n\nThe command to set up a new domain is `civo domain create domainname`:\n```\n$ civo domain create civoclidemo.xyz\nCreated a domain called civoclidemo.xyz with ID 418181b2-fcd2-46a2-ba7f-c843c331e79b\n```\nYou can then proceed to add DNS records to this domain.\n\n#### List Domain Names\nTo see your created domains, simply call `civo domain list`:\n```\n$ civo domain list\n+--------------------------------------+-----------------+\n| ID                                   | Name            |\n+--------------------------------------+-----------------+\n| 418181b2-fcd2-46a2-ba7f-c843c331e79b | civoclidemo.xyz |\n+--------------------------------------+-----------------+\n```\n#### Deleting a Domain\nIf you choose to delete a domain, you can call `civo domain remove domain_id` and have the system immediately remove the domain and any associated DNS records. This removal is immediate, so use with caution.\n\n#### Creating a DNS Record\nA DNS record creation command takes a number of options in the format `civo domainrecord create record_name type value` with optional `-p` (priority for MX records) and `-t` (time-to-live of record cache, in seconds).\n\n`type` is one of the following:\n`a` -\u003e Alias a hostname to an IP address\n`cname` or `canonical` -\u003e Point a hostname to another hostname\n`mx` -\u003e The hostname of a mail server\n`txt` or `text` -\u003e Generic text record\n\n Usage is as follows:\n```\n$ civo domainrecord create civoclidemo.xyz mx 10.0.0.1 -p=10 -t=1000\n\n#\u003cCivo::DnsRecord id: \"2079e6e1-0633-4cd0-b883-e82a8991a91a\", created_at: \"2019-06-17 12:38:02\", updated_at: \"2019-06-17 12:38:02\", account_id: nil, domain_id: \"418181b2-fcd2-46a2-ba7f-c843c331e79b\", name: \"@\", value: \"10.0.0.1\", type: \"mx\", priority: 10, ttl: 1000, ETag: \"187cf7e849ce53336a889b2bde7ed061\", Status: 200\u003e\nCreated MX record civoclidemo.xyz for civoclidemo.xyz with a TTL of 1000 seconds and with a priority of 10 with ID 2079e6e1-0633-4cd0-b883-e82a8991a91a\n```\n#### Listing DNS Records\nYou can get an overview of all records you have created for a particular domain by requesting `civo domainrecord list domain.name`:\n```\ncivo domainrecord list civoclidemo.xyz\n+--------------------------------------+------+-------------------+----------+------+----------+\n| ID                                   | Type | Name              | Value    | TTL  | Priority |\n+--------------------------------------+------+-------------------+----------+------+----------+\n| 2079e6e1-0633-4cd0-b883-e82a8991a91a | MX   | @.civoclidemo.xyz | 10.0.0.1 | 1000 | 10       |\n+--------------------------------------+------+-------------------+----------+------+----------+\n```\n#### Deleting a DNS Record\nYou can remove a particular DNS record from a domain you own by requesting `civo domainrecord remove record_id`. This immediately removes the associated record, so use with caution:\n```\n$ civo domainrecord remove 2079e6e1-0633-4cd0-b883-e82a8991a91a\nRemoved the record @ record with ID 2079e6e1-0633-4cd0-b883-e82a8991a91a\n```\n\n## Firewalls\n#### Introduction\nYou can configure custom firewall rules for your instances using the Firewall component of Civo CLI. These are freely configurable, however customers should be careful to not lock out their own access to their instances. By default, all ports are closed for custom firewalls.\n\nFirewalls can be configured with rules, and they can be made to apply to your chosen instance(s) with subsequent commands.\n\n#### Configuring a New Firewall\nTo create a new Firewall, use `civo firewall create new_firewall_name`:\n```\n$ civo firewall create civocli_demo\n Created firewall civocli_demo\n```\nYou will then be able to **configure rules** that allow connections to and from your instance by adding a new rule using `civo firewall new_rule firewall_id` with the required and your choice of optional parameters, listed here and used in an example below:\n* `firewall_id` - The UUID of the firewall you are adding a rule to. Required.\n* `start_port` - The starting port that the rule applies to. Required.\n* `end_port` - The end of the port range that the rule applies to. Optional; if not specified, the rule will only apply to `start_port` specified.\n* `protocol` - The protocol for the rule (`TCP, UDP, ICMP`). If not provided, defaults to `TCP`.\n* `cidr` - The IP address of the other end (i.e. not your instance) to affect, or a valid network CIDR. Defaults to being globally applied, i.e. `0.0.0.0/0`.\n* `direction` -  Will this rule affect `inbound` or `outbound` traffic? Defaults to `inbound`.\n* `label` - A label for your own reference for this rule. Optional.\n\nExample usage:\n```\n$ civo firewall new_rule --firewall_id=09f8d85b-0cf1-4dcf-a472-ba247fb4be21 --start_port=22 --direction=inbound --label='SSH access for CLI demo'\n New rule SSH access for CLI demo created\n\n$ civo firewall list_rules 09f8d85b-0cf1-4dcf-a472-ba247fb4be21\n+--------------------------------------+----------+------------+----------+-----------+-------------------------+\n|                            Firewall rules for 09f8d85b-0cf1-4dcf-a472-ba247fb4be21                            |\n+--------------------------------------+----------+------------+----------+-----------+-------------------------+\n| ID                                   | Protocol | Start Port | End Port | CIDR      | Label                   |\n+--------------------------------------+----------+------------+----------+-----------+-------------------------+\n| 4070f87b-e6c6-4208-91c5-fc4bc72c1587 | tcp      | 22         | 22       | 0.0.0.0/0 | SSH access for CLI demo |\n+--------------------------------------+----------+------------+----------+-----------+-------------------------+\n```\nYou can see all active rules for a particular firewall by calling `civo firewall list_rules firewall_id`, where `firewall_id` is the UUID of your particular firewall.\n\n#### Managing Firewalls\nYou can see an overview of your firewalls using `civo firewall list` showing you which firewalls have been configured with rules, and whether any of your instances are using a given firewall, such as in this case where the firewall we have just configured has the one rule, but no instances using it.\n```\n$ civo firewall list\n+--------------------------------------+--------------+--------------+-----------------+\n| ID                                   | Name         | No. of Rules | instances using |\n+--------------------------------------+--------------+--------------+-----------------+\n| 09f8d85b-0cf1-4dcf-a472-ba247fb4be21 | civocli_demo | 1            | 0               |\n+--------------------------------------+--------------+--------------+-----------------+\n```\nTo configure an instance to use a particular firewall, see [Instances/Setting firewalls elsewhere in this guide](#setting-firewalls).\n\nTo get more detail about the specific rule(s) of a particular firewall, you can use `civo firewall list_rules firewall_id`.\n\n#### Deleting Firewall Rules and Firewalls\nYou can remove a firewall rule simply by calling `civo firewall delete_rule firewall_id rule_id` - confirming the Firewall ID to delete a particular rule from - as follows:\n```\n$ civo firewall delete_rule 09f8d85b-0cf1-4dcf-a472-ba247fb4be21 4070f87b-e6c6-4208-91c5-fc4bc72c1587\n        Removed Firewall rule 4070f87b-e6c6-4208-91c5-fc4bc72c1587\n\n$ civo firewall list_rules 09f8d85b-0cf1-4dcf-a472-ba247fb4be21\n+-------+----------+------------+----------+------+-------+\n| Firewall rules for 09f8d85b-0cf1-4dcf-a472-ba247fb4be21 |\n+-------+----------+------------+----------+------+-------+\n| ID    | Protocol | Start Port | End Port | CIDR | Label |\n+-------+----------+------------+----------+------+-------+\n+-------+----------+------------+----------+------+-------+\n```\nSimilarly, you can delete a firewall itself by calling `civo firewall remove firewall_id`:\n```\n$ civo firewall remove 09f8d85b-0cf1-4dcf-a472-ba247fb4be21\n        Removed firewall 09f8d85b-0cf1-4dcf-a472-ba247fb4be21\n\n$ civo firewall list\n+----+------+--------------+-----------------+\n| ID | Name | No. of Rules | instances using |\n+----+------+--------------+-----------------+\n+----+------+--------------+-----------------+\n```\n\n## Networks\n#### Introduction\nCivo allows for true private networking if you want to isolate instances from each other. For example, you could set up three instances, keeping one as a [\n](https://en.wikipedia.org/wiki/Bastion_host) and load balancer, with instances acting as e.g. a database server and a separate application server, both with private IPs only.\n\n#### Viewing Networks\nYou can list your currently-configured networks by calling `civo network list`. This will show the network ID, name label and its CIDR range.\n\n#### Creating Networks\nYou can create a new private network using `civo network create network_label`:\n```\n$ civo network create cli-demo\nCreate a private network called cli-demo with ID 74b69006-ea59-46a0-96c4-63f5bfa290e1\n```\n#### Removing Networks\nRemoval of a network, provided you do not need it and your applications do not depend on routing through it, is simple - simply call `civo network remove network_ID`:\n```\n$ civo network remove 74b69006-ea59-46a0-96c4-63f5bfa290e1\nRemoved the network cli-demo with ID 74b69006-ea59-46a0-96c4-63f5bfa290e1\n```\n\n## Load Balancers\n#### Introduction\nCivo supports load balancing for your instances, allowing you to spread web traffic between them to maximise availability. You can view details about load balancers you may have running, create new oness, update information and even remove them from the command line.\n\n#### Viewing Load Balancers\nYou can list currently-active load balancers by calling `civo loadbalancer list`. This will draw a table detailing the unique ID, hostname, protocol, port, TLS certificate information, backend check path and connection information.\n\n#### Creating Load Balancers\nCreate a new load balancer by calling `civo loadbalancer create` as well as any options you provide. The options are:\n* `hostname` -  A valid hostname for your load balancer. Defaults to `loadbalancer-[uuid].civo.com`.\n* `protocol` - Either `http` or `https`. If you specify `https` then you must also provide the next two fields.\n* `tls_certificate` - TLS certificate in Base64-encoded PEM. Required if `--protocol` is `https`.\n* `tls_key` - TLS key in Base64-encoded PEM. Required if `--protocol` is `https`.\n* `max_request_size` - Maximum request content size, in MB. Defaults to 20.\n* `port` - Listening port. Defaults to 80 to match default `http` protocol.\n* `policy` - Traffic management policy. One of: `least_conn` (sends new requests to the least busy server), `random` (sends new requests to a random backend), `round_robin` (sends new requests to the next backend in order), `ip_hash` (sends requests from a given IP address to the same backend), default is \"random\".\n* `health_check_path` - URL to check for a valid (2xx/3xx) HTTP status on the backends. Defaults to `/`.\n* `fail_timeout` - Timeout in seconds to consider a backend to have failed. Defaults to `30`.\n* `max_conns` - Maximum concurrent connections to each backend. Defaults to `10`.\n* `ignore_invalid_backend_tls` - Should self-signed/invalid certificates be ignored from backend servers? Defaults to `true`.\n* `backend` - Specify a backend instance to associate with the load balancer. Takes `instance_id`, `protocol` and `port` in the format `--backend=instance_id: instance-id protocol: http port: 80`.\n```\n$ civo loadbalancer create\nCreated a new Load Balancer with hostname loadbalancer-01da06bc-40ef-4d4c-bb68-d0765d288b54.civo.com\n```\n\n#### Updating Load Balancers\nUpdating an existing load balancer takes the same options as creation, with the syntax being `civo loadbalancer update ID [options]`. For example, we can update the hostname of the load balancer created above using `--hostname`:\n```\n$ civo loadbalancer update 01da06bc-40ef-4d4c-bb68-d0765d288b54 --hostname=\"civo-demo-loadbalancer.civo.com\"\nUpdated Load Balancer\n```\n\n#### Removing Load Balancers\nRemoving a load balancer is simple - simply call `civo loadbalancer remove loadbalancer_id`. Please note that this change is immediate:\n\n```\n$ civo loadbalancer remove 01da06bc-40ef-4d4c-bb68-d0765d288b54\nRemoved the load balancer civo-demo-loadbalancer.civo.com with ID 01da06bc-40ef-4d4c-bb68-d0765d288b54\n```\n\n## Quota\nAll customers joining Civo will have a default quota applied to their account. The quota has nothing to do with charges or payments, but with the limits on the amount of simultaneous resources you can use. You can view the state of your quota at any time by running `civo quota`. Here is my current quota usage at the time of writing:\n```\n$ civo quota\n+------------------+-------+-------+\n| Item             | Usage | Limit |\n+------------------+-------+-------+\n| Instances        | 4     | 16    |\n| CPU cores        | 5     | 16    |\n| RAM MB           | 7168  | 32768 |\n| Disk GB          | 150   | 400   |\n| Volumes          | 4     | 16    |\n| Snapshots        | 1     | 48    |\n| Public IPs       | 4     | 16    |\n| Subnets          | 1     | 10    |\n| Private networks | 1     | 10    |\n| Firewalls        | 1     | 16    |\n| Firewall rules   | 1     | 160   |\n+------------------+-------+-------+\nAny items in red are at least 80% of your limit\n```\nIf you have a legitimate need for a quota increase, visit the [Quota page](https://www.civo.com/account/quota) to place your request - we won't unreasonably withhold any increase, it's just in place so we can control the rate of growth of our platform and so that erran scripts using our API don't suddenly exhaust our available resources.\n\n## Regions\nAs Civo grows, more regions for hosting your instances will become available. You can run `civo region` to list the regions available. Block storage (Volumes) is region-specific, so if you configure an instance in one region, any volumes you wish to attach to that instance would have to be in the same region.\n\n## Sizes\nCivo instances come in a variety of sizes depending on your need and budget. You can get details of the sizes of instances available by calling `civo sizes` or `civo sizes list`. You will get something along the lines of the following:\n```\n$ civo sizes\n+------------+----------------------------------------------------+-----+----------+-----------+\n| Name       | Description                                        | CPU | RAM (MB) | Disk (GB) |\n+------------+----------------------------------------------------+-----+----------+-----------+\n| g2.xsmall  | Extra Small - 1GB RAM, 1 CPU Core, 25GB SSD Disk   | 1   | 1024     | 25        |\n| g2.small   | Small - 2GB RAM, 1 CPU Core, 25GB SSD Disk         | 1   | 2048     | 25        |\n| g2.medium  | Medium - 4GB RAM, 2 CPU Cores, 50GB SSD Disk       | 2   | 4096     | 50        |\n| g2.large   | Large - 8GB RAM, 4 CPU Cores, 100GB SSD Disk       | 4   | 8192     | 100       |\n| g2.xlarge  | Extra Large - 16GB RAM, 6 CPU Core, 150GB SSD Disk | 6   | 16386    | 150       |\n| g2.2xlarge | 2X Large - 32GB RAM, 8 CPU Core, 200GB SSD Disk    | 8   | 32768    | 200       |\n+------------+----------------------------------------------------+-----+----------+-----------+\n```\nThis command is useful for getting the name of the instance type if you do not remember it - you will need to specify the instance size name when creating an instance using the CLI tool.\n\n## Snapshots\n#### Introduction\nSnapshots are a clever way to back up your instances. A snapshot is an exact copy of the instance's virtual hard drive at the moment of creation. At any point, you can restore an instance to the state it was at snapshot creation, or use snapshots to build new instances that are configured exactly the same as other servers you host.\n\nAs snapshot storage is chargeable (see [\nQuota](#quota)), at any time these can be deleted by you. They can also be scheduled rather than immediately created, and if desired repeated at the same schedule each week (although the repeated snapshot will overwrite itself each week, not keep multiple weekly snapshots).\n\n#### Creating Snapshots\nYou can create a snapshot from an existing instance on the command line by using `civo snapshot create snapshot_name instance_id`\nFor a one-off snapshot that's all you will need:\n```\ncivo snapshot create CLI-demo-snapshot 715f95d1-3cee-4a3c-8759-f9b49eec34c4\nCreated snapshot CLI-demo-snapshot with ID d6d7704b-3402-44d0-aeb1-09875f71d168\n```\nFor scheduled snapshots, include the `-c '0 * * * *'` switch, where the `'0 * * * *'` string is in `cron` format.\n\nCreating snapshots is not instant, and will take a while depending on the size of the instance being backed up. You will be able to monitor the status of your snapshot by listing your snapshots as described below.\n\n#### Listing Snapshots\nYou can view all your currently-stored snapshots and a bit of information about them by running `civo snapshot list`:\n```\n$ ./exe/civo snapshot list\n+--------------------------------------+-------------------+----------------+-----------+---------+\n| ID                                   | Name              | State          | Size (GB) | Cron    |\n+--------------------------------------+-------------------+----------------+-----------+---------+\n| 3506a013-85a5-4628-bf51-3e25a3bb3dbd | hello_world       | complete       | 25        | One-off |\n| d6d7704b-3402-44d0-aeb1-09875f71d168 | CLI-demo-snapshot | ready_to_start |           | One-off |\n+--------------------------------------+-------------------+----------------+-----------+---------+\n```\n(The 'ready_to_start' status in the above is indicative of the `CLI-demo-snapshot` being in the process of being created.)\n\n#### Removing Snapshots\nSnapshots that are not associated with an instance can be removed using `civo snapshot remove snapshot_id` as follows:\n```\n$ civo snapshot remove d6d7704b-3402-44d0-aeb1-09875f71d168\nRemoved snapshot CLI-demo-snapshot with ID d6d7704b-3402-44d0-aeb1-09875f71d168\n```\nIf an instance was created from a snapshot, you will not be able to remove the snapshot itself.\n\n## SSH Keys\n#### Introduction\nTo manage the SSH keys for an account that are used to log in to cloud instances, the Civo CLI tool provides the following commands. You would need to [\ngenerate a new key](https://www.civo.com/learn/ssh-key-basics) according to your particular circumstances, if you do not have a suitable SSH key yet.\n\n#### Uploading a New SSH Key\nYou will need the path to your public SSH Key to upload a new key to Civo. The usage is as follows: `civo sshkey upload NAME /path/to/FILENAME`\n\n#### Listing Your SSH Keys\nYou will be able to list the SSH keys known for the current account holder by invoking `civo sshkey list`:\n```\n$ civo sshkeys\n+--------------------------------------+------------------+----------------------------------------------------+\n| ID                                   | Name             | Fingerprint                                        |\n+--------------------------------------+------------------+----------------------------------------------------+\n| 8aa45fea-a395-471c-93a6-27485a8429f3 | civo_cli_demo    | SHA256:[Unique SSH Fingerprint]                    |\n+--------------------------------------+------------------+----------------------------------------------------+\n```\n#### Removing a SSH Key\nYou can delete a SSH key by calling `remove` for it by ID:\n```\n$ civo sshkeys remove 531d0998-4152-410a-af20-0cccb1c7c73b\nRemoved SSH key cli-demo with ID 531d0998-4152-410a-af20-0cccb1c7c73b\n```\n\n## Templates\n#### Introduction\nCivo instances are built from a template that specifies a disk image. Templates can contain the bare-bones OS install such as Ubuntu or Debian, or custom pre-configured operating systems that you can create yourself from a bootable volume. This allows you to speedily deploy pre-configured instances.\n\n#### Listing Available Template Images\nA simple list of available templates, both globally-defined ones and user-configured account-specific templates, can be seen by running `civo template list` or `civo template list --verbose` for maximum information:\n```\n$ civo template list --verbose\n+--------------------------------------+----------------------+--------------------------------------+--------------------------------------+------------------+\n| ID                                   | Name                 | Image ID                             | Volume ID                            | Default Username |\n+--------------------------------------+----------------------+--------------------------------------+--------------------------------------+------------------+\n| 62f9c8a5-c3aa-4873-afad-44e1ee01ed43 | Ubuntu 14.04         | 637b163e-ca9c-42a8-bc02-d60e3025e9b2 | 65288478-50d0-4ab7-837e-18ddcf71ea5f | ubuntu           |\n| 458ae900-30e0-4ade-bd68-d137d57d4e47 | CentOS 7             | e17ec38a-1e77-4c45-bef3-569567c9b169 | cf3368dd-ccb3-4f6d-adf5-bad9a8ae9177 | centos           |\n| 67c4df28-8db8-48e5-84b3-d79b9d59920b | CentOS 6             | 04d66ce1-f20e-4d84-a6d4-cdde5a07ff7e | d69c297b-a18d-4388-b4ce-9f11e04fc45f | centos           |\n| c2124658-0f9f-4d40-bb52-6288819fdc39 | Debian Jessie        | 38686161-ba25-4899-ac0a-54eaf35239c0 | 5c37a01d-342e-4732-9a59-79fcbc4c91f4 | admin            |\n| 1427e49f-d159-4421-b6cc-34c43775764b | CoreOS               | e5a2be4a-fb83-48e8-875d-5e5ff565c9e5 |                                      | core             |\n| 5d61621a-f9c1-4261-b863-2a205792b12f | Ubuntu 17.04         | a478ab7f-1ac0-4d86-9a57-e607b2bbbcf0 |                                      | ubuntu           |\n| 033c35a0-a8c3-4518-8114-d156a4d4c512 | Debian Stretch       | 2ffff07e-6953-4864-8ce9-1f754d70de31 | 1b117fe1-a237-43b2-8cab-d47086ce3d30 | admin            |\n| 359494e6-2439-471e-a528-f8866dade6ba | FreeBSD 11.1-RELEASE | 8d3886df-c5c1-4efe-aa5a-659217b466a5 |                                      | freebsd          |\n| b0d30599-898a-4072-86a1-6ed2965320d9 | Ubuntu 16.04         | 8b4d81e0-6283-4ea3-bbc4-478df568024e | ea411e3f-479a-4767-9273-b8cc758ca619 | ubuntu           |\n| 811a8dfb-8202-49ad-b1ef-1e6320b20497 | Ubuntu 18.04         | e4838e89-f086-41a1-86b2-60bc4b0a259e | 7c9f99a5-909a-4d4f-91a2-e0174fe4d2a9 | ubuntu           |\n+--------------------------------------+----------------------+--------------------------------------+--------------------------------------+------------------+\n```\n\n#### Viewing Details of a Template\nDetailed information about a template can be obtained via the CLI using `civo template show template_ID`.\n\n\n#### Creating a Template\nYou can convert a **bootable** Volume (virtual disk) of an instance, or alternatively use an existing image ID, to create a template. The options for the `civo template create` command are:\n```\nOptions:\n  -c, [--cloud-init-file=CLOUD_INIT_FILENAME] # The filename of a file to be used as user-data/cloud-init\n  -d, [--description=DESCRIPTION] # A full/long multiline description (optional)\n  -i, [--image-id=IMAGE_ID] # The glance ID of the base filesystem image\n  -v, [--volume-id=VOLUME_ID] # The volume ID of the base filesystem volume\n  -n, [--name=NICE_NAME] # A nice name to be used for the template\n  -s, [--short-description=SUMMARY] # A one line short summary of the template\n```\n\n```\n$ civo template create -n=\"cli-demo\" -v=1427e49f-d159-4421-b6cc-34c43775764b --description=\"This is a demo template made from a CoreOS image\" --short-description=\"CoreOS CLI demo\"\n\tCreated template cli-demo\n```\n\n#### Updating Template Information\nOnce you have  created a custom template, you can update information that allows for the easy identification and management of the template. Usage is `civo template update template_id [options]`:\n\n```\nOptions:\n  -c, [--cloud-init-file=CLOUD_INIT_FILENAME]  # The filename of a file to be used as user-data/cloud-init\n  -d, [--description=DESCRIPTION]              # A full/long multiline description\n  -i, [--image-id=IMAGE_ID]                    # The glance ID of the base filesystem image\n  -v, [--volume-id=VOLUME_ID]                  # The volume ID of the base filesystem volume\n  -n, [--name=NICE_NAME]                       # A nice name to be used for the template\n  -s, [--short-description=SUMMARY]            # A one line short summary of the template\n```\n#### Removing a Template\nRemoving an account-specific template is done using the `template remove template_id` command:\n```\n$ civo template remove 1427e22f-d149-4421-b6ab-34c43754224c\n```\nPlease note that template removal is immediate! Use with caution.\n\n## Volumes\n#### Introduction\nVolumes are flexible-size additional storage for instances. By creating and associating a Volume with an instance, an additional virtual disk will be made available for backups or database files that can then moved to another instance.\n\nVolumes take disk space on your account's quota, and can only be created up to this quota limit. For more information about the quota system, see [Quota](#quota).\n\n#### Creating a Volume\nYou can create a new volume by calling `civo volume create NAME SIZE(GB)`:\n```\n$ civo volume create CLI-demo-volume 25\nCreated a new 25GB volume called CLI-demo-volume with ID 9b232ffa-7e05-45a4-85d8-d3643e68952e\n```\n#### Attaching a Volume to an Instance\nMounting (Attaching) a volume onto an instance will allow that instance to use the volume as a drive:\n```\n$ civo volume attach 9b232ffa-7e05-45a4-85d8-d3643e68952e 715f95d1-3cee-4a3c-8759-f9b49eec34c4\nAttached volume CLI-demo-volume with ID 9b232ffa-7e05-45a4-85d8-d3643e68952e to api-demo.test\n```\nIf this is a newly-created volume, you would need to partition, format and mount the volume. For more information, [see the Learn guide here](https://www.civo.com/learn/configuring-block-storage-on-civo).\nNote: You can only attach a volume to one instance at a time.\n\n#### Detaching a Volume From an Instance\nIf you want to detach a volume to move it to another instance, or are just finished with it, you can detach it once it's been [unmounted](https://www.civo.com/learn/configuring-block-storage-on-civo) using `civo volume detach volume_id`:\n```\n$ civo volume detach 9b232ffa-7e05-45a4-85d8-d3643e68952e\nDetached volume CLI-demo-volume with ID 9b232ffa-7e05-45a4-85d8-d3643e68952e\n```\n#### Listing Volumes\nYou can get an overall view of your volumes, their sizes and status by using `civo volume list`.\n\n#### Resizing Volumes\nAn un-attached volume can be resized if you need extra space. This is done by calling `civo volume resize volume_id new_size` where `new-size` is in gigabytes:\n```\n$ civo volume resize 9b232ffa-7e05-45a4-85d8-d3643e68952e 30\nResized volume CLI-demo-volume with ID 9b232ffa-7e05-45a4-85d8-d3643e68952e to be 30GB\n```\n\n#### Deleting Volumes\n\nTo free up quota and therefore the amount to be billed to your account, you can delete a volume through `civo volume delete volume_id`. This deletion is immediate:\n```\n$ civo volume delete 9b232ffa-7e05-45a4-85d8-d3643e68952e\nRemoved volume CLI-demo-volume with ID 9b232ffa-7e05-45a4-85d8-d3643e68952e (was 30GB)\n$ civo volume list\n+----+------+---------+-----------+\n| ID | Name | Mounted | Size (GB) |\n+----+------+---------+-----------+\n+----+------+---------+-----------+\n```\n\n## Development\n\nAfter checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.\n\nTo install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).\n\nFor more information on some commonly used Gems in this project see:\n\n* [Civo API](https://github.com/absolutedevops/civo-ruby)\n* [Thor](http://whatisthor.com/)\n* [Terminal Table](https://github.com/tj/terminal-table)\n* [Colorize](https://github.com/fazibear/colorize)\n\n## Contributing\n\nBug reports and pull requests are welcome on GitHub at https://github.com/civo/cli.\n\n## License\n\nThe gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcivo%2Fcli-rubygem","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcivo%2Fcli-rubygem","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcivo%2Fcli-rubygem/lists"}