cloudsim 1.0.0__tar.gz

cloudsim-1.0.0/.env.example

@@ -0,0 +1,14 @@
+# Example environment for CloudSim
+
+# Where CloudSim writes runtime state (VM folders and SQLite state).
+# Recommended: set an absolute path.
+# Windows example: E:\cloudsim-workspace
+# macOS/Linux example: /home/you/cloudsim-workspace
+CLOUDSIM_WORKSPACE=cloudsim-workspace
+
+# Optional: real PostgreSQL admin connection (for real Cloud SQL simulation)
+CLOUDSIM_PG_HOST=127.0.0.1
+CLOUDSIM_PG_PORT=5432
+CLOUDSIM_PG_ADMIN_USER=postgres
+CLOUDSIM_PG_ADMIN_PASSWORD=pg123
+CLOUDSIM_PG_ADMIN_DB=postgres

cloudsim-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 CloudSim
+
+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.

cloudsim-1.0.0/MANIFEST.in

@@ -0,0 +1,12 @@
+include README.md
+include LICENSE
+include .env.example
+include pyproject.toml
+include MANIFEST.in
+
+recursive-include cloudsim *.py
+recursive-include cloudsim/docs *.md
+recursive-include cloudsim/scripts *.py
+recursive-include cloudsim/services *.py
+recursive-include cloudsim/web *.py
+include cloudsim/.env.example

cloudsim-1.0.0/PKG-INFO

@@ -0,0 +1,248 @@
+Metadata-Version: 2.4
+Name: cloudsim
+Version: 1.0.0
+Summary: Local-first cloud infrastructure simulator (Flask API + CLI).
+Author: CloudSim
+License-Expression: MIT
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: Flask==3.1.0
+Requires-Dist: psycopg[binary]==3.2.3
+Requires-Dist: pymongo==4.10.1
+Dynamic: license-file
+
+# CloudSim
+
+CloudSim is a local-first cloud infrastructure simulator (Flask API + CLI) designed to teach you how the cloud works.
+
+---
+
+## Cloud Architect Academy
+Want to learn the cloud step-by-step? We've built a premium interactive course website just for you.
+
+[![Launch Academy](https://img.shields.io/badge/Academy_Site-Visit_Now-8A2BE2?style=for-the-badge&logo=googlescholar)](http://localhost:5173)
+
+---
+
+## Install
+
+### PyPI (normal)
+```bash
+pip install cloudsim
+```
+
+### TestPyPI (testing)
+TestPyPI does not mirror all dependencies, so include the real PyPI index for dependencies:
+```bash
+pip install -i https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple cloudsim==1.0.2
+```
+
+## Configuration (.env)
+
+Fastest setup:
+```bash
+cloudsim config init --workspace ./cloudsim-workspace
+cloudsim config show
+
+# Start API
+cloudsim-server
+```
+
+`cloudsim config init` writes:
+- `<workspace>/.env` (your environment config)
+- `~/.cloudsim/config.json` (default workspace pointer, so you can run `cloudsim` from any folder)
+
+If you do not want a global default workspace file, use:
+```bash
+cloudsim config init --workspace ./cloudsim-workspace --no-default
+```
+
+CloudSim reads environment variables from a workspace `.env` file:
+- `<workspace>/.env`
+
+If you installed via `pip`, an example file is also included inside the installed package at `cloudsim/.env.example`.
+To print its path:
+```bash
+python -c "import cloudsim; from pathlib import Path; print(Path(cloudsim.__file__).resolve().parent / '.env.example')"
+```
+
+Quick start (PowerShell):
+```powershell
+$env:CLOUDSIM_WORKSPACE = "E:\\codex\\cloudsim-workspace"
+New-Item -ItemType Directory -Force $env:CLOUDSIM_WORKSPACE | Out-Null
+Copy-Item .\\.env.example "$env:CLOUDSIM_WORKSPACE\\.env"
+```
+
+Quick start (macOS/Linux):
+```bash
+export CLOUDSIM_WORKSPACE="$HOME/cloudsim-workspace"
+mkdir -p "$CLOUDSIM_WORKSPACE"
+cp ./.env.example "$CLOUDSIM_WORKSPACE/.env"
+```
+
+PostgreSQL (optional, for "real" Cloud SQL):
+- `CLOUDSIM_PG_HOST=127.0.0.1`
+- `CLOUDSIM_PG_PORT=5432`
+- `CLOUDSIM_PG_ADMIN_USER=postgres`
+- `CLOUDSIM_PG_ADMIN_PASSWORD=pg123`
+- `CLOUDSIM_PG_ADMIN_DB=postgres`
+
+If these are not set (or Postgres is not reachable), CloudSim continues to work using per-VM SQLite by default.
+
+## Workspace (Where VMs/DBs Are Created)
+
+CloudSim writes runtime state into a *workspace* directory (not inside the installed package directory).
+
+Workspace resolution order:
+1. `CLOUDSIM_WORKSPACE`
+2. `~/.cloudsim/config.json` (`workspace`) (created by `cloudsim config init`)
+3. current working directory
+
+Windows (PowerShell):
+```powershell
+$env:CLOUDSIM_WORKSPACE = "E:\codex\cloudsim-workspace"
+```
+
+macOS/Linux:
+```bash
+export CLOUDSIM_WORKSPACE="$HOME/cloudsim-workspace"
+```
+
+Files created in the workspace:
+- `<workspace>/.cloudsim/simulation.db` (global state)
+- `<workspace>/.cloudsim/sql_service.db` (simulated Cloud SQL accounts/tenancy)
+- `<workspace>/vms/<vmId>/vm_state.db` (per-VM state snapshot)
+- `<workspace>/vms/<vmId>/vm_sqlite.db` (per-VM SQLite database)
+- `<workspace>/autoscale-vms/<vmId>/...` (autoscaled VMs)
+
+## Start Backend API
+
+```bash
+python -m cloudsim.app
+```
+
+Default API base URL: `http://127.0.0.1:5000`
+
+## CLI: Run Globally Or Inside A VM Shell
+
+There are two common ways to use CloudSim CLI:
+
+### A) Global CLI (works immediately, no PATH changes)
+```bash
+python -m cloudsim.cli_services.runtime --help
+python -m cloudsim.cli_services.runtime health
+```
+
+### B) Direct `cloudsim` command (global install)
+`pip install cloudsim` installs a launcher (`cloudsim` / `cloudsim.exe`) into your Python scripts folder.
+You can run `cloudsim` directly only if that scripts folder is on your `PATH`.
+
+Windows: find user-base
+```powershell
+python -m site --user-base
+```
+Add `<user-base>\Scripts` to `PATH`, open a new terminal, then:
+```powershell
+cloudsim --help
+```
+
+macOS/Linux: find user-base
+```bash
+python -m site --user-base
+```
+Add `<user-base>/bin` to `PATH`, open a new terminal, then:
+```bash
+cloudsim --help
+```
+
+Example paths:
+- Windows (Microsoft Store Python): `C:\Users\CHIRAG\AppData\Local\Packages\PythonSoftwareFoundation.Python.3.13_qbz5n2kfra8p0\LocalCache\local-packages\Python313\Scripts`
+- Windows (python.org installer, common): `C:\Users\CHIRAG\AppData\Roaming\Python\Python313\Scripts`
+- macOS/Linux (common): `$HOME/.local/bin`
+
+### C) Direct `cloudsim` command (virtualenv)
+Activating a venv automatically adds its scripts folder to `PATH`, so `cloudsim` works inside that venv.
+
+Windows (PowerShell):
+```powershell
+python -m venv .venv
+.\.venv\Scripts\Activate.ps1
+cloudsim --help
+```
+
+Windows (cmd):
+```bat
+python -m venv .venv
+.\.venv\Scripts\activate.bat
+cloudsim --help
+```
+
+macOS/Linux:
+```bash
+python -m venv .venv
+source .venv/bin/activate
+cloudsim --help
+```
+
+## VM Shell (`cloudsim ssh`)
+
+`cloudsim ssh <vmId>` opens a VM workspace shell and sets VM context variables:
+- `CLOUDSIM_IN_VM_SHELL=1`
+- `CLOUDSIM_VM_ID=<vmId>`
+- `CLOUDSIM_VM_SPACE=vm_<vmId>`
+
+From inside the VM shell, per-VM commands can auto-target that VM (example: per-VM SQLite).
+
+## Create A VM
+
+```bash
+python -m cloudsim.cli_services.runtime vm create \
+  --name vm1 \
+  --region us-central1 \
+  --machine-type e2-micro \
+  --image "Ubuntu 22.04 LTS" \
+  --backend-profile-id python-fastapi
+```
+
+## Per-VM SQLite (Default "Cloud SQL" Fallback)
+
+```bash
+python -m cloudsim.cli_services.runtime sql provision --vm-id <vmId>
+python -m cloudsim.cli_services.runtime sql execute --vm-id <vmId> --mode local --query "CREATE TABLE items(id INTEGER PRIMARY KEY, name TEXT)"
+python -m cloudsim.cli_services.runtime sql execute --vm-id <vmId> --mode local --query "INSERT INTO items(name) VALUES (?)" --params-json '["alpha"]'
+python -m cloudsim.cli_services.runtime sql execute --vm-id <vmId> --mode local --query "SELECT id,name FROM items"
+```
+
+## Load Balancer + Traffic Simulation
+
+```bash
+python -m cloudsim.cli_services.runtime lb create --name lb1 --type HTTP(S) --region global --backend-vm-id <vmId>
+python -m cloudsim.cli_services.runtime simulate --lb-id <lbId> --endpoint-key "GET /health" --requests 500
+```
+
+## Autoscale Demo
+
+```bash
+python -m cloudsim.cli_services.runtime autoscale-test --requests 1000 --max-instances 5
+```
+
+## Real PostgreSQL (Optional)
+
+Set these env vars (or use `<workspace>/.env`) before starting the backend:
+- `CLOUDSIM_PG_HOST=...`
+- `CLOUDSIM_PG_PORT=...`
+- `CLOUDSIM_PG_ADMIN_USER=...`
+- `CLOUDSIM_PG_ADMIN_PASSWORD=...`
+- `CLOUDSIM_PG_ADMIN_DB=...`
+
+Then:
+```bash
+python -m cloudsim.cli_services.runtime sql real-status
+python -m cloudsim.cli_services.runtime sql real-provision --vm-id <vmId>
+python -m cloudsim.cli_services.runtime sql real-connect --vm-id <vmId>
+```
+
+## License
+
+MIT (see `LICENSE`).

cloudsim-1.0.0/README.md

@@ -0,0 +1,234 @@
+# CloudSim
+
+CloudSim is a local-first cloud infrastructure simulator (Flask API + CLI) designed to teach you how the cloud works.
+
+---
+
+## Cloud Architect Academy
+Want to learn the cloud step-by-step? We've built a premium interactive course website just for you.
+
+[![Launch Academy](https://img.shields.io/badge/Academy_Site-Visit_Now-8A2BE2?style=for-the-badge&logo=googlescholar)](http://localhost:5173)
+
+---
+
+## Install
+
+### PyPI (normal)
+```bash
+pip install cloudsim
+```
+
+### TestPyPI (testing)
+TestPyPI does not mirror all dependencies, so include the real PyPI index for dependencies:
+```bash
+pip install -i https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple cloudsim==1.0.2
+```
+
+## Configuration (.env)
+
+Fastest setup:
+```bash
+cloudsim config init --workspace ./cloudsim-workspace
+cloudsim config show
+
+# Start API
+cloudsim-server
+```
+
+`cloudsim config init` writes:
+- `<workspace>/.env` (your environment config)
+- `~/.cloudsim/config.json` (default workspace pointer, so you can run `cloudsim` from any folder)
+
+If you do not want a global default workspace file, use:
+```bash
+cloudsim config init --workspace ./cloudsim-workspace --no-default
+```
+
+CloudSim reads environment variables from a workspace `.env` file:
+- `<workspace>/.env`
+
+If you installed via `pip`, an example file is also included inside the installed package at `cloudsim/.env.example`.
+To print its path:
+```bash
+python -c "import cloudsim; from pathlib import Path; print(Path(cloudsim.__file__).resolve().parent / '.env.example')"
+```
+
+Quick start (PowerShell):
+```powershell
+$env:CLOUDSIM_WORKSPACE = "E:\\codex\\cloudsim-workspace"
+New-Item -ItemType Directory -Force $env:CLOUDSIM_WORKSPACE | Out-Null
+Copy-Item .\\.env.example "$env:CLOUDSIM_WORKSPACE\\.env"
+```
+
+Quick start (macOS/Linux):
+```bash
+export CLOUDSIM_WORKSPACE="$HOME/cloudsim-workspace"
+mkdir -p "$CLOUDSIM_WORKSPACE"
+cp ./.env.example "$CLOUDSIM_WORKSPACE/.env"
+```
+
+PostgreSQL (optional, for "real" Cloud SQL):
+- `CLOUDSIM_PG_HOST=127.0.0.1`
+- `CLOUDSIM_PG_PORT=5432`
+- `CLOUDSIM_PG_ADMIN_USER=postgres`
+- `CLOUDSIM_PG_ADMIN_PASSWORD=pg123`
+- `CLOUDSIM_PG_ADMIN_DB=postgres`
+
+If these are not set (or Postgres is not reachable), CloudSim continues to work using per-VM SQLite by default.
+
+## Workspace (Where VMs/DBs Are Created)
+
+CloudSim writes runtime state into a *workspace* directory (not inside the installed package directory).
+
+Workspace resolution order:
+1. `CLOUDSIM_WORKSPACE`
+2. `~/.cloudsim/config.json` (`workspace`) (created by `cloudsim config init`)
+3. current working directory
+
+Windows (PowerShell):
+```powershell
+$env:CLOUDSIM_WORKSPACE = "E:\codex\cloudsim-workspace"
+```
+
+macOS/Linux:
+```bash
+export CLOUDSIM_WORKSPACE="$HOME/cloudsim-workspace"
+```
+
+Files created in the workspace:
+- `<workspace>/.cloudsim/simulation.db` (global state)
+- `<workspace>/.cloudsim/sql_service.db` (simulated Cloud SQL accounts/tenancy)
+- `<workspace>/vms/<vmId>/vm_state.db` (per-VM state snapshot)
+- `<workspace>/vms/<vmId>/vm_sqlite.db` (per-VM SQLite database)
+- `<workspace>/autoscale-vms/<vmId>/...` (autoscaled VMs)
+
+## Start Backend API
+
+```bash
+python -m cloudsim.app
+```
+
+Default API base URL: `http://127.0.0.1:5000`
+
+## CLI: Run Globally Or Inside A VM Shell
+
+There are two common ways to use CloudSim CLI:
+
+### A) Global CLI (works immediately, no PATH changes)
+```bash
+python -m cloudsim.cli_services.runtime --help
+python -m cloudsim.cli_services.runtime health
+```
+
+### B) Direct `cloudsim` command (global install)
+`pip install cloudsim` installs a launcher (`cloudsim` / `cloudsim.exe`) into your Python scripts folder.
+You can run `cloudsim` directly only if that scripts folder is on your `PATH`.
+
+Windows: find user-base
+```powershell
+python -m site --user-base
+```
+Add `<user-base>\Scripts` to `PATH`, open a new terminal, then:
+```powershell
+cloudsim --help
+```
+
+macOS/Linux: find user-base
+```bash
+python -m site --user-base
+```
+Add `<user-base>/bin` to `PATH`, open a new terminal, then:
+```bash
+cloudsim --help
+```
+
+Example paths:
+- Windows (Microsoft Store Python): `C:\Users\CHIRAG\AppData\Local\Packages\PythonSoftwareFoundation.Python.3.13_qbz5n2kfra8p0\LocalCache\local-packages\Python313\Scripts`
+- Windows (python.org installer, common): `C:\Users\CHIRAG\AppData\Roaming\Python\Python313\Scripts`
+- macOS/Linux (common): `$HOME/.local/bin`
+
+### C) Direct `cloudsim` command (virtualenv)
+Activating a venv automatically adds its scripts folder to `PATH`, so `cloudsim` works inside that venv.
+
+Windows (PowerShell):
+```powershell
+python -m venv .venv
+.\.venv\Scripts\Activate.ps1
+cloudsim --help
+```
+
+Windows (cmd):
+```bat
+python -m venv .venv
+.\.venv\Scripts\activate.bat
+cloudsim --help
+```
+
+macOS/Linux:
+```bash
+python -m venv .venv
+source .venv/bin/activate
+cloudsim --help
+```
+
+## VM Shell (`cloudsim ssh`)
+
+`cloudsim ssh <vmId>` opens a VM workspace shell and sets VM context variables:
+- `CLOUDSIM_IN_VM_SHELL=1`
+- `CLOUDSIM_VM_ID=<vmId>`
+- `CLOUDSIM_VM_SPACE=vm_<vmId>`
+
+From inside the VM shell, per-VM commands can auto-target that VM (example: per-VM SQLite).
+
+## Create A VM
+
+```bash
+python -m cloudsim.cli_services.runtime vm create \
+  --name vm1 \
+  --region us-central1 \
+  --machine-type e2-micro \
+  --image "Ubuntu 22.04 LTS" \
+  --backend-profile-id python-fastapi
+```
+
+## Per-VM SQLite (Default "Cloud SQL" Fallback)
+
+```bash
+python -m cloudsim.cli_services.runtime sql provision --vm-id <vmId>
+python -m cloudsim.cli_services.runtime sql execute --vm-id <vmId> --mode local --query "CREATE TABLE items(id INTEGER PRIMARY KEY, name TEXT)"
+python -m cloudsim.cli_services.runtime sql execute --vm-id <vmId> --mode local --query "INSERT INTO items(name) VALUES (?)" --params-json '["alpha"]'
+python -m cloudsim.cli_services.runtime sql execute --vm-id <vmId> --mode local --query "SELECT id,name FROM items"
+```
+
+## Load Balancer + Traffic Simulation
+
+```bash
+python -m cloudsim.cli_services.runtime lb create --name lb1 --type HTTP(S) --region global --backend-vm-id <vmId>
+python -m cloudsim.cli_services.runtime simulate --lb-id <lbId> --endpoint-key "GET /health" --requests 500
+```
+
+## Autoscale Demo
+
+```bash
+python -m cloudsim.cli_services.runtime autoscale-test --requests 1000 --max-instances 5
+```
+
+## Real PostgreSQL (Optional)
+
+Set these env vars (or use `<workspace>/.env`) before starting the backend:
+- `CLOUDSIM_PG_HOST=...`
+- `CLOUDSIM_PG_PORT=...`
+- `CLOUDSIM_PG_ADMIN_USER=...`
+- `CLOUDSIM_PG_ADMIN_PASSWORD=...`
+- `CLOUDSIM_PG_ADMIN_DB=...`
+
+Then:
+```bash
+python -m cloudsim.cli_services.runtime sql real-status
+python -m cloudsim.cli_services.runtime sql real-provision --vm-id <vmId>
+python -m cloudsim.cli_services.runtime sql real-connect --vm-id <vmId>
+```
+
+## License
+
+MIT (see `LICENSE`).

cloudsim-1.0.0/cloudsim/.env.example

@@ -0,0 +1,14 @@
+# Example environment for CloudSim
+
+# Where CloudSim writes runtime state (VM folders and SQLite state).
+# Recommended: set an absolute path.
+# Windows example: E:\cloudsim-workspace
+# macOS/Linux example: /home/you/cloudsim-workspace
+CLOUDSIM_WORKSPACE=cloudsim-workspace
+
+# Optional: real PostgreSQL admin connection (for real Cloud SQL simulation)
+CLOUDSIM_PG_HOST=127.0.0.1
+CLOUDSIM_PG_PORT=5432
+CLOUDSIM_PG_ADMIN_USER=postgres
+CLOUDSIM_PG_ADMIN_PASSWORD=pg123
+CLOUDSIM_PG_ADMIN_DB=postgres

cloudsim-1.0.0/cloudsim/__init__.py

@@ -0,0 +1 @@
+"""Nimbus Cloud Simulator backend package."""

cloudsim-1.0.0/cloudsim/app.py

@@ -0,0 +1,26 @@
+import argparse
+import sys
+from cloudsim.web.app_factory import create_app
+
+app = create_app()
+
+
+def main(argv: list[str] | None = None) -> int:
+    if argv is None:
+        argv = sys.argv[1:]
+
+    parser = argparse.ArgumentParser(prog="cloudsim-server", description="Start the CloudSim API server.")
+    parser.add_argument("--host", default="127.0.0.1", help="The interface to bind to (default: 127.0.0.1)")
+    parser.add_argument("--port", type=int, default=5000, help="The port to bind to (default: 5000)")
+    parser.add_argument("--debug", action="store_true", help="Enable Flask debug mode")
+    
+    args = parser.parse_args(argv)
+
+    print(f"[*] Starting CloudSim Server on {args.host}:{args.port} (debug={args.debug})")
+    app.run(host=args.host, port=args.port, debug=args.debug)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())
+

cloudsim-1.0.0/cloudsim/cli.py

@@ -0,0 +1,10 @@
+from __future__ import annotations
+
+import sys
+
+from cloudsim.cli_services.main import main
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv[1:]))
+

cloudsim-1.0.0/cloudsim/cli_services/common.py

@@ -0,0 +1,74 @@
+from __future__ import annotations
+
+import json
+import os
+import urllib.error
+import urllib.request
+from pathlib import Path
+from typing import Any
+
+from cloudsim import paths
+
+DEFAULT_API_URL = os.environ.get("CLOUDSIM_API_URL", "http://127.0.0.1:5000").rstrip("/")
+
+
+def get_repo_root() -> Path:
+    # Keep legacy name used across CLI handlers; this is the workspace root.
+    return paths.workspace_root()
+
+
+class CliError(Exception):
+    def __init__(self, message: str, status_code: int = 1) -> None:
+        super().__init__(message)
+        self.message = message
+        self.status_code = status_code
+
+
+def _parse_json(value: str, label: str) -> Any:
+    try:
+        return json.loads(value)
+    except json.JSONDecodeError as error:
+        raise CliError(f"Invalid JSON for {label}: {error.msg}") from error
+
+
+def _request(base_url: str, method: str, path: str, payload: dict[str, Any] | None = None) -> dict[str, Any]:
+    url = f"{base_url}{path}"
+    headers = {"Content-Type": "application/json"}
+    body = None if payload is None else json.dumps(payload).encode("utf-8")
+    req = urllib.request.Request(url=url, method=method, data=body, headers=headers)
+    try:
+        with urllib.request.urlopen(req, timeout=15) as response:
+            raw = response.read().decode("utf-8")
+            data = json.loads(raw) if raw else {}
+    except urllib.error.HTTPError as error:
+        raw = error.read().decode("utf-8")
+        message = f"HTTP {error.code}"
+        if raw:
+            try:
+                data = json.loads(raw)
+                message = data.get("error") or data.get("message") or message
+            except json.JSONDecodeError:
+                message = f"{message}: {raw}"
+        raise CliError(message, status_code=error.code)
+    except urllib.error.URLError as error:
+        raise CliError(f"Unable to reach backend at {base_url}: {error}") from error
+    except json.JSONDecodeError as error:
+        raise CliError(f"Invalid JSON response from backend: {error}") from error
+
+    if isinstance(data, dict) and data.get("ok") is False:
+        raise CliError(str(data.get("error") or "Request failed"))
+    return data
+
+
+def _print(data: Any, key: str | None = None) -> None:
+    if key and isinstance(data, dict):
+        if "state" in data:
+            data = data["state"]
+        if key in data:
+            target = data[key]
+            if isinstance(target, list) and target:
+                print(json.dumps(target[0], indent=2, sort_keys=True))
+            else:
+                print(json.dumps(target, indent=2, sort_keys=True))
+            return
+    print(json.dumps(data, indent=2, sort_keys=True))