UpCloud Command-Line Interface, or UpCloud CLI for short, is a text-based user interface to UpCloud\u2019s Infrastructure-as-a-service. It provides a fast command-line tool for accessing and managing your UpCloud resources.<\/p>\n\n\n\n
UpCloud CLI allows you to control your Cloud Servers, storage and networking from your local command line with simple and intuitive command structures. It\u2019s offered as an addition to the current methods such as the UpCloud Control Panel and API for all users but especially developers and system administrators will likely find it highly useful!<\/p>\n\n\n\n
In this tutorial, we\u2019ll show you how to install the UpCloud CLI on your own computer and go over some of the basic functions.<\/p>\n\n\n\n
Before you can begin, you first need to enable API access to your UpCloud account.<\/p>\n\n\n\n
We recommend creating a separate workspace username and password for every API integration for easier access control. To do so, go to your UpCloud Control Panel<\/a> under the People section.<\/p>\n\n\n\n You can find more detailed instructions on API credentials in our tutorial for getting started with UpCloud API<\/a>.<\/p>\n\n\n\n Afterwards, you need to store your API credentials on your own computer.<\/p>\n\n\n\n To do so, create a config file called upctl.yaml<\/tt> with user credentials in the .config<\/tt> folder in your home directory ($HOME\/.config\/upctl.yaml)<\/p>\n\n\n\n Alternatively, your credentials can also be stored in the environment variables UPCLOUD_USERNAME and UPCLOUD_PASSWORD. If the variables are set, matching config file items are ignored.<\/p>\n\n\n\n Now that you\u2019ve enabled API access to your UpCloud account, you can get started.<\/p>\n\n\n\n Go ahead and download the latest release of the UpCloud CLI<\/a> from our GitHub repository. Pick the release as appropriate for your operating system.<\/p>\n\n\n\n Then make the file executable and move it to a directory found in your PATH environmental variable. For example, the following commands will do the trick on most Linux systems.<\/p>\n\n\n\n On macOS, you can install the command-line interface using Brew. First, add the repository and then run the install command as shown below.<\/p>\n\n\n\n UpCloud CLI also supports bash-completion but setting it up requires a few more commands.<\/p>\n\n\n\n UpCloud CLI is available for a number of popular distributions e.g. Debian, Ubuntu and Arch Linux.<\/p>\n\n\n\n AUR<\/strong><\/p>\n\n\n\n On Arch Linux, you can install the CLI with the following command.<\/p>\n\n\n\n Ubuntu and other Debian based distributions<\/strong><\/p>\n\n\n\n Use the package corresponding to your Linux distribution, such as deb, rpm, or apk. For example, to install UpCloud CLI on Debian or Ubuntu, use the following commands.<\/p>\n\n\n\n Other Linux distributions<\/strong><\/p>\n\n\n\n If you can\u2019t find a package applicable to your flavour of Linux, you can always use the precompiled version. Download and extract the CLI to a suitable location, for example, $HOME\/.local\/bin<\/tt> directory.<\/p>\n\n\n\n Bash completion can also be set up with some extra commands. You should adapt this for your package manager.<\/p>\n\n\n\n Windows users can also make use of the UpCloud Command-Line Interface. Simply download the ZIP file, extract it and run the portable executable. No installation is required.<\/p>\n\n\n\n Once you\u2019ve enabled API access and installed the UpCloud CLI, you are ready to get cracking.<\/p>\n\n\n\n First, check the top-level command options. The help output is printed by default on most commands to make the CLI easy to explore and learn.<\/p>\n\n\n\n If the CLI is working, test that it is able to access your UpCloud API credentials.<\/p>\n\n\n\n Account<\/strong> command lets you check the details of your UpCloud account.<\/p>\n\n\n\n Server<\/strong> command is a top-level command that you will likely be using a fair bit. Run the following command to list all Cloud Servers your API account has permission to.<\/p>\n\n\n\n Storage<\/strong> command can be used to manage both your own cloud storage devices as well as explore the public templates. The next command will list all public templates.<\/p>\n\n\n\n The command outputs can also be piped to other command-line tools. For example, use grep to narrow down the list of templates to find a specific public template.<\/p>\n\n\n\n Other commands include options for managing your networking such as static and floating IP addresses, SDN Private networks and SDN Routers. We\u2019ll go more into detail on this further ahead in this tutorial.<\/p>\n\n\n\n One of the main benefits of the UpCloud CLI is the speed and ease of managing your cloud services. For example, deploying a new Cloud Server takes but a single command.<\/p>\n\n\n\n The example below deploys a new Cloud Server using the 2xCPU-4GB Simple plan running Debian 10. It also allows you to secure the server right from deployment by enabling SSH keys and disabling password login.<\/p>\n\n\n\n You can find the full detailed list of the configuration parameters using the command below.<\/p>\n\n\n\n Once deployed, check the status of the new server.<\/p>\n\n\n\n Notice how using the UpCloud CLI, you do not need to remember UUIDs. Rather most resources can be addressed by their name as in the example command below.<\/p>\n\n\n\n The example output above shows the first few lines of details about the Cloud Server.<\/p>\n\n\n\n If you want to make changes to your Cloud Server, e.g. change the hostname or description, enable Firewall or Metadata, many of the changes can be done without shutting down the server.<\/p>\n\n\n\n However, if you want to change the server plan, you first need to shut down the server.<\/p>\n\n\n\n Wait a moment for the Cloud Server to shut down gracefully.<\/p>\n\n\n\n Afterwards, you can make changes to the server configuration.<\/p>\n\n\n\n Then start up the server again.<\/p>\n\n\n\n That\u2019s it! Your Cloud Server should then start up momentarily with the additional resources available right away.<\/p>\n\n\n\n All Cloud Servers deployed using Simple plans offer ample storage out of the gate but sometimes you just need more capacity. Luckily, UpCloud CLI offers quick and easy commands for creating additional storage devices and attaching them to your Cloud Server.<\/p>\n\n\n\n Furthermore, most storage operations can even be done without shutting down the server!<\/p>\n\n\n\n Create new storage devices<\/strong> by defining the type, size, and location, as well as naming the storage. For example, let\u2019s create a secondary MaxIOPS storage for our example.com Cloud Server.<\/p>\n\n\n\n Once created, you can query the storage devices for details using the command below.<\/p>\n\n\n\n Attaching storage<\/strong> devices to a server is as easy as creating them.<\/p>\n\n\n\n Note that here the storage device needs to be identified by its UUID. This can be found in the device details using the command above.<\/p>\n\n\n\n Then check the server details again to see that the new storage device was attached successfully.<\/p>\n\n\n\n Quick and easy! However, after attaching new storage devices, it\u2019s still necessary to finish the process at the operating system level. You can find out more about formatting the storage device in our tutorial on adding storage devices<\/a>.<\/p>\n\n\n\n Networking is also an important part of any cloud infrastructure and naturally, you can manage yours via the UpCloud CLI.<\/p>\n\n\n\n Creating SDN Private networks<\/strong> is a great way for securely connecting Cloud Servers. Let\u2019s test out the command-line interface by setting up a new SDN Private network for our example.com Cloud Server.<\/p>\n\n\n\n When done, check that the network you created was added to the list.<\/p>\n\n\n\n Now that we have our network ready, let\u2019s attach our Cloud Server to it.<\/p>\n\n\n\n First, however, we\u2019ll need to shut down the server.<\/p>\n\n\n\n The shutdown will take a second, once done you can continue.<\/p>\n\n\n\n Create a new network interface<\/strong> and attach SDN Private network<\/strong> to it with the command below. Note that with this command, the network needs to be addressed via its UUID.<\/p>\n\n\n\n Afterwards, start up the server again.<\/p>\n\n\n\n Besides networks, UpCloud CLI also allows you to manage your individual IP addresses.<\/p>\n\n\n\n Create a new floating IP address<\/strong> with the example command below.<\/p>\n\n\n\n Once created, the new floating IP will show up on the list of IP addresses. The command below will show all IP addresses reserved to your UpCloud account.<\/p>\n\n\n\n Attach the floating IP address<\/strong> to the example.com server with the next command. For this, you will need the MAC address of one of the public network interfaces on your Cloud Server. Commonly this should be the first public IP address on your Cloud Server. Check the output from upctl server show example.com<\/tt> to find the right one.<\/p>\n\n\n\n When attached, the floating IP address will show up to your Cloud Server. However, to enable network traffic through the floating IP, you would still need to configure it on the operating system level. Check out our other tutorials on OS-specific instructions for attaching floating IP addresses<\/a>.<\/p>\n\n\n\n Congratulations! By following along and completing the steps explained in this tutorial, you should now have a pretty good grasp of the UpCloud Command-Line Interface. It really makes it quick work managing your cloud infrastructure!<\/p>\n\n\n\n Additionally, using the UpCloud CLI, you could easily script and automate common tasks to further speed up your workflow. You might be surprised at how much can be accomplished with a few simple lines of clever commands.<\/p>\n","protected":false},"author":3,"featured_media":21010,"comment_status":"open","ping_status":"closed","template":"","community-category":[223],"class_list":["post-2065","tutorial","type-tutorial","status-publish","has-post-thumbnail","hentry"],"acf":[],"_links":{"self":[{"href":"https:\/\/upcloud.com\/global\/wp-json\/wp\/v2\/tutorial\/2065","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/upcloud.com\/global\/wp-json\/wp\/v2\/tutorial"}],"about":[{"href":"https:\/\/upcloud.com\/global\/wp-json\/wp\/v2\/types\/tutorial"}],"author":[{"embeddable":true,"href":"https:\/\/upcloud.com\/global\/wp-json\/wp\/v2\/users\/3"}],"replies":[{"embeddable":true,"href":"https:\/\/upcloud.com\/global\/wp-json\/wp\/v2\/comments?post=2065"}],"version-history":[{"count":0,"href":"https:\/\/upcloud.com\/global\/wp-json\/wp\/v2\/tutorial\/2065\/revisions"}],"wp:attachment":[{"href":"https:\/\/upcloud.com\/global\/wp-json\/wp\/v2\/media?parent=2065"}],"wp:term":[{"taxonomy":"community-category","embeddable":true,"href":"https:\/\/upcloud.com\/global\/wp-json\/wp\/v2\/community-category?post=2065"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}\n
username: your_upcloud_username\npassword: your_upcloud_password<\/pre>\n\n\n\n
Installing the UpCloud CLI<\/h2>\n\n\n\n
macOS<\/h3>\n\n\n\n
brew tap UpCloudLtd\/tap\nbrew install upcloud-cli<\/pre>\n\n\n\n
brew install bash-completion\nsudo upctl completion bash > \/usr\/local\/etc\/bash_completion.d\/upctl\necho \"[ -f \/usr\/local\/etc\/bash_completion ] && . \/usr\/local\/etc\/bash_completion\" >> ~\/.bash_profile . \/usr\/local\/etc\/bash_completion<\/pre>\n\n\n\n
Linux<\/h3>\n\n\n\n
yay -S upcloud-cli<\/pre>\n\n\n\n
sudo curl -L -o upcloud.deb https:\/\/github.com\/UpCloudLtd\/upcloud-cli\/releases\/download\/v<VERSION><\/span>\/upcloud-cli-<VERSION><\/span>_amd64.deb\nsudo dpkg -i upcloud.deb<\/pre>\n\n\n\nsudo curl -L -o upcloud-cli.tar.gz https:\/\/github.com\/UpCloudLtd\/upcloud-cli\/releases\/download\/v<VERSION>\/upcloud-cli_<VERSION>_linux_x86_64.tar.gz\ntar -C $HOME\/.local\/bin -xf upcloud-cli_<VERSION>_linux_x86_64.tar.gz<\/pre>\n\n\n\n
sudo apt install bash-completion\nupctl completion bash | sudo tee \/etc\/bash_completion.d\/upctl\necho \"[ -f \/etc\/bash_completion ] && . \/etc\/bash_completion\" >> ~\/.bash_profile . \/etc\/bash_completion<\/pre>\n\n\n\n
Windows<\/h3>\n\n\n\n
Invoke-WebRequest -Uri \"https:\/\/github.com\/UpCloudLtd\/upcloud-cli\/releases\/download\/v<VERSION><\/span>\/upcloud-cli-<VERSION><\/span>_windows_x86_64.zip\" -OutFile \"upcloud-cli.zip\"\nunzip upcloud-cli.zip\nupctl.exe -h<\/pre>\n\n\n\nTesting basic commands<\/h2>\n\n\n\n
upctl --help<\/pre>\n\n\n\n
Usage:\nupctl [command]\n\nAvailable Commands:\naccount Manage account\ncompletion Generates shell completion\nhelp Help about any command\nip-address Manage ip address\nnetwork Manage network\nrouter Manage router\nserver Manage servers\nstorage Manage storages\nversion Display software information<\/pre>\n\n\n\n
upctl account show<\/pre>\n\n\n\n
Username: maxupcloud \n Credits: 98.47$\n \n Resource Limits:\n Cores: 100 \n Detached Floating IPs: 0 \n Memory: 307200 \n Networks: 100 \n Public IPv4: 20 \n Public IPv6: 100 \n Storage HDD: 10240 \n Storage SSD: 10240<\/pre>\n\n\n\n
upctl server list<\/pre>\n\n\n\n
UUID Hostname Plan Zone State\n\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500 \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500 \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500 \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500 \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n 00229ddf-0e46-45b5-a8f7-cad2c8d11f6a server1 2xCPU-4GB de-fra1 stopped\n 003c9d77-0237-4ee7-b3a1-306efba456dc server2 1xCPU-2GB sg-sin1 started<\/pre>\n\n\n\n
upctl storage list --public<\/pre>\n\n\n\n
upctl storage list --public | grep Debian<\/pre>\n\n\n\n
01000000-0000-4000-8000-000020030101 Debian GNU\/Linux 8.6.0 (Jessie) Installation CD cdrom 1 online public 0001-01-01 00:00:00 +0000 UTC \n 01000000-0000-4000-8000-000020040100 Debian GNU\/Linux 9 (Stretch) template 3 online public 0001-01-01 00:00:00 +0000 UTC \n 01000000-0000-4000-8000-000020040101 Debian GNU\/Linux 9.0.0 (Stretch) Installation CD cdrom 1 online public 0001-01-01 00:00:00 +0000 UTC \n 01000000-0000-4000-8000-000020050100 Debian GNU\/Linux 10 (Buster) template 3 online public 0001-01-01 00:00:00 +0000 UTC \n 01000000-0000-4000-8000-000020050102 Debian GNU\/Linux 10.0.0 (Buster) Installation CD cdrom 1 online public 0001-01-01 00:00:00 +0000 UTC<\/pre>\n\n\n\n
Cloud Servers<\/h2>\n\n\n\n
upctl server create \n--zone de-fra1 \n--plan 2xCPU-4GB \n--os-storage-size 80 \n--os \"Debian GNU\/Linux 10 (Buster)\" \n--ssh-keys ~<\/span>\/.ssh\/id_rsa.pub \n--create-password false \n--hostname example.com \n--title \"Example server\"<\/pre>\n\n\n\nupctl server create --help<\/pre>\n\n\n\n
upctl server show example.com<\/pre>\n\n\n\n
Common\n UUID: 00eeab44-1670-4fc2-b858-c99477fdf78b \n Hostname: example.com \n Title: Example server \n Plan: 2xCPU-4GB \n Zone: de-fra1 \n State: started<\/span>\n...<\/pre>\n\n\n\nupctl server modify example.com --metadata true<\/pre>\n\n\n\n
upctl server stop example.com<\/pre>\n\n\n\n
upctl server modify example.com --plan 4xCPU-8GB<\/pre>\n\n\n\n
upctl server start example.com<\/pre>\n\n\n\n
Storage devices<\/h2>\n\n\n\n
upctl storage create \n --title example.com-storage1 \n --size 50 \n --zone de-fra1 \n --tier maxiops<\/pre>\n\n\n\n
upctl storage show example.com-storage1<\/pre>\n\n\n\n
upctl server storage attach example.com --storage 0116d96d-a655-4c45-b773-e729831c8df7<\/pre>\n\n\n\n
upctl server show example.com<\/pre>\n\n\n\n
...\n Storage: (Flags: B = bootdisk, P = part of plan)\n\n UUID Title Type Address Size (GiB) Flags \n \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500 \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500 \u2500\u2500\u2500\u2500\u2500\u2500 \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500 \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500 \u2500\u2500\u2500\u2500\u2500\u2500\u2500\n 019ec51c-f3ee-4112-ad89-d6396402181d example.com-osDisk disk virtio:0 80 P \n 0116d96d-a655-4c45-b773-e729831c8df7 example.com-storage1 disk virtio:1 50\n...<\/pre>\n\n\n\n
Networks and IP addresses<\/h2>\n\n\n\n
upctl network create --name sdn.example --zone de-fra1 --ip-network 'address=192.168.10.1\/24,dhcp=true'<\/pre>\n\n\n\n
upctl network list\n\n UUID Name Router Type Zone \n\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500 \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500 \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500 \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500 \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n 03ba4ed0-55f4-4832-8fab-efd7a6cc0f91 sdn.example private de-fra1<\/pre>\n\n\n\n
upctl server stop example.com<\/pre>\n\n\n\n
upctl server network-interface create example.com --network 03ba4ed0-55f4-4832-8fab-efd7a6cc0f91<\/pre>\n\n\n\n
upctl server start example.com<\/pre>\n\n\n\n
upctl ip-address assign --floating true --zone de-fra1<\/pre>\n\n\n\n
upctl ip-address list<\/pre>\n\n\n\n
Address Access Family Part of Plan PTR Record Server Floating Zone \n\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500 \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500 \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500 \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500 \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500 \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500 \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500 \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n 2a04:3542:1000:910:6cd7:1bff:febf:7605 public IPv6 no 6cd7-1bff-febf-7605.v6.de-fra1.upcloud.host 00eeab44-1670-4fc2-b858-c99477fdf78b no de-fra1 \n 10.4.15.153 utility IPv4 no 00eeab44-1670-4fc2-b858-c99477fdf78b no de-fra1 \n 94.237.98.120 public IPv4 no 94-237-98-120.de-fra1.upcloud.host yes de-fra1 \n 94.237.103.26 public IPv4 yes 94-237-103-26.de-fra1.upcloud.host 00eeab44-1670-4fc2-b858-c99477fdf78b no de-fra1<\/pre>\n\n\n\n
upctl ip-address modify 94.237.98.120 --mac 6e:d7:1b:bf:64:94<\/pre>\n\n\n\n
Conclusions<\/h2>\n\n\n\n