Hcloud Setup

hcloud CLI Setup and Configuration

Installation

Manual (GitHub Releases)

Download pre-built binaries from GitHub releases. Extract and move the binary to a directory in your PATH.

Example for 64-bit Linux:

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

Go

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

Note: Binaries built with Go will not have the correct version embedded.

Homebrew (Linux / macOS)

brew install hcloud

Windows

WinGet:

winget install HetznerCloud.CLI

Scoop:

scoop install hcloud

Note: The WinGet and Scoop package entries are not maintained by Hetzner.

Docker

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

To persist configuration, mount the config file:

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

Interactive shell:

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

Debian-based distributions (using apt) provide outdated versions of the hcloud CLI. Use one of the other installation methods instead.

Shell Completion

Bash

Load into current shell:

source <(hcloud completion bash)

Make permanent by adding the line above to ~/.bashrc.

Zsh

Generate the completion file:

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

Add to ~/.zshrc (the fpath line must come before compinit):

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

Restart the shell for changes to take effect.

Fish

Permanent installation:

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

Load into current shell only:

hcloud completion fish | source

PowerShell

Save completion script:

hcloud completion powershell > hcloud.ps1

Load into current shell:

hcloud completion powershell | Out-String | Invoke-Expression

Source the saved file from your PowerShell profile for persistence.

Context Management

Contexts manage multiple Hetzner Cloud API tokens and per-project configuration.

Create a context

hcloud context create <name>

Prompts interactively for an API token. To use the HCLOUD_TOKEN environment variable instead:

hcloud context create --token-from-env <name>

Switch context

hcloud context use <context>

Show active context

hcloud context active

List all contexts

hcloud context list [options]

Available columns: active, name.

Delete a context

hcloud context delete <context>

Rename a context

hcloud context rename <context> <name>

Unset active context

hcloud context unset

Config Management

Configuration file location: ~/.config/hcloud/cli.toml

Config hierarchy (highest to lowest priority)

1. Flags
2. Environment variables
3. Configuration file (context)
4. Configuration file (global)
5. Default values

Set a value

hcloud config set <key> <value>...

Get a value

hcloud config get <key>

List configuration

hcloud config list

Add values to a list

hcloud config add <key> <value>...

Remove values from a list

hcloud config remove <key> <value>...

Unset a value

hcloud config unset <key>

Preference keys

These keys can be used with set, unset, add, and remove:

Non-preference keys (read-only via config)

These cannot be modified with hcloud config set or hcloud config unset, but can be retrieved with hcloud config get and hcloud config list.

Global Flags

These flags are inherited by all commands:

Output Formatting

JSON output

Supported by describe, list, and create commands. Lists return an array, describe returns an object.

hcloud server list --output json
hcloud server describe my-server --output json

Use with jq for filtering:

hcloud server list -o json | jq '.[] | .name'

YAML output

Supported by describe, list, and create commands.

hcloud server list --output yaml

Use with yq for filtering:

hcloud server list --output yaml | yq '.[] | .name'

Go template format (describe only)

hcloud server describe my-server --output format='{{.ServerType.Cores}}'

Table options (list only)

Remove the table header:

hcloud server list --output noheader

Select specific columns:

hcloud server list --output columns=id,name

Combine options:

hcloud server list --output noheader --output columns=id,name

Use --help on any list command to see all available columns.

Other Commands

Print version

hcloud version

List all resources

hcloud all list [options]

Lists all resources in the project (Servers, Images, Placement Groups, Primary IPs, ISOs, Volumes, Load Balancers, Floating IPs, Networks, Firewalls, Certificates, SSH Keys, Storage Boxes, Zones). Does not include static/public resources like Locations or public ISOs.