Hetzner Cloud CLI for coding agents

When you give a coding agent shell access to a Hetzner Cloud project, it can use the official hcloud command-line interface (CLI) to inspect and manage the project from the terminal. The CLI sends requests to Hetzner Cloud’s API, the service it uses to list servers, networks, firewalls, and volumes.

As a first task, ask an agent to list the project’s servers and report their status and location. The list command reads project data without changing cloud resources. The agent needs a project API token, a credential for accessing the project, in its environment. Keep the token out of its prompt.

What the agent can do

The hcloud CLI provides commands for Hetzner Cloud resources, including servers, networks, firewalls, volumes, load balancers, SSH keys, and primary IP addresses. A coding agent can use those commands to answer infrastructure questions or carry out approved changes through the same interface a person would use.

For example, an agent investigating a deployment could list servers and identify which ones are running. It can then compare that inventory with configuration in the repository. The CLI reads live project data for the inventory, while examining repository files is local work.

Install and authenticate

On macOS or Linux with Homebrew, install the CLI with:

brew install hcloud

The project also publishes release binaries on its GitHub releases page. The setup tutorial covers other options, like go install and a Docker image. It also offers Debian and RPM packages, which it marks as experimental. On Windows, it lists WinGet and Scoop packages, which Hetzner does not maintain.

Create an API token in the Hetzner Console. The API reference says you open the project, go to Security and then API Tokens. A token belongs to one project. The CLI reads the token from the HCLOUD_TOKEN environment variable, and its configuration reference says that setting this variable is often enough. Treat the token like a password: store it in a local secret manager or inject it into the agent’s environment, and do not include it in the agent prompt or repository.

For a local shell test, replace the placeholder below with the token without sharing it:

export HCLOUD_TOKEN="<your-project-api-token>"
hcloud server list

The first command sets an environment variable in the current shell. The second makes a read request to Hetzner Cloud and prints the project’s server list. The placeholder is not a real token.

The setup tutorial also shows hcloud context create <context-name>. It asks for the token and saves it as a named context in ~/.config/hcloud/cli.toml. An agent that can read that file can also read the token.

Inventory servers without changing them

Use the table output for a quick scan, or request JSON when the agent needs structured data:

hcloud server list
hcloud server list --output json

Both commands query the cloud project; neither creates or modifies resources. The JSON form gives an agent data it can inspect or compare with repository configuration. The hcloud server list manual page lists the other output options, like yaml and a choice of table columns.

A practical coding-agent prompt could be:

Use hcloud server list --output json to inspect the servers in the configured Hetzner project. Report each server’s name, status, and location. Do not create, change, or delete any cloud resources.

The agent runs the command on your machine, and Hetzner returns the server inventory in response to the command’s API request. If the command fails, check that the agent process received HCLOUD_TOKEN and that the token belongs to the intended project.

Check before making changes

The CLI also creates and changes resources, and Hetzner bills for resources like servers and Primary IPs. The API reference on server types says each server type has an hourly and a monthly price, and that prices can differ between locations. Confirm the server type and location with the agent before it runs a create command. A server type is also not available in every location. This read-only command shows the locations where each type is available:

hcloud server-type list --output columns=name,location_available

Before the agent makes a change, ask it to describe the command and what it will do. The read-only inventory command does not show what a later change command will do.

Some CLI commands are marked experimental. The project warns that experimental features can change incompatibly within minor releases, so avoid building critical automation around those commands without checking their current documentation and behavior. The CLI prints a warning when you run an experimental command, and its help text marks it too.