Hetzner Cloud API - Rhai Wrapper

This project provides a Rhai wrapper for interacting with the Hetzner Cloud API, allowing you to manage your servers through simple scripts.

Setup

To use this wrapper, you need to set your Hetzner API Token as an environment variable. You can create your own API Token by following the steps from the Hetzner docs.

export HETZNER_API_TOKEN="YOUR_API_TOKEN_HERE"

Replace "YOUR_API_TOKEN_HERE" with your actual Hetzner API token.

Usage

You can execute any .rhai script by passing it as an argument to cargo run.

cargo run -- <script_name>.rhai

For example, to run the provided test.rhai script:

cargo run -- test.rhai

API Examples

Here are some examples of what you can do with the API, taken from the test.rhai script.

1. Create a Client

All API interactions start by creating a client instance.

// Create client to communicate with Hetzner API
let client = new_hetzner_client(HETZNER_API_TOKEN);

2. Create a Server

You can create a new server using the ServerBuilder pattern. This provides a flexible way to configure the server before creation.

// Create a server builder with required parameters
let server_builder = new_server_builder("my-new-server", "cpx11", "ubuntu-20.04");

// Chain optional parameters
let server_builder = server_builder
    .with_location("fsn1")
    .with_datacenter("fsn1-dc14")
    .with_start_after_create(true)
    .with_user_data("#cloud-config\nruncmd:\n  - [ ls, -l, / ]");

// Specify SSH key IDs. If this is omitted, all SSH keys in your project will be used.
let server_builder = server_builder.with_ssh_keys([12345, 67890]);

// Create the server
let response = client.create_server(server_builder);

print(`Server creation initiated for: ${response.name}`);

The following options are available on the ServerBuilder:

Method	Description
with_location(string)	Sets the server location (e.g., "fsn1").
with_datacenter(string)	Sets the datacenter (e.g., "fsn1-dc14").
with_user_data(string)	Provides user data for cloud-init.
with_start_after_create(bool)	Specifies whether the server should start after creation.
with_ssh_keys(array)	An array of SSH Key IDs to attach to the server.

3. List Servers & Display Details

You can fetch all your servers and display their details in a formatted table.

// List all servers and print in table
print("Listing all servers...");
let servers = client.list_servers();
print(servers.show_table());

// Get a specific server by ID and show its details
let test_server = client.get_server(104301883);
print(test_server.show_details());

4. List SSH Keys

You can also list all the SSH keys in your project.

// List all SSH keys and print in table
print("Listing all SSH keys...");
let ssh_keys = client.list_ssh_keys();
print(ssh_keys.show_table());

5. Manage Server State

Perform actions like enabling rescue mode, disabling it, or rebooting the server.

// Enable rescue mode and get the root password
print(`Enabling rescue mode on server with ID: ${test_server.id}`);
let root_password = client.enable_rescue_mode(test_server.id);
print(`Root password is: ${root_password}`);

// Disable rescue mode
print(`Disabling rescue mode on server with ID: ${test_server.id}`);
client.disable_rescue_mode(test_server.id);

// Reboot server
print(`Rebooting server with ID: ${test_server.id}`);
client.reboot(test_server.id);

Injecting SSH Keys into Rescue Mode

You can also inject SSH keys into the rescue image. The enable_rescue_mode function accepts an optional SSH key ID (integer) or an array of SSH key IDs. If no keys are provided, all available SSH keys in your project will be automatically used.

Important: The SSH keys must already exist in your Hetzner Cloud project. You can add them in the Hetzner Cloud Console. For more details, refer to the official documentation on enabling rescue mode.

Here are some examples of how to use this feature in your Rhai script:

// A single SSH key ID
client.enable_rescue_mode(test_server.id, 1337);

// An array of SSH key IDs
let ssh_keys = [123, 456, 789];
client.enable_rescue_mode(test_server.id, ssh_keys);

// Reading an SSH key from an environment variable
let ssh_key_from_env = get_env("SSH_KEY_ID");
if ssh_key_from_env != "" {
    client.enable_rescue_mode(test_server.id, ssh_key_from_env.parse_int());
}

6. Example Output (from test.rhai script)

Listing all servers...
+-------------+-------------------+---------+-------------+
| Server List |                   |         |             |
+=============+===================+=========+=============+
| ID          | Name              | Status  | Public IPv4 |
+-------------+-------------------+---------+-------------+
| 104298257   | ubuntu-4gb-fsn1-2 | Running | 91.99.1.255 |
+-------------+-------------------+---------+-------------+
| 104301883   | ubuntu-4gb-fsn1-4 | Running | 91.99.178.6 |
+-------------+-------------------+---------+-------------+

Listing all SSH keys...
+-----------+------------------------------+-------------------------------------------------+
| SSH Keys  |                              |                                                 |
+===========+==============================+=================================================+
| ID        | Name                         | Fingerprint                                     |
+-----------+------------------------------+-------------------------------------------------+
| 100324992 | mahmmoud.hassanein@gmail.com | 45:67:42:b7:e0:38:0d:40:40:80:a6:8a:0d:ac:73:6b |
+-----------+------------------------------+-------------------------------------------------+
| 100325001 | maxime@maxime-arch           | e0:73:80:26:80:46:f0:c8:bb:74:f4:d0:2d:10:2d:6f |
+-----------+------------------------------+-------------------------------------------------+

Listing details from server with ID 104301883...
+-------------------+----------------------+
| ubuntu-4gb-fsn1-4 |                      |
+===================+======================+
| ID                | 104301883            |
+-------------------+----------------------+
| Status            | Running              |
+-------------------+----------------------+
| Created           | 2025-07-15T12:25:29Z |
+-------------------+----------------------+
| IPv4              | 91.99.178.6          |
+-------------------+----------------------+
| Type              | cx22                 |
+-------------------+----------------------+
| Included Traffic  | 20480 GB             |
+-------------------+----------------------+
| Ingoing Traffic   | 0 MB                 |
+-------------------+----------------------+
| Outgoing Traffic  | 0 MB                 |
+-------------------+----------------------+
| Primary Disk Size | 40                   |
+-------------------+----------------------+
| Rescue Enabled    | false                |
+-------------------+----------------------+