gcube-cli 0.2.0__tar.gz → 0.3.0__tar.gz

{gcube_cli-0.2.0 → gcube_cli-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gcube-cli
-Version: 0.2.0
+Version: 0.3.0
 Summary: Official command-line tool for the gcube AI GPU cloud platform
 Author-email: Data Alliance <support@data-alliance.com>
 License: Apache-2.0
@@ -162,7 +162,9 @@ Manage the full lifecycle of GPU workloads. Each workload is identified by a **S
 | `gcube workload describe <ser>` | Show workload details |
 | `gcube workload start <ser>` | Start a workload and monitor deployment status in real time |
 | `gcube workload start <ser> --no-watch` | Start a workload without monitoring |
+| `gcube workload start <ser> --timeout <sec>` | Stop monitoring after N seconds if the deploy hasn't finished (exit code 124) |
 | `gcube workload watch <ser>` | Re-attach to a deploying workload and monitor its status |
+| `gcube workload watch <ser> --plain` | Force plain line-per-event output instead of the live dashboard |
 | `gcube workload stop <ser>` | Stop a workload |
 | `gcube workload delete <ser>` | Delete a workload |
 | `gcube workload logs <ser>` | Stream container logs in real time |
@@ -248,6 +250,14 @@ gpuSpecs:
 - Use `--no-watch` to start without monitoring (e.g. in scripts).
 - For deployments with more than 5 replicas, progress is shown as an aggregate counter (e.g. `Deploying...  60/100`) instead of per-stage detail.
 
+**Non-interactive / scripting**
+
+`start` and `watch` adapt their output for automation:
+
+- When stdout is **not a terminal** (piped or redirected), or with `--plain`, output switches from the live dashboard to a plain line-per-event stream (`HH:MM:SS [ser] message`, server timestamps, flushed per line — safe to `tail -f` and durable even if the process is hard-killed).
+- With `-o json` / `-o yaml`, only a single result object is printed: `{ser, status, startedAt, completedAt, durationSec, failReason}`. `status` is one of `success`, `failed`, `timeout`, `interrupted`, `skipped`.
+- `--timeout <sec>` stops an unfinished watch after N seconds and exits `124` (GNU `timeout` convention); it also keeps `Ctrl+C` responsive on a silent stream.
+
 ---
 
 ### GPU
@@ -355,6 +365,7 @@ gcube -o yaml workload list      # YAML
 | `2` | gcube API error |
 | `3` | Authentication failure or token expired |
 | `4` | Network error |
+| `124` | `workload watch`/`start` timed out (`--timeout`) before the deploy finished |
 
 ---
 
@@ -394,6 +405,26 @@ gcube workload stop 2212
 gcube workload delete 2212
 ```
 
+### Scripting / Batch Deployment
+
+```bash
+# Plain log to a file (auto-detected; no live dashboard). Capture stderr too so
+# failure/timeout messages land in the log. Branch on the exit code.
+gcube workload watch 2212 --timeout 1800 > 2212.log 2>&1
+echo "exit=$?"   # 0 success · 1 failed · 124 timeout
+
+# Machine-readable result for aggregating many deploys
+gcube -o json workload watch 2212 --timeout 1800 > 2212.json
+# {"ser":2212,"status":"success","startedAt":...,"completedAt":...,"durationSec":...,"failReason":null}
+
+# Per-student burst with distinct tokens (one process each)
+for ser in "${SERS[@]}"; do
+  GCUBE_ACCESS_TOKEN="${TOKENS[$ser]}" \
+    gcube -o json workload watch "$ser" --timeout 1800 > "$ser.json" &
+done
+wait
+```
+
 ### Update a Workload
 
 ```bash

{gcube_cli-0.2.0 → gcube_cli-0.3.0}/README.md

@@ -123,7 +123,9 @@ Manage the full lifecycle of GPU workloads. Each workload is identified by a **S
 | `gcube workload describe <ser>` | Show workload details |
 | `gcube workload start <ser>` | Start a workload and monitor deployment status in real time |
 | `gcube workload start <ser> --no-watch` | Start a workload without monitoring |
+| `gcube workload start <ser> --timeout <sec>` | Stop monitoring after N seconds if the deploy hasn't finished (exit code 124) |
 | `gcube workload watch <ser>` | Re-attach to a deploying workload and monitor its status |
+| `gcube workload watch <ser> --plain` | Force plain line-per-event output instead of the live dashboard |
 | `gcube workload stop <ser>` | Stop a workload |
 | `gcube workload delete <ser>` | Delete a workload |
 | `gcube workload logs <ser>` | Stream container logs in real time |
@@ -209,6 +211,14 @@ gpuSpecs:
 - Use `--no-watch` to start without monitoring (e.g. in scripts).
 - For deployments with more than 5 replicas, progress is shown as an aggregate counter (e.g. `Deploying...  60/100`) instead of per-stage detail.
 
+**Non-interactive / scripting**
+
+`start` and `watch` adapt their output for automation:
+
+- When stdout is **not a terminal** (piped or redirected), or with `--plain`, output switches from the live dashboard to a plain line-per-event stream (`HH:MM:SS [ser] message`, server timestamps, flushed per line — safe to `tail -f` and durable even if the process is hard-killed).
+- With `-o json` / `-o yaml`, only a single result object is printed: `{ser, status, startedAt, completedAt, durationSec, failReason}`. `status` is one of `success`, `failed`, `timeout`, `interrupted`, `skipped`.
+- `--timeout <sec>` stops an unfinished watch after N seconds and exits `124` (GNU `timeout` convention); it also keeps `Ctrl+C` responsive on a silent stream.
+
 ---
 
 ### GPU
@@ -316,6 +326,7 @@ gcube -o yaml workload list      # YAML
 | `2` | gcube API error |
 | `3` | Authentication failure or token expired |
 | `4` | Network error |
+| `124` | `workload watch`/`start` timed out (`--timeout`) before the deploy finished |
 
 ---
 
@@ -355,6 +366,26 @@ gcube workload stop 2212
 gcube workload delete 2212
 ```
 
+### Scripting / Batch Deployment
+
+```bash
+# Plain log to a file (auto-detected; no live dashboard). Capture stderr too so
+# failure/timeout messages land in the log. Branch on the exit code.
+gcube workload watch 2212 --timeout 1800 > 2212.log 2>&1
+echo "exit=$?"   # 0 success · 1 failed · 124 timeout
+
+# Machine-readable result for aggregating many deploys
+gcube -o json workload watch 2212 --timeout 1800 > 2212.json
+# {"ser":2212,"status":"success","startedAt":...,"completedAt":...,"durationSec":...,"failReason":null}
+
+# Per-student burst with distinct tokens (one process each)
+for ser in "${SERS[@]}"; do
+  GCUBE_ACCESS_TOKEN="${TOKENS[$ser]}" \
+    gcube -o json workload watch "$ser" --timeout 1800 > "$ser.json" &
+done
+wait
+```
+
 ### Update a Workload
 
 ```bash

{gcube_cli-0.2.0 → gcube_cli-0.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "gcube-cli"
-version = "0.2.0"
+version = "0.3.0"
 description = "Official command-line tool for the gcube AI GPU cloud platform"
 readme = "README.md"
 license = { text = "Apache-2.0" }

{gcube_cli-0.2.0 → gcube_cli-0.3.0}/src/gcube_cli/api/sse.py

@@ -23,12 +23,28 @@ class SSEAuthError(Exception):
     pass
 
 
+class SSEReadTimeout(Exception):
+    """No data received within ``read_timeout`` — the stream went idle (not a failure).
+
+    Kept distinct from SSEConnectionError so the caller can re-check its own deadline and
+    resubscribe without consuming a connection-retry budget.
+    """
+
+
 class SSEClient:
     def __init__(self, platform_url: str, token: str) -> None:
         self.platform_url = platform_url.rstrip("/")
         self.token = token
 
-    def stream(self, namespace: str, ser: str) -> Iterator[SSEEvent]:
+    def stream(
+        self, namespace: str, ser: str, read_timeout: float | None = None
+    ) -> Iterator[SSEEvent]:
+        """Yield parsed SSE events.
+
+        ``read_timeout`` (seconds) bounds how long a single read may block with no data;
+        on expiry an :class:`SSEReadTimeout` is raised so the caller can check its own
+        deadline (and keep Ctrl-C responsive). ``None`` blocks indefinitely (legacy).
+        """
         url = f"{self.platform_url}/api/sse/subscribe/{namespace}/{ser}"
         headers = {
             "Authorization": f"Bearer {self.token}",
@@ -37,7 +53,7 @@ class SSEClient:
             "Connection": "keep-alive",
         }
         try:
-            timeout = httpx.Timeout(connect=10.0, read=None, write=None, pool=None)
+            timeout = httpx.Timeout(connect=10.0, read=read_timeout, write=None, pool=None)
             with httpx.stream("GET", url, headers=headers, timeout=timeout) as r:
                 if r.status_code in (401, 403):
                     raise SSEAuthError()
@@ -51,6 +67,8 @@ class SSEClient:
                         event = _parse_sse_message(message)
                         if event:
                             yield event
+        except httpx.ReadTimeout as e:
+            raise SSEReadTimeout(str(e)) from e
         except (httpx.NetworkError, httpx.RemoteProtocolError, httpx.TimeoutException) as e:
             raise SSEConnectionError(str(e)) from e
 

{gcube_cli-0.2.0 → gcube_cli-0.3.0}/src/gcube_cli/api/workload.py

@@ -270,14 +270,27 @@ class WorkloadAPI:
             },
         )
 
-    def list(self, owner: str | None = None) -> builtins.list[Workload]:
+    def list(
+        self,
+        owner: str | None = None,
+        org_code: str | None = None,
+        class_id: int | None = None,
+    ) -> builtins.list[Workload]:
         """List workloads.
 
         ``GET /api/workloads/gai/list?owner={email}``
+
+        EDU admins/staff (``ROLE_ADMIN``, ``ROLE_EDU_STAFF``) may pass
+        ``org_code`` and ``class_id`` together to retrieve every workload
+        belonging to that class.
         """
         params: dict[str, str] = {}
         if owner is not None:
             params["owner"] = owner
+        if org_code is not None:
+            params["orgCode"] = org_code
+        if class_id is not None:
+            params["classId"] = str(class_id)
         data = self._client.get(_GAI_BASE + "list", params=params)
         items: builtins.list[dict[str, Any]] = data.get(
             "workloads", data.get("data", data.get("items", []))

{gcube_cli-0.2.0 → gcube_cli-0.3.0}/src/gcube_cli/commands/workload.py

@@ -8,13 +8,15 @@ PBI-014 (update + camelCase unification).
 from __future__ import annotations
 
 import base64
+import contextlib
 import json as _json
 import math
 import re
 import sys
 import time
+from collections.abc import Callable
 from dataclasses import dataclass, field
-from datetime import datetime
+from datetime import datetime, timezone
 from typing import Any
 
 import click
@@ -25,7 +27,7 @@ from rich.text import Text
 
 from gcube_cli._group import OrderedGroup
 from gcube_cli.api.client import APIError, AuthError, Client
-from gcube_cli.api.sse import SSEAuthError, SSEClient, SSEConnectionError
+from gcube_cli.api.sse import SSEAuthError, SSEClient, SSEConnectionError, SSEReadTimeout
 from gcube_cli.api.user import UserAPI
 from gcube_cli.api.workload import GpuPricing, Workload, WorkloadAPI, is_gpu_available
 from gcube_cli.config.config import Config
@@ -152,6 +154,22 @@ class DeployState:
     deploy_progress: list[int] = field(default_factory=list, init=False)  # per-replica download %
     # podName → replica slot, assigned in first-seen order (see _slot_for_pod)
     pod_slots: dict[str, int] = field(default_factory=dict, init=False)
+    # Server timestamp of the event currently being processed (set in update()), so
+    # _add_log stamps log lines with the platform's time instead of the local clock.
+    _current_ts: str | None = field(default=None, init=False)
+    # Local HH:MM:SS at which each stage reached "done" (replica 0 timeline), shown
+    # next to the stage in the single-replica detail view. Stamped once per stage.
+    stage_done_time: list[str | None] = field(
+        default_factory=lambda: [None, None, None, None], init=False
+    )
+    # Server timestamps for the final result: when this deployment was created
+    # (depCreatedAt, first seen) and when it finished (timestamp of the is_done event).
+    deploy_started_ts: str | None = field(default=None, init=False)
+    done_ts: str | None = field(default=None, init=False)
+    # Optional callback invoked by _add_log with (local_time, message) — used by the
+    # non-interactive (plain) watch path to stream each event line immediately. None in
+    # the Live dashboard path, which renders from recent_logs on its own refresh tick.
+    log_sink: Callable[[str, str], None] | None = field(default=None, init=False)
 
     def __post_init__(self) -> None:
         self.replicas = [ReplicaStage() for _ in range(max(self.replica_count, 1))]
@@ -165,6 +183,7 @@ class DeployState:
 
     def update(self, event: Any) -> None:
         d = event.data
+        self._current_ts = d.get("timestamp")
         event_type = d.get("eventType")
         raw_replica = d.get("replica", 0)
 
@@ -178,6 +197,26 @@ class DeployState:
         elif "replicas" in d:
             self._handle_snapshot(d)
 
+        dep_created = d.get("depCreatedAt")
+        if dep_created and self.deploy_started_ts is None:
+            self.deploy_started_ts = dep_created
+        self._record_stage_done_times()
+        if self.is_done and self.done_ts is None:
+            self.done_ts = self._current_ts
+
+    def _record_stage_done_times(self) -> None:
+        """Stamp the server time each stage reached "done" (replica 0 timeline).
+
+        Uses displayed_stages so stages inferred-done (vm/node skipped on tier2/3, or
+        a fast snapshot completing several at once) are stamped with the timestamp of
+        the event that advanced the deploy. Falls back to the local clock when the
+        triggering event carried no timestamp (e.g. Format B snapshots). Stamped once
+        per stage — the first time it shows done.
+        """
+        for i, s in enumerate(self.replicas[0].displayed_stages()):
+            if s == "done" and self.stage_done_time[i] is None:
+                self.stage_done_time[i] = self._fmt_event_time(self._current_ts)
+
     def _clamp(self, r: int) -> int:
         return max(0, min(r, len(self.replicas) - 1))
 
@@ -373,10 +412,47 @@ class DeployState:
         # No replica label: event logs come from Format A, whose `replica` is always 0,
         # so a "[replica-N]" prefix would be misleading. Per-replica progress lives in
         # the stage view (driven by Format B), not the log lines.
-        timestamp = datetime.now().strftime("%H:%M:%S")
-        entry = f"  {timestamp}  {msg}"
-        self.recent_logs.insert(0, entry)
+        ts = self._fmt_event_time(self._current_ts)
+        self.recent_logs.insert(0, f"  {ts}  {msg}")
         self.recent_logs = self.recent_logs[:MAX_LOG_LINES]
+        if self.log_sink is not None:
+            self.log_sink(ts, msg)
+
+    def result(self, ser: str) -> dict[str, Any]:
+        """Machine-readable terminal result of the deploy (for ``-o json``/``yaml``).
+
+        Times are the server's own timestamps (``depCreatedAt`` → the is_done event),
+        so the duration is the real elapsed time regardless of when the CLI attached.
+        """
+        status = "failed" if self.is_failed else ("success" if self.is_done else "incomplete")
+        return {
+            "ser": _ser_value(ser),
+            "status": status,
+            "startedAt": self.deploy_started_ts,
+            "completedAt": self.done_ts,
+            "durationSec": _duration_seconds(self.deploy_started_ts, self.done_ts),
+            "failReason": (self.fail_reason or None) if self.is_failed else None,
+        }
+
+    @staticmethod
+    def _fmt_event_time(raw: str | None) -> str:
+        """Format a server event timestamp as local HH:MM:SS.
+
+        The platform sends UTC timestamps in two shapes: node events use a naive
+        ``"YYYY-MM-DD HH:MM:SS"`` (no offset → assumed UTC) and workload events use
+        ISO-8601 with an explicit ``+00:00`` offset. Both are converted to the local
+        timezone. Falls back to the local clock when the field is missing/unparseable
+        (e.g. Format B snapshots carry no timestamp, but they emit no log lines anyway).
+        """
+        if raw:
+            try:
+                dt = datetime.fromisoformat(raw)
+                if dt.tzinfo is None:
+                    dt = dt.replace(tzinfo=timezone.utc)
+                return dt.astimezone().strftime("%H:%M:%S")
+            except ValueError:
+                pass
+        return datetime.now().strftime("%H:%M:%S")
 
 
 # ---------------------------------------------------------------------------
@@ -384,6 +460,44 @@ class DeployState:
 # ---------------------------------------------------------------------------
 
 
+def _ser_value(ser: str) -> int | str:
+    """SER as an int when numeric (cleaner JSON), otherwise the raw string."""
+    return int(ser) if str(ser).isdigit() else ser
+
+
+def _emit_result(output: str, result: dict[str, Any]) -> None:
+    """Print a single machine-readable deploy result object for ``-o json``/``yaml``."""
+    if output == "yaml":
+        from gcube_cli.output.yaml_out import print_yaml
+
+        print_yaml(result)
+    else:
+        from gcube_cli.output.json_out import print_json
+
+        print_json(result)
+
+
+def _duration_seconds(start_raw: str | None, done_raw: str | None) -> int | None:
+    """Whole seconds between two server timestamps, or None if either is missing/unparseable.
+
+    Accepts both timestamp shapes (naive UTC ``"YYYY-MM-DD HH:MM:SS"`` and ISO-8601 with
+    offset). Clamped to >= 0 so clock skew between events never yields a negative duration.
+    """
+    def _parse(raw: str | None) -> datetime | None:
+        if not raw:
+            return None
+        try:
+            dt = datetime.fromisoformat(raw)
+        except (ValueError, TypeError):
+            return None
+        return dt.replace(tzinfo=timezone.utc) if dt.tzinfo is None else dt
+
+    start, done = _parse(start_raw), _parse(done_raw)
+    if start is None or done is None:
+        return None
+    return max(0, int((done - start).total_seconds()))
+
+
 def _container_index(name: str) -> int:
     """Extract the app container index from a snapshot container name.
 
@@ -462,6 +576,8 @@ def _render(state: DeployState) -> Any:
                 prog = state.deploy_progress[0] if state.deploy_progress else -1
                 if prog >= 0:
                     suffix += f"  {prog}%"
+            if stages[i] == "done" and state.stage_done_time[i]:
+                suffix += f"  {state.stage_done_time[i]}"
             lines.append(Text.from_markup(f"  \\[{icon}] {name}{suffix}"))
     else:
         for r_idx, rep in enumerate(state.replicas):
@@ -969,8 +1085,22 @@ def _watch_deploy(
     client: Client,
     *,
     verb: str = "Deploying",
+    plain: bool = False,
+    timeout: int | None = None,
 ) -> None:
-    """Stream SSE deploy events and render real-time status with Rich Live."""
+    """Stream SSE deploy events and render deployment status until done.
+
+    Rendering mode is chosen automatically:
+      - **Live dashboard** (default) on an interactive terminal.
+      - **Plain** line-per-event stream when stdout is not a TTY (piped/redirected),
+        when ``plain`` is forced, or under ``-o json``/``yaml`` — so batch scripts get
+        clean, parseable output without a pseudo-terminal wrapper.
+    With ``-o json``/``yaml`` only a single machine-readable result object is emitted.
+    """
+    output = getattr(ctx.obj, "output", "table")
+    structured = output in ("json", "yaml")
+    # Non-interactive whenever output isn't a live terminal, is forced, or is structured.
+    plain = structured or plain or (not sys.stdout.isatty())
     cfg = Config.load()
     api = WorkloadAPI(client)
     user_api = UserAPI(client)
@@ -1002,7 +1132,20 @@ def _watch_deploy(
     # just hang with no events (e.g. watching a long-stopped workload).
     phase, is_deploying = _derive_phase(wl)
     if not is_deploying:
-        if phase == "not deployed":
+        if structured:
+            _emit_result(
+                output,
+                {
+                    "ser": _ser_value(ser),
+                    "status": "skipped",
+                    "phase": phase,
+                    "startedAt": None,
+                    "completedAt": None,
+                    "durationSec": None,
+                    "failReason": None,
+                },
+            )
+        elif phase == "not deployed":
             click.echo(f"Workload {ser} is not deployed yet. Run: gcube workload start {ser}")
         else:
             click.echo(f"Workload {ser} is already {phase}.")
@@ -1023,9 +1166,17 @@ def _watch_deploy(
     # stale/empty config token and is rejected with 403.
     sse = SSEClient(ctx.obj.platform_url, ctx.obj.token or "")
 
-    replica_label = f" ({wl.replica} replicas)" if wl.replica > 1 else ""
-    click.echo(f'{verb} workload {ser} "{wl.description}"{replica_label}...')
-    click.echo()
+    # Human preamble only when we're rendering for a person — suppressed under -o
+    # json/yaml so stdout carries nothing but the final result object.
+    if not structured:
+        replica_label = f" ({wl.replica} replicas)" if wl.replica > 1 else ""
+        click.echo(f'{verb} workload {ser} "{wl.description}"{replica_label}...')
+        click.echo()
+        # Redirected stdout is block-buffered, so a batch script tailing the file (or
+        # hard-killing on timeout) would see nothing / lose buffered lines. Flush each
+        # plain line as it is written so the log is live and durable.
+        if plain:
+            sys.stdout.flush()
 
     state = DeployState(
         replica_count=wl.replica,
@@ -1033,25 +1184,48 @@ def _watch_deploy(
         images=[ct.get("containerImage", "") for ct in wl.container_array],
     )
 
+    # Plain (non-structured) mode: stream each event line to stdout as it arrives.
+    if plain and not structured:
+        def _emit_line(ts: str, msg: str) -> None:
+            click.echo(f"{ts} [{ser}] {msg}")
+            sys.stdout.flush()
+
+        state.log_sink = _emit_line
+
     MAX_RETRIES = 5
     retry = 0
     interrupted = False
+    timed_out = False
 
-    # --debug 시 서버가 보내는 원본 SSE 이벤트를 파일로 덤프
-    # (Live가 화면을 점유하므로 stderr 대신 파일).
+    # When a deadline is set, bound each read so the loop can re-check the deadline (and
+    # so Ctrl-C is delivered) instead of blocking forever on a silent stream. Poll cadence
+    # is capped so an idle stream is noticed promptly; None keeps the legacy infinite read.
+    deadline = (time.monotonic() + timeout) if timeout else None
+    read_timeout = min(float(timeout), 15.0) if timeout else None
+
+    # --debug dumps raw SSE events to a file (the Live dashboard owns the screen, so a
+    # file is used instead of stderr). The "→ file" notice goes to stderr to keep both
+    # stdout streams (plain log / json result) clean.
     debug = bool(getattr(ctx.obj, "debug", False))
     dbg_fh = open(f"gcube-sse-{ser}.log", "w", encoding="utf-8") if debug else None
     if dbg_fh:
-        click.echo(f"[debug] raw SSE events → gcube-sse-{ser}.log")
-
-    # _LiveView.__rich__가 auto_refresh(4fps)마다 _render(state)를 재계산
-    # → 스피너 애니메이션 + 실시간 갱신. live.update()를 이벤트마다 호출하지
-    # 않아도 됨 (PBI 갱신 throttle 설계와 일치).
-    with Live(_LiveView(state), refresh_per_second=4, auto_refresh=True):
+        click.echo(f"[debug] raw SSE events → gcube-sse-{ser}.log", err=True)
+
+    # Live dashboard only on an interactive terminal; plain mode runs the same loop with
+    # no live region (events are streamed via state.log_sink instead).
+    live_ctx: Any = (
+        contextlib.nullcontext()
+        if plain
+        else Live(_LiveView(state), refresh_per_second=4, auto_refresh=True)
+    )
+    with live_ctx:
         try:
             while retry <= MAX_RETRIES:
+                if deadline is not None and time.monotonic() >= deadline:
+                    timed_out = True
+                    break
                 try:
-                    for event in sse.stream(namespace, ser):
+                    for event in sse.stream(namespace, ser, read_timeout=read_timeout):
                         if dbg_fh:
                             raw = _json.dumps(event.data, ensure_ascii=False)
                             dbg_fh.write(f"{event.event}\t{raw}\n")
@@ -1059,10 +1233,17 @@ def _watch_deploy(
                         state.update(event)
                         if state.is_done:
                             break
+                        if deadline is not None and time.monotonic() >= deadline:
+                            timed_out = True
+                            break
                     else:
                         # Generator exhausted without completion → server closed stream
                         raise SSEConnectionError("Stream closed by server")
-                    break  # is_done set — exit retry loop
+                    break  # is_done or timed_out — exit retry loop
+                except SSEReadTimeout:
+                    # Idle gap (no data within read_timeout). Not a failure: loop back to
+                    # re-check the deadline and resubscribe without spending a retry.
+                    continue
                 except SSEAuthError:
                     click.echo(
                         "Token expired or invalid. "
@@ -1083,11 +1264,40 @@ def _watch_deploy(
         dbg_fh.close()
 
     if interrupted:
-        click.echo()
-        click.echo(
-            f"Monitoring stopped. Workload {ser} continues deploying in the background."
-        )
-        _hint(f"Re-attach: gcube workload watch {ser}")
+        if structured:
+            res = state.result(ser)
+            res["status"] = "interrupted"
+            _emit_result(output, res)
+        else:
+            click.echo()
+            click.echo(
+                f"Monitoring stopped. Workload {ser} continues deploying in the background."
+            )
+            _hint(f"Re-attach: gcube workload watch {ser}")
+        return
+
+    if timed_out:
+        # Inconclusive: deploy neither completed nor reported terminal failure within the
+        # deadline. Exit 124 (GNU `timeout` convention) so batch scripts can branch on it.
+        if structured:
+            res = state.result(ser)
+            res["status"] = "timeout"
+            _emit_result(output, res)
+        else:
+            click.echo()
+            click.echo(
+                f"Watch timed out after {timeout}s — workload {ser} did not finish "
+                "deploying. It continues in the background.",
+                err=True,
+            )
+            _hint(f"Re-attach: gcube workload watch {ser}")
+        sys.exit(124)
+
+    # Structured: emit only the result object (no human text on stdout).
+    if structured:
+        _emit_result(output, state.result(ser))
+        if state.is_failed:
+            sys.exit(1)
         return
 
     click.echo()
@@ -1104,7 +1314,9 @@ def _watch_deploy(
                 err=True,
             )
         sys.exit(1)
-    click.echo(f"Workload {ser} deployed successfully.")
+    dur = _duration_seconds(state.deploy_started_ts, state.done_ts)
+    took = f" (took {dur}s)" if dur is not None else ""
+    click.echo(f"Workload {ser} deployed successfully.{took}")
     _hint(f"View logs: gcube workload logs {ser}")
     _hint(f"Details:   gcube workload describe {ser}")
 
@@ -1448,13 +1660,34 @@ def workload_update(
 
 @workload.command("list")
 @click.option("--owner", default=None, help="Filter by owner email")
+@click.option(
+    "--org-code",
+    default=None,
+    help="EDU 단체코드 (EDU 관리자/운영자 전용, --class-id와 함께 사용)",
+)
+@click.option(
+    "--class-id",
+    type=int,
+    default=None,
+    help="EDU 클래스 ID (= 그룹 ID, 그룹 목록 조회에서 확인, --org-code와 함께 사용)",
+)
 @click.pass_context
-def workload_list(ctx: click.Context, owner: str | None) -> None:
+def workload_list(
+    ctx: click.Context,
+    owner: str | None,
+    org_code: str | None,
+    class_id: int | None,
+) -> None:
     """List workloads."""
+    if (org_code is None) != (class_id is None):
+        click.echo(
+            "--org-code 와 --class-id 는 함께 사용해야 합니다.", err=True
+        )
+        sys.exit(1)
     try:
         client = _make_client(ctx)
         api = WorkloadAPI(client)
-        workloads = api.list(owner=owner)
+        workloads = api.list(owner=owner, org_code=org_code, class_id=class_id)
 
         output = ctx.obj.output
         list_dicts = [
@@ -1533,8 +1766,23 @@ def workload_describe(ctx: click.Context, ser: str) -> None:
     default=False,
     help="Start workload without monitoring deployment status",
 )
+@click.option(
+    "--plain",
+    is_flag=True,
+    default=False,
+    help="Stream plain line-per-event output instead of the live dashboard "
+    "(auto-enabled when output is piped/redirected or with -o json/yaml)",
+)
+@click.option(
+    "--timeout",
+    type=int,
+    default=None,
+    help="Stop watching after N seconds if the deploy hasn't finished (exit code 124)",
+)
 @click.pass_context
-def workload_start(ctx: click.Context, ser: str, no_watch: bool) -> None:
+def workload_start(
+    ctx: click.Context, ser: str, no_watch: bool, plain: bool, timeout: int | None
+) -> None:
     """Deploy (start) a workload (and monitor deployment by default)."""
     client = _make_client(ctx)
     try:
@@ -1551,7 +1799,7 @@ def workload_start(ctx: click.Context, ser: str, no_watch: bool) -> None:
         click.echo(f"Workload {ser} started.")
         return
 
-    _watch_deploy(ctx, ser, client)
+    _watch_deploy(ctx, ser, client, plain=plain, timeout=timeout)
 
 
 # ---------------------------------------------------------------------------
@@ -1561,11 +1809,24 @@ def workload_start(ctx: click.Context, ser: str, no_watch: bool) -> None:
 
 @workload.command("watch")
 @click.argument("ser")
+@click.option(
+    "--plain",
+    is_flag=True,
+    default=False,
+    help="Stream plain line-per-event output instead of the live dashboard "
+    "(auto-enabled when output is piped/redirected or with -o json/yaml)",
+)
+@click.option(
+    "--timeout",
+    type=int,
+    default=None,
+    help="Stop watching after N seconds if the deploy hasn't finished (exit code 124)",
+)
 @click.pass_context
-def workload_watch(ctx: click.Context, ser: str) -> None:
+def workload_watch(ctx: click.Context, ser: str, plain: bool, timeout: int | None) -> None:
     """Monitor real-time deployment status of a running workload."""
     client = _make_client(ctx)
-    _watch_deploy(ctx, ser, client, verb="Connecting to")
+    _watch_deploy(ctx, ser, client, verb="Connecting to", plain=plain, timeout=timeout)
 
 
 # ---------------------------------------------------------------------------

{gcube_cli-0.2.0 → gcube_cli-0.3.0}/src/gcube_cli.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gcube-cli
-Version: 0.2.0
+Version: 0.3.0
 Summary: Official command-line tool for the gcube AI GPU cloud platform
 Author-email: Data Alliance <support@data-alliance.com>
 License: Apache-2.0
@@ -162,7 +162,9 @@ Manage the full lifecycle of GPU workloads. Each workload is identified by a **S
 | `gcube workload describe <ser>` | Show workload details |
 | `gcube workload start <ser>` | Start a workload and monitor deployment status in real time |
 | `gcube workload start <ser> --no-watch` | Start a workload without monitoring |
+| `gcube workload start <ser> --timeout <sec>` | Stop monitoring after N seconds if the deploy hasn't finished (exit code 124) |
 | `gcube workload watch <ser>` | Re-attach to a deploying workload and monitor its status |
+| `gcube workload watch <ser> --plain` | Force plain line-per-event output instead of the live dashboard |
 | `gcube workload stop <ser>` | Stop a workload |
 | `gcube workload delete <ser>` | Delete a workload |
 | `gcube workload logs <ser>` | Stream container logs in real time |
@@ -248,6 +250,14 @@ gpuSpecs:
 - Use `--no-watch` to start without monitoring (e.g. in scripts).
 - For deployments with more than 5 replicas, progress is shown as an aggregate counter (e.g. `Deploying...  60/100`) instead of per-stage detail.
 
+**Non-interactive / scripting**
+
+`start` and `watch` adapt their output for automation:
+
+- When stdout is **not a terminal** (piped or redirected), or with `--plain`, output switches from the live dashboard to a plain line-per-event stream (`HH:MM:SS [ser] message`, server timestamps, flushed per line — safe to `tail -f` and durable even if the process is hard-killed).
+- With `-o json` / `-o yaml`, only a single result object is printed: `{ser, status, startedAt, completedAt, durationSec, failReason}`. `status` is one of `success`, `failed`, `timeout`, `interrupted`, `skipped`.
+- `--timeout <sec>` stops an unfinished watch after N seconds and exits `124` (GNU `timeout` convention); it also keeps `Ctrl+C` responsive on a silent stream.
+
 ---
 
 ### GPU
@@ -355,6 +365,7 @@ gcube -o yaml workload list      # YAML
 | `2` | gcube API error |
 | `3` | Authentication failure or token expired |
 | `4` | Network error |
+| `124` | `workload watch`/`start` timed out (`--timeout`) before the deploy finished |
 
 ---
 
@@ -394,6 +405,26 @@ gcube workload stop 2212
 gcube workload delete 2212
 ```
 
+### Scripting / Batch Deployment
+
+```bash
+# Plain log to a file (auto-detected; no live dashboard). Capture stderr too so
+# failure/timeout messages land in the log. Branch on the exit code.
+gcube workload watch 2212 --timeout 1800 > 2212.log 2>&1
+echo "exit=$?"   # 0 success · 1 failed · 124 timeout
+
+# Machine-readable result for aggregating many deploys
+gcube -o json workload watch 2212 --timeout 1800 > 2212.json
+# {"ser":2212,"status":"success","startedAt":...,"completedAt":...,"durationSec":...,"failReason":null}
+
+# Per-student burst with distinct tokens (one process each)
+for ser in "${SERS[@]}"; do
+  GCUBE_ACCESS_TOKEN="${TOKENS[$ser]}" \
+    gcube -o json workload watch "$ser" --timeout 1800 > "$ser.json" &
+done
+wait
+```
+
 ### Update a Workload
 
 ```bash

{gcube_cli-0.2.0 → gcube_cli-0.3.0}/tests/test_workload.py

@@ -317,6 +317,14 @@ class TestWorkloadAPIList:
         request = httpx_mock.get_request()
         assert "owner=" in str(request.url)
 
+    def test_list_with_edu_org_and_class(self, httpx_mock: Any) -> None:
+        httpx_mock.add_response(json=ok_envelope(workloads=[WORKLOAD_ITEM]))
+        make_api().list(org_code="samsung", class_id=5)
+
+        url = str(httpx_mock.get_request().url)
+        assert "orgCode=samsung" in url
+        assert "classId=5" in url
+
     def test_list_returns_empty_list(self, httpx_mock: Any) -> None:
         httpx_mock.add_response(json=ok_envelope(workloads=[]))
         result = make_api().list()

{gcube_cli-0.2.0 → gcube_cli-0.3.0}/tests/test_workload_commands.py

@@ -203,6 +203,33 @@ class TestWorkloadList:
         assert result.exit_code == 0
         assert "owner=" in str(httpx_mock.get_request().url)
 
+    def test_edu_org_and_class_send_query_params(
+        self, runner: CliRunner, httpx_mock: Any, config_dir: Path
+    ) -> None:
+        httpx_mock.add_response(json=ok_envelope(workloads=[WORKLOAD_ITEM]))
+        result = run(
+            runner,
+            ["workload", "list", "--org-code", "samsung", "--class-id", "5"],
+        )
+        assert result.exit_code == 0
+        url = str(httpx_mock.get_request().url)
+        assert "orgCode=samsung" in url
+        assert "classId=5" in url
+
+    def test_org_code_without_class_id_exits_1(
+        self, runner: CliRunner, config_dir: Path
+    ) -> None:
+        result = run(runner, ["workload", "list", "--org-code", "samsung"])
+        assert result.exit_code == 1
+        assert "함께 사용" in result.output
+
+    def test_class_id_without_org_code_exits_1(
+        self, runner: CliRunner, config_dir: Path
+    ) -> None:
+        result = run(runner, ["workload", "list", "--class-id", "5"])
+        assert result.exit_code == 1
+        assert "함께 사용" in result.output
+
     def test_empty_list_exits_0(
         self, runner: CliRunner, httpx_mock: Any, config_dir: Path
     ) -> None:

{gcube_cli-0.2.0 → gcube_cli-0.3.0}/tests/test_workload_sse.py

@@ -15,6 +15,7 @@ import json
 from pathlib import Path
 from typing import Any
 
+import httpx
 import pytest
 from click.testing import CliRunner
 
@@ -23,6 +24,7 @@ from gcube_cli.api.sse import (
     SSEClient,
     SSEConnectionError,
     SSEEvent,
+    SSEReadTimeout,
     _parse_sse_message,
 )
 from gcube_cli.api.workload import Workload
@@ -219,6 +221,16 @@ class TestSSEClientStream:
         events = list(SSEClient(PLATFORM_URL, TOKEN).stream("ns123", "2143"))
         assert len(events) == 1
 
+    def test_read_timeout_raises_sse_read_timeout(self, httpx_mock: Any) -> None:
+        """An idle read (httpx.ReadTimeout) maps to SSEReadTimeout, not a connection error."""
+        httpx_mock.add_exception(
+            httpx.ReadTimeout("timed out"),
+            method="GET",
+            url=f"{PLATFORM_URL}/api/sse/subscribe/ns123/2143",
+        )
+        with pytest.raises(SSEReadTimeout):
+            list(SSEClient(PLATFORM_URL, TOKEN).stream("ns123", "2143", read_timeout=1))
+
 
 # ---------------------------------------------------------------------------
 # DeployState — Format A events
@@ -648,6 +660,44 @@ class TestDeployStateSnapshotInProgress:
         assert state.is_done  # slot 0 completed (1 replica)
 
 
+# ---------------------------------------------------------------------------
+# Event log timestamps — use the server's UTC time (→ local), not the local clock
+# ---------------------------------------------------------------------------
+
+
+class TestEventLogTimestamp:
+    def _ev(self, data: dict[str, Any]) -> SSEEvent:
+        return SSEEvent(event="deployEvent", data=data)
+
+    def test_naive_timestamp_treated_as_utc(self) -> None:
+        # node format (no offset) and the same instant with explicit +00:00 must agree,
+        # regardless of the machine's local timezone.
+        naive = DeployState._fmt_event_time("2026-06-02 05:10:02")
+        aware = DeployState._fmt_event_time("2026-06-02T05:10:02+00:00")
+        assert naive == aware
+
+    def test_workload_iso_timestamp_parsed(self) -> None:
+        out = DeployState._fmt_event_time("2026-06-02T05:10:19.941647+00:00")
+        assert len(out) == 8 and out.count(":") == 2
+
+    def test_missing_timestamp_falls_back_to_local_clock(self) -> None:
+        out = DeployState._fmt_event_time(None)
+        assert len(out) == 8 and out.count(":") == 2
+
+    def test_malformed_timestamp_falls_back(self) -> None:
+        out = DeployState._fmt_event_time("not-a-timestamp")
+        assert len(out) == 8 and out.count(":") == 2
+
+    def test_log_line_uses_server_timestamp(self) -> None:
+        state = DeployState(replica_count=1, container_count=1)
+        state.update(self._ev({
+            "eventType": "workload", "reason": "image_pull_started",
+            "replica": "0", "timestamp": "2026-06-02T05:10:19+00:00",
+        }))
+        expected = DeployState._fmt_event_time("2026-06-02T05:10:19+00:00")
+        assert state.recent_logs[0].strip().startswith(expected)
+
+
 # ---------------------------------------------------------------------------
 # Rendering — large-scale (>5) simple completed-counter view (no per-stage bars)
 # ---------------------------------------------------------------------------
@@ -705,6 +755,39 @@ class TestAggregateCounterRender:
         assert "replica-0" in out
 
 
+class TestSingleReplicaStageTime:
+    """Single-replica detail view shows each stage's server completion time."""
+
+    def _ev(self, data: dict[str, Any]) -> SSEEvent:
+        return SSEEvent(event="deployEvent", data=data)
+
+    def test_done_stage_shows_server_completion_time(self) -> None:
+        state = DeployState(replica_count=1, container_count=1)
+        state.update(self._ev({
+            "eventType": "workload", "reason": "container_started",
+            "replica": "0", "containerIndex": 0,
+            "timestamp": "2026-06-02T05:10:30+00:00",
+        }))
+        expected = DeployState._fmt_event_time("2026-06-02T05:10:30+00:00")
+        assert state.is_done
+        assert all(t == expected for t in state.stage_done_time)
+        assert expected in _render_text(state)
+
+    def test_running_and_pending_stages_have_no_time(self) -> None:
+        state = DeployState(replica_count=1, container_count=1)
+        state.update(self._ev({
+            "eventType": "workload", "reason": "image_pulling",
+            "replica": "0", "downloadProgress": "50.0",
+            "timestamp": "2026-06-02T05:10:10+00:00",
+        }))
+        # vm/node are inferred-done (lower than the running stage) → stamped;
+        # the running image-pull stage and the pending container stage are not.
+        assert state.stage_done_time[STAGE_VM] is not None
+        assert state.stage_done_time[STAGE_NODE] is not None
+        assert state.stage_done_time[STAGE_DEPLOY_START] is None
+        assert state.stage_done_time[STAGE_DEPLOY_DONE] is None
+
+
 # ---------------------------------------------------------------------------
 # _derive_phase — pre-watch state check (operations history, not the DB-echo state)
 # ---------------------------------------------------------------------------
@@ -918,7 +1001,15 @@ class TestWorkloadWatchCommand:
         """watch command invokes _watch_deploy (mocked to avoid Live/SSE)."""
         called: dict[str, Any] = {}
 
-        def mock_watch(ctx: Any, ser: str, client: Any, *, verb: str = "Deploying") -> None:
+        def mock_watch(
+            ctx: Any,
+            ser: str,
+            client: Any,
+            *,
+            verb: str = "Deploying",
+            plain: bool = False,
+            timeout: int | None = None,
+        ) -> None:
             called["ser"] = ser
             called["verb"] = verb
 
@@ -943,7 +1034,15 @@ class TestWorkloadWatchCommand:
         )
         called: dict[str, Any] = {}
 
-        def mock_watch(ctx: Any, ser: str, client: Any, *, verb: str = "Deploying") -> None:
+        def mock_watch(
+            ctx: Any,
+            ser: str,
+            client: Any,
+            *,
+            verb: str = "Deploying",
+            plain: bool = False,
+            timeout: int | None = None,
+        ) -> None:
             called["ser"] = ser
             called["verb"] = verb
 
@@ -975,6 +1074,118 @@ class MockLive:
         pass
 
 
+class TestDeployResult:
+    """Server-timestamp based final result (for -o json) and duration helper."""
+
+    def _ev(self, data: dict[str, Any]) -> SSEEvent:
+        return SSEEvent(event="deployEvent", data=data)
+
+    def test_duration_seconds(self) -> None:
+        from gcube_cli.commands.workload import _duration_seconds
+
+        # naive(UTC) start → ISO+offset done = 9s
+        assert _duration_seconds("2026-06-12 07:24:48", "2026-06-12T07:24:57+00:00") == 9
+        # missing/unparseable → None
+        assert _duration_seconds(None, "2026-06-12T07:24:57+00:00") is None
+        assert _duration_seconds("nope", "also-nope") is None
+        # done before start (clock skew) → clamped to 0, never negative
+        assert _duration_seconds("2026-06-12T07:24:57+00:00", "2026-06-12T07:24:48+00:00") == 0
+
+    def test_result_success_uses_server_times(self) -> None:
+        state = DeployState(replica_count=1, container_count=1)
+        state.update(self._ev({
+            "eventType": "workload", "reason": "container_started", "replica": "0",
+            "containerIndex": 0, "timestamp": "2026-06-12T07:24:57+00:00",
+            "depCreatedAt": "2026-06-12 07:24:48",
+        }))
+        assert state.result("2143") == {
+            "ser": 2143,
+            "status": "success",
+            "startedAt": "2026-06-12 07:24:48",
+            "completedAt": "2026-06-12T07:24:57+00:00",
+            "durationSec": 9,
+            "failReason": None,
+        }
+
+
+class TestWatchPlainAndJson:
+    """Non-interactive paths used by batch scripts (no pseudo-terminal needed)."""
+
+    def _setup(self, httpx_mock: Any) -> None:
+        httpx_mock.add_response(
+            method="GET",
+            url=f"{PLATFORM_URL}/api/workloads/gai/2143",
+            json=ok_envelope(workload=WORKLOAD_ITEM),
+        )
+        httpx_mock.add_response(
+            method="GET",
+            url=f"{PLATFORM_URL}/api/users/user@example.com",
+            json=USER_RESPONSE,
+        )
+
+    _DONE_EVENT = {
+        "eventType": "workload", "reason": "container_started", "replica": "0",
+        "containerIndex": 0, "timestamp": "2026-06-12T07:24:57+00:00",
+        "depCreatedAt": "2026-06-12 07:24:48",
+    }
+
+    def test_plain_streams_ser_tagged_lines(
+        self, runner: CliRunner, httpx_mock: Any, config_with_email: Path
+    ) -> None:
+        self._setup(httpx_mock)
+        httpx_mock.add_response(
+            method="GET",
+            url=f"{PLATFORM_URL}/api/sse/subscribe/ns904811bf/2143",
+            content=sse_message("deployEvent", self._DONE_EVENT).encode(),
+        )
+        # CliRunner stdout is not a TTY → plain mode auto-engages (no Live needed).
+        result = run(runner, ["workload", "watch", "2143"])
+        assert result.exit_code == 0
+        assert "[2143]" in result.output  # ser-tagged event line
+        assert "deployed successfully" in result.output
+
+    def test_json_emits_single_result_object(
+        self, runner: CliRunner, httpx_mock: Any, config_with_email: Path
+    ) -> None:
+        self._setup(httpx_mock)
+        httpx_mock.add_response(
+            method="GET",
+            url=f"{PLATFORM_URL}/api/sse/subscribe/ns904811bf/2143",
+            content=sse_message("deployEvent", self._DONE_EVENT).encode(),
+        )
+        result = run(runner, ["--output", "json", "workload", "watch", "2143"])
+        assert result.exit_code == 0
+        data = json.loads(result.output)
+        assert data["ser"] == 2143
+        assert data["status"] == "success"
+        assert data["durationSec"] == 9
+        assert data["startedAt"] and data["completedAt"]
+
+    def test_timeout_exits_124_with_status_timeout(
+        self,
+        runner: CliRunner,
+        httpx_mock: Any,
+        config_with_email: Path,
+        monkeypatch: pytest.MonkeyPatch,
+    ) -> None:
+        """--timeout: if the deadline passes before completion, exit 124, status=timeout.
+
+        The clock is advanced past the deadline so the loop times out on its first check
+        (before any SSE subscribe), keeping the test deterministic and fast."""
+        self._setup(httpx_mock)
+        # monotonic(): 1st call computes the deadline (=0+5), every later call is past it.
+        clock = iter([0.0])
+        monkeypatch.setattr(
+            "gcube_cli.commands.workload.time.monotonic",
+            lambda: next(clock, 1000.0),
+        )
+        result = run(runner, ["--output", "json", "workload", "watch", "2143", "--timeout", "5"])
+        assert result.exit_code == 124
+        data = json.loads(result.output)
+        assert data["ser"] == 2143
+        assert data["status"] == "timeout"
+
+
 class TestWatchDeployIntegration:
     def test_watch_skips_sse_for_stopped_workload(
         self,