gaarutyunov Hetzner Cloud CLI (hcloud)
Overview
hcloud is the official CLI for Hetzner Cloud. Use it for quick operations, scripting, and CI/CD workflows. For complex automation or custom Go integrations, use the hetzner:hcloud-go-sdk skill instead.
Quick Setup
# Install
brew install hcloud # or: go install github.com/hetznercloud/cli/cmd/hcloud@latest
# Authenticate
hcloud context create myproject
# Enter your API token when prompted (from https://console.hetzner.cloud)
See references/configuration.md for multi-project and advanced setup.
Quick Reference
| Task | Command |
|---|---|
| Servers | |
| List servers | hcloud server list |
| Create server | hcloud server create --name web --type cpx22 --image ubuntu-24.04 |
| SSH to server | hcloud server ssh web |
| Delete server | hcloud server delete web |
| Reboot/Reset | hcloud server reboot web / hcloud server reset web |
| Networks | |
| Create network | hcloud network create --name private --ip-range 10.0.0.0/8 |
| Attach server | hcloud server attach-to-network web --network private |
| Volumes | |
| Create volume | hcloud volume create --name data --size 100 --server web |
| Attach volume | hcloud volume attach data --server web --automount |
| Firewalls | |
| Create firewall | hcloud firewall create --name web-fw |
| Add rule | hcloud firewall add-rule web-fw --direction in --protocol tcp --port 80 |
| Apply to server | hcloud firewall apply-to-resource web-fw --type server --server web |
| Load Balancers | |
| Create LB | hcloud load-balancer create --name lb --type lb11 --location fsn1 |
| Add target | hcloud load-balancer add-target lb --server web |
| SSH Keys | |
| Upload key | hcloud ssh-key create --name mykey --public-key-from-file ~/.ssh/id_rsa.pub |
| DNS (Zones) | |
| List zones | hcloud zone list |
| Create zone | hcloud zone create --name example.com |
Command Categories
See references/commands.md for complete command reference:
- Servers (lifecycle, rescue, metrics, console)
- Networks, subnets, routes
- Volumes, storage boxes
- Firewalls and rules
- Load balancers, targets, services
- Floating IPs, primary IPs
- SSH keys, images, ISOs
- DNS zones and records
- Certificates, placement groups
Output Formats
# JSON output for scripting
hcloud server list --output json | jq '.[] | select(.status == "running")'
# YAML output
hcloud server describe web --output yaml
# Go template formatting
hcloud server describe web --output format='{{.ServerType.Cores}} cores'
# Table customization
hcloud server list --output columns=id,name,status,ipv4
hcloud server list --output noheader
Context Management (Multi-Project)
# Create contexts for different projects/tokens
hcloud context create production
hcloud context create staging
# Switch context
hcloud context use production
# List contexts
hcloud context list
Common Patterns
# Create server with SSH key and private network
hcloud server create \
--name web-01 \
--type cpx22 \
--image ubuntu-24.04 \
--ssh-key mykey \
--network private \
--location fsn1
# Create firewall with rules file
hcloud firewall create --name web-fw --rules-file rules.json
# Bulk server creation
for i in {1..3}; do
hcloud server create --name "node-$i" --type cx22 --image ubuntu-24.04
done
# Wait for server to be running
hcloud server create --name app --type cx22 --image ubuntu-24.04
while [[ $(hcloud server describe app -o format='{{.Status}}') != "running" ]]; do
sleep 2
done
Common Mistakes
| Problem | Solution |
|---|---|
| "context not set" | Run hcloud context create <name> and enter token |
| "resource not found" | Check hcloud <resource> list - might be in different project |
| Token expired | Update with hcloud context create <name> (same name replaces) |
| Wrong location | Use --location fsn1 or nbg1 or hel1 explicitly |
| Server unreachable | Check firewall rules, ensure SSH port 22 is open |
| Volume not visible | Use --automount or mount manually via SSH |