aircloud-cli 0.1.0__py3-none-any.whl

aircloud_cli/client.py

@@ -0,0 +1,166 @@
+from dataclasses import dataclass, field
+from typing import Any
+
+import httpx
+
+
+class AirCloudError(Exception):
+    """Base exception for AirCloud CLI client."""
+
+
+class AirCloudAPIError(AirCloudError):
+    """Raised when the AirCloud API returns an error response."""
+
+    def __init__(self, message: str, status_code: int | None = None):
+        super().__init__(message)
+        self.status_code = status_code
+
+
+@dataclass
+class AirCloudClient:
+    base_url: str
+    api_key: str
+    timeout: int = 30
+    _http: httpx.Client = field(init=False, repr=False)
+
+    def __post_init__(self):
+        self._http = httpx.Client(
+            base_url=self.base_url.rstrip("/"),
+            headers={
+                "Authorization": f"Bearer {self.api_key}",
+                "Accept": "application/json",
+            },
+            timeout=self.timeout,
+        )
+
+    def _request_json(
+        self,
+        method: str,
+        path: str,
+        *,
+        query: dict[str, Any] | None = None,
+        body: dict[str, Any] | None = None,
+    ) -> Any:
+        params = {k: v for k, v in (query or {}).items() if v is not None} or None
+        try:
+            response = self._http.request(
+                method.upper(),
+                path,
+                params=params,
+                json=body,
+            )
+            response.raise_for_status()
+        except httpx.HTTPStatusError as exc:
+            detail = exc.response.text
+            message = f"API request failed with HTTP {exc.response.status_code}"
+            if detail:
+                try:
+                    error_payload = exc.response.json()
+                    message = error_payload.get("detail") or error_payload.get("message") or message
+                except Exception:
+                    message = detail
+            raise AirCloudAPIError(message, status_code=exc.response.status_code) from exc
+        except httpx.ConnectError as exc:
+            raise AirCloudError(f"Failed to reach AirCloud API: {exc}") from exc
+
+        if not response.text:
+            return None
+        return response.json()
+
+    def get_me(self) -> dict[str, Any]:
+        return self._request_json("GET", "/external/api/v1/me")
+
+    def list_endpoints(
+        self,
+        *,
+        search: str | None = None,
+        is_active: bool | None = None,
+        page: int = 1,
+        size: int = 50,
+    ) -> dict[str, Any]:
+        return self._request_json(
+            "GET",
+            "/external/api/v1/endpoints",
+            query={
+                "search": search,
+                "is_active": str(is_active).lower() if is_active is not None else None,
+                "page": page,
+                "size": size,
+            },
+        )
+
+    def get_endpoint(self, endpoint_id: str) -> dict[str, Any]:
+        return self._request_json("GET", f"/external/api/v1/endpoints/{endpoint_id}")
+
+    def get_replicas(self, endpoint_id: str) -> list[dict[str, Any]]:
+        return self._request_json(
+            "GET",
+            f"/external/api/v1/endpoints/{endpoint_id}/replicas",
+        )
+
+    def list_logs(
+        self,
+        endpoint_id: str,
+        *,
+        replica_id: str | None = None,
+        include_history: bool = True,
+    ) -> list[dict[str, Any]]:
+        return self._request_json(
+            "GET",
+            f"/external/api/v1/endpoints/{endpoint_id}/logs",
+            query={
+                "replica_id": replica_id,
+                "include_history": str(include_history).lower(),
+            },
+        )
+
+    def read_log_file(
+        self,
+        endpoint_id: str,
+        *,
+        node_id: str,
+        filename: str,
+        start_line: int = 1,
+        end_line: int = 200,
+    ) -> dict[str, Any]:
+        return self._request_json(
+            "GET",
+            f"/external/api/v1/endpoints/{endpoint_id}/logs/file",
+            query={
+                "node_id": node_id,
+                "filename": filename,
+                "start_line": start_line,
+                "end_line": end_line,
+            },
+        )
+
+    def start_endpoint(self, endpoint_id: str) -> dict[str, Any]:
+        return self._request_json(
+            "POST",
+            f"/external/api/v1/endpoints/{endpoint_id}/start",
+        )
+
+    def stop_endpoint(self, endpoint_id: str) -> dict[str, Any]:
+        return self._request_json(
+            "POST",
+            f"/external/api/v1/endpoints/{endpoint_id}/stop",
+        )
+
+    def scale_endpoint(self, endpoint_id: str, num_replicas: int) -> dict[str, Any]:
+        return self._request_json(
+            "POST",
+            f"/external/api/v1/endpoints/{endpoint_id}/scale",
+            body={"num_replicas": num_replicas},
+        )
+
+    def patch_endpoint(
+        self,
+        endpoint_id: str,
+        **kwargs: Any,
+    ) -> dict[str, Any]:
+        body = {k: v for k, v in kwargs.items() if v is not None}
+        return self._request_json(
+            "PATCH",
+            f"/external/api/v1/endpoints/{endpoint_id}",
+            body=body,
+        )

aircloud_cli/config.py

@@ -0,0 +1,35 @@
+import json
+from pathlib import Path
+
+CONFIG_DIR = Path.home() / ".aircloud"
+CONFIG_FILE = CONFIG_DIR / "config.json"
+DEFAULT_API_BASE_URL = "https://your-aircloud-host.example.com"
+
+
+def _load() -> dict:
+    if CONFIG_FILE.exists():
+        return json.loads(CONFIG_FILE.read_text())
+    return {}
+
+
+def _save(data: dict):
+    CONFIG_DIR.mkdir(parents=True, exist_ok=True)
+    CONFIG_FILE.write_text(json.dumps(data, indent=2))
+
+
+def get(key: str) -> str | None:
+    return _load().get(key)
+
+
+def set(key: str, value: str):
+    data = _load()
+    data[key] = value
+    _save(data)
+
+
+def get_api_base_url() -> str:
+    return get("api-base-url") or DEFAULT_API_BASE_URL
+
+
+def get_api_key() -> str | None:
+    return get("api-key")

aircloud_cli/container_exec.py

@@ -0,0 +1,149 @@
+import asyncio
+import json
+import os
+import sys
+import termios
+import tty
+
+import websockets
+
+
+async def _run_exec(ws_url: str, api_key: str, cmd: list[str]):
+    headers = {"Authorization": f"Bearer {api_key}"}
+
+    try:
+        ws = await websockets.connect(
+            ws_url,
+            additional_headers=headers,
+            ping_interval=None,
+            max_size=None,
+        )
+    except websockets.exceptions.InvalidStatusCode as e:
+        if e.status_code in (401, 403):
+            print(f"  Access denied (HTTP {e.status_code}). Check API key.")
+        elif e.status_code == 302:
+            print("  Authentication failed (redirected to login).")
+        else:
+            print(f"  WebSocket handshake failed: HTTP {e.status_code}")
+        return
+    except Exception as e:
+        print(f"  Failed to connect: {e}")
+        return
+
+    if not sys.stdin.isatty():
+        print("  exec requires an interactive TTY (stdin).")
+        await ws.close()
+        return
+
+    fd = sys.stdin.fileno()
+    old_attr = termios.tcgetattr(fd)
+    tty.setraw(fd)
+
+    loop = asyncio.get_event_loop()
+    stopping = asyncio.Event()
+
+    input_buffer = bytearray()
+    exit_task: asyncio.Task | None = None
+
+    def schedule_close():
+        nonlocal exit_task
+        if exit_task and not exit_task.done():
+            exit_task.cancel()
+
+        async def _close():
+            try:
+                await asyncio.sleep(2.0)
+                try:
+                    await ws.close(code=1000, reason="client-initiated close")
+                except Exception:
+                    pass
+                stopping.set()
+            except asyncio.CancelledError:
+                pass
+
+        exit_task = asyncio.create_task(_close())
+
+    def inspect_input(data: bytes):
+        for b in data:
+            if b == 0x04:  # Ctrl-D
+                schedule_close()
+                input_buffer.clear()
+            elif b in (0x0D, 0x0A):  # CR / LF
+                line = (
+                    bytes(input_buffer)
+                    .decode("utf-8", errors="replace")
+                    .strip()
+                )
+                if line == "exit" or line.endswith(" exit"):
+                    schedule_close()
+                input_buffer.clear()
+            elif b == 0x7F:  # Backspace
+                if input_buffer:
+                    input_buffer.pop()
+            else:
+                input_buffer.append(b)
+
+    async def send_bytes(data: bytes):
+        try:
+            await ws.send(data)
+        except websockets.exceptions.ConnectionClosed:
+            stopping.set()
+        except Exception:
+            stopping.set()
+
+    def on_stdin_readable():
+        try:
+            data = os.read(fd, 1024)
+        except OSError:
+            stopping.set()
+            return
+        if not data:
+            stopping.set()
+            return
+        inspect_input(data)
+        asyncio.ensure_future(send_bytes(data))
+
+    async def ws_to_stdout():
+        try:
+            async for msg in ws:
+                if isinstance(msg, bytes):
+                    os.write(sys.stdout.fileno(), msg)
+                elif isinstance(msg, str):
+                    os.write(sys.stdout.fileno(), msg.encode())
+        except (asyncio.CancelledError, websockets.exceptions.ConnectionClosed):
+            pass
+        finally:
+            stopping.set()
+
+    try:
+        await ws.send(json.dumps({"cmd": cmd, "tty": True}))
+        loop.add_reader(fd, on_stdin_readable)
+        ws_task = asyncio.create_task(ws_to_stdout())
+
+        await stopping.wait()
+
+        ws_task.cancel()
+        try:
+            await ws_task
+        except (asyncio.CancelledError, Exception):
+            pass
+    finally:
+        try:
+            loop.remove_reader(fd)
+        except Exception:
+            pass
+        termios.tcsetattr(fd, termios.TCSADRAIN, old_attr)
+        if exit_task and not exit_task.done():
+            exit_task.cancel()
+        try:
+            await ws.close()
+        except Exception:
+            pass
+
+
+def start_exec(ws_url: str, api_key: str, cmd: list[str]):
+    """Open a docker exec session to an endpoint's container over WS."""
+    try:
+        asyncio.run(_run_exec(ws_url, api_key, cmd))
+    except KeyboardInterrupt:
+        pass

aircloud_cli/main.py

@@ -0,0 +1,508 @@
+import json
+from datetime import datetime
+from typing import Any
+from urllib.parse import urlparse, urlunparse
+
+import click
+
+from aircloud_cli import config
+from aircloud_cli.client import AirCloudAPIError, AirCloudClient, AirCloudError
+from aircloud_cli.container_exec import start_exec
+from aircloud_cli.ssh_tunnel import start_ssh, start_tunnel
+
+DEFAULT_SSH_HOST = "your-aircloud-host.example.com"
+
+
+def _mask_value(key: str, value: str) -> str:
+    if key == "api-key":
+        return value[:8] + "..." if value else value
+    return value
+
+
+def _format_timestamp(value: str | None) -> str:
+    if not value:
+        return "-"
+    try:
+        parsed = datetime.fromisoformat(value.replace("Z", "+00:00"))
+        return parsed.strftime("%Y-%m-%d %H:%M:%S")
+    except ValueError:
+        return value
+
+
+def _get_client(api_key: str | None = None, base_url: str | None = None) -> AirCloudClient:
+    resolved_api_key = api_key or config.get_api_key()
+    if not resolved_api_key:
+        raise click.ClickException(
+            "API key not set. Run: aircloud config set api-key <key>"
+        )
+
+    resolved_base_url = base_url or config.get_api_base_url()
+    return AirCloudClient(
+        base_url=resolved_base_url,
+        api_key=resolved_api_key,
+    )
+
+
+def _render_json(value: Any) -> None:
+    click.echo(json.dumps(value, indent=2, sort_keys=False))
+
+
+def _pick_default_log_file(logs: list[dict[str, Any]]) -> dict[str, Any] | None:
+    if not logs:
+        return None
+
+    live_logs = [log for log in logs if not log.get("is_historical")]
+    candidates = live_logs or logs
+    return sorted(
+        candidates,
+        key=lambda item: (
+            item.get("is_historical", False),
+            item.get("start_time") or "",
+            item.get("filename") or "",
+        ),
+    )[-1]
+
+
+def _render_log_content(content: str, raw: bool) -> None:
+    if raw:
+        click.echo(content.rstrip("\n"))
+        return
+
+    for line in content.splitlines():
+        if not line.strip():
+            continue
+        try:
+            payload = json.loads(line)
+        except json.JSONDecodeError:
+            click.echo(line)
+            continue
+
+        timestamp = payload.get("timestamp")
+        message = payload.get("log") or payload.get("message") or line
+        click.echo(f"{timestamp or '-'} {message}")
+
+
+@click.group()
+@click.version_option(version="0.1.0")
+def cli():
+    """AirCloud CLI."""
+
+
+@cli.group("config")
+def config_cmd():
+    """Manage CLI configuration."""
+
+
+@config_cmd.command("set")
+@click.argument("key")
+@click.argument("value")
+def config_set(key: str, value: str):
+    """Set a config value."""
+    config.set(key, value)
+    click.echo(f"{key} = {_mask_value(key, value)}")
+
+
+@config_cmd.command("get")
+@click.argument("key")
+def config_get(key: str):
+    """Get a config value."""
+    value = config.get(key)
+    if value is None:
+        click.echo(f"{key} is not set")
+        return
+    click.echo(f"{key} = {_mask_value(key, value)}")
+
+
+@config_cmd.command("list")
+def config_list():
+    """List common config values."""
+    values = {
+        "api-base-url": config.get_api_base_url(),
+        "api-key": config.get_api_key(),
+        "host": config.get("host") or DEFAULT_SSH_HOST,
+    }
+    for key, value in values.items():
+        if value is None:
+            click.echo(f"{key} = <not set>")
+        else:
+            click.echo(f"{key} = {_mask_value(key, value)}")
+
+
+@cli.command("whoami")
+@click.option("--base-url", default=None, help="External API base URL")
+@click.option("--api-key", default=None, help="API key")
+def whoami(base_url: str | None, api_key: str | None):
+    """Show API key context."""
+    client = _get_client(api_key=api_key, base_url=base_url)
+    _render_json(client.get_me())
+
+
+@cli.group("endpoints")
+def endpoints_cmd():
+    """Inspect and manage endpoints."""
+
+
+@endpoints_cmd.command("list")
+@click.option("--search", default=None, help="Search by endpoint name")
+@click.option(
+    "--active/--all",
+    "active_only",
+    default=False,
+    help="Show only active endpoints",
+)
+@click.option("--page", default=1, show_default=True, help="Page number")
+@click.option("--size", default=50, show_default=True, help="Page size")
+@click.option("--base-url", default=None, help="External API base URL")
+@click.option("--api-key", default=None, help="API key")
+def endpoints_list(
+    search: str | None,
+    active_only: bool,
+    page: int,
+    size: int,
+    base_url: str | None,
+    api_key: str | None,
+):
+    """List accessible endpoints."""
+    client = _get_client(api_key=api_key, base_url=base_url)
+    payload = client.list_endpoints(
+        search=search,
+        is_active=True if active_only else None,
+        page=page,
+        size=size,
+    )
+    items = payload.get("items", [])
+    if not items:
+        click.echo("No endpoints found.")
+        return
+
+    header = f"{'ID':36}  {'NAME':28}  {'ACTIVE':6}  {'STATUS':12}  {'REPLICAS':8}"
+    click.echo(header)
+    click.echo("-" * len(header))
+    for item in items:
+        click.echo(
+            f"{item['id'][:36]:36}  "
+            f"{item['name'][:28]:28}  "
+            f"{str(item['is_active']):6}  "
+            f"{item['status'][:12]:12}  "
+            f"{str(item['num_replicas']):8}"
+        )
+
+
+@endpoints_cmd.command("get")
+@click.argument("endpoint_id")
+@click.option("--base-url", default=None, help="External API base URL")
+@click.option("--api-key", default=None, help="API key")
+def endpoints_get(endpoint_id: str, base_url: str | None, api_key: str | None):
+    """Get endpoint details."""
+    client = _get_client(api_key=api_key, base_url=base_url)
+    _render_json(client.get_endpoint(endpoint_id))
+
+
+@endpoints_cmd.command("start")
+@click.argument("endpoint_id")
+@click.option("--base-url", default=None, help="External API base URL")
+@click.option("--api-key", default=None, help="API key")
+def endpoints_start(endpoint_id: str, base_url: str | None, api_key: str | None):
+    """Start an endpoint."""
+    client = _get_client(api_key=api_key, base_url=base_url)
+    _render_json(client.start_endpoint(endpoint_id))
+
+
+@endpoints_cmd.command("stop")
+@click.argument("endpoint_id")
+@click.option("--base-url", default=None, help="External API base URL")
+@click.option("--api-key", default=None, help="API key")
+def endpoints_stop(endpoint_id: str, base_url: str | None, api_key: str | None):
+    """Stop an endpoint."""
+    client = _get_client(api_key=api_key, base_url=base_url)
+    _render_json(client.stop_endpoint(endpoint_id))
+
+
+@endpoints_cmd.command("scale")
+@click.argument("endpoint_id")
+@click.option("--replicas", required=True, type=int, help="Target replica count")
+@click.option("--base-url", default=None, help="External API base URL")
+@click.option("--api-key", default=None, help="API key")
+def endpoints_scale(endpoint_id: str, replicas: int, base_url: str | None, api_key: str | None):
+    """Scale endpoint replicas."""
+    client = _get_client(api_key=api_key, base_url=base_url)
+    _render_json(client.scale_endpoint(endpoint_id, replicas))
+
+
+@endpoints_cmd.command("patch")
+@click.argument("endpoint_id")
+@click.option("--command", "start_command", default=None, help="Container start command")
+@click.option("--port", "container_port", default=None, type=click.IntRange(1, 65535), help="Container port (1-65535)")
+@click.option("--health-check-path", default=None, help="Health check path")
+@click.option("--health-check-timeout", default=None, type=click.IntRange(min=1), help="Container health check timeout (seconds, >=1)")
+@click.option("--endpoint-health-timeout", default=None, type=click.IntRange(min=1), help="Endpoint-level health check timeout (seconds, >=1)")
+@click.option("--metric-path", default=None, help="Container metric path")
+@click.option("--env", "env_vars", multiple=True, help="Environment variable (KEY=VALUE), repeatable")
+@click.option("--base-url", default=None, help="External API base URL")
+@click.option("--api-key", default=None, help="API key")
+def endpoints_patch(
+    endpoint_id: str,
+    start_command: str | None,
+    container_port: int | None,
+    health_check_path: str | None,
+    health_check_timeout: int | None,
+    endpoint_health_timeout: int | None,
+    metric_path: str | None,
+    env_vars: tuple[str, ...],
+    base_url: str | None,
+    api_key: str | None,
+):
+    """Patch endpoint settings (endpoint must be inactive)."""
+    parsed_env = None
+    if env_vars:
+        parsed_env = []
+        for entry in env_vars:
+            if "=" not in entry:
+                raise click.ClickException(f"Invalid env format: {entry!r}  (expected KEY=VALUE)")
+            key, value = entry.split("=", 1)
+            parsed_env.append({"key": key, "value": value})
+
+    updates = {
+        "container_start_command": start_command,
+        "container_port": container_port,
+        "container_health_check_path": health_check_path,
+        "container_health_check_timeout": health_check_timeout,
+        "health_check_timeout": endpoint_health_timeout,
+        "container_metric_path": metric_path,
+        "container_env_vars": parsed_env,
+    }
+    if all(v is None for v in updates.values()):
+        raise click.ClickException("Provide at least one field to patch.")
+
+    client = _get_client(api_key=api_key, base_url=base_url)
+    _render_json(client.patch_endpoint(endpoint_id, **updates))
+
+
+@endpoints_cmd.command("replicas")
+@click.argument("endpoint_id")
+@click.option("--base-url", default=None, help="External API base URL")
+@click.option("--api-key", default=None, help="API key")
+def endpoints_replicas(endpoint_id: str, base_url: str | None, api_key: str | None):
+    """List replicas for an endpoint."""
+    client = _get_client(api_key=api_key, base_url=base_url)
+    items = client.get_replicas(endpoint_id)
+    if not items:
+        click.echo("No live replicas found.")
+        return
+
+    header = f"{'REPLICA':12}  {'STATE':12}  {'NODE':24}  {'ACTOR':24}"
+    click.echo(header)
+    click.echo("-" * len(header))
+    for item in items:
+        click.echo(
+            f"{item['replica_id'][:12]:12}  "
+            f"{item['state'][:12]:12}  "
+            f"{(item.get('node_id') or '-')[:24]:24}  "
+            f"{(item.get('actor_id') or '-')[:24]:24}"
+        )
+
+
+@endpoints_cmd.command("logs")
+@click.argument("endpoint_id")
+@click.option("--replica-id", default=None, help="Filter logs by replica ID")
+@click.option("--history/--no-history", default=True, help="Include historical log files")
+@click.option("--list-files", is_flag=True, help="List matching log files instead of reading one")
+@click.option("--raw", is_flag=True, help="Print raw log content")
+@click.option("--start-line", default=1, show_default=True, help="Start line")
+@click.option("--end-line", default=200, show_default=True, help="End line")
+@click.option("--base-url", default=None, help="External API base URL")
+@click.option("--api-key", default=None, help="API key")
+def endpoints_logs(
+    endpoint_id: str,
+    replica_id: str | None,
+    history: bool,
+    list_files: bool,
+    raw: bool,
+    start_line: int,
+    end_line: int,
+    base_url: str | None,
+    api_key: str | None,
+):
+    """Read logs for an endpoint."""
+    client = _get_client(api_key=api_key, base_url=base_url)
+    log_files = client.list_logs(
+        endpoint_id,
+        replica_id=replica_id,
+        include_history=history,
+    )
+    if not log_files:
+        click.echo("No log files found.")
+        return
+
+    if list_files:
+        header = f"{'REPLICA':12}  {'LIVE':4}  {'START':19}  {'FILE'}"
+        click.echo(header)
+        click.echo("-" * len(header))
+        for item in log_files:
+            click.echo(
+                f"{item['replica_id'][:12]:12}  "
+                f"{('yes' if not item.get('is_historical') else 'no'):4}  "
+                f"{_format_timestamp(item.get('start_time')):19}  "
+                f"{item['filename']}"
+            )
+        return
+
+    selected_log = _pick_default_log_file(log_files)
+    if not selected_log:
+        raise click.ClickException("Failed to select a log file.")
+
+    payload = client.read_log_file(
+        endpoint_id,
+        node_id=selected_log["node_id"],
+        filename=selected_log["filename"],
+        start_line=start_line,
+        end_line=end_line,
+    )
+    _render_log_content(payload.get("content", ""), raw=raw)
+
+
+@cli.command()
+@click.argument("endpoint_id")
+@click.option("--port", "-p", default=2222, help="Local port for SSH tunnel")
+@click.option(
+    "--host",
+    "-h",
+    default=None,
+    help="Override host in the derived WS URL (default: inferred from endpoint)",
+)
+@click.option("--api-key", "-k", default=None, help="API key (default: from config)")
+@click.option("--user", "-u", default="root", help="SSH user (default: root)")
+@click.option(
+    "--replica-id",
+    "-r",
+    default=None,
+    help="Pin the SSH tunnel to a specific replica (default: load-balanced)",
+)
+@click.option(
+    "--identity-file",
+    "-i",
+    default=None,
+    help="Path to SSH private key. Defaults to ~/.ssh/id_ed25519, id_ecdsa, id_rsa.",
+)
+@click.option("--tunnel-only", is_flag=True, help="Open tunnel without auto SSH connect")
+def ssh(
+    endpoint_id: str,
+    port: int,
+    host: str | None,
+    api_key: str | None,
+    user: str,
+    replica_id: str | None,
+    identity_file: str | None,
+    tunnel_only: bool,
+):
+    """SSH into a container."""
+    resolved_api_key = api_key or config.get_api_key()
+    if not resolved_api_key:
+        raise click.ClickException(
+            "API key not set. Run: aircloud config set api-key <key>"
+        )
+
+    client = _get_client(api_key=resolved_api_key)
+    endpoint = client.get_endpoint(endpoint_id)
+    serving_url = endpoint.get("serving_endpoint_url")
+    if not serving_url:
+        raise click.ClickException(
+            "Endpoint is missing serving_endpoint_url; cannot build SSH tunnel URL."
+        )
+
+    parsed = urlparse(serving_url)
+    scheme = "wss" if parsed.scheme == "https" else "ws"
+    netloc = host or parsed.netloc
+    path = parsed.path.rstrip("/") + "/ssh/tunnel"
+    ws_url = urlunparse((scheme, netloc, path, "", "", ""))
+
+    if tunnel_only:
+        click.echo("AirCloud SSH Tunnel")
+        click.echo(f"  Endpoint: {endpoint_id}")
+        if replica_id:
+            click.echo(f"  Replica:  {replica_id}")
+        click.echo(f"  Listening on 127.0.0.1:{port}")
+        identity_hint = f" -i {identity_file}" if identity_file else ""
+        click.echo(f"  Run: ssh -p {port}{identity_hint} {user}@127.0.0.1")
+        click.echo("")
+        start_tunnel(ws_url, resolved_api_key, port, replica_id)
+    else:
+        start_ssh(
+            ws_url,
+            resolved_api_key,
+            port,
+            user,
+            replica_id,
+            identity_file=identity_file,
+        )
+
+
+@cli.command("exec")
+@click.argument("endpoint_id")
+@click.option(
+    "--replica-id",
+    "-r",
+    default=None,
+    help="Pin the exec session to a specific replica (default: load-balanced)",
+)
+@click.option(
+    "--cmd",
+    "-c",
+    default="/bin/bash",
+    show_default=True,
+    help="Command to run inside the container",
+)
+@click.option("--api-key", "-k", default=None, help="API key (default: from config)")
+def exec_cmd(
+    endpoint_id: str,
+    replica_id: str | None,
+    cmd: str,
+    api_key: str | None,
+):
+    """Open an interactive shell in the container via docker exec."""
+    resolved_api_key = api_key or config.get_api_key()
+    if not resolved_api_key:
+        raise click.ClickException(
+            "API key not set. Run: aircloud config set api-key <key>"
+        )
+
+    client = _get_client(api_key=resolved_api_key)
+    endpoint = client.get_endpoint(endpoint_id)
+    serving_url = endpoint.get("serving_endpoint_url")
+    if not serving_url:
+        raise click.ClickException(
+            "Endpoint is missing serving_endpoint_url; cannot build exec URL."
+        )
+
+    parsed = urlparse(serving_url)
+    scheme = "wss" if parsed.scheme == "https" else "ws"
+    path = parsed.path.rstrip("/") + "/exec"
+    query = f"replica_id={replica_id}" if replica_id else ""
+    ws_url = urlunparse((scheme, parsed.netloc, path, "", query, ""))
+
+    click.echo("AirCloud Exec")
+    click.echo(f"  Endpoint: {endpoint_id}")
+    if replica_id:
+        click.echo(f"  Replica:  {replica_id}")
+    click.echo(f"  Command:  {cmd}")
+    click.echo("")
+
+    start_exec(ws_url, resolved_api_key, cmd.split())
+
+
+@cli.result_callback()
+def handle_errors(*_args, **_kwargs):
+    """Let click handle command lifecycle."""
+
+
+def main():
+    try:
+        cli()
+    except AirCloudAPIError as exc:
+        raise click.ClickException(str(exc)) from exc
+    except AirCloudError as exc:
+        raise click.ClickException(str(exc)) from exc
+
+
+if __name__ == "__main__":
+    main()

aircloud_cli/ssh_tunnel.py

@@ -0,0 +1,380 @@
+import asyncio
+import os
+import select
+import signal
+import sys
+import termios
+import threading
+import time
+import tty
+
+import paramiko
+import websockets
+
+
+_DEFAULT_IDENTITY_CANDIDATES = (
+    "~/.ssh/id_ed25519",
+    "~/.ssh/id_ecdsa",
+    "~/.ssh/id_rsa",
+)
+
+# 우리가 시도할 키 클래스. DSA 는 cryptography 44+ 와 호환 깨지는 케이스가 있어
+# 의도적으로 제외.
+_PKEY_CLASSES: tuple[type, ...] = (
+    paramiko.Ed25519Key,
+    paramiko.ECDSAKey,
+    paramiko.RSAKey,
+)
+
+
+def _resolve_identity_files(explicit: str | None) -> list[str]:
+    """Return absolute paths to existing private key files.
+
+    If `explicit` is given, only that path is returned (and validated).
+    Otherwise, common defaults are probed in order.
+    """
+    if explicit:
+        path = os.path.expanduser(explicit)
+        if not os.path.exists(path):
+            raise FileNotFoundError(f"Identity file not found: {path}")
+        return [path]
+
+    found: list[str] = []
+    for candidate in _DEFAULT_IDENTITY_CANDIDATES:
+        path = os.path.expanduser(candidate)
+        if os.path.exists(path):
+            found.append(path)
+    return found
+
+
+def _load_pkey(path: str) -> paramiko.PKey:
+    """Load a private key from disk, trying known key classes in order.
+
+    paramiko's own ``key_filename`` auto-detection plus ``allow_agent`` can
+    pick up unrelated keys (e.g. DSA keys in the agent that newer
+    ``cryptography`` versions refuse to sign with). We bypass that by
+    parsing the file ourselves and handing a single ``pkey`` object to
+    ``client.connect()``.
+    """
+    last_err: Exception | None = None
+    for klass in _PKEY_CLASSES:
+        try:
+            return klass.from_private_key_file(path)
+        except paramiko.PasswordRequiredException:
+            raise
+        except paramiko.SSHException as e:
+            last_err = e
+            continue
+    raise paramiko.SSHException(
+        f"Unable to parse private key at {path}: {last_err}"
+    )
+
+
+async def _run_tunnel(
+    ws_url: str,
+    api_key: str,
+    local_port: int,
+    ready: threading.Event,
+    replica_id: str | None = None,
+):
+    """Open local TCP port and relay to WebSocket SSH tunnel."""
+
+    async def handle_client(reader: asyncio.StreamReader, writer: asyncio.StreamWriter):
+        ws_conn = None
+        try:
+            headers = {"Authorization": f"Bearer {api_key}"}
+            if replica_id:
+                headers["serve_multiplexed_model_id"] = replica_id
+            ws_conn = await websockets.connect(
+                ws_url,
+                additional_headers=headers,
+                ping_interval=5,
+                ping_timeout=30,
+                max_size=None,
+            )
+
+            async def tcp_to_ws():
+                try:
+                    while True:
+                        data = await reader.read(4096)
+                        if not data:
+                            break
+                        await ws_conn.send(data)
+                except (ConnectionError, asyncio.CancelledError):
+                    pass
+
+            async def ws_to_tcp():
+                try:
+                    async for message in ws_conn:
+                        if isinstance(message, bytes):
+                            writer.write(message)
+                        elif isinstance(message, str):
+                            writer.write(message.encode())
+                        await writer.drain()
+                except (ConnectionError, asyncio.CancelledError):
+                    pass
+
+            await asyncio.gather(tcp_to_ws(), ws_to_tcp())
+
+        except websockets.exceptions.InvalidStatusCode as e:
+            if e.status_code == 302:
+                print(f"  Authentication failed (redirected to login)")
+            elif e.status_code == 403:
+                print(f"  Access denied. Check your API key.")
+            else:
+                print(f"  WebSocket connection failed: HTTP {e.status_code}")
+        except websockets.exceptions.ConnectionClosed as e:
+            print(f"  WebSocket closed: {e.code} {e.reason}")
+        except Exception as e:
+            print(f"  Connection error: {e}")
+        finally:
+            writer.close()
+            if ws_conn:
+                await ws_conn.close()
+
+    server = await asyncio.start_server(handle_client, "127.0.0.1", local_port)
+    ready.set()
+    try:
+        await server.serve_forever()
+    except asyncio.CancelledError:
+        pass
+    finally:
+        server.close()
+        await server.wait_closed()
+
+
+def _start_tunnel_thread(
+    ws_url: str,
+    api_key: str,
+    local_port: int,
+    replica_id: str | None = None,
+) -> threading.Event:
+    """Start the WebSocket tunnel in a background daemon thread."""
+    ready = threading.Event()
+
+    def run():
+        asyncio.run(_run_tunnel(ws_url, api_key, local_port, ready, replica_id))
+
+    t = threading.Thread(target=run, daemon=True)
+    t.start()
+    return ready
+
+
+def _interactive_shell(channel: paramiko.Channel):
+    """Forward stdin/stdout to the SSH channel.
+
+    Local stdin is put into raw mode so that every keystroke (incl. Tab,
+    arrow keys, Ctrl-C, Ctrl-D, backspace) flows to the remote shell
+    instead of being processed by the local terminal. The remote terminal
+    is also kept in sync with local terminal size, including SIGWINCH-
+    driven resizes during the session.
+    """
+    if not sys.stdin.isatty():
+        # Non-interactive stdin: just forward bytes both ways without
+        # touching termios.
+        channel.settimeout(0.0)
+        try:
+            while True:
+                r, _, _ = select.select([channel, sys.stdin], [], [])
+                if channel in r:
+                    data = channel.recv(4096)
+                    if not data:
+                        return
+                    sys.stdout.buffer.write(data)
+                    sys.stdout.flush()
+                if sys.stdin in r:
+                    chunk = sys.stdin.buffer.read1(4096)
+                    if not chunk:
+                        return
+                    channel.send(chunk)
+        except Exception:
+            return
+
+    fd = sys.stdin.fileno()
+    old_attr = termios.tcgetattr(fd)
+
+    def _on_winch(_signum, _frame):
+        try:
+            size = os.get_terminal_size(fd)
+            channel.resize_pty(width=size.columns, height=size.lines)
+        except Exception:
+            pass
+
+    prev_winch = signal.getsignal(signal.SIGWINCH)
+
+    try:
+        # Sync initial terminal size with remote pty.
+        try:
+            size = os.get_terminal_size(fd)
+            channel.resize_pty(width=size.columns, height=size.lines)
+        except Exception:
+            pass
+
+        signal.signal(signal.SIGWINCH, _on_winch)
+        tty.setraw(fd)
+        channel.settimeout(0.0)
+
+        while True:
+            r, _, _ = select.select([channel, sys.stdin], [], [])
+            if channel in r:
+                try:
+                    data = channel.recv(4096)
+                except Exception:
+                    break
+                if not data:
+                    break
+                os.write(sys.stdout.fileno(), data)
+            if sys.stdin in r:
+                try:
+                    chunk = os.read(fd, 4096)
+                except OSError:
+                    break
+                if not chunk:
+                    break
+                channel.send(chunk)
+    finally:
+        termios.tcsetattr(fd, termios.TCSADRAIN, old_attr)
+        try:
+            signal.signal(signal.SIGWINCH, prev_winch)
+        except Exception:
+            pass
+
+
+def start_ssh(
+    ws_url: str,
+    api_key: str,
+    local_port: int,
+    user: str,
+    replica_id: str | None = None,
+    identity_file: str | None = None,
+):
+    """Start tunnel + SSH connection (public-key auth).
+
+    Auth flow:
+      1. If ``identity_file`` is given, that key is used.
+      2. Otherwise common paths (~/.ssh/id_ed25519, id_ecdsa, id_rsa) are tried.
+      3. ssh-agent is also consulted if available.
+
+    The WS layer is gated by our external-auth (API key); the SSH layer
+    inside the tunnel verifies the user's public key against the keys
+    injected into the container via AIRCLOUD_AUTHORIZED_KEYS.
+    """
+
+    print("AirCloud SSH")
+    print(f"  Opening tunnel on 127.0.0.1:{local_port}...")
+
+    ready = _start_tunnel_thread(ws_url, api_key, local_port, replica_id)
+    if not ready.wait(timeout=10):
+        print("  Failed to start tunnel.")
+        return
+
+    try:
+        identity_files = _resolve_identity_files(identity_file)
+    except FileNotFoundError as e:
+        print(f"  {e}")
+        return
+
+    pkeys: list[tuple[str, paramiko.PKey]] = []
+    for path in identity_files:
+        try:
+            pkeys.append((path, _load_pkey(path)))
+        except paramiko.PasswordRequiredException:
+            print(
+                f"  {path} is encrypted. Add it to ssh-agent first: "
+                f"ssh-add {path}"
+            )
+        except paramiko.SSHException as e:
+            print(f"  Skipping {path}: {e}")
+
+    if not pkeys:
+        print(
+            "  No usable SSH private key. Provide one with -i, generate one "
+            "with `ssh-keygen -t ed25519`, or add it to ssh-agent."
+        )
+        return
+
+    used = ", ".join(p for p, _ in pkeys)
+    print(f"  Using identity: {used}")
+    print(f"  Connecting as {user}...")
+
+    client = paramiko.SSHClient()
+    client.set_missing_host_key_policy(paramiko.AutoAddPolicy())
+
+    retries = 3
+    last_err: Exception | None = None
+
+    # 명시적으로 로드한 pkey 들을 순서대로 시도. paramiko 의 key_filename /
+    # allow_agent 자동 탐색은 의도치 않은 키 (예: agent 에 남아있는 DSA) 를
+    # 잡아 sign 시도하다 cryptography 호환성 문제로 실패할 수 있어 사용 안 함.
+    for path, pkey in pkeys:
+        last_err = None
+        for attempt in range(retries):
+            try:
+                client.connect(
+                    "127.0.0.1",
+                    port=local_port,
+                    username=user,
+                    pkey=pkey,
+                    look_for_keys=False,
+                    allow_agent=False,
+                    timeout=10,
+                )
+                last_err = None
+                break
+            except paramiko.AuthenticationException as e:
+                last_err = e
+                break  # auth 실패는 재시도해도 의미 없음
+            except Exception as e:
+                last_err = e
+                if attempt < retries - 1:
+                    time.sleep(1)
+
+        if last_err is None:
+            break  # 이 키로 인증 성공
+
+    if last_err is not None:
+        if isinstance(last_err, paramiko.AuthenticationException):
+            print("  SSH authentication failed.")
+            print(
+                "  Make sure your public key is registered in the AirCloud "
+                "console (Project → SSH Keys) and applied to this endpoint, "
+                "and that the endpoint has been (re)started since the key "
+                "was added."
+            )
+        else:
+            print(f"  SSH connection failed: {last_err}")
+        return
+
+    print("  Connected!\n")
+
+    try:
+        try:
+            size = os.get_terminal_size(sys.stdin.fileno())
+            channel = client.invoke_shell(
+                term=os.environ.get("TERM", "xterm-256color"),
+                width=size.columns,
+                height=size.lines,
+            )
+        except (OSError, ValueError):
+            channel = client.invoke_shell(term="xterm-256color")
+        _interactive_shell(channel)
+    except KeyboardInterrupt:
+        pass
+    finally:
+        client.close()
+        print("\n  Connection closed.")
+
+
+def start_tunnel(
+    ws_url: str,
+    api_key: str,
+    local_port: int,
+    replica_id: str | None = None,
+):
+    """Start tunnel only (no auto SSH). For manual SSH connection."""
+    try:
+        asyncio.run(
+            _run_tunnel(ws_url, api_key, local_port, threading.Event(), replica_id)
+        )
+    except KeyboardInterrupt:
+        print("\n  Tunnel closed.")

aircloud_cli-0.1.0.dist-info/METADATA

@@ -0,0 +1,130 @@
+Metadata-Version: 2.4
+Name: aircloud-cli
+Version: 0.1.0
+Summary: AirCloud CLI — endpoint management, SSH, and container exec
+Author-email: AirCloud Team <support@aieev.com>
+License: Proprietary
+Project-URL: Homepage, https://aieev.com
+Project-URL: Repository, https://github.com/aieev/aircloud-cli
+Keywords: aircloud,ssh,cli,endpoint,exec
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: System Administrators
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development
+Classifier: Topic :: System :: Shells
+Classifier: Topic :: Utilities
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: websockets>=12.0
+Requires-Dist: click>=8.0
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: paramiko>=3.0
+Requires-Dist: cryptography>=3.0
+
+# aircloud-cli
+
+CLI for the [AirCloud](https://aieev.com) platform — endpoint management,
+SSH access, and container shell exec.
+
+## Install
+
+```bash
+pip install aircloud-cli
+```
+
+Requires Python 3.9+.
+
+## Quick start
+
+```bash
+# one-time setup
+aircloud config set api-key <YOUR_API_KEY>
+aircloud config set api-base-url <API_BASE_URL>
+
+# inspect endpoints
+aircloud endpoints list
+aircloud endpoints get <endpoint_id>
+
+# open a shell in a container
+aircloud ssh <endpoint_id>            # public-key auth, sshd-based
+aircloud exec <endpoint_id>           # docker exec over WS, no sshd needed
+```
+
+## Commands
+
+### `aircloud config`
+
+Manage CLI configuration in `~/.aircloud/config.json`.
+
+```bash
+aircloud config set api-key <key>
+aircloud config set api-base-url <url>
+aircloud config list
+aircloud config get <key>
+```
+
+### `aircloud endpoints`
+
+```bash
+aircloud endpoints list                          # paged list
+aircloud endpoints get <id>                      # detail
+aircloud endpoints start <id>
+aircloud endpoints stop <id>
+aircloud endpoints scale <id> --replicas N
+aircloud endpoints patch <id> --command "..." --port 8080 --env KEY=VALUE
+aircloud endpoints replicas <id>                 # current replicas
+aircloud endpoints logs <id> [--replica-id X] [--start-line N --end-line M]
+```
+
+### `aircloud ssh`
+
+SSH into a container via WebSocket tunnel using public-key authentication.
+
+```bash
+aircloud ssh <endpoint_id>                       # auto-discover ~/.ssh/id_*
+aircloud ssh <endpoint_id> -i ~/.ssh/aircloud_key
+aircloud ssh <endpoint_id> -r <replica_id>       # pin to specific replica
+aircloud ssh <endpoint_id> --tunnel-only         # open tunnel only
+```
+
+Auto-discovers identity files in this order: `~/.ssh/id_ed25519`,
+`~/.ssh/id_ecdsa`, `~/.ssh/id_rsa`. Override with `-i / --identity-file`.
+
+The container image must have `sshd` running and consume the
+`AIRCLOUD_AUTHORIZED_KEYS` environment variable (AirCloud-provided template
+images do this by default).
+
+### `aircloud exec`
+
+Open an interactive shell in the container via `docker exec` over a
+WebSocket. Works on any image — no `sshd` required.
+
+```bash
+aircloud exec <endpoint_id>
+aircloud exec <endpoint_id> -r <replica_id>      # pin replica
+aircloud exec <endpoint_id> -c "/bin/sh"         # custom command
+```
+
+### `aircloud whoami`
+
+Print the identity associated with the current API key.
+
+```bash
+aircloud whoami
+```
+
+## Status
+
+This is an early functional release. Interfaces may change before `1.0.0`.
+
+## License
+
+Proprietary. © AIEEV / AirCloud.

aircloud_cli-0.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+aircloud_cli/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+aircloud_cli/client.py,sha256=m3RSgW50RROL9jdoOCRPdZpM4DZ4YBRfzpiS03uYJ2s,5016
+aircloud_cli/config.py,sha256=qD5qcbFswbqBlpA6kMJ4XOZvfoT3OTEkBp8UbdKF8Jo,731
+aircloud_cli/container_exec.py,sha256=vopx8xKVq6gCH-vuhLWpnJ2eSZ8VopH4JpLkcOQkGk4,4262
+aircloud_cli/main.py,sha256=9cU8GqnBAk4DqMAPdRQSIWYGQ6ysTgvAlwi1hukgRSc,16782
+aircloud_cli/ssh_tunnel.py,sha256=67w5F0Vw1SKzuiQ2XtJe_edHjWgMGk2oiT5MPKIva04,12089
+aircloud_cli-0.1.0.dist-info/METADATA,sha256=3UEENw5mYvZosvCE4rAtSLSfAW7DkyQOVyHoTE_i7pw,3723
+aircloud_cli-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+aircloud_cli-0.1.0.dist-info/entry_points.txt,sha256=zZ7qUGBgOIrb1EbOxGmUFg8LN7Zggok8rHY_95pamok,52
+aircloud_cli-0.1.0.dist-info/top_level.txt,sha256=xH15vUuUKOaY23w1psZXdidHbtLiZa9eshvPjMLBJgQ,13
+aircloud_cli-0.1.0.dist-info/RECORD,,

aircloud_cli-0.1.0.dist-info/WHEEL

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

aircloud_cli-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+aircloud = aircloud_cli.main:main

aircloud_cli-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+aircloud_cli