How-to: Hetzner Cloud CLI

Introduction

In this how-to you will learn to use the hcloud-cli. This includes how to create, list and delete servers and how to do more complex scenarios like attaching a volume to a server.

Prerequisites

Hetzner Cloud API Token
- Basic knowledge about the Hetzner Cloud
  - We assume that you know, what a server, an image, a server type or a volume is.
- Visit Hetzner Cloud Console at https://console.hetzner.cloud, select your project, and create a new API Token.
hcloud-cli is installed
- Windows, FreeBSD
  - Grab your pre-built binary from Github
- Linux
  - Using Homebrew
    - brew install hcloud
  - Grab your pre-built binary from Github
- MacOS
  - Using Homebrew
    - brew install hcloud
  - Grab your pre-built binary from Github

Step 1 - Basic Usage

After the installation, you should open a terminal and just type:

hcloud

You should see an overview of all available commands like, server, volume or context. You can see the current version of your hcloud-cli installation with:

hcloud version

The most commands have some subcommands like:

hcloud server list

You can see an overview of all available subcommands by just typing the command. See sample output for hcloud server below

Usage:
  hcloud server
  hcloud server [command]

Available Commands:
  add-label          Add a label to a server
  attach-iso         Attach an ISO to a server
  change-type        Change type of a server
  create             Create a server
  create-image       Create an image from a server
  delete             Delete a server
  describe           Describe a server
  detach-iso         Detach an ISO from a server
  disable-backup     Disable backup for a server
  disable-protection Disable resource protection for a server
  disable-rescue     Disable rescue for a server
  enable-backup      Enable backup for a server
  enable-protection  Enable resource protection for a server
  enable-rescue      Enable rescue for a server
  list               List servers
  poweroff           Poweroff a server
  poweron            Poweron a server
  reboot             Reboot a server
  rebuild            Rebuild a server
  remove-label       Remove a label from a server
  reset              Reset a server
  reset-password     Reset the root password of a server
  set-rdns           Change reverse DNS of a server
  shutdown           Shutdown a server
  ssh                Spawn an SSH connection for the server
  update             Update a server

Flags:
  -h, --help   help for server

Global Flags:
      --poll-interval duration   Interval at which to poll information, for example action progress (default 500ms)

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

If you want to see all available parameters for a (sub-)command you can always use the --help-flag, the output below is a sample output for hcloud server list --help:

Displays a list of servers.

Output can be controlled with the -o flag. Use -o noheader to suppress the
table header. Displayed columns and their order can be set with
-o columns=backup_window,datacenter (see available columns below).

Columns:
 - backup_window
 - datacenter
 - id
 - ipv4
 - ipv6
 - labels
 - location
 - locked
 - name
 - protection
 - rescue_enabled
 - status
 - type
 - volumes

Usage:
  hcloud server list [FLAGS]

Flags:
  -h, --help                 help for list
  -o, --output stringArray   output options: noheader|columns=...
  -l, --selector string      Selector to filter by labels

Global Flags:
      --poll-interval duration   Interval at which to poll information, for example action progress (default 500ms)

Step 2 - Add a context

Before you can start using the hcloud-cli you need to have a context available. A context is a specific API Token from the Hetzner Cloud Console. We have chosen context as a reference to the kubectl for Kubernetes. So you can assume in our hcloud-cli a context is a project in the Hetzner Cloud Console.

You can add as many contexts as you want.

Create a hcloud-cli context with the command hcloud context create and add a free choosable name.

hcloud context create my-super-project

This command will create a new context called my-super-project. After the command, you will be prompted to enter your API token. Keep in mind, the token is not visible while you are entering it. Press enter when you have entered the token. You should see a confirmation message Context my-super-project created and activated.

Now you should see an active context when you run

hcloud context list

The output should be similar to:

ACTIVE   NAME
*        my-super-project

Congratulations! You have created your first context, let's go to the next step!

Step 3 - Add a server

You have already set up your context, now you can create a new server with hcloud server create and use it!

First of all, you need to know which server you want to create. You can see a list of all available server types with:

hcloud server-type list

You should see an output similar to:

ID   NAME        CORES   MEMORY     DISK     STORAGE TYPE
1    cx23        1       2.0 GB     20 GB    local
[...]

We want to create the cheapest server, a cx23. Now just save this information in your mind, you will need it later!

Then we need an image, which should be the base of the server. The Hetzner Cloud supports a various range of images. You can list all available images with: hcloud image list

You can grab any image you want from there, we will choose ubuntu-24.04 for this tutorial.

So now you have all values which are needed for creating a basic server!

The command to create a server is hcloud server create, so if you want to create a server with the server type cx23 and the image ubuntu-24.04 just run the following command in your console

hcloud server create --image ubuntu-24.04 --type cx23 --name my-cool-server

Cool! You now created a server called my-cool-server! After the creation finished you should see a similar output like:

Waiting for server 1234 to have started... done
Server 1234 created
IPv4: <10.0.0.1>
Root password: TmRsdC3NCgHAbnf9f3rq

You can now connect to your server via SSH with the Root password! Please note, for security purposes it's always recommended to setup key based ssh-access.

Step 4 - Describe a server

You have created a new server in the last step and now you want to show more details about your server? With hcloud server describe you can see all available information about your server.

hcloud server describe my-cool-server

You can now see all the information about the server:

ID:        1234
Name:        my-cool-server
Status:        running
Created:    Wed Mar  6 15:17:22 CET 2019 (17 minutes ago)
Server Type:    cx23 (ID: 1)
  ID:        1
  Name:        cx23
  Description:    CX23
  Cores:    1
  Memory:    2 GB
  Disk:        20 GB
  Storage Type:    local
Public Net:
  IPv4:
    IP:        <10.0.0.1>
    Blocked:    no
    DNS:    static.10.101.203.116.clients.your-server.de
  IPv6:
    IP:        <2001:db8::/64>
    Blocked:    no
  Floating IPs:
    No Floating IPs
Volumes:
  - ID:        1986518
    Name:    my-volume
    Size:    123 GB
Image:
  ID:        168855
  Type:        system
  Status:    available
  Name:        ubuntu-24.04
  Description:    Ubuntu 24.04
  Image size:    -
  Disk size:    5 GB
  Created:    Wed May  2 13:02:30 CEST 2018 (10 months ago)
  OS flavor:    ubuntu
  OS version:    24.04
  Rapid deploy:    yes
Datacenter:
  ID:        2
  Name:        nbg1-dc3
  Description:    Nuremberg 1 DC 3
  Location:
    Name:        nbg1
    Description:    Nuremberg DC Park 1
    Country:        DE
    City:        Nuremberg
    Latitude:        49.452102
    Longitude:        11.076665
Traffic:
  Outgoing:    0 B
  Ingoing:    0 B
  Included:    22 TB
Backup Window:    Backups disabled
Rescue System:    disabled
ISO:
  No ISO attached
Protection:
  Delete:    no
  Rebuild:    no
Labels:
  No labels

Step 5 - List all servers

Do you want to show which servers are in your context? With hcloud server list you can list all of your servers in your context. You should see a similar output like below:

ID        NAME             STATUS    IPV4             IPV6                      DATACENTER
1234      my-cool-server   running   <10.0.0.1>       <2001:db8::/64>           nbg1-dc3

Step 6 - Delete a server

Do you want to delete your server? No problem! You can use the hcloud server delete command!

hcloud server delete my-cool-server

After this you will get a confirmation:

Server 1234 deleted

Step 7 - Create a volume and attach it to a server

In the last steps, we have covered how you can create, list and delete servers. Now I want to show you a little more complex example. We will create a server and then create a volume and attach the volume to the server!

First of all, let's create a server:

hcloud server create --image ubuntu-24.04 --type cx23 --name my-cool-server

Waiting for server 1234 to have started... done
Server 1234 created
IPv4: <10.0.0.1>
Root password: TmRsdC3NCgHAbnf9f3rq

Now we create a volume, which is a similar command to the server creation:

hcloud volume create --size 123 --name my-volume --server my-cool-server

With this command, we will create a volume with the size 123 (GB) and the name my-volume and we attach it to the server my-cool-server.

You should see a similar output like:

   1s [====================================================================] 100%
Waiting for volume 123 to have been attached to server 1234... done
Volume 123 created

You can now detach the volume from the server by calling:

hcloud volume detach my-volume

Congratulations! You have created a volume and attached it to a server!

Conclusion

You have learned how to use the hcloud-cli. We have covered how to create, list and delete servers and how to do more complex scenarios like attaching a volume to a server. You can find more help by adding the --help-flag to every command. If you need deeper help, just open an issue on our Github Repository.

How-to: Hetzner Cloud CLI

Author

Published

Time to read

Table of Contents