feat: add CLI shell and exec commands for pod terminal access

centml/cli/main.py

@@ -2,6 +2,7 @@
 
 from centml.cli.login import login, logout
 from centml.cli.cluster import ls, get, delete, pause, resume
+from centml.cli.shell import shell, exec_cmd
 
 
 @click.group()
@@ -47,6 +48,8 @@ def ccluster():
 ccluster.add_command(delete)
 ccluster.add_command(pause)
 ccluster.add_command(resume)
+ccluster.add_command(shell)
+ccluster.add_command(exec_cmd, name="exec")
 
 
 cli.add_command(ccluster, name="cluster")

centml/cli/shell.py

@@ -0,0 +1,92 @@
+"""CLI commands for interactive shell and command execution in deployment pods."""
+
+import asyncio
+import sys
+
+import click
+
+from centml.cli.cluster import handle_exception
+from centml.sdk import auth
+from centml.sdk.api import get_centml_client
+from centml.sdk.config import settings
+from centml.sdk.shell import (
+    PodNotFoundError,
+    ShellError,
+    build_ws_url,
+    exec_session,
+    get_running_pods,
+    interactive_session,
+)
+
+
+def _resolve_pod(running_pods: list[str], pod_name: str) -> str:
+    """Validate that *pod_name* exists in *running_pods*."""
+    if pod_name not in running_pods:
+        pods_list = ", ".join(running_pods)
+        raise PodNotFoundError(f"Pod '{pod_name}' not found. Available running pods: {pods_list}")
+    return pod_name
+
+
+def _select_pod(running_pods, deployment_id):
+    click.echo(f"Multiple running pods found for deployment {deployment_id}:")
+    for i, name in enumerate(running_pods, 1):
+        click.echo(f"  [{i}] {name}")
+
+    choice = click.prompt(
+        "Select a pod", type=click.IntRange(1, len(running_pods)), prompt_suffix=f" [1-{len(running_pods)}]: "
+    )
+    return running_pods[choice - 1]
+
+
+def _connect_args(deployment_id, pod, shell_type, first_pod=False):
+    """Resolve pod, build WebSocket URL, and obtain auth token."""
+    with get_centml_client() as cclient:
+        running_pods = get_running_pods(cclient, deployment_id)
+        if not running_pods:
+            raise click.ClickException(f"No running pods found for deployment {deployment_id}")
+
+        if pod is not None:
+            try:
+                pod_name = _resolve_pod(running_pods, pod)
+            except ShellError as exc:
+                raise click.ClickException(str(exc)) from exc
+        elif len(running_pods) == 1 or first_pod:
+            pod_name = running_pods[0]
+        else:
+            pod_name = _select_pod(running_pods, deployment_id)
+
+    ws_url = build_ws_url(settings.CENTML_PLATFORM_API_URL, deployment_id, pod_name, shell_type)
+    token = auth.get_centml_token()
+    return ws_url, token
+
+
+@click.command(help="Open an interactive shell to a deployment pod")
+@click.argument("deployment_id", type=int)
+@click.option("--pod", default=None, help="Specify a pod name")
+@click.option("--shell", "shell_type", default=None, type=click.Choice(["bash", "sh", "zsh"]), help="Shell type")
+@click.option(
+    "--first-pod", is_flag=True, default=False, help="Auto-select the first running pod (skip interactive selection)"
+)
+@handle_exception
+def shell(deployment_id, pod, shell_type, first_pod):
+    if not sys.stdin.isatty():
+        raise click.ClickException("Interactive shell requires a terminal (TTY)")
+
+    ws_url, token = _connect_args(deployment_id, pod, shell_type, first_pod)
+    exit_code = asyncio.run(interactive_session(ws_url, token))
+    sys.exit(exit_code)
+
+
+@click.command(help="Execute a command in a deployment pod", context_settings={"ignore_unknown_options": True})
+@click.argument("deployment_id", type=int)
+@click.argument("command", nargs=-1, required=True, type=click.UNPROCESSED)
+@click.option("--pod", default=None, help="Specific pod name")
+@click.option("--shell", "shell_type", default=None, type=click.Choice(["bash", "sh", "zsh"]), help="Shell type")
+@click.option(
+    "--first-pod", is_flag=True, default=False, help="Auto-select the first running pod (skip interactive selection)"
+)
+@handle_exception
+def exec_cmd(deployment_id, command, pod, shell_type, first_pod):
+    ws_url, token = _connect_args(deployment_id, pod, shell_type, first_pod)
+    exit_code = asyncio.run(exec_session(ws_url, token, " ".join(command)))
+    sys.exit(exit_code)

centml/sdk/api.py

@@ -27,6 +27,9 @@ def get(self, depl_type):
     def get_status(self, id):
         return self._api.get_deployment_status_deployments_status_deployment_id_get(id)
 
+    def get_status_v3(self, deployment_id):
+        return self._api.get_deployment_status_v3_deployments_status_v3_deployment_id_get(deployment_id)
+
     def get_inference(self, id):
         """Get Inference deployment details - automatically handles both V2 and V3 deployments"""
         # Try V3 first (recommended), fallback to V2 if deployment is V2

centml/sdk/shell/__init__.py

@@ -0,0 +1,12 @@
+from centml.sdk.shell.exceptions import NoPodAvailableError, PodNotFoundError, ShellError
+from centml.sdk.shell.session import build_ws_url, exec_session, get_running_pods, interactive_session
+
+__all__ = [
+    "ShellError",
+    "NoPodAvailableError",
+    "PodNotFoundError",
+    "build_ws_url",
+    "get_running_pods",
+    "interactive_session",
+    "exec_session",
+]

centml/sdk/shell/exceptions.py

@@ -0,0 +1,10 @@
+class ShellError(Exception):
+    """Base exception for shell operations."""
+
+
+class NoPodAvailableError(ShellError):
+    """No running pods found for the deployment."""
+
+
+class PodNotFoundError(ShellError):
+    """Specified pod not found among running pods."""