hrobot-py 0.1.0

Unofficial Hetzner Robot Webservice OpenAPI client and CLI

hrobot-py

hrobot-py is an unofficial Python client and command line interface for the Hetzner Robot Webservice API. It includes an OpenAPI specification, a generated Python client, and the hrobot CLI.

Disclaimer: this project is not affiliated with, endorsed by, or maintained by Hetzner. It targets the Hetzner Robot Webservice API for dedicated servers, not the Hetzner Cloud API.

Requirements

You need a Hetzner Robot Webservice user. Robot Webservice credentials can be created in the Robot web interface under the account preferences/settings area.

Installation

pip install hrobot-py

Credentials

The CLI reads credentials from the environment:

export HROBOT_USER='your-robot-webservice-user'
export HROBOT_PASSWORD='your-robot-webservice-password'

You can also provide the username and enter the password interactively:

hrobot --user your-robot-webservice-user --ask-password servers

Or load a simple shell-style env file with HROBOT_USER and HROBOT_PASSWORD:

hrobot --env-file .env servers

Be careful with repeated bad credentials: the Robot documentation says the source IP can be blocked temporarily after multiple failed login attempts.

CLI examples

hrobot servers
hrobot server 123456

hrobot ips
hrobot ip 203.0.113.10

hrobot reset options
hrobot boot status 123456
hrobot boot rescue options 123456
hrobot wol status 123456

The CLI prints JSON by default. Use --compact for compact output and --show-status to include the HTTP status code.

Some operations can change server state, destroy data, or affect billing. These commands require confirmation unless --yes is supplied:

hrobot boot rescue activate 123456 --os linux --arch 64 --authorized-key 'fingerprint'
hrobot reset execute 123456 --type hw
hrobot wol trigger 123456

The raw command can call endpoints that do not have a dedicated CLI wrapper:

hrobot raw GET /server
hrobot raw GET /boot/123456/rescue
hrobot raw POST /reset/123456 --data type=hw --dry-run

Secret-looking response fields such as password are redacted by default. Use --show-secrets only when you intentionally need to display returned secrets.

Python client example

import os

import httpx

from hetzner_robot_webservice_api_unofficial_client import Client
from hetzner_robot_webservice_api_unofficial_client.api.server import list_servers

client = Client(
    base_url="https://robot-ws.your-server.de",
    httpx_args={
        "auth": httpx.BasicAuth(
            os.environ["HROBOT_USER"],
            os.environ["HROBOT_PASSWORD"],
        ),
    },
)

with client:
    response = list_servers.sync_detailed(client=client)

print(response.status_code)
print(response.parsed)

OpenAPI and generated client

The OpenAPI document is stored at the repository root:

openapi-hetzner-robot-unofficial.json

The Python client is generated with openapi-python-client. The OpenAPI specification is the source of truth; generated code should be regenerated from it instead of patched by hand.

openapi-python-client generate \
  --path openapi-hetzner-robot-unofficial.json \
  --meta none \
  --output-path src/hetzner_robot_webservice_api_unofficial_client \
  --overwrite