hcloud（hcloud 命令行）

Hetzner Cloud CLI (hcloud)

Manage Hetzner Cloud infrastructure with the official CLI tool.

Prerequisites

Installation (if not already installed):

# Detect architecture
ARCH=$(uname -m)
if [ "$ARCH" = "aarch64" ] || [ "$ARCH" = "arm64" ]; then
  URL="https://github.com/hetznercloud/cli/releases/latest/download/hcloud-linux-arm64.tar.gz"
else
  URL="https://github.com/hetznercloud/cli/releases/latest/download/hcloud-linux-amd64.tar.gz"
fi

# Install
cd /tmp
wget -q "$URL"
tar xzf hcloud-linux-*.tar.gz
sudo mv hcloud /usr/local/bin/
chmod +x /usr/local/bin/hcloud

Configuration (first time):

mkdir -p ~/.config/hcloud
cat > ~/.config/hcloud/cli.toml <<EOF
active_context = "default"

[[contexts]]
name = "default"
token = "YOUR_HETZNER_API_TOKEN"
EOF
chmod 600 ~/.config/hcloud/cli.toml

Verify:

hcloud version
hcloud server list

Common Commands

Servers

# List servers
hcloud server list

# Get server details
hcloud server describe <name-or-id>

# Create server
hcloud server create \
  --name my-server \
  --type cx11 \
  --image ubuntu-24.04 \
  --ssh-key <key-id-or-name> \
  --location nbg1

# Start/stop/reboot
hcloud server start <name-or-id>
hcloud server stop <name-or-id>
hcloud server reboot <name-or-id>

# Delete server
hcloud server delete <name-or-id>

# SSH into server
hcloud server ssh <name-or-id>

# Run command on server
hcloud server ssh <name-or-id> -- 'uname -a'

Firewalls

# List firewalls
hcloud firewall list

# Get firewall details
hcloud firewall describe <name-or-id>

# Create firewall
hcloud firewall create \
  --name my-firewall \
  --rules-file rules.json

# Add rule to firewall
hcloud firewall add-rule <name-or-id> \
  --direction in \
  --port 22 \
  --protocol tcp \
  --source-ips 0.0.0.0/0 \
  --source-ips ::/0 \
  --description "SSH"

# Apply firewall to server
hcloud firewall apply-to-resource <firewall-name> \
  --type server \
  --server <server-name-or-id>

# Remove firewall from server
hcloud firewall remove-from-resource <firewall-name> \
  --type server \
  --server <server-name-or-id>

# Delete firewall
hcloud firewall delete <name-or-id>

SSH Keys

# List SSH keys
hcloud ssh-key list

# Add SSH key
hcloud ssh-key create \
  --name my-key \
  --public-key-from-file ~/.ssh/id_ed25519.pub

# Delete SSH key
hcloud ssh-key delete <name-or-id>

Server Types & Images

# List available server types
hcloud server-type list

# List available images
hcloud image list
hcloud image list --type system  # Only system images

# List locations
hcloud location list

Volumes

# List volumes
hcloud volume list

# Create volume
hcloud volume create \
  --name my-volume \
  --size 10 \
  --location nbg1

# Attach volume to server
hcloud volume attach <volume-name> <server-name>

# Detach volume
hcloud volume detach <volume-name>

# Delete volume
hcloud volume delete <volume-name>

Networks

# List networks
hcloud network list

# Create network
hcloud network create \
  --name my-network \
  --ip-range 10.0.0.0/16

# Add subnet
hcloud network add-subnet <network-name> \
  --type cloud \
  --network-zone eu-central \
  --ip-range 10.0.1.0/24

# Attach server to network
hcloud server attach-to-network <server-name> \
  --network <network-name>

Load Balancers

# List load balancers
hcloud load-balancer list

# Create load balancer
hcloud load-balancer create \
  --name my-lb \
  --type lb11 \
  --location nbg1

# Add target (server)
hcloud load-balancer add-target <lb-name> \
  --server <server-name>

# Add service
hcloud load-balancer add-service <lb-name> \
  --protocol http \
  --listen-port 80 \
  --destination-port 80

Firewall Rules Format

For complex firewall rules, use JSON:

[
  {
    "direction": "in",
    "port": "22",
    "protocol": "tcp",
    "source_ips": ["0.0.0.0/0", "::/0"],
    "description": "SSH"
  },
  {
    "direction": "in",
    "port": "80",
    "protocol": "tcp",
    "source_ips": ["0.0.0.0/0", "::/0"],
    "description": "HTTP"
  },
  {
    "direction": "in",
    "port": "443",
    "protocol": "tcp",
    "source_ips": ["0.0.0.0/0", "::/0"],
    "description": "HTTPS"
  },
  {
    "direction": "in",
    "protocol": "icmp",
    "source_ips": ["0.0.0.0/0", "::/0"],
    "description": "ICMP (ping)"
  }
]

Common Server Types

cx series: Shared vCPU (cost-optimized) cpx series: Dedicated vCPU (performance-optimized)

Tips

• Use --output json for parsing: hcloud server list --output json | jq
• Context switching: Create multiple contexts in ~/.config/hcloud/cli.toml for different projects/accounts
• Server labels: Use labels for organization: --labels environment=production,project=web
• Default location: Set default location to avoid specifying: hcloud context config default-location nbg1
• Dry run: Many commands support --dry-run or --validate flags

Documentation

Official docs: https://docs.hetzner.cloud/ GitHub: https://github.com/hetznercloud/cli