Manage VM Instances on Hetzner Cloud using hcloud CLI

Posted on 95 views

The Hetzner Cloud is a consistent, reliable, and cost-effective platform that provides web hosting, dedicated servers, colocation, and custom hosting solutions. Using this platform, you can also use the Hetzner Cloud module for HostBill to sell VPS hosting and resell the virtual instances.

The Hetzner cloud servers are located in Germany and Finland in the Hetzner state-of-the-art data centers. Hetzner also provides cloud services in the USA at a partner data center. Hetzner cloud offers incredible performance at a starting fee of € 3.49 per month. With a little fee, you get AMD EPYC™ 2nd Gen, Intel® Xeon® Gold processors with speedy NVMe SSDs.

The other features associated with the Hetzner Cloud platform are:

  • Block Storage Volumes: the cloud can always be expanded with SSD-based storage as needed. The volumes go up to 10TB and up to 16 volumes per cloud server.
  • Load balancers: they help to easily scale your applications and distribute the load across your infrastructure.
  • Primary IPs: you can assign primary IPs to your server that can be used to establish a connection to the internet. Alternatively, you can create a private-network-only cloud server by not adding any Primary IPs. These options can be changed when required.
  • Firewalls: stateful firewalls are provided to make it easy to secure your infrastructure at no additional cost
  • Documentation and API: due to the many features available, you have documentation to help you navigate easily. There is also a REST-API and a CLI tool for developers.
  • Snapshots: this feature allows you to manually take backups of the servers and revert to them when required. You can also use the saved images to create new cloud servers.
  • Traffic: Hetzner provides up to 20 TB of traffic to help provide you with enough bandwidth for your projects.

There are several ways one can access and use the VM Instances on Hetzner Cloud. The available options are:

  • Using a web interface
  • Using the CLI
  • Automation through APIs such as terraform

The hcloud is a command line tool that helps you manage the VM Instances on Hetzner Cloud with ease. This tool eliminates the complexity involved when creating, listing, and deleting the VM instances on Hetzner Cloud. It also supports more complex scenarios such as attaching volumes to the server e.t.c

In this guide, we will learn how to manage VM Instances on Hetzner Cloud Using hcloud CLI.


To be able to use hcloud you need:

  • Basic knowledge about the Hetzner Cloud.
    • We assume that you know what is a server, an image, a server type or volume
  • Hetzner Cloud API Token: this can be created by visiting the Hetzner Cloud, create a project, and a new API token

Step 1 – Install hcloud Hetzner Cloud CLI

hcloudcan be installed on FreeBSD, Linux, macOS, and Windows systems. This can be achieved as shown below:

Install hcloud on Windows

You can install hcloud on Windows using Scoop with the command:

scoop install hcloud

Alternatively, you can download a pre-built binary for Windows from the releases page. You can also use wget to pull the archive:

##For AMD64

##For ARM64

##For i386$VER/

Install hcloud on macOS

It is also possible to install hcloud on macOS. This can either be done using Homebrew with the command:

brew install hcloud

Or use pre-built binaries from the releases page. Use wget to pull the archive:

VER=$(curl -s|grep tag_name|cut -d '"' -f 4|sed 's/v//')

##For AMD64

##For ARM64

Once downloaded, extract the file with the command:

tar -xvf hcloud-darwin-*.tar.gz

Install hcloud by copying the binary to your PATH:

sudo mv hcloud /usr/local/bin/

To verify the installation, use the command:

hcloud version

Install hcloud on Linux

You can install hcloud using Linuxbrew on Linux:

brew install hcloud

You can also use pre-built binaries downloaded from the releases page. These files can be downloaded using wget:

VER=$(curl -s|grep tag_name|cut -d '"' -f 4|sed 's/v//')

##For AMD64

##For ARM64

##For i386

Once downloaded, extract the file with the command:

tar -xvf hcloud-linux-*.tar.gz

Install hcloud by copying the binary to your PATH:

sudo mv hcloud /usr/local/bin/

To verify the installation, use the command:

$ hcloud version

Step 2 – Configure hcloud autocompletion

Once installed, you can configure TAB completion for hcloud. To achieve this, configure your shell as below

  • For Bash
echo "source <(hcloud completion bash)" | tee -a ~/.bashrc

Source your profile:

source ~/.bashrc
  • For Zsh

Enable shell completions on Zsh as shown:

sudo tee -a ~/.zshrc<

Source the profile:

source ~/.zshrc

To load shell completions for each session, proceed as shown:

mkdir -p ~/.config/hcloud/completion/zsh
hcloud completion zsh > ~/.config/hcloud/completion/zsh/_hcloud

Edit the Zsh file as shown:

$ vim ~/.zshrc
autoload -Uz compinit; compinit
  • For Fish

For Fish, use the command below to make the completions:

hcloud completion fish | source
hcloud completion fish > ~/.config/fish/completions/
  • PowerShell

To load the shell completions on PowerShell, use the commands:

##For Current shell
hcloud completion powershell | Out-String | Invoke-Expression

##For changes to persist
hcloud completion powershell > hcloud.ps1

Step 3 – Manage Instances on Hetzner Cloud using hcloud

At this time, you are set to use hcloud to manage instances on Hetzner Cloud. First, you need to configure the environment variables. The following are the variable involved:


There are two ways of setting the variables, you can export them directly for example:

export HCLOUD_CONTEXT=my-context

For Token:


You can also make the settings in a .envrc file.

We will now learn how to create and manage VM Instances on Hetzner Cloud with hcloud. There are several commands that can be used here. To view all the commands, use the command:

$ hcloud help
A command-line interface for Hetzner Cloud

  hcloud [command]

Available Commands:
  certificate        Manage certificates
  completion         Output shell completion code for the specified shell
  context            Manage contexts
  datacenter         Manage datacenters
  firewall           Manage Firewalls
  floating-ip        Manage Floating IPs
  help               Help about any command
  image              Manage images
  iso                Manage ISOs
  load-balancer      Manage Load Balancers
  load-balancer-type Manage Load Balancer types
  location           Manage locations
  network            Manage networks
  placement-group    Manage Placement Groups
  primary-ip         Manage Primary IPs
  server             Manage servers
  server-type        Manage server types
  ssh-key            Manage SSH keys
  version            Print version information
  volume             Manage Volumes

  -h, --help                     help for hcloud
      --poll-interval duration   Interval at which to poll information, for example action progress (default 500ms)

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

To view the subcommands, add the –help flag to the above command:

hcloud server list --help

1. Add a Context

Before you begin working on Hetzner Cloud with hcloud, you need to have a context. A context can be defined as an API Token from the Hetzner Cloud Console. This is simply created in a project on the Hetzner Cloud Console.

To create a context provide the name:

hcloud context create my-sample-project

Provide an API token(for the project) in order to create the context.

Context my-sample-project created and activated

Once created, list the contexts with the command:

$ hcloud context list
*        my-sample-project

2. Add a Server

Once a context is set up, you can now add a server on Hetzner Cloud. First, list the available server types:

$ hcloud server-type list
1    cx11    1       shared      2.0 GB     20 GB    local
3    cx21    2       shared      4.0 GB     40 GB    local
5    cx31    2       shared      8.0 GB     80 GB    local
7    cx41    4       shared      16.0 GB    160 GB   local
9    cx51    8       shared      32.0 GB    240 GB   local
11   ccx11   2       dedicated   8.0 GB     80 GB    local
12   ccx21   4       dedicated   16.0 GB    160 GB   local
13   ccx31   8       dedicated   32.0 GB    240 GB   local
14   ccx41   16      dedicated   64.0 GB    360 GB   local

For example, if you want to create a cx11 server type, you need to save this in mind since you will use it later.

Also, list the available images that act as the base for your system.

$ hcloud image list
3          system   centos-7             CentOS 7             -            5 GB        Mon Jan 15 12:34:45 CET 2018    -
168855     system   ubuntu-18.04         Ubuntu 18.04         -            5 GB        Wed May  2 13:02:30 CEST 2018   -
5924233    system   debian-10            Debian 10            -            5 GB        Mon Jul  8 08:35:48 CEST 2019   -
15512617   system   ubuntu-20.04         Ubuntu 20.04         -            5 GB        Thu Apr 23 19:55:14 CEST 2020   -
40093247   app      docker-ce            docker-ce            -            20 GB       Tue Jun  8 08:22:47 CEST 2021   -
40093435   app      gitlab               gitlab               -            20 GB       Tue Jun  8 08:24:08 CEST 2021   -
45557056   system   debian-11            Debian 11            -            5 GB        Mon Aug 16 13:12:01 CEST 2021   -
45778012   system   centos-stream-8      CentOS Stream 8      -            5 GB        Thu Aug  5 07:07:23 CEST 2021   -
45780948   system   rocky-8              Rocky Linux 8        -            5 GB        Thu Aug 19 08:30:23 CEST 2021   -
67794396   system   ubuntu-22.04         Ubuntu 22.04         -            5 GB        Thu Apr 21 15:32:38 CEST 2022   -
69726282   system   fedora-36            Fedora 36            -            5 GB        Wed May 11 07:50:00 CEST 2022   -
71127104   app      ruby                 ruby                 -            20 GB       Wed May 25 12:06:36 CEST 2022   -

Now you can choose the preferred image for your system. For this guide, we will go for Ubuntu 22.04

Now create the server with the hcloud server createcommand as shown below:

hcloud server create --image ubuntu-22.04 --type cx11 --name Ubuntu22-server

Sample Output:


3. Describe a server

Once the desired servers have been created, you can view details related to a preferred server. List the available servers in the context.

$ hcloud server list
ID         NAME              STATUS    IPV4              IPV6                     PRIVATE NET   DATACENTER
23151785   Ubuntu22-server   running   168.*.*.*   2a01:*******::/64   -             nbg1-dc3

Check the details related to a server

hcloud server describe <server-name>

For example;


4. Create an additional volume

It is also possible to perform complex settings with hcloud. For example, if you want to create an extra disk and attach it to an existing server, you can use the command with the following syntax:

hcloud volume create --size 20 --name my-volume --server Ubuntu22-server

In the command:

  • 20 is the size of the volume in GB
  • my-volume is the name of the volume
  • Ubuntu22-server is the name of the server to which the volume will be attached.

Once created, you will see the below output:

3.0s [===================================] 100.00%
Waiting for volume 22221892 to have been attached to server 23151785
 ... done                                                                                                                                   
Volume 22221892 created

To detach the volume from the server, use the command:

$ hcloud volume detach my-volume
2.0s [===================================] 100.00%
Volume 22221892 detached

5. Delete a server

If you do not need a server anymore and you want to delete it from the Hetzner Cloud, you can easily do that from the CLI.

For example:

$ hcloud server delete Ubuntu22-server
Server Ubuntu22-server deleted

It is that easy!

This guide provides the required knowledge on how to install and get started with the hcloud CLI. There are many other configurations you can perform on Hetzner Cloud Using hcloud CLI. I believe you are now set to explore them on your own.


Gravatar Image
A systems engineer with excellent skills in systems administration, cloud computing, systems deployment, virtualization, containers, and a certified ethical hacker.