tuca 0.1__py3-none-any.whl

tuca/__init__.py

@@ -0,0 +1,42 @@
+# SPDX-FileCopyrightText: 2026 René de Hesselle <dehesselle@web.de>
+#
+# SPDX-License-Identifier: GPL-2.0-or-later
+
+import argparse
+
+from tuca.auth import setup_auth_cli
+from tuca.config import config
+from tuca.endpoints import (
+    setup_images_endpoint,
+    setup_keypairs_endpoint,
+    setup_servers_endpoint,
+    setup_sizes_endpoint,
+    setup_snapshots_endpoint,
+)
+from tuca.version import VERSION
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="unofficial CLI for Clouding.io")
+    parser.add_argument(
+        "-v",
+        "--verbose",
+        action="store_true",
+        default=False,
+        help="make output verbose",
+    )
+    parser.add_argument("--version", action="version", version=f"tuca {VERSION}")
+    endpoints = parser.add_subparsers(help="manageable endpoints", dest="endpoint")
+    setup_auth_cli(endpoints)
+    setup_images_endpoint(endpoints)
+    setup_keypairs_endpoint(endpoints)
+    setup_servers_endpoint(endpoints)
+    setup_snapshots_endpoint(endpoints)
+    setup_sizes_endpoint(endpoints)
+
+    args = parser.parse_args()
+    config.be_verbose = args.verbose
+    try:
+        args.func(args)
+    except AttributeError:
+        parser.print_usage()

tuca/_version.py

@@ -0,0 +1,34 @@
+# file generated by setuptools-scm
+# don't change, don't track in version control
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+TYPE_CHECKING = False
+if TYPE_CHECKING:
+    from typing import Tuple
+    from typing import Union
+
+    VERSION_TUPLE = Tuple[Union[int, str], ...]
+    COMMIT_ID = Union[str, None]
+else:
+    VERSION_TUPLE = object
+    COMMIT_ID = object
+
+version: str
+__version__: str
+__version_tuple__: VERSION_TUPLE
+version_tuple: VERSION_TUPLE
+commit_id: COMMIT_ID
+__commit_id__: COMMIT_ID
+
+__version__ = version = '0.1'
+__version_tuple__ = version_tuple = (0, 1)
+
+__commit_id__ = commit_id = None

tuca/auth.py

@@ -0,0 +1,47 @@
+# SPDX-FileCopyrightText: 2026 René de Hesselle <dehesselle@web.de>
+#
+# SPDX-License-Identifier: GPL-2.0-or-later
+
+import os
+from argparse import _SubParsersAction
+from enum import StrEnum, auto
+from getpass import getpass
+
+import keyring
+
+SERVICENAME = "Clouding.io API token"
+USERNAME = "tuca"
+
+
+class Action(StrEnum):
+    CREATE = auto()
+    DELETE = auto()
+
+
+def set_token(_) -> None:
+    token = getpass("API token:")
+    keyring.set_password(SERVICENAME, USERNAME, token)
+
+
+def get_token(_) -> str:
+    if api_token := os.getenv("CLOUDINGIO_API_TOKEN"):
+        return api_token
+    else:
+        return keyring.get_password(SERVICENAME, USERNAME)
+
+
+def delete_token(_) -> None:
+    keyring.delete_password(SERVICENAME, USERNAME)
+
+
+def setup_auth_cli(subparser: _SubParsersAction):
+    auth = subparser.add_parser("auth", help="manage authentication token")
+    auth_actions = auth.add_subparsers()
+    auth_action_set = auth_actions.add_parser(
+        Action.CREATE, help="set authentication token"
+    )
+    auth_action_set.set_defaults(func=set_token)
+    auth_action_delete = auth_actions.add_parser(
+        Action.DELETE, help="delete authentication token"
+    )
+    auth_action_delete.set_defaults(func=delete_token)

tuca/clouding.py

@@ -0,0 +1,133 @@
+# SPDX-FileCopyrightText: 2026 René de Hesselle <dehesselle@web.de>
+#
+# SPDX-License-Identifier: GPL-2.0-or-later
+
+import json
+from http import HTTPStatus
+
+import requests
+from pydantic import BaseModel, Field
+from urlpath import URL
+
+from tuca.auth import get_token
+
+
+class ResponseHeader(BaseModel):
+    # rate_limit_limit: str = Field(alias="X-Rate-Limit-Limit", default="")
+    rate_limit_remaining: str = Field(alias="X-Rate-Limit-Remaining")
+    # rate_limit_reset: str = Field(alias="X-Rate-Limit-Reset", default="")
+
+
+class DeleteResponse(BaseModel):
+    id: str
+    status: str = ""
+    startedAt: str = ""
+    resourceId: str = ""
+    resourceType: str = ""
+
+
+class ResponseLinks(BaseModel):
+    next: str | None
+    previous: str | None
+
+
+class ResponseMeta(BaseModel):
+    total: int
+
+
+ValidStatusCodes = [
+    HTTPStatus.OK,
+    HTTPStatus.CREATED,
+    HTTPStatus.ACCEPTED,
+    HTTPStatus.NO_CONTENT,
+    HTTPStatus.BAD_REQUEST,
+    HTTPStatus.UNAUTHORIZED,
+    HTTPStatus.FORBIDDEN,
+    HTTPStatus.NOT_FOUND,
+    HTTPStatus.METHOD_NOT_ALLOWED,
+    HTTPStatus.TOO_MANY_REQUESTS,
+    HTTPStatus.INTERNAL_SERVER_ERROR,
+    HTTPStatus.SERVICE_UNAVAILABLE,
+]  # https://api.clouding.io/docs/#section/Introduction/Responses
+
+
+class Clouding:
+    def __init__(self):
+        self.api_url = URL("https://api.clouding.io/v1")
+        self.api_auth = {"X-API-KEY": get_token(None)}
+        self.endpoint = ""
+        self.query = ""
+        self.response = requests.Response()
+        self.response_header = ResponseHeader(**{"X-Rate-Limit-Remaining": ""})
+        self.response_links = ResponseLinks(next=None, previous=None)
+        self.response_meta = ResponseMeta(total=0)
+        self.delete_response = DeleteResponse(id="")
+
+    def get(self, endpoint: str):
+        self.endpoint = endpoint
+        self.response = requests.get(
+            self.api_url / endpoint / "?pageSize=100", headers=self.api_auth
+        )
+        self._post_processing()
+
+    def post(self, endpoint: str, payload: dict, headers: dict = {}):
+        self.endpoint = endpoint
+        headers.update(self.api_auth)
+        self.response = requests.post(
+            self.api_url / endpoint, data=json.dumps(payload), headers=headers
+        )
+        self._post_processing()
+
+    def delete(self, endpoint: str, id: str):
+        self.endpoint = endpoint
+        self.response = requests.delete(
+            self.api_url / endpoint / id, headers=self.api_auth
+        )
+        if self.has_content:
+            self.delete_response = DeleteResponse.model_validate(self.response.json())
+        else:
+            self.delete_response.resourceId = id  # the only piece of info we got
+        self._post_processing()
+
+    def next(self) -> bool:
+        if url := self.response_links.next:
+            print(self.response_links.next)
+            self.response = requests.get(url, headers=self.api_auth)
+            self._post_processing()
+            return True
+        else:
+            return False
+
+    @property
+    def is_status_ok(self) -> bool:
+        return self.response.status_code in [
+            HTTPStatus.OK,
+            HTTPStatus.CREATED,
+            HTTPStatus.ACCEPTED,
+            HTTPStatus.NO_CONTENT,
+        ]
+
+    @property
+    def is_status_valid(self) -> bool:
+        return self.response.status_code in ValidStatusCodes
+
+    @property
+    def has_content(self) -> bool:
+        return self.is_status_ok and self.response.status_code != HTTPStatus.NO_CONTENT
+
+    def _post_processing(self):
+        if self.is_status_valid:
+            self.response_header = ResponseHeader.model_validate(self.response.headers)
+            try:
+                self.response_links = ResponseLinks.model_validate(
+                    self.response.json()["links"]
+                )
+                self.response_meta = ResponseMeta.model_validate(
+                    self.response.json()["meta"]
+                )
+            except KeyError:
+                pass  # non-paginated responses don't have links and meta
+        else:
+            # FIXME: rework error handling
+            print("invalid HTTP status", self.response.status_code)
+            exit(1)

tuca/config.py

@@ -0,0 +1,13 @@
+# SPDX-FileCopyrightText: 2026 René de Hesselle <dehesselle@web.de>
+#
+# SPDX-License-Identifier: GPL-2.0-or-later
+
+from dataclasses import dataclass
+
+
+@dataclass
+class Config:
+    be_verbose: bool = False
+
+
+config = Config()

tuca/endpoints/__init__.py

@@ -0,0 +1,9 @@
+# SPDX-FileCopyrightText: 2026 René de Hesselle <dehesselle@web.de>
+#
+# SPDX-License-Identifier: GPL-2.0-or-later
+
+from .images import setup_images_endpoint
+from .keypairs import setup_keypairs_endpoint
+from .servers import setup_servers_endpoint
+from .sizes import setup_sizes_endpoint
+from .snapshots import setup_snapshots_endpoint

tuca/endpoints/endpoint.py

@@ -0,0 +1,140 @@
+# SPDX-FileCopyrightText: 2026 René de Hesselle <dehesselle@web.de>
+#
+# SPDX-License-Identifier: GPL-2.0-or-later
+
+import argparse
+import json
+
+from pydantic import BaseModel, ValidationError
+
+from tuca.clouding import Clouding, DeleteResponse
+from tuca.config import config
+from tuca.resource import Resource
+
+
+class RequestPayload(BaseModel):
+    pass
+
+
+class Endpoint[T: Resource]:
+    def __init__(self, component_type: T, endpoint: str):
+        self.clouding = Clouding()
+        self.resources: list[T] = []
+        self.component_type = component_type
+        self.endpoint = endpoint
+        self.response_key = endpoint
+
+    def create(self, payload: RequestPayload) -> list[T]:
+        self.clouding.post(
+            self.endpoint,
+            payload.model_dump(),
+            headers={"Content-Type": "application/json"},
+        )
+        return self._deserialize_response()
+
+    def delete(self, id: str) -> DeleteResponse:
+        self.clouding.delete(self.endpoint, id)
+        return self.clouding.delete_response
+
+    def get(self) -> list[T]:
+        if not self.resources:
+            self.clouding.get(self.endpoint)
+            self.resources.extend(self._deserialize_response(self.response_key))
+            while (
+                len(self.resources) < 100 and self.clouding.next()
+            ):  # TODO configurable limit?
+                self.resources.extend(self._deserialize_response(self.response_key))
+        return self.resources
+
+    def get_by_id(self, id: str) -> T | None:
+        try:
+            return self._by_id[id]
+        except KeyError:
+            return None
+
+    def get_by_name(self, name: str) -> T | None:
+        try:
+            return self._by_name[name]
+        except KeyError:
+            return None
+
+    def to_str(self, models: list[BaseModel] | BaseModel | None = None) -> str:
+        list_name = self.endpoint
+        if models is None:
+            models = self.get()
+        elif not isinstance(models, list):
+            if isinstance(models, DeleteResponse):
+                list_name = "delete"
+            models = [models]
+        result = {list_name: [model.model_dump() for model in models]}
+        if config.be_verbose:
+            result["verbose"] = {
+                "endpoint": self.endpoint,
+                "status_code": self.clouding.response.status_code,
+            }
+            result["verbose"].update(self.clouding.response_header.model_dump())
+        return json.dumps(
+            result,
+            indent=4,
+            sort_keys=True,
+        )
+
+    @classmethod
+    def list_resources(cls, args: argparse.Namespace):
+        endpoint = cls()
+        if hasattr(args, "id") and args.id:
+            print(endpoint.to_str(endpoint.get_by_id(args.id)))
+        elif hasattr(args, "name") and args.name:
+            print(endpoint.to_str(endpoint.get_by_name(args.name)))
+        else:
+            print(endpoint.to_str())
+
+    @classmethod
+    def delete_resource(cls, args: argparse.Namespace):
+        endpoint = cls()
+        if args.name:
+            if resource := endpoint.get_by_name(args.name):
+                resource_id = resource.id
+            else:
+                resource_id = ""
+        else:
+            resource_id = args.id
+
+        if resource_id:
+            response = endpoint.delete(resource_id)
+            # TODO not checking anything
+            print(endpoint.to_str(response))
+        else:
+            print(f"resource_id not found: {resource_id}")  # TODO
+            exit(1)
+
+    def _deserialize_response(self, key: str = "") -> list[T]:
+        result = []
+        if self.clouding.is_status_ok:
+            try:
+                result.extend(
+                    [
+                        self.component_type.model_validate(_)
+                        for _ in (
+                            self.clouding.response.json()[key]
+                            if key
+                            else [self.clouding.response.json()]
+                        )
+                    ]
+                )
+            except KeyError:
+                print("keyerror")  # TODO
+            except ValidationError:
+                print("validationerror")  # TODO
+                print(self.clouding.response.json()[key])
+        else:
+            print(f"HTTP {self.clouding.response.status_code}")  # TODO
+        return result
+
+    @property
+    def _by_id(self) -> dict[str, T]:
+        return {component.id: component for component in self.get()}
+
+    @property
+    def _by_name(self) -> dict[str, T]:
+        return {component.name: component for component in self.get()}

tuca/endpoints/firewalls.py

@@ -0,0 +1,18 @@
+# SPDX-FileCopyrightText: 2026 René de Hesselle <dehesselle@web.de>
+#
+# SPDX-License-Identifier: GPL-2.0-or-later
+
+from tuca.resource import Resource
+
+from .endpoint import Endpoint
+
+
+class Firewall(Resource):
+    id: str
+    name: str
+
+
+class Firewalls(Endpoint[Firewall]):
+    def __init__(self):
+        super().__init__(Firewall, "firewalls")
+        self.response_key = "values"

tuca/endpoints/images.py

@@ -0,0 +1,40 @@
+# SPDX-FileCopyrightText: 2026 René de Hesselle <dehesselle@web.de>
+#
+# SPDX-License-Identifier: GPL-2.0-or-later
+
+from argparse import _SubParsersAction
+from enum import StrEnum, auto
+
+from pydantic import BaseModel
+
+from tuca.resource import Resource
+
+from .endpoint import Endpoint
+
+
+class Action(StrEnum):
+    LIST = auto()
+
+
+class AccessMethods(BaseModel):
+    sshKey: str
+    password: str
+
+
+class Image(Resource):
+    id: str
+    name: str
+    accessMethods: AccessMethods
+    minimumSizeGb: int | None = None  # 'None' default for reusability in Snapshot
+
+
+class Images(Endpoint[Image]):
+    def __init__(self):
+        super().__init__(Image, "images")
+
+
+def setup_images_endpoint(subparser: _SubParsersAction):
+    images = subparser.add_parser("images", help="manage images")
+    images_actions = images.add_subparsers(help="available actions")
+    images_action_list = images_actions.add_parser(Action.LIST, help="list snapshots")
+    images_action_list.set_defaults(func=Images.list_resources)

tuca/endpoints/keypairs.py

@@ -0,0 +1,68 @@
+# SPDX-FileCopyrightText: 2026 René de Hesselle <dehesselle@web.de>
+#
+# SPDX-License-Identifier: GPL-2.0-or-later
+
+from argparse import _SubParsersAction
+from enum import StrEnum, auto
+
+from tuca.resource import Resource
+
+from .endpoint import Endpoint, RequestPayload
+
+
+class Action(StrEnum):
+    CREATE = auto()
+    DELETE = auto()
+    LIST = auto()
+
+
+class Keypair(Resource):
+    id: str
+    name: str
+    fingerprint: str
+
+
+class Keypairs(Endpoint[Keypair]):
+    def __init__(self):
+        super().__init__(Keypair, "keypairs")
+        self.response_key = "values"
+
+    @classmethod
+    def create_resource(cls, args):
+        payload = CreateRequestPayload(
+            name=args.name, publicKey=args.publickey, privateKey=args.privatekey
+        )
+        keypairs = Keypairs()
+        keypair = keypairs.create(payload)
+        print(keypairs.to_str(keypair))
+
+
+class CreateRequestPayload(RequestPayload):
+    name: str
+    publicKey: str
+    privateKey: str
+
+
+def setup_keypairs_endpoint(subparser: _SubParsersAction):
+    snapshots = subparser.add_parser("keypairs", help="manage keypairs")
+    keypair_actions = snapshots.add_subparsers(help="available actions")
+
+    keypair_action_create = keypair_actions.add_parser(
+        Action.CREATE, help="create new server"
+    )
+    keypair_action_create.add_argument("--name", type=str, required=True)
+    keypair_action_create.add_argument("--publickey", type=str, required=True)
+    keypair_action_create.add_argument("--privatekey", type=str, default="")
+    keypair_action_create.set_defaults(func=Keypairs.create_resource)
+
+    keypair_action_delete = keypair_actions.add_parser(
+        Action.DELETE, help="delete a server"
+    )
+    id_or_name = keypair_action_delete.add_mutually_exclusive_group(required=True)
+    id_or_name.add_argument("--id", type=str, default="")
+    id_or_name.add_argument("--name", type=str, default="")
+    keypair_action_delete.set_defaults(func=Keypairs.delete_resource)
+
+    keypair_action_list = keypair_actions.add_parser(Action.LIST, help="list keypairs")
+    keypair_action_list.add_argument("-i", "--id", default="", required=False)
+    keypair_action_list.set_defaults(func=Keypairs.list_resources)

tuca/endpoints/servers.py

@@ -0,0 +1,181 @@
+# SPDX-FileCopyrightText: 2026 René de Hesselle <dehesselle@web.de>
+#
+# SPDX-License-Identifier: GPL-2.0-or-later
+
+import platform
+import signal
+import time
+from argparse import _SubParsersAction
+from concurrent.futures import ThreadPoolExecutor, TimeoutError
+from enum import StrEnum, auto
+
+from pydantic import BaseModel
+from slugify import slugify
+
+from tuca.resource import Resource
+
+from .endpoint import Endpoint, RequestPayload
+from .firewalls import Firewalls
+from .images import Images
+from .sizes import Flavors
+from .snapshots import Snapshots
+
+
+class Action(StrEnum):
+    LIST = auto()
+    CREATE = auto()
+    DELETE = auto()
+
+
+class Status(StrEnum):
+    CREATING = "Creating"
+    ACTIVE = "Active"
+    PENDING = "Pending"
+
+
+class AccessConfiguration(BaseModel):
+    sshKeyId: str | None
+    password: str | None
+    savePassword: bool
+
+
+class Volume(BaseModel):
+    source: str
+    id: str
+    ssdGb: int
+
+
+class CreateRequestPayload(RequestPayload):
+    name: str
+    hostname: str
+    flavorId: str
+    accessConfiguration: AccessConfiguration
+    volume: Volume
+    publicPortFirewallIds: list[str]
+
+
+class Server(Resource):
+    id: str
+    name: str
+    createdAt: str = ""
+    publicIp: str | None = ""
+    status: str
+
+
+class Servers(Endpoint[Server]):
+    def __init__(self):
+        super().__init__(Server, "servers")
+
+    @classmethod
+    def create_resource(cls, args):
+        if args.flavorid not in Flavors().all:
+            print(f"flavor not supported: {args.flavorid}")
+            exit(1)
+
+        if args.snapshot:
+            if snapshot := Snapshots().get_by_id(args.snapshot):
+                volume = Volume(
+                    source="snapshot", id=args.snapshot, ssdGb=snapshot.sizeGb
+                )
+            else:
+                print(f"snapshot not found: {args.snapshot}")
+                exit(1)
+        elif args.image:
+            if image := Images().get_by_id(args.image):
+                volume = Volume(
+                    source="image", id=args.image, ssdGb=image.minimumSizeGb
+                )
+            else:
+                print(f"image not found: {args.image}")
+                exit(1)
+        else:
+            print("mandatory mutually exclusive option missing")
+            exit(1)
+
+        if args.password:
+            access_configuration = AccessConfiguration(
+                sshKeyId=None, password=args.password, savePassword=True
+            )
+        elif args.sshkey:
+            access_configuration = AccessConfiguration(
+                sshKeyId=args.sshkey, password=None, savePassword=False
+            )
+        else:
+            print("mandatory mutually exclusive option missing")
+            exit(1)
+
+        firewall_id = 0
+        if firewall := Firewalls().get_by_name(args.firewall):
+            firewall_id = firewall.id
+        if firewall_id:
+            payload = CreateRequestPayload(
+                name=args.name,
+                hostname=slugify(args.name),
+                flavorId=args.flavorid,
+                accessConfiguration=access_configuration,
+                volume=volume,
+                publicPortFirewallIds=[firewall_id],
+            )
+            servers = Servers()
+            if server := servers.create(payload):
+                server_id = server[0].id
+                if args.wait:
+                    if platform.system() == "Windows":
+                        signal.signal(signal.SIGINT, signal.SIG_DFL)  # make ctrl+c work
+                    with ThreadPoolExecutor() as executor:
+
+                        def wait(id: str, status: Status, seconds: int) -> None:
+                            while Servers().get_by_id(id).status != status:
+                                time.sleep(seconds)
+
+                        future = executor.submit(wait, server_id, Status.ACTIVE, 30)
+                        try:
+                            future.result(timeout=300)
+                        except TimeoutError:
+                            future.cancel()
+                print(servers.to_str(Servers().get_by_id(server_id)))
+            else:
+                print("failed to create server")
+        else:
+            print("error no firewall_id")  # TODO
+            exit(1)
+
+
+def setup_servers_endpoint(subparser: _SubParsersAction):
+    servers = subparser.add_parser("servers", help="manage servers")
+    server_actions = servers.add_subparsers(help="available actions")
+
+    server_action_create = server_actions.add_parser(
+        Action.CREATE, help="create new server"
+    )
+    server_action_create.add_argument("--name", type=str, required=True)
+    image_or_snapshot = server_action_create.add_mutually_exclusive_group(required=True)
+    image_or_snapshot.add_argument("--snapshot", type=str, default="")
+    image_or_snapshot.add_argument("--image", type=str, default="")
+    server_action_create.add_argument("--flavorid", type=str, required=True)
+    server_action_create.add_argument(
+        "--firewall", type=str, required=False, default="default"
+    )
+    password_or_sshkey = server_action_create.add_mutually_exclusive_group(
+        required=True
+    )
+    password_or_sshkey.add_argument("--password", type=str, default="")
+    password_or_sshkey.add_argument("--sshkey", type=str, default="")
+    server_action_create.add_argument(
+        "--wait", action="store_true", default=False, help="wait until server is active"
+    )
+    server_action_create.set_defaults(func=Servers.create_resource)
+
+    server_action_delete = server_actions.add_parser(
+        Action.DELETE, help="delete a server"
+    )
+    id_or_name = server_action_delete.add_mutually_exclusive_group(required=True)
+    id_or_name.add_argument("--id", type=str, default="")
+    id_or_name.add_argument("--name", type=str, default="")
+    server_action_delete.set_defaults(func=Servers.delete_resource)
+
+    server_action_list = server_actions.add_parser(Action.LIST, help="list servers")
+    id_or_name = server_action_list.add_mutually_exclusive_group(required=False)
+    id_or_name.add_argument("--id", type=str, default="")
+    id_or_name.add_argument("--name", type=str, default="")
+    server_action_list.set_defaults(func=Servers.list_resources)

tuca/endpoints/sizes.py

@@ -0,0 +1,62 @@
+# SPDX-FileCopyrightText: 2026 René de Hesselle <dehesselle@web.de>
+#
+# SPDX-License-Identifier: GPL-2.0-or-later
+
+from argparse import _SubParsersAction
+from enum import StrEnum, auto
+
+from tuca.resource import Resource
+
+from .endpoint import Endpoint
+
+
+class Action(StrEnum):
+    LIST = auto()
+
+
+class Flavor(Resource):
+    id: str
+    vCores: float
+    ramGb: int
+    pricePerHour: float
+    pricePerMonthApprox: float
+
+
+class VolumeSize(Resource):
+    storageType: str
+    sizeGb: int
+    pricePerHour: float
+    pricePerMonthApprox: float
+
+
+class Flavors(Endpoint[Flavor]):
+    def __init__(self):
+        super().__init__(Flavor, "sizes/flavors")
+        self.response_key = "flavors"
+
+    @property
+    def all(self) -> list[str]:
+        self.get()
+        return [flavor.id for flavor in self.resources]
+
+
+class Sizes(Endpoint[VolumeSize]):
+    def __init__(self):
+        super().__init__(VolumeSize, "sizes/volumes")
+        self.response_key = "volumeSizes"
+
+
+def setup_sizes_endpoint(subparser: _SubParsersAction):
+    volumesizes = subparser.add_parser("volumesizes", help="query volume sizes")
+    volumesizes_actions = volumesizes.add_subparsers(help="available actions")
+    volumesizes_action_list = volumesizes_actions.add_parser(
+        Action.LIST, help="list volume sizes"
+    )
+    volumesizes_action_list.set_defaults(func=Sizes.list_resources)
+
+    flavors = subparser.add_parser("flavors", help="query cpu/memory combos")
+    flavors_actions = flavors.add_subparsers(help="available actions")
+    flavors_action_list = flavors_actions.add_parser(
+        Action.LIST, help="list volume sizes"
+    )
+    flavors_action_list.set_defaults(func=Flavors.list_resources)

tuca/endpoints/snapshots.py

@@ -0,0 +1,37 @@
+# SPDX-FileCopyrightText: 2026 René de Hesselle <dehesselle@web.de>
+#
+# SPDX-License-Identifier: GPL-2.0-or-later
+
+from argparse import _SubParsersAction
+from enum import StrEnum, auto
+
+from tuca.resource import Resource
+
+from .endpoint import Endpoint
+from .images import Image
+
+
+class Action(StrEnum):
+    LIST = auto()
+
+
+class Snapshot(Resource):
+    id: str
+    name: str
+    createdAt: str
+    sizeGb: int
+    image: Image
+
+
+class Snapshots(Endpoint[Snapshot]):
+    def __init__(self):
+        super().__init__(Snapshot, "snapshots")
+
+
+def setup_snapshots_endpoint(subparser: _SubParsersAction):
+    snapshots = subparser.add_parser("snapshots", help="manage snapshots")
+    snapshot_actions = snapshots.add_subparsers(help="available actions")
+    snapshot_action_list = snapshot_actions.add_parser(
+        Action.LIST, help="list snapshots"
+    )
+    snapshot_action_list.set_defaults(func=Snapshots.list_resources)

tuca/resource.py

@@ -0,0 +1,19 @@
+# SPDX-FileCopyrightText: 2026 René de Hesselle <dehesselle@web.de>
+#
+# SPDX-License-Identifier: GPL-2.0-or-later
+
+import json
+
+from pydantic import BaseModel
+
+
+class Resource(BaseModel):
+    pass
+
+    @property
+    def as_str(self):
+        return json.dumps(
+            self.model_dump(),
+            indent=4,
+            sort_keys=True,
+        )

tuca/version.py

@@ -0,0 +1,8 @@
+# SPDX-FileCopyrightText: 2026 René de Hesselle <dehesselle@web.de>
+#
+# SPDX-License-Identifier: GPL-2.0-or-later
+
+try:
+    from ._version import version as VERSION
+except ImportError:
+    VERSION = "0.0.0"

tuca-0.1.dist-info/METADATA

@@ -0,0 +1,214 @@
+Metadata-Version: 2.4
+Name: tuca
+Version: 0.1
+Summary: tool using clouding api
+Author-email: René de Hesselle <dehesselle@web.de>
+Requires-Python: >=3.12
+Requires-Dist: keyring>=25.7.0
+Requires-Dist: pydantic>=2.12.5
+Requires-Dist: python-slugify>=8.0.4
+Requires-Dist: requests>=2.32.5
+Requires-Dist: urlpath>=2.0.0
+Description-Content-Type: text/markdown
+
+# tool using Clouding.io API
+
+This is an unofficial CLI tool that interacts with the Clouding.io's REST API. Its main goal is to provide a simple interface that I can use to create and destroy servers from shell scripts. Therefore it neither provides access to all available API endpoints nor to all available attributes and/or actions.
+
+The project status is best described as "alpha" as things are still very much in motion and specifically tailored towards my usecase.
+
+## Installation
+
+`tuca` is on [PyPi](https://pypi.org/project/tuca/), you can use the package manager of your choice to set yourself up. Here is an example using `uv`:
+
+```bash
+uv tool install tuca
+```
+
+## Usage
+
+### the basics
+
+The CLI interface follows this pattern:
+
+```bash
+tuca <endpoint> <action> [options]
+```
+
+- `endpoint` is the same as in https://api.clouding.io/docs/
+- `action` is one of `create`, `list` and `delete`
+- `options` depend on `endpoint` and `action`, consult `--help` for details
+
+`tuca` writes pretty-printed JSON (no colors) to `stdout`. It's both human-readable and intended to be piped into `jq` for non-interactive usage. The following example shows the available SSH keys (redacted values) in a freshly created account:
+
+```json
+{
+    "keypairs": [
+        {
+            "fingerprint": "00:00:00:00:00:00:00:00:00:00:00:00:00:00:00:00",
+            "id": "xxxxxxxxxxxxxxxx",
+            "name": "default"
+        }
+    ]
+}
+```
+
+The output is
+
+- always organized as list, even if the result count is 1 or 0
+- usually named after the endpoint
+- contains only a limited number attributes, but always `id` and `name`
+- limited to 100 entries
+
+### authentication
+
+Before showing you examples, you need to setup an API token first. You can do that via environment variable:
+
+```
+export CLOUDINGIO_API_TOKEN=my_secret_token
+```
+
+Or, more securely, have tuca write it into your desktop's keyring. The following command will give you an interactive prompt to do that.
+
+```
+tuca auth create
+```
+
+_And before you say anything, I'm aware that `auth` is not an endpoint._
+
+If you provide both, the environment variable takes precendence.
+
+### here we go
+
+Time to create your first server. First, pick an image.
+
+```bash
+tuca images list
+```
+
+<details>
+<summary>Output</summary>
+
+_(modified/shortened for brevity)_
+
+```json
+{
+    "sizes/flavors": [
+        ...
+        {
+            "accessMethods": {
+                "password": "required",
+                "sshKey": "not-supported"
+            },
+            "id": "jXEm7yK3MJ2VYkQ9",
+            "minimumSizeGb": 25,
+            "name": "Windows 11 (English 64Bit | Based on Windows Server 2025)"
+        },
+        ...
+    ]
+}
+```
+</details>
+
+Now pick a size.
+
+```bash
+tuca flavors list
+```
+
+<details>
+<summary>Output</summary>
+
+_(modified/shortened for brevity)_
+
+```json
+{
+    "sizes/flavors": [
+        ...
+        {
+            "id": "8x16",
+            "pricePerHour": 0.05472,
+            "pricePerMonthApprox": 39.9456,
+            "ramGb": 16,
+            "vCores": 8.0
+        },
+        ...
+    ]
+}
+```
+</details>
+
+That's all to create a server with minimal configuration.
+
+```bash
+# Windows 11 compatible image
+# 8 cores, 16 GB RAM
+# default firewall
+# default image size
+tuca servers create --image jXEm7yK3MJ2VYkQ9 --name MyWinServer --flavorid 8x16 --password start123
+```
+
+<details>
+<summary>Output</summary>
+
+```json
+{
+    "servers": [
+        {
+            "createdAt": "2026-02-04T23:42:16",
+            "id": "mJOZBKqGP702Xjax",
+            "name": "MyWinServer",
+            "publicIp": null,
+            "status": "Pending"
+        }
+    ]
+}
+```
+</details>
+
+Spooling up the server can take some time and you can check how it's doing.
+
+```bash
+tuca servers list --name MyWinServer
+```
+<details>
+<summary>Output</summary>
+
+```json
+{
+    "servers": [
+        {
+            "createdAt": "2026-02-04T23:42:16",
+            "id": "mJOZBKqGP702Xjax",
+            "name": "MyWinServer",
+            "publicIp": "103.23.60.115",
+            "status": "Creating"
+        }
+    ]
+}
+```
+</details>
+
+The server will be ready eventually.
+
+<details>
+<summary>Output</summary>
+
+```json
+{
+    "servers": [
+        {
+            "createdAt": "2026-02-04T23:42:16",
+            "id": "mJOZBKqGP702Xjax",
+            "name": "MyWinServer",
+            "publicIp": "103.23.60.115",
+            "status": "Active"
+        }
+    ]
+}
+```
+</details>
+
+## License
+
+[GPL-2.0-or-later](https://github.com/dehesselle/tuca/blob/main/LICENSE)

tuca-0.1.dist-info/RECORD

@@ -0,0 +1,19 @@
+tuca/__init__.py,sha256=KzDQV85fxm0H_ASGBafaDf69e2L-0oKI0_t0goAIOfg,1208
+tuca/_version.py,sha256=zCgmOZqbKglNFIB9lB_sgjMOR6jrNzUWcCp-9rpWq18,699
+tuca/auth.py,sha256=OAFRSOOTAsyBPmKJ7KHb3L0ejXRiYVfzs1rVovcT888,1279
+tuca/clouding.py,sha256=Tgejg5O_8pbHj8_CQ986kdmob9ojheyXnH7gqUKdjdk,4295
+tuca/config.py,sha256=aLakXs_1mv8zHLFq3xwncKsIWgjVWoLX9G3gGKQRviw,239
+tuca/resource.py,sha256=gYz6MZ3CYqgypidx-0pEYdYV7On4L1pfD38ULGJqdmA,372
+tuca/version.py,sha256=taB1W2GReTIAt84Pmu0AMkKNNQ8ikyaiZ86scz4O2gQ,216
+tuca/endpoints/__init__.py,sha256=FH69f1PqpNSIqvEOwwklaynpd53XWtj1ONNH_AYbd5w,345
+tuca/endpoints/endpoint.py,sha256=SY5bVXJGWIKLUVrYg2nJjWVlnG7E9-GzJ_2ZFV4OOZ8,4735
+tuca/endpoints/firewalls.py,sha256=e_ch3O8Amp8e_mj6bT1D_FtAqNZtjaIDWecNvpGRUVY,403
+tuca/endpoints/images.py,sha256=VT7_rH4gi6VcpT_AwYoesklhYmxbY43mFih39LTGnBs,1048
+tuca/endpoints/keypairs.py,sha256=cjjCCcuW-YIezwBvqlIkrBPSAkdZxKMpgPWWPuT74nc,2269
+tuca/endpoints/servers.py,sha256=hjdnsuRMt2_afUIvVzhZduKGs1HNeNV8dM_GsbiceuY,6355
+tuca/endpoints/sizes.py,sha256=1RXSbvc8R2GcA9tvj7NG1H64tYEZ6XQ2fq7R8KqEJzI,1755
+tuca/endpoints/snapshots.py,sha256=Pu2Xt66LN9j9m6gQtl9i_-Of65dwg8UcOHS1WfAi1iU,962
+tuca-0.1.dist-info/METADATA,sha256=CYEjLYKCnLr4427Fb_dnCpo6PQkuems5iUUpCzeCd9k,4834
+tuca-0.1.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+tuca-0.1.dist-info/entry_points.txt,sha256=wRAMuApJ2TVsoGlTJn_krDLmjhKV07pELJ1ccGdMI5o,35
+tuca-0.1.dist-info/RECORD,,

tuca-0.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.28.0
+Root-Is-Purelib: true
+Tag: py3-none-any

tuca-0.1.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+tuca = tuca:main