lcloud-cli 0.1.0__py3-none-any.whl

lambda_cloud/__init__.py

@@ -0,0 +1,3 @@
+"""Unofficial community CLI for the Lambda Cloud API."""
+
+__version__ = "0.1.0"

lambda_cloud/__main__.py

@@ -0,0 +1,6 @@
+"""Allow `python -m lambda_cloud`."""
+
+from .cli.app import main
+
+if __name__ == "__main__":
+    main()

lambda_cloud/api/__init__.py

@@ -0,0 +1,17 @@
+"""API access layer: HTTP client and high-level service functions."""
+
+from . import service
+from .client import (
+    DEFAULT_BASE_URL,
+    DEFAULT_MAX_RETRIES,
+    DEFAULT_MIN_INTERVAL_SECONDS,
+    LambdaCloudClient,
+)
+
+__all__ = [
+    "DEFAULT_BASE_URL",
+    "DEFAULT_MAX_RETRIES",
+    "DEFAULT_MIN_INTERVAL_SECONDS",
+    "LambdaCloudClient",
+    "service",
+]

lambda_cloud/api/client.py

@@ -0,0 +1,150 @@
+"""HTTP client for the Lambda Cloud API.
+
+Handles authentication, the documented rate limits (1 request/second in
+general), retries on ``429 Too Many Requests``, and conversion of error
+responses into :class:`~lambda_cloud.errors.APIError` exceptions.
+"""
+
+from __future__ import annotations
+
+import os
+import time
+from typing import Any
+
+import httpx
+
+from .. import __version__
+from ..core.errors import APIError
+
+DEFAULT_BASE_URL = "https://cloud.lambda.ai/api/v1"
+BASE_URL_ENV_VAR = "LAMBDA_CLOUD_API_URL"
+MIN_INTERVAL_ENV_VAR = "LAMBDA_CLOUD_MIN_INTERVAL"
+
+#: Default minimum delay between two API calls, per the documented rate limit.
+DEFAULT_MIN_INTERVAL_SECONDS = 1.05
+
+#: Maximum number of retries after a 429 response.
+DEFAULT_MAX_RETRIES = 3
+
+
+class LambdaCloudClient:
+    """Thin wrapper around :class:`httpx.Client` for the Lambda Cloud API."""
+
+    def __init__(
+        self,
+        api_key: str,
+        *,
+        base_url: str | None = None,
+        timeout: float = 30.0,
+        min_interval: float | None = None,
+        max_retries: int = DEFAULT_MAX_RETRIES,
+        transport: httpx.BaseTransport | None = None,
+    ) -> None:
+        resolved_base_url = base_url or os.environ.get(BASE_URL_ENV_VAR) or DEFAULT_BASE_URL
+        if min_interval is None:
+            min_interval = float(os.environ.get(MIN_INTERVAL_ENV_VAR, DEFAULT_MIN_INTERVAL_SECONDS))
+        self._min_interval = min_interval
+        self._max_retries = max_retries
+        self._last_request_at = 0.0
+        self._client = httpx.Client(
+            base_url=resolved_base_url.rstrip("/"),
+            headers={
+                "Authorization": f"Bearer {api_key}",
+                "Accept": "application/json",
+                "User-Agent": f"lambda-cloud-cli/{__version__}",
+            },
+            timeout=timeout,
+            transport=transport,
+        )
+
+    def __enter__(self) -> LambdaCloudClient:
+        return self
+
+    def __exit__(self, *exc_info: object) -> None:
+        self.close()
+
+    def close(self) -> None:
+        self._client.close()
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: dict[str, Any] | None = None,
+        json: Any | None = None,
+    ) -> dict[str, Any]:
+        """Perform one API call (with retries) and return the raw payload."""
+        for attempt in range(self._max_retries + 1):
+            self._throttle()
+            response = self._client.request(method, path, params=params, json=json)
+
+            if response.status_code == 429 and attempt < self._max_retries:
+                time.sleep(self._retry_delay(response))
+                continue
+
+            if not response.is_success:
+                raise APIError.from_response(response)
+
+            if response.status_code == 204 or not response.content:
+                return {}
+            payload = response.json()
+            return payload if isinstance(payload, dict) else {"data": payload}
+
+        # Unreachable in practice: the last attempt either returns or raises.
+        raise APIError(429, "global/rate-limited", "Too many requests after retries.")
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: dict[str, Any] | None = None,
+        json: Any | None = None,
+    ) -> Any:
+        """Perform an API call and return the unwrapped ``data`` payload.
+
+        Raises:
+            APIError: if the API responds with a non-2xx status.
+        """
+        return self._request(method, path, params=params, json=json).get("data")
+
+    def get_page(
+        self, path: str, *, params: dict[str, Any] | None = None
+    ) -> tuple[Any, str | None]:
+        """GET an endpoint that paginates with a top-level ``page_token``."""
+        payload = self._request("GET", path, params=params)
+        return payload.get("data"), payload.get("page_token")
+
+    def get(self, path: str, *, params: dict[str, Any] | None = None) -> Any:
+        return self.request("GET", path, params=params)
+
+    def post(
+        self, path: str, *, json: Any | None = None, params: dict[str, Any] | None = None
+    ) -> Any:
+        return self.request("POST", path, json=json, params=params)
+
+    def patch(self, path: str, *, json: Any | None = None) -> Any:
+        return self.request("PATCH", path, json=json)
+
+    def put(self, path: str, *, json: Any | None = None) -> Any:
+        return self.request("PUT", path, json=json)
+
+    def delete(self, path: str) -> Any:
+        return self.request("DELETE", path)
+
+    def _throttle(self) -> None:
+        """Enforce the minimum interval between two API requests."""
+        if self._min_interval <= 0:
+            return
+        elapsed = time.monotonic() - self._last_request_at
+        if elapsed < self._min_interval:
+            time.sleep(self._min_interval - elapsed)
+        self._last_request_at = time.monotonic()
+
+    @staticmethod
+    def _retry_delay(response: httpx.Response) -> float:
+        try:
+            return min(float(response.headers.get("Retry-After", "1")), 30.0)
+        except ValueError:
+            return 1.0

lambda_cloud/api/service.py

@@ -0,0 +1,242 @@
+"""High-level API operations shared by commands and tests.
+
+Every function takes a :class:`LambdaCloudClient` and returns validated
+pydantic models, keeping commands free of HTTP details.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+
+from ..core.errors import LambdaCloudError
+from ..mngr.models import (
+    AuditEvent,
+    Filesystem,
+    FirewallRule,
+    FirewallRuleset,
+    GeneratedSSHKey,
+    GlobalFirewallRuleset,
+    Image,
+    Instance,
+    InstanceTypeOffer,
+    NetworkProtocol,
+    Region,
+    SSHKey,
+    TagEntry,
+)
+from .client import LambdaCloudClient
+
+
+def validate_tags(tags: list[TagEntry]) -> list[dict[str, str]]:
+    """Serialize tags for the launch payload."""
+    return [tag.model_dump() for tag in tags]
+
+
+def validate_firewall_rules(rules: list[FirewallRule]) -> None:
+    """Enforce the API's port_range constraints before submitting rules."""
+    for rule in rules:
+        if rule.protocol is NetworkProtocol.ICMP and rule.port_range is not None:
+            raise LambdaCloudError("Firewall rule with protocol 'icmp' must not define port_range.")
+        if rule.protocol is not NetworkProtocol.ICMP and rule.port_range is None:
+            raise LambdaCloudError(
+                f"Firewall rule with protocol '{rule.protocol.value}' requires "
+                "port_range [min, max]."
+            )
+
+
+def serialize_firewall_rules(rules: list[FirewallRule]) -> list[dict]:
+    """Serialize rules, dropping an empty port_range for icmp."""
+    payload = []
+    for rule in rules:
+        item = rule.model_dump(mode="json")
+        if item.get("port_range") is None:
+            item.pop("port_range", None)
+        payload.append(item)
+    return payload
+
+
+def filter_images(
+    images: list[Image],
+    region: str | None = None,
+    family: str | None = None,
+) -> list[Image]:
+    """Apply client-side filters to an image list."""
+    if region:
+        images = [img for img in images if img.region and img.region.name == region]
+    if family:
+        images = [img for img in images if img.family == family]
+    return images
+
+
+def sort_images_by_updated(images: list[Image]) -> list[Image]:
+    """Sort images by last update, oldest first."""
+    return sorted(images, key=lambda img: img.updated_time or img.created_time or datetime.min)
+
+
+def parse_instance_types(data: dict[str, dict]) -> list[InstanceTypeOffer]:
+    """Parse the dict response of ``GET /instance-types``."""
+    offers = [InstanceTypeOffer.model_validate(value) for value in data.values()]
+    return sorted(offers, key=lambda offer: offer.instance_type.price_cents_per_hour)
+
+
+def list_instance_types(client: LambdaCloudClient) -> list[InstanceTypeOffer]:
+    """Fetch and sort all instance type offers by hourly price."""
+    return parse_instance_types(client.get("/instance-types"))
+
+
+# ---------------------------------------------------------------- thin wrappers
+
+
+def list_instances(client: LambdaCloudClient, cluster_id: str | None = None) -> list[Instance]:
+    params = {"cluster_id": cluster_id} if cluster_id else None
+    data = client.get("/instances", params=params)
+    return [Instance.model_validate(item) for item in data]
+
+
+def get_instance(client: LambdaCloudClient, instance_id: str) -> Instance:
+    return Instance.model_validate(client.get(f"/instances/{instance_id}"))
+
+
+def launch_instances(client: LambdaCloudClient, payload: dict) -> list[str]:
+    data = client.post("/instance-operations/launch", json=payload)
+    return data["instance_ids"]
+
+
+def restart_instances(client: LambdaCloudClient, instance_ids: list[str]) -> list[Instance]:
+    data = client.post("/instance-operations/restart", json={"instance_ids": instance_ids})
+    return [Instance.model_validate(item) for item in data["restarted_instances"]]
+
+
+def terminate_instances(client: LambdaCloudClient, instance_ids: list[str]) -> list[Instance]:
+    data = client.post("/instance-operations/terminate", json={"instance_ids": instance_ids})
+    return [Instance.model_validate(item) for item in data["terminated_instances"]]
+
+
+def rename_instance(client: LambdaCloudClient, instance_id: str, name: str) -> None:
+    client.post(f"/instances/{instance_id}", json={"name": name})
+
+
+def list_ssh_keys(client: LambdaCloudClient) -> list[SSHKey]:
+    data = client.get("/ssh-keys")
+    return [SSHKey.model_validate(item) for item in data]
+
+
+def add_ssh_key(
+    client: LambdaCloudClient, name: str, public_key: str | None = None
+) -> SSHKey | GeneratedSSHKey:
+    payload: dict[str, str] = {"name": name}
+    if public_key:
+        payload["public_key"] = public_key
+    data = client.post("/ssh-keys", json=payload)
+    if "private_key" in data:
+        return GeneratedSSHKey.model_validate(data)
+    return SSHKey.model_validate(data)
+
+
+def delete_ssh_key(client: LambdaCloudClient, key_id: str) -> None:
+    client.delete(f"/ssh-keys/{key_id}")
+
+
+def list_filesystems(client: LambdaCloudClient) -> list[Filesystem]:
+    data = client.get("/file-systems")
+    return [Filesystem.model_validate(item) for item in data]
+
+
+def create_filesystem(client: LambdaCloudClient, name: str, region: str) -> Filesystem:
+    data = client.post("/filesystems", json={"name": name, "region": region})
+    return Filesystem.model_validate(data)
+
+
+def delete_filesystem(client: LambdaCloudClient, filesystem_id: str) -> None:
+    client.delete(f"/filesystems/{filesystem_id}")
+
+
+def list_images(client: LambdaCloudClient) -> list[Image]:
+    data = client.get("/images")
+    return [Image.model_validate(item) for item in data]
+
+
+def list_regions(client: LambdaCloudClient) -> list[Region]:
+    data = client.get("/regions")
+    return [Region.model_validate(item) for item in data]
+
+
+def list_firewall_rulesets(client: LambdaCloudClient) -> list[FirewallRuleset]:
+    data = client.get("/firewall-rulesets")
+    return [FirewallRuleset.model_validate(item) for item in data]
+
+
+def get_firewall_ruleset(client: LambdaCloudClient, ruleset_id: str) -> FirewallRuleset:
+    return FirewallRuleset.model_validate(client.get(f"/firewall-rulesets/{ruleset_id}"))
+
+
+def create_firewall_ruleset(
+    client: LambdaCloudClient, name: str, region: str, rules: list[FirewallRule]
+) -> FirewallRuleset:
+    validate_firewall_rules(rules)
+    data = client.post(
+        "/firewall-rulesets",
+        json={"name": name, "region": region, "rules": serialize_firewall_rules(rules)},
+    )
+    return FirewallRuleset.model_validate(data)
+
+
+def update_firewall_ruleset(
+    client: LambdaCloudClient,
+    ruleset_id: str,
+    name: str | None = None,
+    rules: list[FirewallRule] | None = None,
+) -> FirewallRuleset:
+    payload: dict = {}
+    if name is not None:
+        payload["name"] = name
+    if rules is not None:
+        validate_firewall_rules(rules)
+        payload["rules"] = serialize_firewall_rules(rules)
+    data = client.patch(f"/firewall-rulesets/{ruleset_id}", json=payload)
+    return FirewallRuleset.model_validate(data)
+
+
+def delete_firewall_ruleset(client: LambdaCloudClient, ruleset_id: str) -> None:
+    client.delete(f"/firewall-rulesets/{ruleset_id}")
+
+
+def get_global_firewall_ruleset(client: LambdaCloudClient) -> GlobalFirewallRuleset:
+    return GlobalFirewallRuleset.model_validate(client.get("/firewall-rulesets/global"))
+
+
+def update_global_firewall_ruleset(
+    client: LambdaCloudClient, rules: list[FirewallRule]
+) -> GlobalFirewallRuleset:
+    validate_firewall_rules(rules)
+    data = client.patch(
+        "/firewall-rulesets/global", json={"rules": serialize_firewall_rules(rules)}
+    )
+    return GlobalFirewallRuleset.model_validate(data)
+
+
+def list_audit_events(
+    client: LambdaCloudClient,
+    start: str | None = None,
+    end: str | None = None,
+    resource_type: str | None = None,
+    all_pages: bool = False,
+) -> list[AuditEvent]:
+    params = {
+        key: value
+        for key, value in {
+            "start": start,
+            "end": end,
+            "resource_type": resource_type,
+        }.items()
+        if value is not None
+    }
+    events: list[AuditEvent] = []
+    data, page_token = client.get_page("/audit-events", params=params)
+    events.extend(AuditEvent.model_validate(item) for item in data)
+    while all_pages and page_token:
+        data, page_token = client.get_page(
+            "/audit-events", params={**params, "page_token": page_token}
+        )
+        events.extend(AuditEvent.model_validate(item) for item in data)
+    return events

lambda_cloud/cli/__init__.py

@@ -0,0 +1 @@
+"""Command-line interface layer."""

lambda_cloud/cli/app.py

@@ -0,0 +1,111 @@
+"""Root Typer application assembling every command group."""
+
+from __future__ import annotations
+
+import httpx
+import typer
+
+from .. import __version__
+from ..core.errors import LambdaCloudError
+from .commands import (
+    audit,
+    auth,
+    completion,
+    config_cmd,
+    filesystems,
+    firewall,
+    images,
+    instance_types,
+    instances,
+    regions,
+    ssh_keys,
+)
+from .state import State
+from .ui.console import OutputFormat, console, err_console, exit_with_error
+
+
+def _version_callback(value: bool) -> None:
+    if value:
+        console.print(f"lambda-cloud {__version__}")
+        raise typer.Exit()
+
+
+app = typer.Typer(
+    name="lambda-cloud",
+    help=(
+        "Unofficial community CLI for the Lambda Cloud API "
+        "(https://cloud.lambda.ai)."
+        "\n\nManage on-demand GPU instances, SSH keys, filesystems, images, "
+        "regions and firewall rulesets."
+    ),
+    no_args_is_help=True,
+    add_completion=False,
+    rich_markup_mode="rich",
+)
+
+
+@app.callback()
+def callback(
+    ctx: typer.Context,
+    api_key: str | None = typer.Option(
+        None,
+        "--api-key",
+        help="API key. Overrides LAMBDA_API_KEY and the stored config.",
+        show_envvar=False,
+    ),
+    output_format: OutputFormat = typer.Option(
+        OutputFormat.TABLE,
+        "--output",
+        "-o",
+        help="Output format.",
+    ),
+    verbose: bool = typer.Option(False, "--verbose", help="Verbose output."),
+    show_completion: str | None = typer.Option(
+        None,
+        "--show-completion",
+        help="Print shell completion instructions (bash, zsh, fish, powershell).",
+        is_eager=True,
+    ),
+    version: bool = typer.Option(
+        False,
+        "--version",
+        callback=_version_callback,
+        is_eager=True,
+        help="Show version and exit.",
+    ),
+) -> None:
+    """Store global options on the context; commands pick them up lazily."""
+    completion.handle_completion(show_completion)
+    state = State(api_key=api_key, output=output_format, verbose=verbose)
+    ctx.obj = state
+    ctx.call_on_close(state.close)
+
+
+app.add_typer(instances.app, name="instances")
+app.add_typer(instance_types.app, name="types")
+app.add_typer(ssh_keys.app, name="ssh-keys")
+app.add_typer(filesystems.app, name="filesystems")
+app.add_typer(images.app, name="images")
+app.add_typer(regions.app, name="regions")
+app.add_typer(firewall.app, name="firewall")
+app.add_typer(audit.app, name="audit")
+app.add_typer(config_cmd.app, name="config")
+
+app.command("login", help="Store and validate your Lambda Cloud API key.")(auth.login)
+app.command("logout", help="Remove the stored API key.")(auth.logout)
+app.command("whoami", help="Show which credentials are in use and validate them.")(auth.whoami)
+
+
+def main() -> None:
+    """Console entry point: convert errors into clean exits."""
+    try:
+        app()
+    except LambdaCloudError as exc:
+        exit_with_error(exc)
+    except httpx.HTTPError as exc:
+        err_console.print(f"Network error: {exc}", style="bold red")
+        raise SystemExit(1) from None
+
+
+if __name__ == "__main__":
+    main()

lambda_cloud/cli/commands/__init__.py

@@ -0,0 +1 @@
+"""Typer command groups for every Lambda Cloud resource."""

lambda_cloud/cli/commands/audit.py

@@ -0,0 +1,37 @@
+"""Query account audit events."""
+
+from __future__ import annotations
+
+import typer
+
+from ...api import service
+from ..state import CommandBase
+from ..ui.tables import audit_events_table
+
+app = typer.Typer(no_args_is_help=True, help="Query account audit events.")
+
+
+@app.command("list")
+def list_audit_events(
+    ctx: typer.Context,
+    start: str | None = typer.Option(
+        None, "--start", help="ISO 8601 timestamp, inclusive (e.g. 2025-09-01T00:00:00Z)."
+    ),
+    end: str | None = typer.Option(None, "--end", help="ISO 8601 timestamp, inclusive."),
+    resource_type: str | None = typer.Option(
+        None, "--resource-type", help="Filter by resource type, e.g. cloud.api_key."
+    ),
+    all_pages: bool = typer.Option(
+        False, "--all", help="Follow pagination until all events are fetched."
+    ),
+) -> None:
+    """List audit events (newest time range by default)."""
+    cmd = CommandBase(ctx)
+    events = service.list_audit_events(
+        cmd.client,
+        start=start,
+        end=end,
+        resource_type=resource_type,
+        all_pages=all_pages,
+    )
+    cmd.emit(events, audit_events_table(events))

lambda_cloud/cli/commands/auth.py

@@ -0,0 +1,69 @@
+"""Manage the local Lambda Cloud API key."""
+
+from __future__ import annotations
+
+import os
+
+import typer
+
+from ...api import LambdaCloudClient
+from ...core.config import (
+    API_KEY_ENV_VAR,
+    delete_stored_config,
+    describe_api_key_source,
+    mask_api_key,
+    save_api_key,
+)
+from ...core.errors import ConfigError, LambdaCloudError
+from ..state import CommandBase
+from ..ui.console import info, success, warn
+
+
+def login(
+    ctx: typer.Context,
+    api_key: str | None = typer.Option(
+        None,
+        "--api-key",
+        help="Skip the prompt by passing the key directly.",
+    ),
+) -> None:
+    """Prompt for a key, validate it against the API, and save it."""
+    CommandBase(ctx, needs_client=False)
+    if api_key is None:
+        api_key = typer.prompt("Lambda Cloud API key (input hidden)", hide_input=True)
+    api_key = api_key.strip()
+    if not api_key:
+        raise LambdaCloudError("Empty API key.")
+
+    with LambdaCloudClient(api_key) as client:
+        client.get("/instances")
+
+    path = save_api_key(api_key)
+    success(f"Key is valid. Configuration written to {path}")
+
+
+def logout(ctx: typer.Context) -> None:
+    """Delete the stored config file, if any."""
+    CommandBase(ctx, needs_client=False)
+    if delete_stored_config():
+        success("Stored configuration removed.")
+    else:
+        info("No stored configuration found.")
+    if os.environ.get(API_KEY_ENV_VAR):
+        warn(f"{API_KEY_ENV_VAR} is still set in your environment; unset it to fully log out.")
+
+
+def whoami(ctx: typer.Context) -> None:
+    """Show the credentials currently in use and verify they are valid."""
+    CommandBase(ctx, needs_client=False)
+    source = describe_api_key_source(ctx.obj.api_key)
+    if source is None:
+        raise ConfigError(
+            f"No API key configured. Run `lambda-cloud login` or set {API_KEY_ENV_VAR}."
+        )
+    label, key = source
+    info(f"Source: {label}")
+    info(f"Key:    {mask_api_key(key)}")
+    with LambdaCloudClient(key) as client:
+        client.get("/instances")
+    success("Key is valid.")

lambda_cloud/cli/commands/completion.py

@@ -0,0 +1,37 @@
+"""Shell completion support."""
+
+from __future__ import annotations
+
+import typer
+
+from ...core.errors import LambdaCloudError
+from ..ui.console import console
+
+SUPPORTED_SHELLS = ("bash", "zsh", "fish", "powershell")
+
+_SNIPPETS = {
+    "bash": 'eval "$(_LAMBDA_CLOUD_COMPLETE=bash_source lambda-cloud)"',
+    "zsh": 'eval "$(_LAMBDA_CLOUD_COMPLETE=zsh_source lambda-cloud)"',
+    "fish": "_LAMBDA_CLOUD_COMPLETE=fish_source lambda-cloud | source",
+    "powershell": (
+        "$env:_LAMBDA_CLOUD_COMPLETE='powershell_source'; "
+        "lambda-cloud | Out-String | Invoke-Expression; "
+        "Remove-Item Env:_LAMBDA_CLOUD_COMPLETE"
+    ),
+}
+
+
+def handle_completion(shell: str | None) -> None:
+    """Print activation instructions for shell completion, then exit."""
+    if shell is None:
+        return
+    normalized = shell.lower()
+    if normalized not in _SNIPPETS:
+        raise LambdaCloudError(
+            f"Unsupported shell {shell!r}. Choose from: {', '.join(SUPPORTED_SHELLS)}."
+        )
+    console.print(
+        f"Run the following to enable completion for [bold]{normalized}[/bold]:\n\n"
+        f"  {_SNIPPETS[normalized]}\n"
+    )
+    raise typer.Exit()