hetzner_rhai/README.md

# 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](https://docs.hetzner.com/cloud/api/getting-started/generating-api-token/).

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

```bash
cargo run -- <script_name>.rhai
```

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

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

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

### 2. List Servers & Display Details

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

```rust
// 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());
```

### 3. List SSH Keys

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

```rust
// 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());
```

### 4. Manage Server State

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

```rust
// 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.

**Important:** The SSH keys must already exist in your Hetzner Cloud project. You can add them in the [Hetzner Cloud Console](https://console.hetzner.cloud/). For more details, refer to the [official documentation on enabling rescue mode](https://docs.hetzner.cloud/reference/cloud#server-actions-enable-rescue-mode-for-a-server).

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

```rust
// 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());
}
```

### 5. Example Output (from `test.rhai` script)

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