tuca 0.1__tar.gz

tuca-0.1/.github/workflows/build.yml

@@ -0,0 +1,105 @@
+# SPDX-FileCopyrightText: 2026 René de Hesselle <dehesselle@web.de>
+#
+# SPDX-License-Identifier: GPL-2.0-or-later
+
+name: Build
+on:
+  push:
+jobs:
+  #-----------------------------------------------------------------------------
+
+  Build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      - name: Run Black
+        uses: psf/black@stable
+        with:
+          options: "--check --verbose"
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+
+      - name: Build project
+        run: uv build
+
+      - name: Upload artifacts
+        uses: actions/upload-artifact@v6
+        with:
+          name: dist
+          path: dist/tuca*.*
+
+  #-----------------------------------------------------------------------------
+
+  Prerelease:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    needs: Build
+    if: startsWith(github.ref, 'refs/heads/develop')
+    steps:
+      - name: Download artifacts
+        uses: actions/download-artifact@v7
+        with:
+          name: dist
+
+      - name: Update prerelease
+        uses: ncipollo/release-action@v1
+        with:
+          name: develop
+          artifacts: tuca*.*
+          prerelease: true
+          allowUpdates: true
+          removeArtifacts: true
+          tag: latest
+          body: |
+            This prerelease follows the develop branch.
+            For testing purposes only.
+
+  #-----------------------------------------------------------------------------
+
+  Release:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    needs: Build
+    if: startsWith(github.ref, 'refs/tags/v')
+    steps:
+      - name: Download artifacts
+        uses: actions/download-artifact@v7
+        with:
+          name: dist
+
+      - name: Create release
+        uses: ncipollo/release-action@v1
+        with:
+          artifacts: tuca*.*
+          draft: true
+
+  #-----------------------------------------------------------------------------
+
+  PyPI:
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+    needs:
+      - Build
+      - Release
+    if: startsWith(github.ref, 'refs/tags/v')
+    environment:
+      name: pypi
+      url: https://pypi.org/p/tuca
+
+    steps:
+      - name: Download artifacts
+        uses: actions/download-artifact@v7
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

tuca-0.1/.gitignore

@@ -0,0 +1,11 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+src/tuca/_version.py
+
+# Virtual environments
+.venv

tuca-0.1/.python-version

@@ -0,0 +1 @@
+3.12

tuca-0.1/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,201 @@
+# 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/pyproject.toml

@@ -0,0 +1,27 @@
+[project]
+name = "tuca"
+dynamic = ["version"]
+description = "tool using clouding api"
+readme = "README.md"
+authors = [{ name = "René de Hesselle", email = "dehesselle@web.de" }]
+requires-python = ">=3.12"
+dependencies = [
+    "keyring>=25.7.0",
+    "pydantic>=2.12.5",
+    "python-slugify>=8.0.4",
+    "requests>=2.32.5",
+    "urlpath>=2.0.0",
+]
+
+[project.scripts]
+tuca = "tuca:main"
+
+[build-system]
+requires = ["hatchling", "hatch-vcs"]
+build-backend = "hatchling.build"
+
+[tool.hatch.version]
+source = "vcs"
+
+[tool.hatch.build.hooks.vcs]
+version-file = "src/tuca/_version.py"

tuca-0.1/src/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-0.1/src/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-0.1/src/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)