hyper-wireless 1.0.0__py3-none-any.whl

hyper_wireless-1.0.0.dist-info/METADATA

@@ -0,0 +1,160 @@
+Metadata-Version: 2.4
+Name: hyper-wireless
+Version: 1.0.0
+Summary: Hyper Wireless - Cloud Testing Platform for 3GPP 5G NR Conformance
+Author-email: Hyper Wireless Team <dev@hyper-wireless.com>
+Project-URL: Homepage, https://hyper-wireless.com
+Project-URL: Dashboard, https://app.hyper-wireless.com
+Project-URL: API, https://cloud-api.hyper-wireless.com
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Testing
+Classifier: Topic :: System :: Networking
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: requests>=2.28.0
+Requires-Dist: websockets>=12.0
+
+# TTCPP (TTCN-3 C++ Test Suite)
+
+## Overview
+
+**TTCPP** is a C++ implementation of the 3GPP 5G test suite, originally written in TTCN-3. It is designed to test the 5G UE stack (specifically using `srsRAN_5G`'s `srsue` implementation). By transpiling the TTCN-3 test cases and components into C++, TTCPP offers a native, performant environment for 5G testing, completely bypassing the need for a traditional TTCN-3 compiler or heavy runtime environment.
+
+The test suite acts as the network (AMF/gNB) and communicates with the Device Under Test (DUT), the `srsue` stack (packaged as `ttcn3_dut`), exchanging RRC, NAS, and IP packets to validate compliance against 3GPP specifications (such as TS 24.501 and TS 38.331).
+
+## Key Features
+
+- **Native C++ Execution:** The test cases are transpiled from TTCN-3 to modern C++ (`src/TTCN_TestSuite`), enabling standard debugging (GDB, LLDB) and high performance.
+- **5G UE Testing:** Directly integrates with `srsRAN_5G` to validate UE behavior.
+- **Custom Port Handlers:** C++ implementations for standard TTCN-3 port operations (handling sockets, threading, and system-level IPC) in `src/components/` and `src/common/`.
+- **Message Sequence Charts (MSC):** Automatic parsing of test logs to render visual sequence diagrams of test execution.
+- **Web GUI:** A modern Next.js-based graphical dashboard for managing, executing, and reviewing tests.
+
+## Directory Structure
+
+- `src/` - Source code for the transpiled test suite, custom components, codecs, and security algorithms.
+  - `src/suites/<version>/` - Isolated C++ transpiled test suite packages (e.g. `NR5GC_IWD_25wk50`).
+  - `src/TTCN_TestSuite/` - Symlink pointing to the active suite's transpiled modules.
+  - `src/components/` - TTCN-3 port and component handlers.
+  - `src/main.cpp` - The entry point for the `ttcn3_runner` test executor.
+- `ttcn/` - Contains raw TTCN-3 packages organized by deliverable version (e.g. `ttcn/NR5GC_IWD_25wk50/`).
+- `configs/` - Modular configuration repository:
+  - `configs/transpiler/` - Base transpiler configurations and transforms for `TTCN3-X`.
+  - `configs/suites/` - Per-suite transpiler overlay configurations.
+  - `configs/modulepars/` - Per-suite module parameters (PICS/PIXIT).
+- `srsRAN_5G/` - The full-stack 5G RAN and UE source code repository, which compiles the `ttcn3_dut` UE simulator executable.
+- `tools/` - Utility scripts and tools.
+  - `tools/suite_manager.py` - Test suite version manager (list, info, switch, transpile).
+- `logs/` - Directory where test execution logs and artifacts are stored.
+- `usim.cfg` - Configuration for the simulated USIM (Home PLMN, Equivalent PLMNs, etc.).
+
+## Prerequisites & System Dependencies
+
+To compile and run the test suite (specifically the virtual USIM smartcard integration), the following system dependencies and packages are required:
+
+### 1. Host Packages
+Install PC/SC daemon, PCSC-Lite development headers, and tools:
+```bash
+sudo apt-get install pcscd libpcsclite-dev pcsc-tools
+```
+
+### 2. Virtual Smartcard Simulator (`onomondo-uicc`)
+- Implements the softsim smartcard that simulates physical UICC/USIM behavior over PC/SC.
+- Should be cloned and built in a sibling directory (e.g., `../onomondo-uicc` relative to this repository). Respository URL: https://github.com/onomondo/onomondo-uicc.git
+- The test runner defaults to this sibling directory, but you can override it by exporting the `ONOMONDO_UICC_DIR` environment variable.
+- Ensure it is compiled before running tests:
+  ```bash
+  cd ../onomondo-uicc
+  make # or standard build commands for softsim
+  ```
+
+### 3. SIM Card Configuration Utility (`pySim`)
+- Used by the test suite to configure the softsim smartcard (programming IMSIs, security parameters, resetting SQNs, etc.).
+- Should be set up in a sibling directory (e.g., `../pysim` relative to this repository). Respository URL: https://github.com/osmocom/pysim.git
+- The test runner defaults to this sibling directory, but you can override it by exporting the `PYSIM_DIR` environment variable.
+- Ensure the virtual environment and requirements are prepared:
+  ```bash
+  cd ../pysim
+  python3 -m venv venv
+  ./venv/bin/pip install -r requirements.txt
+  ```
+
+## Building the Project
+
+This project uses CMake for its build system. Only the LLVM Clang compiler is supported for building the C++ test runner due to GCC's high CPU consumption during parallel compilation.
+
+### 1. Build the C++ Test Runner (`ttcn3_runner`)
+Configure and build the runner using the Clang preset:
+```bash
+cmake --preset clang
+cmake --build build-clang -j$(nproc) --target ttcn3_runner
+```
+
+### 2. Build the UE Simulator (`ttcn3_dut`)
+Build the simulator inside the `srsRAN_5G` subdirectory:
+```bash
+cd srsRAN_5G
+mkdir -p build
+cd build
+cmake .. -G Ninja -DENABLE_TTCN3=ON -DENABLE_TTCN3_NR=ON
+ninja ttcn3_dut
+```
+
+## Managing TTCN-3 Test Suite Versions
+
+TTCPP supports multiple co-existing versions of the 3GPP TTCN-3 test suite. Use `./tools/suite_manager.py` to inspect, switch, and transpile test suite versions:
+
+```bash
+# List all available raw and transpiled test suite versions
+./tools/suite_manager.py list
+
+# View detailed information about a specific suite
+./tools/suite_manager.py info NR5GC_IWD_25wk50
+
+# Switch the active test suite profile
+./tools/suite_manager.py switch NR5GC_IWD_25wk50
+
+# Transpile a new TTCN-3 deliverable package
+./tools/suite_manager.py transpile NR5GC_IWD_26wk08
+```
+
+## Running Tests
+
+Test execution is orchestrated using the provided bash script, `./tools/scripts/run_test.sh`. This script handles launching the `ttcn3_dut` and the `ttcn3_runner` processes, establishing their communication via sockets.
+
+To run a specific test case (using the active suite):
+```bash
+./tools/scripts/run_test.sh <TEST_CASE_NAME>
+
+# Example:
+./tools/scripts/run_test.sh TC_6_1_1_1_NR5GC
+```
+
+To run a test case against a specific test suite version:
+```bash
+./tools/scripts/run_test.sh --suite NR5GC_IWD_25wk50 TC_6_1_1_1_NR5GC
+```
+
+Test logs (such as `tc_runner.log` and `ttcn3_ue.log`) will be populated in a subfolder corresponding to the test case inside the `logs/` directory (e.g., `logs/<TEST_CASE_NAME>/`).
+
+## Upper Tester (UT) Integration
+
+The test suite orchestrates testcase execution and logs via Upper Tester (UT) interface messages exchanged between the runner (`ttcn3_runner`) and the simulator (`ttcn3_dut`).
+
+In addition to standard MMI commands, the runner sends the following native UT control messages:
+- **`TC_START`**: Sent at the start of a test run to initialize the simulator's logging sink and parameterize the simulator logs (e.g., `logs/<TEST_CASE_NAME>/<TEST_CASE_NAME>_run0_ttcn3_ue.log`) dynamically with the active testcase name.
+  - JSON payload: `{"Cmd": {"TC_START": {"Name": "<TEST_CASE_NAME>"}}}`
+- **`TC_END`**: Sent at the end of a test run to finalize the simulator's test case context.
+  - JSON payload: `{"Cmd": {"TC_END": null}}`
+
+## GUI Dashboard
+
+A graphical web dashboard is provided to easily manage test execution, view historical test runs, and visualize signaling logs using Mermaid.js MSCs.
+
+To start the GUI:
+```bash
+cd tools/gui
+npm install
+npm run dev
+```
+Navigate to `http://localhost:3000` to access the dashboard.

hyper_wireless-1.0.0.dist-info/RECORD

@@ -0,0 +1,6 @@
+ttcn3_cloud_cli.py,sha256=ABbzeYeScEM1icBBdU3I0fnRMsPliszIaqen5Sl6SaM,47041
+hyper_wireless-1.0.0.dist-info/METADATA,sha256=mI2OL1pHw6uV7YjmuCSH9EcDOehtoIzUrv2YqevQb-o,7820
+hyper_wireless-1.0.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+hyper_wireless-1.0.0.dist-info/entry_points.txt,sha256=Rsc9_32-RLm0RsxjnnDJMocX18yOZkdpqYoRHZ9aqQc,85
+hyper_wireless-1.0.0.dist-info/top_level.txt,sha256=fcN7XHL2e8IQqi9eak42OwFbrAgYeClHz4tscAbOXTg,16
+hyper_wireless-1.0.0.dist-info/RECORD,,

hyper_wireless-1.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

hyper_wireless-1.0.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+hyper = ttcn3_cloud_cli:main
+hyper-wireless = ttcn3_cloud_cli:main

hyper_wireless-1.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+ttcn3_cloud_cli

ttcn3_cloud_cli.py

@@ -0,0 +1,994 @@
+#!/usr/bin/env python3
+"""
+ttcn3_cloud_cli.py - Client CLI for the TTCN-3 Cloud Testing Service.
+
+Enables developers and CI/CD pipelines to run 3GPP conformance test suites in the cloud
+while testing local UEs (such as srsRAN_5G `ttcn3_dut` or hardware UEs) bridged over
+a secure WebSocket multiplex tunnel.
+"""
+
+import os
+import sys
+import re
+import json
+import time
+import socket
+import select
+import signal
+import asyncio
+import logging
+import argparse
+import subprocess
+import shutil
+from pathlib import Path
+from typing import Optional, Dict, Any
+
+# Auto-detect local virtual environment if missing dependencies in system python
+_venv_python = Path(__file__).resolve().parent.parent / ".venv" / "bin" / "python3"
+if (sys.prefix == sys.base_prefix) and _venv_python.is_file():
+    try:
+        import requests
+        import websockets
+    except ImportError:
+        os.execv(str(_venv_python), [str(_venv_python)] + sys.argv)
+
+try:
+    import requests
+except ImportError:
+    print("Error: 'requests' package is required.")
+    print("Run: source .venv/bin/activate  (or: pip install --break-system-packages requests)")
+    sys.exit(1)
+
+try:
+    import websockets
+except ImportError:
+    print("Error: 'websockets' package is required.")
+    print("Run: source .venv/bin/activate  (or: pip install --break-system-packages websockets)")
+    sys.exit(1)
+
+
+def load_env_file(path: Path) -> Dict[str, str]:
+    """Reads key-value pairs from an environment/credential file."""
+    if not path.is_file():
+        return {}
+    try:
+        content = path.read_text(encoding="utf-8").strip()
+        env_vars = {}
+        for line in content.splitlines():
+            line = line.strip()
+            if not line or line.startswith('#'):
+                continue
+            if '=' in line:
+                k, v = line.split('=', 1)
+                k = k.strip().removeprefix('export ').strip()
+                v = v.strip().strip('"\'')
+                if k:
+                    env_vars[k] = v
+        return env_vars
+    except Exception:
+        return {}
+
+
+# Auto-load candidate credential files
+for env_candidate in [Path.home() / ".jenkins_credentials", Path.home() / ".jenkins_env", Path.cwd() / ".jenkins_env", Path.cwd() / ".jenkins_credentials"]:
+    loaded = load_env_file(env_candidate)
+    for k, v in loaded.items():
+        if k not in os.environ:
+            os.environ[k] = v
+
+
+
+class CloudClient:
+    def __init__(
+        self,
+        endpoint: str,
+        api_key: str = "",
+        cf_client_id: str = "",
+        cf_client_secret: str = ""
+    ):
+        endpoint = (endpoint or "").strip()
+        if endpoint and not endpoint.startswith("http://") and not endpoint.startswith("https://"):
+            endpoint = f"https://{endpoint}"
+        self.endpoint = endpoint.rstrip("/")
+        self.headers = {"Content-Type": "application/json"}
+        api_key = api_key or os.environ.get("TTCN3_CLOUD_API_KEY", "")
+        cf_client_id = cf_client_id or os.environ.get("CF_ACCESS_CLIENT_ID", "")
+        cf_client_secret = cf_client_secret or os.environ.get("CF_ACCESS_CLIENT_SECRET", "")
+        if api_key:
+            self.headers["Authorization"] = f"Bearer {api_key}"
+        if cf_client_id and cf_client_secret:
+            self.headers["CF-Access-Client-Id"] = cf_client_id
+            self.headers["CF-Access-Client-Secret"] = cf_client_secret
+
+    def get_health(self):
+        resp = requests.get(f"{self.endpoint}/health", headers=self.headers, timeout=10)
+        resp.raise_for_status()
+        return resp.json()
+
+    def get_suites(self):
+        resp = requests.get(f"{self.endpoint}/api/v1/suites", headers=self.headers, timeout=10)
+        resp.raise_for_status()
+        return resp.json()
+
+    def get_testcases(self, suite: str):
+        resp = requests.get(f"{self.endpoint}/api/v1/suites/{suite}/testcases", headers=self.headers, timeout=15)
+        resp.raise_for_status()
+        return resp.json()
+
+    def create_session(
+        self,
+        testcase: str,
+        suite: Optional[str] = None,
+        timeout: int = 300,
+        log_level: str = "info",
+        mode: str = "remote_ue",
+        rat: str = "nr",
+        timer_mode: str = "balanced",
+        timer_step_ms: Optional[int] = None,
+    ):
+        payload = {
+            "testcase": testcase,
+            "suite": suite,
+            "timeout_seconds": timeout,
+            "log_level": log_level,
+            "mode": mode,
+            "rat": rat,
+            "timer_mode": timer_mode,
+        }
+        if timer_step_ms is not None:
+            payload["timer_step_ms"] = timer_step_ms
+        max_attempts = 15
+        for attempt in range(max_attempts):
+            try:
+                resp = requests.post(f"{self.endpoint}/api/v1/sessions", json=payload, headers=self.headers, timeout=30)
+                if resp.status_code in (503, 429) and attempt < max_attempts - 1:
+                    backoff = min(2 * (attempt + 1), 10)
+                    print(f"[*] Cloud runner slots busy (HTTP {resp.status_code}). Retrying in {backoff}s (attempt {attempt + 1}/{max_attempts})...")
+                    time.sleep(backoff)
+                    continue
+                resp.raise_for_status()
+                return resp.json()
+            except requests.exceptions.RequestException as e:
+                status_code = getattr(getattr(e, 'response', None), 'status_code', None)
+                if attempt < max_attempts - 1 and status_code in (503, 429):
+                    backoff = min(2 * (attempt + 1), 10)
+                    print(f"[*] Cloud runner slots busy (HTTP {status_code}). Retrying in {backoff}s (attempt {attempt + 1}/{max_attempts})...")
+                    time.sleep(backoff)
+                    continue
+                raise
+
+    def get_session(self, session_id: str):
+        resp = requests.get(f"{self.endpoint}/api/v1/sessions/{session_id}", headers=self.headers, timeout=10)
+        resp.raise_for_status()
+        return resp.json()
+
+    def cancel_session(self, session_id: str):
+        resp = requests.delete(f"{self.endpoint}/api/v1/sessions/{session_id}", headers=self.headers, timeout=10)
+        resp.raise_for_status()
+        return resp.json()
+
+    def list_artifacts(self, session_id: str):
+        try:
+            resp = requests.get(f"{self.endpoint}/api/v1/sessions/{session_id}/artifacts", headers=self.headers, timeout=10)
+            if resp.status_code == 200:
+                return resp.json().get("artifacts", [])
+        except Exception:
+            pass
+        return []
+
+    def download_artifact(self, session_id: str, filename: str, target_path: Path):
+        resp = requests.get(f"{self.endpoint}/api/v1/sessions/{session_id}/artifacts/{filename}", headers=self.headers, stream=True, timeout=30)
+        if resp.status_code == 200:
+            target_path.parent.mkdir(parents=True, exist_ok=True)
+            with open(target_path, "wb") as f:
+                for chunk in resp.iter_content(chunk_size=8192):
+                    f.write(chunk)
+            return True
+        return False
+
+    def download_logs_archive(self, session_id: str, target_path: Path) -> bool:
+        """Downloads all session execution logs in a single compressed .tar.gz bundle."""
+        url = f"{self.endpoint}/api/v1/sessions/{session_id}/logs.tar.gz"
+        try:
+            resp = requests.get(url, headers=self.headers, stream=True, timeout=60)
+            if resp.status_code == 200:
+                target_path.parent.mkdir(parents=True, exist_ok=True)
+                with open(target_path, "wb") as f:
+                    for chunk in resp.iter_content(chunk_size=65536):
+                        if chunk:
+                            f.write(chunk)
+                return True
+        except Exception:
+            pass
+        return False
+
+
+
+def get_ws_kwargs(headers_dict):
+    if not headers_dict:
+        return {}
+    import inspect
+    sig = inspect.signature(websockets.connect)
+    if "additional_headers" in sig.parameters:
+        return {"additional_headers": headers_dict}
+    return {"extra_headers": headers_dict}
+
+
+async def run_local_relay(local_port: int, remote_ws_url: str, headers: dict, stop_event: asyncio.Event, ready_event: Optional[asyncio.Event] = None):
+    """
+    Listens on local_port for TCP connections (from srsue/ttcn3_dut) and bridges
+    raw bytes to the remote WebSocket MUX tunnel.
+    """
+    server = None
+
+    async def handle_client(reader: asyncio.StreamReader, writer: asyncio.StreamWriter):
+        sock = writer.get_extra_info("socket")
+        if sock:
+            try:
+                sock.setsockopt(socket.IPPROTO_TCP, socket.TCP_NODELAY, 1)
+            except Exception:
+                pass
+
+        print(f"\n[\033[1;34mRELAY\033[0m] Local UE connected on port {local_port}. Connecting to cloud MUX tunnel...")
+        try:
+            extra_headers = {}
+            if "Authorization" in headers:
+                extra_headers["Authorization"] = headers["Authorization"]
+            if "CF-Access-Client-Id" in headers:
+                extra_headers["CF-Access-Client-Id"] = headers["CF-Access-Client-Id"]
+                extra_headers["CF-Access-Client-Secret"] = headers["CF-Access-Client-Secret"]
+
+            ws_kwargs = get_ws_kwargs(extra_headers)
+
+            ws = None
+            for attempt in range(10):
+                if stop_event.is_set():
+                    return
+                try:
+                    ws = await websockets.connect(
+                        remote_ws_url,
+                        ping_interval=20,
+                        ping_timeout=20,
+                        max_size=10 * 1024 * 1024,
+                        **ws_kwargs,
+                    )
+                    break
+                except Exception as ce:
+                    if attempt == 9:
+                        print(f"[\033[1;31mRELAY ERROR\033[0m] Failed to connect to cloud MUX tunnel at {remote_ws_url}: {ce}")
+                        return
+                    await asyncio.sleep(0.3)
+
+            if not ws:
+                return
+
+            async with ws:
+                print(f"[\033[1;32mRELAY\033[0m] Cloud MUX WebSocket tunnel established.")
+
+                is_done = False
+
+                async def tcp_to_ws():
+                    nonlocal is_done
+                    try:
+                        while not is_done and not stop_event.is_set():
+                            data = await reader.read(65536)
+                            if not data:
+                                break
+                            await ws.send(data)
+                    except Exception:
+                        pass
+                    finally:
+                        is_done = True
+
+                async def ws_to_tcp():
+                    nonlocal is_done
+                    try:
+                        while not is_done and not stop_event.is_set():
+                            msg = await ws.recv()
+                            if isinstance(msg, bytes):
+                                writer.write(msg)
+                                await writer.drain()
+                            elif isinstance(msg, str):
+                                writer.write(msg.encode("utf-8"))
+                                await writer.drain()
+                    except Exception:
+                        pass
+                    finally:
+                        is_done = True
+
+                t1 = asyncio.create_task(tcp_to_ws())
+                t2 = asyncio.create_task(ws_to_tcp())
+                await asyncio.wait([t1, t2], return_when=asyncio.FIRST_COMPLETED)
+                is_done = True
+                t1.cancel()
+                t2.cancel()
+
+        except Exception as e:
+            print(f"[\033[1;31mRELAY ERROR\033[0m] Error in relay bridge: {e}")
+        finally:
+            try:
+                writer.close()
+                await writer.wait_closed()
+            except Exception:
+                pass
+            print(f"[\033[1;34mRELAY\033[0m] Relay connection closed.")
+
+    try:
+        server = await asyncio.start_server(handle_client, "127.0.0.1", local_port)
+        print(f"[\033[1;32mRELAY\033[0m] Local TCP Multiplex Relay listening on 127.0.0.1:{local_port}")
+        if ready_event:
+            ready_event.set()
+        while not stop_event.is_set():
+            await asyncio.sleep(0.5)
+    except Exception as e:
+        print(f"[\033[1;31mRELAY ERROR\033[0m] Failed to bind local relay on port {local_port}: {e}")
+    finally:
+        if server:
+            server.close()
+            await server.wait_closed()
+
+
+SIGNALING_PATTERNS = [
+    (re.compile(r'Starting execution of target testcase:\s*(\S+)'), 'Test Case Execution Started: \\1'),
+    (re.compile(r'\"rrcSetupRequest\"'), 'RRC: RRCSetupRequest (UE -> Network)'),
+    (re.compile(r'\"rrcSetup\"'), 'RRC: RRCSetup (Network -> UE)'),
+    (re.compile(r'\"rrcSetupComplete\"'), 'RRC: RRCSetupComplete (UE -> Network)'),
+    (re.compile(r'\"securityModeCommand\"'), 'RRC: SecurityModeCommand (Network -> UE)'),
+    (re.compile(r'\"securityModeComplete\"'), 'RRC: SecurityModeComplete (UE -> Network)'),
+    (re.compile(r'\"rrcReconfiguration\"'), 'RRC: RRCReconfiguration (Network -> UE)'),
+    (re.compile(r'\"rrcReconfigurationComplete\"'), 'RRC: RRCReconfigurationComplete (UE -> Network)'),
+    (re.compile(r'\"rrcRelease\"'), 'RRC: RRCRelease (Network -> UE)'),
+    (re.compile(r'f_NR_PreliminaryPass.*\"(Step[^\"]+)\"'), 'Preliminary Pass: \\1'),
+    (re.compile(r'Active cell changed to (\d+)'), 'Cell Configuration: Active Cell -> \\1'),
+    (re.compile(r'AS Security StartRestart.*CellId (\d+)'), 'Security: AS Security Activated (Cell \\1)'),
+    (re.compile(r'AS Security Release.*CellId (\d+)'), 'Security: AS Security Released (Cell \\1)'),
+    (re.compile(r'Testcase gracefully stopped'), 'Test Case Execution Stopped Gracefully'),
+]
+
+
+def format_elapsed(seconds: float) -> str:
+    m = int(seconds) // 60
+    s = int(seconds) % 60
+    return f"{m:02d}:{s:02d}"
+
+
+async def stream_logs(remote_ws_url: str, headers: dict, stop_event: asyncio.Event, verdict_holder: dict, raw_logs: bool = False, start_time: Optional[float] = None):
+    """
+    Subscribes to the live log stream WebSocket on the cloud runner and displays
+    real-time test progress (steps, signaling milestones, verdicts, elapsed time).
+    """
+    extra_headers = {}
+    if "Authorization" in headers:
+        extra_headers["Authorization"] = headers["Authorization"]
+    if "CF-Access-Client-Id" in headers:
+        extra_headers["CF-Access-Client-Id"] = headers["CF-Access-Client-Id"]
+        extra_headers["CF-Access-Client-Secret"] = headers["CF-Access-Client-Secret"]
+
+    ws_kwargs = get_ws_kwargs(extra_headers)
+
+    ws = None
+    last_err = None
+    for _ in range(15):
+        if stop_event.is_set():
+            return
+        try:
+            ws = await websockets.connect(remote_ws_url, **ws_kwargs)
+            break
+        except Exception as e:
+            last_err = e
+            await asyncio.sleep(0.3)
+
+    if not ws:
+        print(f"[\033[1;31mSTREAM ERROR\033[0m] Could not connect to cloud log stream at {remote_ws_url}: {last_err}", flush=True)
+        return
+
+    if start_time is None:
+        start_time = time.time()
+    current_step = None
+    last_event = None
+    last_heartbeat_time = time.time()
+
+    def print_progress(text: str, event_type: str = "milestone"):
+        elapsed = format_elapsed(time.time() - start_time)
+        if event_type == "step":
+            print(f"\n\033[1;36m[{elapsed}] ───▶ {text}\033[0m", flush=True)
+        elif event_type == "verdict":
+            color = "\033[1;32m" if "PASS" in text else "\033[1;31m"
+            print(f"\n{color}[{elapsed}] =========================================================================\033[0m", flush=True)
+            print(f"{color}[{elapsed}] >>> {text}\033[0m", flush=True)
+            print(f"{color}[{elapsed}] =========================================================================\033[0m\n", flush=True)
+        elif event_type == "pass":
+            print(f"   \033[1;32m✔\033[0m \033[32m[{elapsed}] {text}\033[0m", flush=True)
+        elif event_type == "status":
+            print(f"\033[1;33m[{elapsed}] [*] {text}\033[0m", flush=True)
+        elif event_type == "error":
+            print(f"\033[1;31m[{elapsed}] [!] {text}\033[0m", flush=True)
+        else:
+            print(f"   \033[1;34m✔\033[0m \033[90m[{elapsed}]\033[0m {text}", flush=True)
+
+    try:
+        async with ws:
+            while not stop_event.is_set():
+                try:
+                    msg_text = await asyncio.wait_for(ws.recv(), timeout=1.0)
+                    msg = json.loads(msg_text)
+                    mtype = msg.get("type", "log")
+                    content = msg.get("content", "")
+
+                    if mtype == "step":
+                        if content != current_step:
+                            current_step = content
+                            print_progress(content, event_type="step")
+                            last_event = None
+                            last_heartbeat_time = time.time()
+                    elif mtype == "verdict":
+                        if not verdict_holder.get("verdict"):
+                            verdict_holder["verdict"] = content
+                            print_progress(f"Final Test Verdict: {content}", event_type="verdict")
+                    elif mtype == "status":
+                        print_progress(content, event_type="status")
+                    elif mtype == "error":
+                        print_progress(content, event_type="error")
+                    else:
+                        if raw_logs:
+                            sys.stdout.write(content)
+                            sys.stdout.flush()
+                        else:
+                            for raw_line in content.splitlines():
+                                clean = re.sub(r'^\[\d{4}-\d{2}-\d{2}[ T]\d{2}:\d{2}:\d{2}(?:\.\d+)?\]\s*', '', raw_line.strip())
+                                if re.match(r'^Steps?\s+[0-9a-zA-Z]', clean, re.IGNORECASE) and len(clean) < 60:
+                                    if clean != current_step:
+                                        current_step = clean
+                                        print_progress(clean, event_type="step")
+                                        last_event = None
+                                        last_heartbeat_time = time.time()
+                                    continue
+
+                                if "Final Test Verdict:" in clean:
+                                    v = clean.split("Final Test Verdict:", 1)[1].strip()
+                                    if not verdict_holder.get("verdict"):
+                                        verdict_holder["verdict"] = v
+                                        print_progress(f"Final Test Verdict: {v}", event_type="verdict")
+                                    continue
+
+                                if "PreliminaryPass" in clean or "f_NR_PreliminaryPass" in clean:
+                                    m = re.search(r'PreliminaryPass.*\"([^\"]+)\"', clean)
+                                    pass_name = m.group(1) if m else "Pass"
+                                    print_progress(f"Preliminary Pass: {pass_name}", event_type="pass")
+                                    last_heartbeat_time = time.time()
+                                    continue
+
+                                for pat, label in SIGNALING_PATTERNS:
+                                    m = pat.search(clean)
+                                    if m:
+                                        desc = label
+                                        if '\\1' in label and m.groups():
+                                            desc = label.replace('\\1', m.group(1))
+                                        if desc != last_event:
+                                            last_event = desc
+                                            print_progress(desc, event_type="milestone")
+                                            last_heartbeat_time = time.time()
+                                        break
+
+                                if "[RUNNER_STATUS]" in clean:
+                                    print_progress(clean, event_type="status")
+
+                except asyncio.TimeoutError:
+                    if not raw_logs and (time.time() - last_heartbeat_time > 10.0):
+                        elapsed = format_elapsed(time.time() - start_time)
+                        step_info = f" ({current_step})" if current_step else ""
+                        print(f"   \033[90m... [{elapsed}] Executing{step_info}\033[0m", flush=True)
+                        last_heartbeat_time = time.time()
+                    continue
+                except websockets.ConnectionClosed:
+                    break
+    except Exception as e:
+        print(f"[\033[1;33mSTREAM NOTE\033[0m] Stream closed: {e}", flush=True)
+
+
+def run_command_handler(args):
+    client = CloudClient(
+        endpoint=args.endpoint,
+        api_key=args.token or os.environ.get("TTCN3_CLOUD_API_KEY", ""),
+        cf_client_id=args.cf_client_id or os.environ.get("CF_ACCESS_CLIENT_ID", ""),
+        cf_client_secret=args.cf_client_secret or os.environ.get("CF_ACCESS_CLIENT_SECRET", ""),
+    )
+
+    exec_mode = getattr(args, "mode", None)
+    if not exec_mode:
+        if getattr(args, "srsue", False):
+            exec_mode = "remote_ue"
+        else:
+            exec_mode = "cloud_ue"
+
+    mode_label = "Cloud Headless UE (Colocated High-Speed)" if exec_mode == "cloud_ue" else "Remote UE (Local Relay)"
+    timer_mode = getattr(args, "timer_mode", "adaptive")
+    timer_step_ms = getattr(args, "timer_step_ms", None)
+    if timer_step_ms:
+        step_desc = f"{timer_step_ms}ms"
+    elif timer_mode == "accurate":
+        step_desc = "100ms"
+    elif timer_mode == "fast":
+        step_desc = "2000ms"
+    elif timer_mode == "balanced":
+        step_desc = "500ms"
+    elif timer_mode == "adaptive":
+        step_desc = "dynamic 100ms - 5000ms (Gear 3 auto-geared)"
+    else:
+        step_desc = "500ms"
+
+    timeout = getattr(args, "timeout", None)
+    if timeout is None:
+        timeout = 900 if exec_mode == "remote_ue" else 600
+    timeout_desc = f"{timeout}s ({timeout // 60} mins)" if timeout % 60 == 0 else f"{timeout}s"
+
+    print("\n=========================================================================")
+    print(f" TTCN-3 Cloud Runner - Test Session Initialization")
+    print("=========================================================================")
+    print(f" Cloud Endpoint : {args.endpoint}")
+    print(f" Test Case      : {args.tc}")
+    print(f" Execution Mode : {mode_label}")
+    print(f" Simulation Time: {timer_mode} mode (max step: {step_desc})")
+    print(f" Timeout        : {timeout_desc}")
+    if args.suite:
+        print(f" Suite Version  : {args.suite}")
+    print("=========================================================================\n")
+
+    print("[1/4] Creating remote test session in the cloud...")
+    try:
+        session = client.create_session(
+            testcase=args.tc,
+            suite=args.suite,
+            timeout=timeout,
+            log_level=args.loglevel,
+            mode=exec_mode,
+            rat=getattr(args, "rat", "nr"),
+            timer_mode=timer_mode,
+            timer_step_ms=timer_step_ms,
+        )
+    except Exception as e:
+        print(f"Error creating session: {e}")
+        return 1
+
+    session_id = session["session_id"]
+    slot = session["slot"]
+    cloud_mux_port = session["ports"]["multiplex"]
+    vpcd_port = session["ports"]["vpcd"]
+
+    # Use specified local port or avoid collision if testing on localhost
+    is_localhost = "127.0.0.1" in args.endpoint or "localhost" in args.endpoint
+    if args.local_port:
+        local_port = args.local_port
+    elif is_localhost:
+        local_port = cloud_mux_port + 1000
+    else:
+        local_port = cloud_mux_port
+
+    # Resolve URLs
+    stream_url = session["ws_stream_url"]
+    mux_url = session["ws_mux_url"]
+
+    # If URLs are relative, make absolute based on endpoint
+    if stream_url.startswith("/"):
+        ws_base = args.endpoint.replace("https://", "wss://").replace("http://", "ws://")
+        stream_url = f"{ws_base}{stream_url}"
+    if mux_url.startswith("/"):
+        ws_base = args.endpoint.replace("https://", "wss://").replace("http://", "ws://")
+        mux_url = f"{ws_base}{mux_url}"
+
+    print(f"   Allocated Cloud Slot: {slot}")
+    print(f"   Cloud Session ID    : {session_id}")
+    if exec_mode == "cloud_ue":
+        print(f"   Cloud Multiplex Port: {cloud_mux_port} (Internal Loopback)")
+    else:
+        print(f"   Local Multiplex Port: {local_port}")
+        print(f"   Cloud Multiplex Port: {cloud_mux_port}")
+
+    # Start asyncio loop for relay and streaming
+    loop = asyncio.new_event_loop()
+    asyncio.set_event_loop(loop)
+    stop_event = asyncio.Event()
+    verdict_holder = {"verdict": None}
+
+    dut_proc = None
+    softsim_proc = None
+    ue_stdout_file = None
+    softsim_file = None
+
+    def cleanup_all():
+        stop_event.set()
+        if dut_proc and dut_proc.poll() is None:
+            print("\nStopping local UE simulator...")
+            try:
+                os.killpg(os.getpgid(dut_proc.pid), signal.SIGKILL)
+            except Exception:
+                try:
+                    dut_proc.terminate()
+                except Exception:
+                    dut_proc.kill()
+        if softsim_proc and softsim_proc.poll() is None:
+            print("Stopping local SoftSIM...")
+            try:
+                os.killpg(os.getpgid(softsim_proc.pid), signal.SIGKILL)
+            except Exception:
+                pass
+        if ue_stdout_file and not ue_stdout_file.closed:
+            try:
+                ue_stdout_file.close()
+            except Exception:
+                pass
+        if softsim_file and not softsim_file.closed:
+            try:
+                softsim_file.close()
+            except Exception:
+                pass
+        if exec_mode != "cloud_ue":
+            subprocess.run(f"pkill -9 -f 'softsim.*{vpcd_port}' >/dev/null 2>&1 || true", shell=True)
+            subprocess.run(f"pkill -9 -f 'softsim_instance_{slot}' >/dev/null 2>&1 || true", shell=True)
+            subprocess.run(f"fuser -k {vpcd_port}/tcp >/dev/null 2>&1 || true", shell=True)
+            subprocess.run(f"fuser -k {local_port}/tcp >/dev/null 2>&1 || true", shell=True)
+
+    async def main_async():
+        nonlocal dut_proc, softsim_proc, ue_stdout_file, softsim_file
+
+        raw_logs_mode = getattr(args, "raw_logs", False)
+        common_start_time = time.time()
+        ue_monitor_task = None
+
+        if exec_mode == "cloud_ue":
+            print("\n[2/4] Headless UE (`ttcn3_dut` + SoftSIM) running in cloud alongside runner...")
+            print("\n[3/4] Streaming Live Test Progress from Cloud Runner...")
+            print("-------------------------------------------------------------------------")
+            stream_task = asyncio.create_task(stream_logs(stream_url, client.headers, stop_event, verdict_holder, raw_logs=raw_logs_mode, start_time=common_start_time))
+            relay_task = None
+        else:
+            if exec_mode != "cloud_ue":
+                subprocess.run(f"pkill -9 -f 'softsim.*{vpcd_port}' >/dev/null 2>&1 || true", shell=True)
+                subprocess.run(f"pkill -9 -f 'softsim_instance_{slot}' >/dev/null 2>&1 || true", shell=True)
+                subprocess.run(f"fuser -k {local_port}/tcp >/dev/null 2>&1 || true", shell=True)
+                subprocess.run(f"fuser -k {vpcd_port}/tcp >/dev/null 2>&1 || true", shell=True)
+
+            ready_event = asyncio.Event()
+            relay_task = asyncio.create_task(run_local_relay(local_port, mux_url, client.headers, stop_event, ready_event))
+            stream_task = asyncio.create_task(stream_logs(stream_url, client.headers, stop_event, verdict_holder, raw_logs=raw_logs_mode, start_time=common_start_time))
+
+            # Wait for local TCP relay to start listening
+            await ready_event.wait()
+
+            # Optional local srsRAN_5G / softsim launch
+            if args.srsue:
+                print("\n[2/4] Starting local SoftSIM & srsRAN_5G UE (`ttcn3_dut`)...")
+                ttcpp_dir = Path(__file__).resolve().parent.parent
+                dev_dir = ttcpp_dir.parent
+                onomondo_dir = Path(os.environ.get("ONOMONDO_UICC_DIR", dev_dir / "onomondo-uicc"))
+                srsran_dir = Path(os.environ.get("SRSRAN_DIR", dev_dir / "srsRAN_5G"))
+
+                softsim_bin = onomondo_dir / "build" / "src" / "softsim" / "softsim"
+                dut_bin = srsran_dir / "build" / "bin" / "ttcn3_dut"
+
+                if not softsim_bin.exists() and (ttcpp_dir / "bin/softsim").exists():
+                    softsim_bin = ttcpp_dir / "bin/softsim"
+                if not dut_bin.exists() and (ttcpp_dir / "bin/ttcn3_dut").exists():
+                    dut_bin = ttcpp_dir / "bin/ttcn3_dut"
+
+                files_dir = onomondo_dir / "files"
+                if not files_dir.exists() and (ttcpp_dir / "files").exists():
+                    files_dir = ttcpp_dir / "files"
+
+                dut_log_dir = ttcpp_dir / f"logs/{args.tc}"
+                dut_log_dir.mkdir(parents=True, exist_ok=True)
+
+                if softsim_bin.exists():
+                    subprocess.run(f"pkill -9 -f 'softsim.*{vpcd_port}' >/dev/null 2>&1 || true", shell=True)
+                    subprocess.run(f"pkill -9 -f 'softsim_instance_{slot}' >/dev/null 2>&1 || true", shell=True)
+                    softsim_dir = ttcpp_dir / f"logs/softsim_instance_{slot}"
+                    if softsim_dir.exists():
+                        shutil.rmtree(softsim_dir, ignore_errors=True)
+                    softsim_dir.mkdir(parents=True, exist_ok=True)
+                    if files_dir.exists():
+                        shutil.copytree(files_dir, softsim_dir / "files", dirs_exist_ok=True)
+                    sys.path.append(str(ttcpp_dir / "tools" / "usim_configs"))
+                    try:
+                        from softsim_utils import get_init_script_for_testcase
+                        init_script = Path(get_init_script_for_testcase(args.tc, str(ttcpp_dir / "tools" / "usim_configs")))
+                    except Exception:
+                        init_script = ttcpp_dir / "tools/usim_configs/init_softsim_config_1.py"
+                    if init_script.exists():
+                        env_init = os.environ.copy()
+                        env_init["PYTHONPATH"] = str(ttcpp_dir / "tools" / "usim_configs")
+                        subprocess.run([sys.executable, str(init_script), str(softsim_dir)], env=env_init, check=True, stdout=subprocess.DEVNULL)
+
+                    softsim_file = open(dut_log_dir / "softsim.log", "w", encoding="utf-8", errors="replace")
+                    softsim_loop_cmd = f"while true; do '{softsim_bin}' {vpcd_port} || true; sleep 0.2; done"
+                    softsim_proc = subprocess.Popen(
+                        softsim_loop_cmd,
+                        shell=True,
+                        cwd=str(softsim_dir),
+                        stdout=softsim_file,
+                        stderr=subprocess.STDOUT,
+                        preexec_fn=os.setsid,
+                    )
+                    print(f"   SoftSIM running on port {vpcd_port} (PID: {softsim_proc.pid})")
+                    await asyncio.sleep(0.5)
+
+                if dut_bin.exists():
+                    dut_cmd = [
+                        str(dut_bin),
+                        "--tester.instance_id", str(slot),
+                        "--tester.ip", "127.0.0.1",
+                        "--tester.port", str(local_port),
+                        "--usim.mode", "vpcd",
+                        "--rat", args.rat,
+                        "--loglevel", args.loglevel,
+                        "--logfilename", str(dut_log_dir / "ttcn3_ue.log"),
+                        "--log.file_max_size=-1",
+                        "--log.file_max_size_truncate=true",
+                        "--at.port", str(27007 + slot * 20),
+                    ]
+                    dut_env = os.environ.copy()
+                    dut_env["INSTANCE_ID"] = str(slot)
+                    dut_env["TESTER_IP"] = "127.0.0.1"
+                    dut_env["TESTER_PORT"] = str(local_port)
+                    dut_env["SRSRAN_POOL_SIZE"] = "512"
+                    ue_stdout_file = open(dut_log_dir / "ue_stdout.log", "w", encoding="utf-8", errors="replace")
+                    dut_proc = subprocess.Popen(
+                        dut_cmd,
+                        cwd=str(ttcpp_dir),
+                        env=dut_env,
+                        stdout=ue_stdout_file,
+                        stderr=subprocess.STDOUT,
+                        preexec_fn=os.setsid,
+                    )
+                    print(f"   srsRAN_5G `ttcn3_dut` launched (PID: {dut_proc.pid})")
+
+                    async def monitor_local_ue():
+                        ue_log_file = dut_log_dir / "ue_stdout.log"
+                        local_patterns = [
+                            (re.compile(r"Initializing TTCN3 Mux Client"), "Local UE: Connecting to cloud multiplex relay"),
+                            (re.compile(r"Switching on UE"), "Local UE: Powering ON stack"),
+                            (re.compile(r"RRC_NR: SIB1 received! setting for pci=(\d+)"), "Local UE: SIB1 acquired (PCI \\1)"),
+                            (re.compile(r"RRC_NR: (?:send_setup_request|connection_request)"), "Local UE: Transmitting RRCSetupRequest"),
+                            (re.compile(r"MAC_NR: Calling phy->send_prach"), "Local UE: Transmitting PRACH Preamble"),
+                            (re.compile(r"MAC_NR: ra_response_reception"), "Local UE: Random Access Response (RAR) Received"),
+                            (re.compile(r"Applying security context|AS Security"), "Local UE: AS Security Activated"),
+                            (re.compile(r"Received RRC Release|rrcRelease"), "Local UE: RRC Release Received"),
+                        ]
+                        seen_events = set()
+                        while not stop_event.is_set():
+                            if ue_log_file.exists():
+                                try:
+                                    with open(ue_log_file, "r", encoding="utf-8", errors="replace") as f:
+                                        for line in f:
+                                            for pat, desc in local_patterns:
+                                                m = pat.search(line)
+                                                if m and desc not in seen_events:
+                                                    seen_events.add(desc)
+                                                    actual_desc = desc
+                                                    if "\\1" in desc and m.groups():
+                                                        actual_desc = desc.replace("\\1", m.group(1))
+                                                    elapsed = format_elapsed(time.time() - common_start_time)
+                                                    print(f"   \033[1;35m⚙\033[0m \033[90m[{elapsed}]\033[0m \033[35m{actual_desc}\033[0m", flush=True)
+                                except Exception:
+                                    pass
+                            await asyncio.sleep(0.3)
+
+                    ue_monitor_task = asyncio.create_task(monitor_local_ue())
+            else:
+                print(f"\n[2/4] Awaiting local UE connection on 127.0.0.1:{local_port}...")
+                print(f"      (Start your local UE/srsue pointing to tester port {local_port})")
+
+            print("\n[3/4] Establishing Cloud Tunnel & Streaming Logs...")
+            print("-------------------------------------------------------------------------")
+
+        # Check session completion periodically
+        async def poll_status():
+            while not stop_event.is_set():
+                await asyncio.sleep(1.0)
+                try:
+                    s = client.get_session(session_id)
+                    if s["status"] in ("COMPLETED", "FAILED", "TIMEOUT", "CANCELLED"):
+                        verdict_holder["verdict"] = s.get("verdict")
+                        if s.get("error_message"):
+                            print(f"\n\033[1;31m[CLOUD RUNNER ERROR]\033[0m {s['error_message']}\n", flush=True)
+                        stop_event.set()
+                        break
+                except Exception:
+                    pass
+
+        poll_task = asyncio.create_task(poll_status())
+
+        # Wait until stop_event is set
+        while not stop_event.is_set():
+            await asyncio.sleep(0.5)
+
+        if ue_monitor_task:
+            ue_monitor_task.cancel()
+        if relay_task:
+            relay_task.cancel()
+        stream_task.cancel()
+        poll_task.cancel()
+
+    try:
+        loop.run_until_complete(main_async())
+    except KeyboardInterrupt:
+        print("\n\nTest interrupted by user. Cancelling cloud session...")
+        try:
+            client.cancel_session(session_id)
+        except Exception:
+            pass
+    finally:
+        cleanup_all()
+
+    # 4. Summary & Artifact Download
+    print("-------------------------------------------------------------------------")
+    print("\n=========================================================================")
+    print(" TEST EXECUTION SUMMARY")
+    print("=========================================================================")
+    final_session = {}
+    try:
+        final_session = client.get_session(session_id)
+        verdict = final_session.get("verdict") or verdict_holder.get("verdict") or "UNKNOWN"
+        duration = final_session.get("duration_seconds", "N/A")
+        print(f" Test Case : {args.tc}")
+        print(f" Suite     : {final_session.get('suite', args.suite)}")
+        print(f" Duration  : {duration}s")
+        print(f" Verdict   : {verdict}")
+    except Exception:
+        verdict = verdict_holder.get("verdict") or "UNKNOWN"
+        print(f" Verdict   : {verdict}")
+
+    if args.download_artifacts:
+        print("\n[4/4] Downloading compressed execution logs from cloud...")
+        local_log_dir = Path(f"logs/{args.tc}")
+        local_log_dir.mkdir(parents=True, exist_ok=True)
+        archive_path = local_log_dir / f"{args.tc}_{session_id}_logs.tar.gz"
+
+        archive_success = client.download_logs_archive(session_id, archive_path)
+        if archive_success and archive_path.is_file() and archive_path.stat().st_size > 0:
+            compressed_size = archive_path.stat().st_size
+            uncompressed_size = 0
+            extracted_files = []
+            import tarfile
+            with tarfile.open(archive_path, "r:gz") as tar:
+                for member in tar.getmembers():
+                    if member.isfile():
+                        uncompressed_size += member.size
+                        extracted_files.append((member.name, member.size))
+                tar.extractall(path=local_log_dir)
+
+            archive_path.unlink(missing_ok=True)
+            ratio = (1.0 - (compressed_size / max(uncompressed_size, 1))) * 100
+            comp_mb = compressed_size / (1024 * 1024)
+            uncomp_mb = uncompressed_size / (1024 * 1024)
+            print(f"   Downloaded {comp_mb:.2f} MB compressed (uncompressed {uncomp_mb:.2f} MB, {ratio:.1f}% bandwidth saved)")
+            print(f"   Extracted {len(extracted_files)} files to: {local_log_dir}/")
+            for fname, fsize in extracted_files:
+                sz_str = f"{fsize / (1024*1024):.1f} MB" if fsize >= 1024 * 1024 else f"{fsize / 1024:.1f} KB"
+                print(f"     - {fname:<32} ({sz_str})")
+        else:
+            # Fallback to individual artifact downloads
+            artifacts = client.list_artifacts(session_id)
+            if artifacts:
+                for item in artifacts:
+                    fname = item.get("name")
+                    if fname and not fname.endswith(".tar.gz"):
+                        dest = local_log_dir / fname
+                        if client.download_artifact(session_id, fname, dest):
+                            print(f"   Downloaded artifact to: {dest}")
+            else:
+                local_runner_log = local_log_dir / "tc_runner.log"
+                if client.download_artifact(session_id, "tc_runner.log", local_runner_log):
+                    print(f"   Downloaded runner log to: {local_runner_log}")
+                local_ue_log = local_log_dir / "ttcn3_ue.log"
+                if client.download_artifact(session_id, "ttcn3_ue.log", local_ue_log):
+                    print(f"   Downloaded UE simulator log to: {local_ue_log}")
+
+    print("=========================================================================\n")
+    return 0 if verdict == "PASS" else 1
+
+
+def main():
+    default_endpoint = os.environ.get("TTCN3_CLOUD_ENDPOINT")
+    if not default_endpoint or "ttcn-cloud.hyper-wireless.com" in default_endpoint:
+        default_endpoint = "https://cloud-api.hyper-wireless.com"
+
+
+    common_parser = argparse.ArgumentParser(add_help=False)
+    common_parser.add_argument("--endpoint", default=default_endpoint, help=f"Cloud service URL (default: {default_endpoint})")
+    common_parser.add_argument("--token", default=os.environ.get("TTCN3_CLOUD_API_KEY", ""), help="API Bearer Token")
+    common_parser.add_argument("--cf-client-id", default=os.environ.get("CF_ACCESS_CLIENT_ID", ""), help="Cloudflare Access Client ID")
+    common_parser.add_argument("--cf-client-secret", default=os.environ.get("CF_ACCESS_CLIENT_SECRET", ""), help="Cloudflare Access Client Secret")
+
+    parser = argparse.ArgumentParser(description="TTCN-3 Cloud Runner CLI for UE Testing", parents=[common_parser])
+    subparsers = parser.add_subparsers(dest="command")
+
+    # Command: suites
+    subparsers.add_parser("suites", parents=[common_parser], help="List available test suites in the cloud")
+
+    # Command: health
+    subparsers.add_parser("health", parents=[common_parser], help="Check health and slot availability")
+
+    # Command: testcases
+    tc_parser = subparsers.add_parser("testcases", parents=[common_parser], help="List test cases for a suite")
+    tc_parser.add_argument("--suite", default="NR5GC_IWD_25wk50", help="Suite version")
+
+    # Command: run
+    run_parser = subparsers.add_parser("run", parents=[common_parser], help="Run a test case in the cloud")
+    run_parser.add_argument("--tc", required=True, help="Testcase name (e.g. TC_6_1_1_2_NR5GC)")
+    run_parser.add_argument("--suite", default=None, help="Suite version (defaults to active suite)")
+    run_parser.add_argument("--timeout", type=int, default=None, help="Test execution timeout in seconds (default: 600s [10 mins] for cloud UE, 900s [15 mins] for local/remote UE)")
+    run_parser.add_argument("--loglevel", default="info", help="Log level")
+    run_parser.add_argument("--cloud-ue", action="store_true", default=True, help="Execute with headless UE (ttcn3_dut + SoftSIM) colocated in cloud (default: True, high speed)")
+    run_parser.add_argument("--mode", choices=["cloud_ue", "remote_ue", "no_ue"], default=None, help="Explicit execution mode")
+    run_parser.add_argument("--timer-mode", "--speed-mode", dest="timer_mode", choices=["adaptive", "accurate", "balanced", "fast"], default="adaptive", help="Simulation timer mode for lockstep execution: 'adaptive' (dynamic auto-gearing up to 5000ms Gear 3, default), 'accurate' (100ms steps, high precision), 'balanced' (500ms steps), 'fast' (2000ms steps, speed-optimized for UE over WAN/internet)")
+    run_parser.add_argument("--timer-step-ms", "--max-step-ms", dest="timer_step_ms", type=int, default=None, help="Explicit max simulated step size in milliseconds (e.g. 100, 500, 1000, 2000). Overrides --timer-mode preset.")
+    run_parser.add_argument("--local-port", type=int, default=None, help="Local TCP relay listening port (for remote_ue mode)")
+    run_parser.add_argument("--srsue", action="store_true", help="Launch local srsRAN_5G ttcn3_dut (selects remote_ue mode)")
+    run_parser.add_argument("--rat", default="nr", help="RAT for srsue (nr, lte)")
+    run_parser.add_argument("--raw-logs", action="store_true", help="Stream raw unformatted log lines instead of clean progress view")
+    run_parser.add_argument("--download-artifacts", action="store_true", default=True, help="Download execution logs")
+
+    args = parser.parse_args()
+
+    # Ensure flags passed before or after subcommands are preserved
+    for i, arg in enumerate(sys.argv):
+        if arg == "--endpoint" and i + 1 < len(sys.argv):
+            args.endpoint = sys.argv[i + 1]
+        elif arg.startswith("--endpoint="):
+            args.endpoint = arg.split("=", 1)[1]
+        elif arg == "--cf-client-id" and i + 1 < len(sys.argv):
+            args.cf_client_id = sys.argv[i + 1]
+        elif arg.startswith("--cf-client-id="):
+            args.cf_client_id = arg.split("=", 1)[1]
+        elif arg == "--cf-client-secret" and i + 1 < len(sys.argv):
+            args.cf_client_secret = sys.argv[i + 1]
+        elif arg.startswith("--cf-client-secret="):
+            args.cf_client_secret = arg.split("=", 1)[1]
+
+    if not args.command or args.command == "run":
+        if not hasattr(args, "tc") or not args.tc:
+            parser.print_help()
+            sys.exit(1)
+        sys.exit(run_command_handler(args))
+
+    client = CloudClient(
+        endpoint=args.endpoint,
+        api_key=args.token,
+        cf_client_id=args.cf_client_id,
+        cf_client_secret=args.cf_client_secret,
+    )
+
+    if args.command == "health":
+        h = client.get_health()
+        print(json.dumps(h, indent=2))
+        print()
+
+    elif args.command == "suites":
+        suites = client.get_suites()
+        print(f"\nAvailable Cloud Test Suites ({len(suites)} total):")
+        print(f"{'SUITE NAME':<26} {'ACTIVE':<8} {'RUNNER AVAILABLE':<18} {'TESTCASES':<10}")
+        print("-" * 65)
+        for s in suites:
+            active_str = "[*]" if s["is_active"] else "   "
+            runner_str = "YES" if s["has_runner"] else "NO"
+            tc_count = str(s["testcase_count"]) if s["testcase_count"] is not None else "-"
+            print(f"{s['name']:<26} {active_str:<8} {runner_str:<18} {tc_count:<10}")
+        print()
+
+    elif args.command == "testcases":
+        tcs = client.get_testcases(args.suite)
+        print(f"\nTest Cases for Suite '{args.suite}' ({len(tcs)} total):")
+        print(f"{'TESTCASE NAME':<28} {'STATUS':<12} {'CONDITION':<12} {'DESCRIPTION'}")
+        print("-" * 80)
+        for tc in tcs[:50]:
+            status = "Supported" if tc["supported"] else "Not Supported"
+            cond = tc.get("condition") or "-"
+            desc = tc.get("purpose") or ""
+            print(f"{tc['name']:<28} {status:<12} {cond:<12} {desc[:40]}")
+        if len(tcs) > 50:
+            print(f"... and {len(tcs) - 50} more test cases.")
+        print()
+
+
+if __name__ == "__main__":
+    main()