Metadata-Version: 2.4
Name: hrobot-py
Version: 0.1.0
Summary: Unofficial Hetzner Robot Webservice OpenAPI client and CLI
Project-URL: Homepage, https://github.com/ra--/hrobot-py
Project-URL: Repository, https://github.com/ra--/hrobot-py
Project-URL: Issues, https://github.com/ra--/hrobot-py/issues
Project-URL: Source documentation, https://robot.hetzner.com/doc/webservice/en.html
Author: ra
License: MIT License
        
        Copyright (c) 2026 ra
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Keywords: cli,client,hetzner,openapi,robot
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Requires-Dist: attrs
Requires-Dist: httpx
Requires-Dist: python-dateutil
Provides-Extra: dev
Requires-Dist: build; extra == 'dev'
Requires-Dist: openapi-python-client; extra == 'dev'
Requires-Dist: twine; extra == 'dev'
Description-Content-Type: text/markdown

# hrobot-py

`hrobot-py` is an unofficial Python client and command line interface for the
[Hetzner Robot Webservice API](https://robot.hetzner.com/doc/webservice/en.html).
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

```bash
pip install hrobot-py
```

## Credentials

The CLI reads credentials from the environment:

```bash
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:

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

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

```bash
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

```bash
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:

```bash
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:

```bash
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

```python
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:

```text
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.

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