setup-hcloud-cli.md

Setup the hcloud CLI

This tutorial will guide you through the process of setting up the hcloud CLI on your local machine.

Prerequisites:

Before you begin, ensure you have the following:

• A Hetzner Console account.

---

1. Install the hcloud CLI

   Click on one of the options below to view the respective steps.

   Manual installation

   You can download pre-built binaries from our GitHub releases. Install them by extracting the archive and moving the binary to a directory in your PATH.

   On a 64-bit Linux system, it could look something like this:

   curl -sSLO https://github.com/hetznercloud/cli/releases/latest/download/hcloud-linux-amd64.tar.gz
   sudo tar -C /usr/local/bin --no-same-owner -xzf hcloud-linux-amd64.tar.gz hcloud
   rm hcloud-linux-amd64.tar.gz

   ℹ️ Note This installation method does not provide automatic updates. Please make sure to keep your installation up to date manually.

   
   

   Installation using Go

   If you have Go installed, you can also install hcloud CLI from source using the following command:

   go install github.com/hetznercloud/cli/cmd/hcloud@latest

   ℹ️ Note Binaries built with Go will not have the correct version embedded. This installation method does not provide automatic updates. Please make sure to keep your installation up to date manually.

   
   

   Installation using .deb package (Debian/Ubuntu)

   On Debian and Ubuntu-based distributions, you can install the hcloud CLI using the .deb package:

   ⚠️ Warning Debian packages are experimental and might change or break in the future.

   1. Download the latest .deb package from the GitHub releases page.

   2. Install the package using dpkg:

   # Download the package (replace with the actual version and architecture)
   curl -sSLO https://github.com/hetznercloud/cli/releases/latest/download/hcloud-cli_<version>_linux_amd64.deb
   
   # Install the package
   sudo dpkg -i hcloud-cli_<version>_linux_amd64.deb

   The .deb package includes shell completions for bash, zsh, and fish, as well as man pages.

   
   

   Installation using .rpm package (Fedora/RHEL/CentOS)

   On Fedora, RHEL, CentOS, and other RPM-based distributions, you can install the hcloud CLI using the .rpm package:

   ⚠️ Warning RPM packages are experimental and might change or break in the future.

   1. Download the latest .rpm package from the GitHub releases page.

   2. Install the package using rpm or dnf:

   # Download the package (replace with the actual version and architecture)
   curl -sSLO https://github.com/hetznercloud/cli/releases/latest/download/hcloud-cli-<version>-1.x86_64.rpm
   
   # Install using dnf (Fedora/RHEL 8+/CentOS 8+)
   sudo dnf install hcloud-cli-<version>-1.x86_64.rpm
   
   # Or install using rpm
   sudo rpm -i hcloud-cli-<version>-1.x86_64.rpm

   The .rpm package includes shell completions for bash, zsh, and fish, as well as man pages.

   
   

   Installation using Homebrew

   On Linux and macOS you can also install the hcloud CLI using Homebrew:

   brew install hcloud

   
   

   Installation on Windows using WinGet or Scoop

   On Windows, you can install hcloud using WinGet (Windows Package Manager) or Scoop:

   ⚠️ Warning The WinGet and Scoop package entries are not maintained by Hetzner.

   winget install HetznerCloud.CLI

   scoop install hcloud

   
   

   Using hcloud with Docker

   Instead of installing hcloud on the host, you can also use our docker image at hetznercloud/cli.

   docker run --rm -e HCLOUD_TOKEN="<your token>" hetznercloud/cli:latest <command>

   If you want to use (and persist) your configuration, you can mount it to /config.toml:

   docker run --rm -v ~/.config/hcloud/cli.toml:/config.toml hetznercloud/cli:latest <command>

   The image is based on Alpine Linux, so a shell is available in the image. You can use it to run commands interactively:

   docker run -it --rm --entrypoint /bin/sh hetznercloud/cli:latest

   ⚠️ Warning Some third-party package repositories may provide outdated versions of the hcloud CLI. Please consider one of the other installation methods.

2. Setup auto-completion (Optional)

   hcloud CLI offers auto-completion for bash, zsh, fish and PowerShell. It is recommended to enable it for a better user experience.

   Click on one of the options below to view the respective steps.

   Bash

   To load completions into the current shell execute:

   source <(hcloud completion bash)

   In order to make the completions permanent, append the line above to your .bashrc.

   
   

   Zsh

   If shell completions are not already enabled for your environment need to enable them. Add the following line to your ~/.zshrc file:

   autoload -Uz compinit; compinit

   To load completions for each session execute the following commands:

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

   Finally add the following line to your ~/.zshrc file, before you call the compinit function:

   fpath+=(~/.config/hcloud/completion/zsh)

   In the end your ~/.zshrc file should contain the following two lines in the order given here.

   fpath+=(~/.config/hcloud/completion/zsh)
   #  ... anything else that needs to be done before compinit
   autoload -Uz compinit; compinit
   # ...

   You will need to start a new shell for this setup to take effect.

   
   

   Fish

   To load completions into the current shell execute:

   hcloud completion fish | source

   In order to make the completions permanent execute once:

   hcloud completion fish > ~/.config/fish/completions/hcloud.fish

   
   

   PowerShell

   To load completions into the current shell execute:

   PS> hcloud completion powershell | Out-String | Invoke-Expression

   To load completions for every new session, run and source this file from your PowerShell profile.

   PS> hcloud completion powershell > hcloud.ps1

   
   

3. Create a context

   The hcloud CLI uses contexts to manage multiple Hetzner Cloud tokens and set configuration preferences.

   First, you need to create an API token. Follow the instructions in the Hetzner Cloud documentation to create your project API token.

   Once you have your token, you can create a context using the following command:

   hcloud context create <context-name>

   Ideally, keep the context name similar to the project name so you can easily identify it later.

   When prompted, enter the API token you created earlier. Your context should now be created and activated.

4. Verify everything works

   To verify that the hcloud CLI is working correctly, you can run the following command:

   hcloud location list

   You should see something like this:

   ID   NAME   DESCRIPTION             NETWORK ZONE   COUNTRY   CITY
   1    fsn1   Falkenstein DC Park 1   eu-central     DE        Falkenstein
   2    nbg1   Nuremberg DC Park 1     eu-central     DE        Nuremberg
   3    hel1   Helsinki DC Park 1      eu-central     FI        Helsinki
   4    ash    Ashburn, VA             us-east        US        Ashburn, VA
   5    hil    Hillsboro, OR           us-west        US        Hillsboro, OR
   6    sin    Singapore               ap-southeast   SG        Singapore
   

   If you see this output, congratulations! You have successfully set up the hcloud CLI on your local machine.

If there are any problems, make sure you followed all steps of this tutorial correctly. If there still are problems, you can reach out to our Support to get help.