hetzner-cli

A powerful CLI tool for managing Hetzner Cloud and DNS resources including servers, volumes, networks, firewalls, floating IPs, load balancers, certificates, primary IPs, placement groups, and DNS zones/records.

Prefer an interactive interface? Check out @tomkp/hetzner-tui for a terminal UI experience.

Installation

npm install -g @tomkp/hetzner-cli

This will make the hz command available globally.

From source

git clone https://github.com/tomkp/hetzner-cli.git
cd hetzner-cli
npm install
npm run build
npm link

Configuration

API Tokens

You need API tokens to interact with Hetzner services:

• Cloud API Token: Manage servers, volumes, networks, firewalls, and SSH keys
• DNS API Token: Manage DNS zones and records

Get your tokens from the Hetzner Cloud Console.

Setting Tokens

Tokens can be provided in three ways (in order of priority):

1. CLI flags (highest priority):

   hz servers list --token <your-token>
   hz dns zones list --dns-token <your-dns-token>

2. Environment variables:

   export HETZNER_TOKEN=<your-token>
   export HETZNER_DNS_TOKEN=<your-dns-token>

3. Configuration file (lowest priority):

   hz config set token <your-token>
   hz config set dnsToken <your-dns-token>

Interactive Setup

For a guided configuration experience, use the setup wizard:

hz setup

This interactive wizard will:

1. Prompt for your Hetzner Cloud API token
2. Validate the token by connecting to the API
3. Prompt for your Hetzner DNS API token (optional)
4. Save valid tokens to the configuration file

Usage

Global Options

• -j, --json - Output in JSON format
• -t, --token <token> - Hetzner Cloud API token
• --dns-token <token> - Hetzner DNS API token
• -V, --version - Show version
• -h, --help - Show help

Servers

# List all servers
hz servers list

# Get server details (by ID or name)
hz servers get my-server

# Create a new server
hz servers create -n my-server -t cx11 -i ubuntu-22.04 -l fsn1

# Delete a server (by ID or name)
hz servers delete my-server

# Power management
hz servers power-on my-server
hz servers power-off my-server
hz servers reboot my-server

SSH Keys

# List all SSH keys
hz ssh-keys list

# Get SSH key details
hz ssh-keys get my-key

# Create a new SSH key
hz ssh-keys create -n my-key -k "ssh-rsa AAAA..."

# Delete an SSH key
hz ssh-keys delete my-key

Volumes

# List all volumes
hz volumes list

# Get volume details
hz volumes get my-volume

# Create a new volume
hz volumes create -n my-volume -s 10 -l fsn1

# Attach volume to server
hz volumes attach my-volume my-server

# Detach volume
hz volumes detach my-volume

# Resize volume
hz volumes resize my-volume 20

# Delete a volume
hz volumes delete my-volume

Networks

# List all networks
hz networks list

# Get network details
hz networks get my-network

# Create a new network
hz networks create -n my-network -r 10.0.0.0/16

# Delete a network
hz networks delete my-network

Firewalls

# List all firewalls
hz firewalls list

# Get firewall details
hz firewalls get my-firewall

# Create a new firewall
hz firewalls create -n my-firewall

# List firewall rules
hz firewalls rules my-firewall

# Add a rule to a firewall
hz firewalls add-rule my-firewall --direction in --protocol tcp --port 443 --source-ips 0.0.0.0/0

# Remove a rule from a firewall (by index)
hz firewalls remove-rule my-firewall 0

# Delete a firewall
hz firewalls delete my-firewall

Floating IPs

# List all floating IPs
hz floating-ips list

# Get floating IP details
hz floating-ips get 12345

# Create a new floating IP
hz floating-ips create --type ipv4 --home-location fsn1

# Assign floating IP to server
hz floating-ips assign 12345 my-server

# Unassign floating IP from server
hz floating-ips unassign 12345

# Delete a floating IP
hz floating-ips delete 12345

Load Balancers

# List all load balancers
hz load-balancers list

# Get load balancer details
hz load-balancers get my-lb

# Create a new load balancer
hz load-balancers create -n my-lb -t lb11 -l fsn1

# Add a server target
hz load-balancers add-target my-lb --type server --server my-server

# Remove a target
hz load-balancers remove-target my-lb --type server --server my-server

# Delete a load balancer
hz load-balancers delete my-lb

Certificates

# List all certificates
hz certificates list

# Get certificate details
hz certificates get my-cert

# Create a managed certificate
hz certificates create -n my-cert --type managed --domain example.com

# Create an uploaded certificate
hz certificates create -n my-cert --type uploaded --certificate ./cert.pem --private-key ./key.pem

# Retry managed certificate issuance
hz certificates retry my-cert

# Delete a certificate
hz certificates delete my-cert

Primary IPs

# List all primary IPs
hz primary-ips list

# Get primary IP details
hz primary-ips get 12345

# Create a new primary IP
hz primary-ips create -n my-ip --type ipv4 --datacenter fsn1-dc14

# Assign primary IP to server
hz primary-ips assign 12345 my-server

# Unassign primary IP from server
hz primary-ips unassign 12345

# Delete a primary IP
hz primary-ips delete 12345

Placement Groups

# List all placement groups
hz placement-groups list

# Get placement group details
hz placement-groups get my-group

# Create a new placement group
hz placement-groups create -n my-group

# Delete a placement group
hz placement-groups delete my-group

DNS Zones

# List all DNS zones
hz dns zones list

# Get zone details
hz dns zones get example.com

# Create a new zone
hz dns zones create -n example.com

# Delete a zone
hz dns zones delete example.com

DNS Records

# List records for a zone
hz dns records list -z <zone-id>

# Get record details
hz dns records get <record-id>

# Create a new record
hz dns records create -z <zone-id> -t A -n www -v 1.2.3.4

# Delete a record
hz dns records delete <record-id>

Info Commands

# List available locations
hz locations

# List available server types
hz server-types

# List available images
hz images

Configuration

# Show current configuration
hz config show

# Set a configuration value
hz config set token <your-token>
hz config set dnsToken <your-dns-token>
hz config set defaultLocation fsn1
hz config set defaultServerType cx11
hz config set defaultImage ubuntu-22.04

# Get a configuration value
hz config get defaultLocation

# Clear all configuration
hz config clear

Aliases

Common commands have short aliases:

Resource aliases:

• floating-ips → fips
• load-balancers → lbs
• certificates → certs
• primary-ips → pips
• placement-groups → pgs

Subcommand aliases:

• list → ls
• delete → rm

Examples:

hz servers ls           # List servers
hz fips ls              # List floating IPs
hz lbs get my-lb        # Get load balancer details
hz certs rm my-cert     # Delete certificate

JSON Output

Use the -j or --json flag to get JSON output:

hz servers list --json
hz servers get my-server -j

Recipes

Common workflows for managing your Hetzner infrastructure.

Securely Provision a New Server

Create a locked-down server with SSH key authentication and firewall protection:

# 1. Add your SSH key (if not already added)
hz ssh-keys create -n my-key -k "$(cat ~/.ssh/id_ed25519.pub)"

# 2. Create a firewall that only allows SSH
hz firewalls create -n web-firewall
hz firewalls add-rule web-firewall --direction in --protocol tcp --port 22 --source-ips 0.0.0.0/0

# 3. Create the server with your SSH key
hz servers create -n my-server -t cx22 -i ubuntu-24.04 -l fsn1 --ssh-key my-key --firewall web-firewall

# 4. Get the server IP
hz servers get my-server

Provision a Web Server with DNS

Set up a server for web hosting with DNS records:

# 1. Create firewall with web traffic rules
hz firewalls create -n web-firewall
hz firewalls add-rule web-firewall --direction in --protocol tcp --port 22 --source-ips 0.0.0.0/0
hz firewalls add-rule web-firewall --direction in --protocol tcp --port 80 --source-ips 0.0.0.0/0
hz firewalls add-rule web-firewall --direction in --protocol tcp --port 443 --source-ips 0.0.0.0/0

# 2. Create the server
hz servers create -n web-server -t cx22 -i ubuntu-24.04 -l fsn1 --ssh-key my-key --firewall web-firewall

# 3. Get the server's IP address
hz servers get web-server -j | jq -r '.public_net.ipv4.ip'

# 4. Create DNS zone (if you haven't already)
hz dns zones create -n example.com

# 5. Add DNS records pointing to your server (replace IP with actual IP from step 3)
hz dns records create -z example.com -t A -n @ -v 1.2.3.4
hz dns records create -z example.com -t A -n www -v 1.2.3.4

Set Up a Private Network with Multiple Servers

Create an isolated network for server-to-server communication:

# 1. Create a private network
hz networks create -n internal-net -r 10.0.0.0/16

# 2. Create servers attached to the network
hz servers create -n app-server-1 -t cx22 -i ubuntu-24.04 -l fsn1 --ssh-key my-key --network internal-net
hz servers create -n app-server-2 -t cx22 -i ubuntu-24.04 -l fsn1 --ssh-key my-key --network internal-net
hz servers create -n db-server -t cx32 -i ubuntu-24.04 -l fsn1 --ssh-key my-key --network internal-net

# 3. Servers can now communicate via private IPs (10.0.x.x)

Load-Balanced Web Application

Deploy multiple servers behind a load balancer:

# 1. Create backend servers
hz servers create -n web-1 -t cx22 -i ubuntu-24.04 -l fsn1 --ssh-key my-key
hz servers create -n web-2 -t cx22 -i ubuntu-24.04 -l fsn1 --ssh-key my-key

# 2. Create load balancer
hz load-balancers create -n my-lb -t lb11 -l fsn1

# 3. Add servers as targets
hz load-balancers add-target my-lb --type server --server web-1
hz load-balancers add-target my-lb --type server --server web-2

# 4. Get load balancer IP for DNS
hz load-balancers get my-lb

Add Persistent Storage to a Server

Attach a volume for data that persists across server rebuilds:

# 1. Create a volume
hz volumes create -n data-volume -s 50 -l fsn1

# 2. Attach to your server
hz volumes attach data-volume my-server

# 3. SSH into server and mount the volume
# The volume appears as /dev/disk/by-id/scsi-0HC_Volume_<id>
# Format and mount it (first time only):
#   mkfs.ext4 /dev/disk/by-id/scsi-0HC_Volume_<id>
#   mkdir /mnt/data
#   mount /dev/disk/by-id/scsi-0HC_Volume_<id> /mnt/data

Use a Floating IP for High Availability

Assign a floating IP that can be moved between servers:

# 1. Create a floating IP
hz floating-ips create --type ipv4 --home-location fsn1

# 2. Note the floating IP address and ID from the output

# 3. Assign to your primary server
hz floating-ips assign <floating-ip-id> primary-server

# 4. If primary fails, reassign to backup server
hz floating-ips unassign <floating-ip-id>
hz floating-ips assign <floating-ip-id> backup-server

Secure Server with Restricted SSH Access

Lock down SSH to specific IP addresses:

# 1. Create firewall with restricted SSH access
hz firewalls create -n restricted-firewall

# 2. Only allow SSH from your office/home IP
hz firewalls add-rule restricted-firewall --direction in --protocol tcp --port 22 --source-ips 203.0.113.50/32

# 3. Apply to server
hz servers create -n secure-server -t cx22 -i ubuntu-24.04 -l fsn1 --ssh-key my-key --firewall restricted-firewall

Related

• @tomkp/hetzner - TypeScript API client for Hetzner Cloud and DNS
• @tomkp/hetzner-tui - Interactive terminal UI for Hetzner

License

MIT