runbay 0.1.0__tar.gz

runbay-0.1.0/PKG-INFO

@@ -0,0 +1,8 @@
+Metadata-Version: 2.4
+Name: runbay
+Version: 0.1.0
+Summary: RunBay SDK & CLI — deploy Python functions to serverless GPUs
+Requires-Python: >=3.9
+Requires-Dist: requests>=2.31
+Requires-Dist: click>=8.1
+Requires-Dist: rich>=13.0

runbay-0.1.0/README.md

@@ -0,0 +1,55 @@
+# runbay — SDK & CLI
+
+Deploy Python functions to serverless GPUs. Endpoints scale to zero when idle
+and spin GPU workers back up on demand. Everything is declared in code — no
+config files.
+
+## Install
+
+```bash
+pip install -e .
+```
+
+## Quick start
+
+```python
+# handler.py
+from runbay import endpoint, GpuGroup
+
+@endpoint(
+    name="text-generation",
+    gpu=GpuGroup.ADA_24,
+    workers=3,
+    idle_timeout=600,
+    dependencies=["transformers", "torch", "accelerate"],
+)
+def generate_text(prompt, max_length=50):
+    ...
+    return {"generated_text": ...}
+```
+
+```bash
+rb register                    # once — creates account + API key
+rb deploy                      # provision + upload
+```
+
+```python
+from handler import generate_text
+
+generate_text("Once upon a time")          # runs on a serverless GPU
+generate_text.spawn("...").output()        # async
+generate_text.local("...")                 # run on your machine
+```
+
+## CLI overview
+
+| Command | Purpose |
+|---|---|
+| `rb login [API_KEY]` / `rb whoami` | Authenticate with an API key |
+| `rb init` | Scaffold a starter handler.py |
+| `rb deploy [SCRIPT]` | Deploy all @endpoint functions |
+| `rb run [ID] --input '{...}'` | Invoke over HTTP (sync by default) |
+| `rb jobs status ID JOB_ID` / `rb jobs cancel ID JOB_ID` | Job control |
+| `rb jobs list ID` / `rb jobs purge-queue ID` | Job listing + queue control |
+| `rb endpoint health [ID]` | Endpoint runtime state |
+| `rb endpoint list/get/delete/workers` | Endpoint management |

runbay-0.1.0/pyproject.toml

@@ -0,0 +1,21 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "runbay"
+version = "0.1.0"
+description = "RunBay SDK & CLI — deploy Python functions to serverless GPUs"
+requires-python = ">=3.9"
+dependencies = [
+    "requests>=2.31",
+    "click>=8.1",
+    "rich>=13.0",
+]
+
+[project.scripts]
+rb = "runbay.cli:main"
+runbay = "runbay.cli:main"
+
+[tool.setuptools.packages.find]
+include = ["runbay*"]

runbay-0.1.0/runbay/__init__.py

@@ -0,0 +1,46 @@
+"""RunBay SDK — deploy and call serverless GPU endpoints."""
+
+from .client import Endpoint, Job
+from .decorator import (
+    CpuGroup,
+    CpuInstanceType,
+    EndpointFunction,
+    GpuGroup,
+    asgi_app,
+    endpoint,
+    fastapi_endpoint,
+    web_server,
+)
+from .dict import Dict
+from .entrypoint import LocalEntrypoint, is_local, local_entrypoint
+from .environment import Environment
+from .exceptions import (
+    ApiError,
+    AuthError,
+    Error,
+    InsufficientBalanceError,
+    JobError,
+    NotFoundError,
+    RemoteError,
+    SandboxError,
+    TimeoutError,
+)
+from .queue import Queue
+from .retries import Retries
+from .sandbox import Sandbox, SandboxSnapshot, Tunnel
+from .schedule import Cron, Period
+from .secret import Secret
+from .volume import Volume
+from . import serverless
+
+__version__ = "0.1.0"
+__all__ = [
+    "endpoint", "asgi_app", "web_server", "fastapi_endpoint", "local_entrypoint", "LocalEntrypoint", "is_local",
+    "GpuGroup", "CpuGroup", "CpuInstanceType", "Cron", "Period", "Retries",
+    "EndpointFunction", "Endpoint", "Job", "Sandbox", "SandboxSnapshot", "Tunnel",
+    "Secret", "Volume", "Dict", "Queue", "Environment",
+    # exceptions
+    "Error", "ApiError", "AuthError", "NotFoundError", "InsufficientBalanceError",
+    "SandboxError", "JobError", "RemoteError", "TimeoutError",
+    "serverless",
+]

runbay-0.1.0/runbay/api.py

@@ -0,0 +1,384 @@
+"""Management API client (auth, endpoints CRUD, artifact upload)."""
+
+from typing import Any, Dict, List, Optional
+from urllib.parse import quote
+
+import requests
+
+from .config import get_api_url, get_auth_token
+# Re-exported so `from .api import ApiError` (and callers) keep working.
+from .exceptions import ApiError, api_error
+
+
+class ManagementClient:
+    def __init__(self, api_url: Optional[str] = None, token: Optional[str] = None):
+        self.api_url = (api_url or get_api_url()).rstrip("/")
+        self.token = token or get_auth_token()
+        self.session = requests.Session()
+        # explicit UA: proxies (e.g. Cloudflare) may block default python UAs
+        self.session.headers["User-Agent"] = "runbay-sdk/0.1.0"
+
+    def _headers(self, auth: bool = True) -> Dict[str, str]:
+        # requests sets Content-Type itself when json= is passed; sending it
+        # on body-less POSTs makes Fastify reject the empty body with a 400
+        headers: Dict[str, str] = {}
+        if auth:
+            if not self.token:
+                raise ApiError(401, "Not logged in — run 'rb login' or set RB_API_KEY")
+            headers["Authorization"] = f"Bearer {self.token}"
+        return headers
+
+    def _request(self, method: str, path: str, auth: bool = True, **kwargs) -> Any:
+        res = self.session.request(
+            method,
+            f"{self.api_url}{path}",
+            headers=self._headers(auth),
+            timeout=kwargs.pop("timeout", 60),
+            **kwargs,
+        )
+        if res.status_code >= 400:
+            try:
+                message = res.json().get("error", res.text)
+            except ValueError:
+                message = res.text
+            raise api_error(res.status_code, message)
+        return res.json() if res.text else {}
+
+    # ---- auth ----
+
+    def register(self, email: str, name: str, password: str) -> Dict[str, Any]:
+        return self._request(
+            "POST", "/user/register", auth=False,
+            json={"email": email, "name": name, "password": password},
+        )
+
+    def login(self, email: str, password: str) -> Dict[str, Any]:
+        return self._request(
+            "POST", "/user/login", auth=False, json={"email": email, "password": password}
+        )
+
+    def create_api_key(self, name: str = "default") -> Dict[str, Any]:
+        return self._request("POST", "/user/apikey", json={"name": name})
+
+    def me(self) -> Dict[str, Any]:
+        return self._request("GET", "/user/me")
+
+    def balance(self) -> Dict[str, Any]:
+        return self._request("GET", "/user/balance")
+
+    def usage(self, limit: int = 50) -> Dict[str, Any]:
+        return self._request("GET", "/user/usage", params={"limit": str(limit)})
+
+    def gpus(self) -> list:
+        """Merged compute catalog (GPU + CPU entries, each with a `kind` field).
+
+        Backend returns `{gpus: [...], cpus: [...]}`; we merge into one list so
+        callers reading `kind` stay backward compatible.
+        """
+        data = self._request("GET", "/api/gpus")
+        return [*data.get("gpus", []), *data.get("cpus", [])]
+
+    # ---- sandboxes ----
+
+    def create_sandbox(self, spec: Dict[str, Any]) -> Dict[str, Any]:
+        return self._request("POST", "/api/sandboxes", json=spec)["sandbox"]
+
+    def list_sandboxes(self, include_terminated: bool = False) -> list:
+        params = {"all": "true"} if include_terminated else {}
+        return self._request("GET", "/api/sandboxes", params=params)["sandboxes"]
+
+    def get_sandbox(self, sandbox_id: str) -> Dict[str, Any]:
+        return self._request("GET", f"/api/sandboxes/{sandbox_id}")["sandbox"]
+
+    def terminate_sandbox(self, sandbox_id: str) -> Dict[str, Any]:
+        return self._request("DELETE", f"/api/sandboxes/{sandbox_id}")
+
+    # ---- sandbox snapshots ----
+
+    def create_sandbox_snapshot(self, sandbox_id: str) -> Dict[str, Any]:
+        return self._request("POST", f"/api/sandboxes/{sandbox_id}/snapshot")["snapshot"]
+
+    def list_sandbox_snapshots(self, sandbox_id: Optional[str] = None) -> list:
+        params = {"sandboxId": sandbox_id} if sandbox_id else {}
+        return self._request("GET", "/api/sandbox-snapshots", params=params)["snapshots"]
+
+    def get_sandbox_snapshot(self, snapshot_id: str) -> Dict[str, Any]:
+        return self._request("GET", f"/api/sandbox-snapshots/{snapshot_id}")["snapshot"]
+
+    def delete_sandbox_snapshot(self, snapshot_id: str) -> Dict[str, Any]:
+        return self._request("DELETE", f"/api/sandbox-snapshots/{snapshot_id}")
+
+    # ---- endpoints ----
+
+    def create_endpoint(self, spec: Dict[str, Any]) -> Dict[str, Any]:
+        return self._request("POST", "/api/endpoints", json=spec)["endpoint"]
+
+    def list_endpoints(self, environment: Optional[str] = None) -> list:
+        params = {"environment": environment} if environment else {}
+        return self._request("GET", "/api/endpoints", params=params)["endpoints"]
+
+    # ---- environments ----
+
+    def list_environments(self) -> list:
+        return self._request("GET", "/api/environments")["environments"]
+
+    def create_environment(self, name: str, web_suffix: str = "") -> Dict[str, Any]:
+        body: Dict[str, Any] = {"name": name}
+        if web_suffix:
+            body["webSuffix"] = web_suffix
+        return self._request("POST", "/api/environments", json=body)["environment"]
+
+    def update_environment(
+        self,
+        name: str,
+        set_name: Optional[str] = None,
+        set_web_suffix: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        body: Dict[str, Any] = {}
+        if set_name is not None:
+            body["setName"] = set_name
+        if set_web_suffix is not None:
+            body["setWebSuffix"] = set_web_suffix
+        if not body:
+            raise ValueError("update_environment requires set_name or set_web_suffix")
+        return self._request("PATCH", f"/api/environments/{name}", json=body)["environment"]
+
+    def delete_environment(self, name: str) -> Dict[str, Any]:
+        return self._request("DELETE", f"/api/environments/{name}")
+
+    def storage(self) -> Dict[str, Any]:
+        return self._request("GET", "/user/storage")["storage"]
+
+    def get_endpoint(self, endpoint_id: str) -> Dict[str, Any]:
+        return self._request("GET", f"/api/endpoints/{endpoint_id}")["endpoint"]
+
+    def update_endpoint(self, endpoint_id: str, spec: Dict[str, Any]) -> Dict[str, Any]:
+        return self._request("PATCH", f"/api/endpoints/{endpoint_id}", json=spec)["endpoint"]
+
+    def delete_endpoint(self, endpoint_id: str) -> Dict[str, Any]:
+        return self._request("DELETE", f"/api/endpoints/{endpoint_id}")
+
+    def list_jobs(self, endpoint_id: str, status: Optional[str] = None, limit: int = 50) -> list:
+        params = {"limit": str(limit)}
+        if status:
+            params["status"] = status
+        return self._request("GET", f"/api/endpoints/{endpoint_id}/jobs", params=params)["jobs"]
+
+    def list_workers(self, endpoint_id: str) -> list:
+        return self._request("GET", f"/api/endpoints/{endpoint_id}/workers")["workers"]
+
+    # ---- volumes ----
+
+    def create_volume(self, name: str, environment: Optional[str] = None) -> Dict[str, Any]:
+        body: Dict[str, Any] = {"name": name}
+        if environment is not None:
+            body["environment"] = environment
+        return self._request("POST", "/api/volumes", json=body)["volume"]
+
+    def list_volumes(self, environment: Optional[str] = None) -> list:
+        params = {"environment": environment} if environment else {}
+        return self._request("GET", "/api/volumes", params=params)["volumes"]
+
+    def get_volume(self, name: str, environment: Optional[str] = None) -> Dict[str, Any]:
+        params = {"environment": environment} if environment else {}
+        return self._request("GET", f"/api/volumes/{name}", params=params)["volume"]
+
+    def delete_volume(self, name: str, environment: Optional[str] = None) -> Dict[str, Any]:
+        params = {"environment": environment} if environment else {}
+        return self._request("DELETE", f"/api/volumes/{name}", params=params)
+
+    def rename_volume(self, old_name: str, new_name: str, environment: Optional[str] = None) -> Dict[str, Any]:
+        params = {"environment": environment} if environment else {}
+        return self._request("PATCH", f"/api/volumes/{old_name}", params=params, json={"name": new_name})["volume"]
+
+    def list_volume_files(self, name: str, prefix: str = "", environment: Optional[str] = None) -> list:
+        params: Dict[str, str] = {}
+        if prefix:
+            params["prefix"] = prefix
+        if environment is not None:
+            params["environment"] = environment
+        return self._request("GET", f"/api/volumes/{name}/files", params=params)["files"]
+
+    def delete_volume_path(self, name: str, path: str, recursive: bool = False, environment: Optional[str] = None) -> Dict[str, Any]:
+        params = {"environment": environment} if environment else {}
+        return self._request("DELETE", f"/api/volumes/{name}/files", params=params, json={"path": path, "recursive": recursive})
+
+    def get_volume_upload_url(self, name: str, path: str, environment: Optional[str] = None) -> Dict[str, Any]:
+        params = {"environment": environment} if environment else {}
+        return self._request("POST", f"/api/volumes/{name}/upload-url", params=params, json={"path": path})
+
+    def get_volume_download_url(self, name: str, path: str, environment: Optional[str] = None) -> Dict[str, Any]:
+        params = {"environment": environment} if environment else {}
+        return self._request("POST", f"/api/volumes/{name}/download-url", params=params, json={"path": path})
+
+    # ---- dicts ----
+
+    def create_dict(self, name: str, environment: Optional[str] = None) -> Dict[str, Any]:
+        body: Dict[str, Any] = {"name": name}
+        if environment is not None:
+            body["environment"] = environment
+        return self._request("POST", "/api/dicts", json=body)["dict"]
+
+    def list_dicts(self, environment: Optional[str] = None) -> list:
+        params = {"environment": environment} if environment else {}
+        return self._request("GET", "/api/dicts", params=params)["dicts"]
+
+    def get_dict(self, name: str, environment: Optional[str] = None) -> Dict[str, Any]:
+        params = {"environment": environment} if environment else {}
+        return self._request("GET", f"/api/dicts/{name}", params=params)["dict"]
+
+    def rename_dict(self, old_name: str, new_name: str, environment: Optional[str] = None) -> Dict[str, Any]:
+        params = {"environment": environment} if environment else {}
+        return self._request("PATCH", f"/api/dicts/{old_name}", params=params, json={"name": new_name})["dict"]
+
+    def delete_dict(self, name: str, environment: Optional[str] = None) -> Dict[str, Any]:
+        params = {"environment": environment} if environment else {}
+        return self._request("DELETE", f"/api/dicts/{name}", params=params)
+
+    def list_dict_entries(
+        self, name: str, limit: int = 100, search: str = "", environment: Optional[str] = None
+    ) -> Dict[str, Any]:
+        params: Dict[str, str] = {"limit": str(limit)}
+        if search:
+            params["search"] = search
+        if environment is not None:
+            params["environment"] = environment
+        return self._request("GET", f"/api/dicts/{name}/entries", params=params)
+
+    def get_dict_entry(self, name: str, key: str, environment: Optional[str] = None) -> Dict[str, Any]:
+        params = {"environment": environment} if environment else {}
+        return self._request("GET", f"/api/dicts/{name}/entries/{quote(key, safe='')}", params=params)
+
+    def put_dict_entry(self, name: str, key: str, value: Any, environment: Optional[str] = None) -> Dict[str, Any]:
+        params = {"environment": environment} if environment else {}
+        return self._request(
+            "PUT", f"/api/dicts/{name}/entries/{quote(key, safe='')}", params=params, json={"value": value}
+        )
+
+    def put_dict_entries(self, name: str, entries: Dict[str, Any], environment: Optional[str] = None) -> Dict[str, Any]:
+        params = {"environment": environment} if environment else {}
+        return self._request("POST", f"/api/dicts/{name}/entries", params=params, json={"entries": entries})
+
+    def delete_dict_entry(self, name: str, key: str, environment: Optional[str] = None) -> Dict[str, Any]:
+        params = {"environment": environment} if environment else {}
+        return self._request("DELETE", f"/api/dicts/{name}/entries/{quote(key, safe='')}", params=params)
+
+    def clear_dict(self, name: str, environment: Optional[str] = None) -> Dict[str, Any]:
+        params = {"environment": environment} if environment else {}
+        return self._request("POST", f"/api/dicts/{name}/clear", params=params)
+
+    # ---- queues ----
+
+    def create_queue(self, name: str, environment: Optional[str] = None) -> Dict[str, Any]:
+        body: Dict[str, Any] = {"name": name}
+        if environment is not None:
+            body["environment"] = environment
+        return self._request("POST", "/api/queues", json=body)["queue"]
+
+    def list_queues(self, environment: Optional[str] = None) -> list:
+        params = {"environment": environment} if environment else {}
+        return self._request("GET", "/api/queues", params=params)["queues"]
+
+    def get_queue(self, name: str, environment: Optional[str] = None) -> Dict[str, Any]:
+        params = {"environment": environment} if environment else {}
+        return self._request("GET", f"/api/queues/{name}", params=params)["queue"]
+
+    def rename_queue(self, old_name: str, new_name: str, environment: Optional[str] = None) -> Dict[str, Any]:
+        params = {"environment": environment} if environment else {}
+        return self._request("PATCH", f"/api/queues/{old_name}", params=params, json={"name": new_name})["queue"]
+
+    def delete_queue(self, name: str, environment: Optional[str] = None) -> Dict[str, Any]:
+        params = {"environment": environment} if environment else {}
+        return self._request("DELETE", f"/api/queues/{name}", params=params)
+
+    def queue_put(self, name: str, items: List[Any], environment: Optional[str] = None) -> Dict[str, Any]:
+        params = {"environment": environment} if environment else {}
+        return self._request("POST", f"/api/queues/{name}/put", params=params, json={"items": items})
+
+    def queue_pop(self, name: str, n: int = 1, environment: Optional[str] = None) -> List[Any]:
+        params = {"environment": environment} if environment else {}
+        return self._request("POST", f"/api/queues/{name}/pop", params=params, json={"n": n})["items"]
+
+    def queue_peek(self, name: str, limit: int = 50, environment: Optional[str] = None) -> list:
+        params: Dict[str, str] = {"limit": str(limit)}
+        if environment is not None:
+            params["environment"] = environment
+        return self._request("GET", f"/api/queues/{name}/peek", params=params)["entries"]
+
+    def queue_len(self, name: str, environment: Optional[str] = None) -> int:
+        params = {"environment": environment} if environment else {}
+        return self._request("GET", f"/api/queues/{name}/len", params=params)["length"]
+
+    def clear_queue(self, name: str, environment: Optional[str] = None) -> Dict[str, Any]:
+        params = {"environment": environment} if environment else {}
+        return self._request("POST", f"/api/queues/{name}/clear", params=params)
+
+    # ---- secrets ----
+
+    def create_secret(self, name: str, values: Dict[str, str], environment: Optional[str] = None) -> Dict[str, Any]:
+        body: Dict[str, Any] = {"name": name, "values": values}
+        if environment is not None:
+            body["environment"] = environment
+        return self._request("POST", "/api/secrets", json=body)["secret"]
+
+    def list_secrets(self, environment: Optional[str] = None) -> list:
+        params = {"environment": environment} if environment else {}
+        return self._request("GET", "/api/secrets", params=params)["secrets"]
+
+    def get_secret(self, name: str, environment: Optional[str] = None) -> Dict[str, Any]:
+        params = {"environment": environment} if environment else {}
+        return self._request("GET", f"/api/secrets/{name}", params=params)["secret"]
+
+    def update_secret(
+        self,
+        name: str,
+        *,
+        new_name: Optional[str] = None,
+        values: Optional[Dict[str, str]] = None,
+        environment: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        body: Dict[str, Any] = {}
+        if new_name is not None:
+            body["name"] = new_name
+        if values is not None:
+            body["values"] = values
+        params = {"environment": environment} if environment else {}
+        return self._request("PATCH", f"/api/secrets/{name}", params=params, json=body)["secret"]
+
+    def delete_secret(self, name: str, environment: Optional[str] = None) -> Dict[str, Any]:
+        params = {"environment": environment} if environment else {}
+        return self._request("DELETE", f"/api/secrets/{name}", params=params)
+
+    # ---- deploy ----
+
+    def get_upload_url(self, endpoint_id: str) -> Dict[str, Any]:
+        return self._request("POST", f"/api/endpoints/{endpoint_id}/artifact/upload-url")
+
+    def upload_artifact(self, upload_url: str, bundle_path: str) -> None:
+        with open(bundle_path, "rb") as f:
+            res = requests.put(
+                upload_url, data=f, headers={"Content-Type": "application/gzip"}, timeout=600
+            )
+        if res.status_code >= 400:
+            raise ApiError(res.status_code, f"artifact upload failed: {res.text[:500]}")
+
+    def commit_artifact(
+        self,
+        endpoint_id: str,
+        key: str,
+        version: int,
+        handler: Optional[str] = None,
+        python: Optional[str] = None,
+        packages: Optional[List[Any]] = None,
+        files: Optional[List[Dict[str, Any]]] = None,
+    ) -> Dict[str, Any]:
+        body: Dict[str, Any] = {"key": key, "version": version}
+        if handler:
+            body["handler"] = handler
+        if python:
+            body["python"] = python
+        if packages is not None:
+            body["packages"] = packages
+        if files is not None:
+            body["files"] = files
+        return self._request("POST", f"/api/endpoints/{endpoint_id}/artifact/commit", json=body)

runbay-0.1.0/runbay/cli/__init__.py

@@ -0,0 +1,5 @@
+"""RunBay CLI (`rb`) — command package."""
+
+from .main import main
+
+__all__ = ["main"]

runbay-0.1.0/runbay/cli/__main__.py

@@ -0,0 +1,6 @@
+"""`python -m runbay.cli` entry point."""
+
+from .main import main
+
+if __name__ == "__main__":
+    main()

runbay-0.1.0/runbay/cli/commands/__init__.py

@@ -0,0 +1 @@
+"""CLI command modules (each owns its Click group/commands)."""

runbay-0.1.0/runbay/cli/commands/account.py

@@ -0,0 +1,94 @@
+"""Account commands: login, whoami, register(hidden), apikey(hidden)."""
+
+import getpass
+from typing import Any, Dict, Optional
+
+import click
+
+from ...api import ApiError, ManagementClient
+from ...config import save_credentials
+from ..utils.client import _browser_login, _client, _save_login
+from ..utils.output import _die, _print_json
+from ..utils.rich_help import RichCommand as _Cmd
+
+
+@click.command(cls=_Cmd)
+@click.argument("api_key", required=False)
+@click.option("--browser", "use_browser", is_flag=True, help="Authorize through the web console")
+@click.option("--api-url", default=None, help="Backend API URL (persisted)")
+def login(api_key: Optional[str], use_browser: bool, api_url: Optional[str]) -> None:
+    """Log in — through the browser (default) or with an API key.
+
+    rb login                 interactive: browser or paste an API key
+    rb login --browser       straight to browser authorization
+    rb login rb_...          use an existing API key
+    """
+    if api_key:
+        return _save_login(api_key, api_url)
+    if use_browser:
+        return _browser_login(api_url)
+
+    choice = click.prompt(
+        "how do you want to authenticate?\n  [1] browser (opens the web console)\n  [2] paste an API key\n",
+        type=click.Choice(["1", "2"]),
+        default="1",
+        show_choices=False,
+    )
+    if choice == "1":
+        return _browser_login(api_url)
+
+    api_key = getpass.getpass("API key (rb_...): ").strip()
+    if not api_key:
+        _die("an API key is required")
+    _save_login(api_key, api_url)
+
+
+@click.command(cls=_Cmd, hidden=True)
+@click.option("--email", prompt=True)
+@click.option("--name", prompt=True)
+@click.option("--api-url", default=None, help="Backend API URL (persisted)")
+def register(email: str, name: str, api_url: Optional[str]) -> None:
+    """Create an account and an initial API key."""
+    password = getpass.getpass("Password: ")
+    client = ManagementClient(api_url=api_url)
+    try:
+        data = client.register(email, name, password)
+        # mint the first API key with the fresh session and store it
+        session = ManagementClient(api_url=api_url, token=data["token"])
+        key = session.create_api_key("default")["apiKey"]
+    except ApiError as exc:
+        _die(str(exc))
+
+    creds: Dict[str, Any] = {"api_key": key, "email": email}
+    if api_url:
+        creds["api_url"] = api_url
+    save_credentials(creds)
+    click.secho(f"account created for {email}", fg="green")
+    click.echo(f"API key (default): {key}")
+    click.secho("store it now — it cannot be retrieved again (saved to ~/.runbay)", fg="yellow")
+
+
+@click.command(cls=_Cmd, hidden=True)
+@click.option("--name", default="default", help="Label for the key")
+@click.option("--save/--no-save", default=True, help="Store the key in ~/.runbay")
+def apikey(name: str, save: bool) -> None:
+    """Create a new API key."""
+    try:
+        data = _client().create_api_key(name)
+    except ApiError as exc:
+        _die(str(exc))
+    click.echo(f"API key ({name}): {data['apiKey']}")
+    click.secho("store it now — it cannot be retrieved again", fg="yellow")
+    if save:
+        save_credentials({"api_key": data["apiKey"]})
+        click.echo("saved to ~/.runbay/config.json (used for future CLI/SDK calls)")
+
+
+@click.command(cls=_Cmd)
+def whoami() -> None:
+    """Show the logged-in account."""
+    try:
+        data = _client().me()
+    except ApiError as exc:
+        _die(str(exc))
+    _print_json(data)