envloop-cli 0.1.0__py3-none-any.whl → 0.2.0__py3-none-any.whl

envloop/__init__.py

@@ -0,0 +1,5 @@
+"""EnvLoop Python client."""
+
+from .client import Client
+
+__all__ = ["Client"]

envloop/agent_runs.py

@@ -0,0 +1,208 @@
+"""Agent runs: a read-only view of Train Jobs grouped by their agent's run label.
+
+The platform stores no run object. Agents tag every Train Job they create with
+``user_metadata`` (the RSI loop: ``rsi_run``, ``rsi_round``, ``rsi_checkpoint``...);
+this module pages through ``GET /v1/train/jobs`` and derives runs from those tags,
+using the same rules as the Console's agent runs page.
+"""
+
+from datetime import datetime
+
+from .train import TrainJobs
+
+# The generic ``agent_*`` key wins over the RSI loop's ``rsi_*`` one (the Console's rule).
+KEYS = {
+    "run": ("agent_run", "rsi_run"),
+    "round": ("agent_round", "rsi_round"),
+    "purpose": ("agent_purpose", "rsi_purpose"),
+    "method": ("agent_method", "rsi_method"),
+    "checkpoint": ("agent_checkpoint", "rsi_checkpoint"),
+}
+RUN_KEYS = KEYS["run"]  # first non-empty string wins
+ACTIVE_STATUSES = frozenset({"LAUNCHING", "STARTING", "RUNNING", "RECOVERING"})
+TERMINAL_STATUSES = frozenset({"SUCCEEDED", "FAILED", "CANCELLED"})
+PAGE_LIMIT = 100  # the platform's maximum page size
+
+
+class AgentRunError(RuntimeError):
+    """A run lookup or listing failed; ``code`` is safe to print."""
+
+    def __init__(self, code: str) -> None:
+        self.code = code
+        super().__init__(code)
+
+
+def _metadata(job) -> dict:
+    metadata = job.get("user_metadata")
+    return metadata if isinstance(metadata, dict) else {}
+
+
+def _field(job, name: str):
+    metadata = _metadata(job)
+    for key in KEYS[name]:
+        value = metadata.get(key)
+        if value is not None and value != "":
+            return value
+    return None
+
+
+def run_key(job) -> str | None:
+    """The run a Train Job belongs to, or None when it carries no run label."""
+    metadata = _metadata(job)
+    for key in RUN_KEYS:
+        value = metadata.get(key)
+        if isinstance(value, str) and value.strip():
+            return value
+    return None
+
+
+def _round(job) -> int | None:
+    value = _field(job, "round")
+    if isinstance(value, int) and not isinstance(value, bool):
+        return value
+    if isinstance(value, str):
+        try:
+            return int(value.strip())
+        except ValueError:
+            return None
+    return None
+
+
+def _order(job):
+    # Creation order, as the platform pages jobs (newest first, reversed here).
+    return (str(job.get("created_at") or ""), str(job.get("train_job_id") or ""))
+
+
+def _duration_sec(job) -> int | None:
+    if job.get("status") not in TERMINAL_STATUSES:
+        return None
+    try:
+        seconds = (datetime.fromisoformat(job["updated_at"])
+                   - datetime.fromisoformat(job["created_at"])).total_seconds()
+    except (KeyError, TypeError, ValueError):
+        return None
+    return round(seconds) if seconds >= 0 else None
+
+
+def _checkpoint(job) -> dict | None:
+    """The checkpoint a job produced: its agent's version name and platform path."""
+    stored = job.get("checkpoint")
+    path = stored.get("path") if isinstance(stored, dict) else None
+    name = _field(job, "checkpoint")
+    if not isinstance(path, str) or not path:
+        return None
+    return {"name": name, "path": path}
+
+
+def _job_view(job) -> dict:
+    metadata = _metadata(job)
+    return {
+        "train_job_id": job.get("train_job_id"),
+        "status": job.get("status"),
+        "round": _round(job),
+        "purpose": _field(job, "purpose"),
+        "method": _field(job, "method"),
+        "transitions": list(job.get("transitions") or []),
+        "created_at": job.get("created_at"),
+        "updated_at": job.get("updated_at"),
+        "duration_sec": _duration_sec(job),
+        "base_model": job.get("base_model"),
+        "lora_rank": job.get("lora_rank"),
+        "model_id": job.get("model_id"),
+        "checkpoint": _checkpoint(job),
+        "user_metadata": metadata,
+    }
+
+
+def _summary(run: str, jobs: list) -> dict:
+    """Summarize one run's jobs, given in creation order."""
+    latest = jobs[-1]
+    if any(job.get("status") in ACTIVE_STATUSES for job in jobs):
+        status = "running"
+    else:
+        status = str(latest.get("status") or "unknown").lower()
+    succeeded = [job for job in jobs if job.get("status") == "SUCCEEDED"]
+    latest_saved = next((job for job in reversed(jobs) if _checkpoint(job) is not None), None)
+    latest_checkpoint = _checkpoint(latest_saved) if latest_saved is not None else None
+    if latest_checkpoint is not None:
+        latest_checkpoint["train_job_id"] = latest_saved.get("train_job_id")
+    rounds = [number for number in map(_round, jobs) if number is not None]
+    activity = [stamp for job in jobs if isinstance(stamp := job.get("updated_at") or job.get("created_at"), str)]
+    return {
+        "run": run,
+        "agent": _metadata(latest).get("source"),
+        "status": status,
+        "latest_round": max(rounds, default=None),
+        "trainings": {"succeeded": len(succeeded), "total": len(jobs)},
+        "latest_checkpoint": latest_checkpoint,
+        "base_model": latest.get("base_model"),
+        "created_at": jobs[0].get("created_at"),
+        "updated_at": max(activity, default=None),
+    }
+
+
+def _detail(run: str, jobs: list) -> dict:
+    views = [_job_view(job) for job in jobs]
+    rounds: dict = {}
+    for view in views:
+        rounds.setdefault(view["round"], []).append(view)
+    ordered = sorted(rounds, key=lambda number: (number is None, number or 0))
+    checkpoints = [
+        {**view["checkpoint"], "round": view["round"], "train_job_id": view["train_job_id"],
+         "created_at": view["created_at"]}
+        for view in views if view["checkpoint"] is not None
+    ]
+    return {
+        **_summary(run, jobs),
+        "rounds": [{"round": number, "jobs": rounds[number]} for number in ordered],
+        "checkpoints": checkpoints,
+    }
+
+
+class AgentRuns:
+    """Read-only agent runs derived from the visible Train Jobs listing."""
+
+    def __init__(self, train_jobs: TrainJobs) -> None:
+        self._train_jobs = train_jobs
+
+    def _runs(self):
+        jobs, ids, seen, cursor, observed_at = [], set(), set(), None, None
+        while True:
+            page = self._train_jobs.list(cursor=cursor, limit=PAGE_LIMIT)
+            if observed_at is None:
+                observed_at = page.get("observed_at")
+            for job in page.get("items") or []:
+                job_id = job.get("train_job_id") if isinstance(job, dict) else None
+                if not isinstance(job, dict) or job_id in ids:
+                    continue
+                if job_id is not None:
+                    ids.add(job_id)
+                jobs.append(job)
+            cursor = page.get("next_cursor")
+            if cursor is None:
+                break
+            if cursor in seen:
+                raise AgentRunError("TRAIN_JOB_CURSOR_REPEATED")
+            seen.add(cursor)
+        runs: dict = {}
+        for job in jobs:
+            key = run_key(job)
+            if key is not None:
+                runs.setdefault(key, []).append(job)
+        for group in runs.values():
+            group.sort(key=_order)
+        return runs, observed_at
+
+    def list(self) -> dict:
+        """Every run, most recently updated first, as ``{"items": [...], "observed_at"}``."""
+        runs, observed_at = self._runs()
+        items = sorted((_summary(run, jobs) for run, jobs in runs.items()),
+                       key=lambda item: (item["updated_at"] or "", item["run"]), reverse=True)
+        return {"items": items, "observed_at": observed_at}
+
+    def get(self, run: str) -> dict:
+        """One run's summary, its rounds in order with their Train Jobs, and its checkpoints."""
+        runs, observed_at = self._runs()
+        if run not in runs:
+            raise AgentRunError("AGENT_RUN_NOT_FOUND")
+        return {**_detail(run, runs[run]), "observed_at": observed_at}

envloop/auth_cli.py

@@ -0,0 +1,285 @@
+"""Authentication configuration and browser login commands."""
+import argparse
+import json
+import os
+import sys
+
+from .config import ConfigError, ConfigStore, normalize_url, validate_key
+
+DEFAULT_BASE_URL = "https://api.envloop.ai"
+
+
+def add_auth_commands(groups):
+    auth = groups.add_parser("auth", help="Configure credentials, inspect status, or remove a saved key")
+    commands = auth.add_subparsers(dest="auth_command", required=True)
+    login = commands.add_parser("login", help="Open the Clerk sign-in page and authorize CLI/SDK access")
+    login.add_argument("--base-url", help="API Base URL; defaults to the effective connection or official API")
+    login.add_argument("--no-browser", action="store_true", help="Print the login link without opening a browser")
+    login.add_argument("--timeout", type=int, choices=range(1, 601), metavar="SECONDS", default=300,
+                       help="Wait up to 1–600 seconds (default: 300)")
+    configure = commands.add_parser("config", help="Save Base URL and API key for CLI and SDK")
+    configure.add_argument("--no-check", action="store_true", help="Save without API verification (offline; key remains unverified)")
+    actions = configure.add_subparsers(dest="config_action")
+    init = actions.add_parser("init", help="Configure interactively with masked API key input")
+    init.add_argument("--no-check", action="store_true", default=argparse.SUPPRESS, help="Save without API verification (offline)")
+    project = actions.add_parser("project", help="Select and verify a project with its own API key")
+    project.add_argument("project_id", nargs="?", help="Project ID; omit for an interactive list with names and IDs")
+    project.add_argument("--stdin", action="store_true", help="Read the selected project's API key from stdin")
+    setting = actions.add_parser("set", help="Save one field (API key is masked or read from stdin)")
+    setting.add_argument("field", choices=["base-url", "api-key", "workspace-id", "project-id"])
+    setting.add_argument("value", nargs="?", help=f"Base URL (default: {DEFAULT_BASE_URL}) or workspace ID; API keys use masked input or --stdin")
+    setting.add_argument("--stdin", action="store_true", help="Read a single API key from stdin")
+    setting.add_argument("--no-check", action="store_true", default=argparse.SUPPRESS, help="Save API key without verification (offline)")
+    getting = actions.add_parser("get", help="Read saved configuration; never export an API key")
+    getting.add_argument("field", choices=["base-url", "api-key", "workspace-id", "project-id"])
+    actions.add_parser("path", help="Print configuration and credential file paths")
+    show = actions.add_parser("show", help="Show saved and effective settings without revealing keys")
+    show.add_argument("--json", action="store_true")
+    remove = actions.add_parser("unset", help="Delete a saved field; does not revoke the server key")
+    remove.add_argument("field", choices=["base-url", "api-key", "workspace-id", "project-id"])
+    status = commands.add_parser("status", help="Inspect local credentials; --check verifies read access")
+    status.add_argument("--check", action="store_true", help="Make a read-only request to the effective Base URL")
+    status.add_argument("--json", action="store_true")
+    commands.add_parser("logout", help="Remove the saved key for the stored default Base URL (local only)")
+    workspace = commands.add_parser("workspace", help="Select and verify the active workspace")
+    workspace.add_argument("workspace_id", nargs="?", help="Workspace ID; omit for an interactive list")
+    workspace.add_argument("--project-id", help="Project within the workspace; its own API key is required")
+    workspace.add_argument("--stdin", action="store_true", help="Read the selected workspace's API key from stdin")
+
+
+def _key_from_input(stdin=False):
+    if stdin:
+        value = sys.stdin.read(515)
+        if value.endswith("\r\n"):
+            value = value[:-2]
+        elif value.endswith("\n"):
+            value = value[:-1]
+        return value
+    if not sys.stdin.isatty():
+        raise ConfigError("AUTH_INTERACTIVE_REQUIRED")
+    return _masked_key()
+
+
+def _masked_key():
+    if os.name != "posix":
+        raise ConfigError("CONFIG_STORAGE_UNSUPPORTED")
+    import termios
+
+    descriptor = sys.stdin.fileno()
+    original = termios.tcgetattr(descriptor)
+    masked = original[:]
+    masked[6] = original[6][:]
+    masked[3] &= ~(termios.ECHO | termios.ICANON | termios.ISIG | termios.IEXTEN)
+    masked[6][termios.VMIN] = 1
+    masked[6][termios.VTIME] = 0
+    characters = []
+    try:
+        termios.tcsetattr(descriptor, termios.TCSAFLUSH, masked)
+        sys.stderr.write("API key: ")
+        sys.stderr.flush()
+        while True:
+            character = sys.stdin.read(1)
+            if character in {"", "\x04"}:
+                raise EOFError
+            if character == "\x03":
+                raise KeyboardInterrupt
+            if character in {"\r", "\n"}:
+                return "".join(characters)
+            if character in {"\x08", "\x7f"}:
+                if characters:
+                    characters.pop()
+                    sys.stderr.write("\b \b")
+            elif character == "\x15":
+                sys.stderr.write("\b \b" * len(characters))
+                characters.clear()
+            else:
+                characters.append(character)
+                sys.stderr.write("*")
+            sys.stderr.flush()
+    finally:
+        termios.tcsetattr(descriptor, termios.TCSAFLUSH, original)
+        sys.stderr.write("\n")
+        sys.stderr.flush()
+
+
+def _report(args, store):
+    saved, configured = store.inspect()
+    from .cli import resolve_cli_connection
+
+    connection = resolve_cli_connection()
+    return {
+        "saved": {**saved, "api_key": "configured" if configured else "missing"},
+        "effective": {"api_url": connection.api_url, "workspace_id": connection.workspace_id, "project_id": connection.project_id,
+                      "api_key": "configured" if connection.api_key is not None else "missing"},
+        "sources": connection.sources,
+        "check": "not_checked",
+    }, connection
+
+
+def _verify_key(url, key, workspace_id=None, project_id=None):
+    from .http import HttpService, RemoteError
+
+    validate_key(key)
+    print("Checking API key...", flush=True)
+    if workspace_id is not None:
+        from .auth_workspace import _identity
+
+        scope = _identity(url, key, workspace_id, project_id, details=True)
+        return scope if scope.get('project_id') is not None else None
+    try:
+        response = HttpService(url, timeout=5, api_key=key, project_id=project_id, config=False,
+                               environment=False).request("GET", "/v1/me")
+    except RemoteError as error:
+        code = {401: "AUTHENTICATION_REJECTED", 403: "AUTHORIZATION_DENIED"}.get(error.status_code)
+        if code is None:
+            code = error.code if error.status_code is None and error.code in {
+                "NETWORK_ERROR", "INVALID_RESPONSE", "RESPONSE_TOO_LARGE",
+            } else "HTTP_ERROR"
+        raise ConfigError(code) from None
+    if not isinstance(response, dict) or response.get("auth_method") != "api_key":
+        raise ConfigError("AUTH_CHECK_UNCONFIRMED")
+    if response.get('project') is not None or project_id is not None:
+        from .auth_workspace import _scope
+
+        return _scope(response, project=project_id)
+
+
+def _print(report, as_json=False):
+    if as_json:
+        print(json.dumps(report, ensure_ascii=False))
+        return
+    print(f"Base URL: {report['effective']['api_url'] or 'not configured'}")
+    print(f"API key: {report['effective']['api_key']} (source: {report['sources']['api_key'] or 'none'})")
+    print(f"Workspace: {report['effective']['workspace_id'] or 'server default'}")
+    print(f"Project: {report['effective']['project_id'] or 'key scope'}")
+    print(f"Saved Base URL: {report['saved'].get('api_url') or 'not configured'}")
+    print(f"Saved API key: {report['saved']['api_key']}")
+    print(f"Saved workspace: {report['saved'].get('workspace_id') or 'server default'}")
+    print(f"Saved project: {report['saved'].get('project_id') or 'key scope'}")
+    print(f"Check: {report['check']}")
+
+
+def run_auth(args, parser):
+    store = ConfigStore()
+    command = args.auth_command
+    if command == "login":
+        from .auth_login import login
+
+        return login(args, store)
+    if command == "workspace":
+        from .auth_workspace import configure_workspace
+
+        return configure_workspace(args, store)
+    action = getattr(args, "config_action", None)
+    no_check = getattr(args, "no_check", False)
+    if getattr(args, "field", None) == "base-url":
+        args.field = "api-url"
+    if no_check and not (action in {None, "init"} or action == "set" and args.field == "api-key"):
+        parser.error("--no-check applies only to the wizard or set api-key")
+    if command == "config":
+        if action == "project":
+            from .auth_workspace import configure_project
+
+            return configure_project(args, store)
+        if action == "path":
+            print(json.dumps({"home": str(store.path), "config": str(store.path / "config.toml"), "auth": str(store.path / "auth.json")}))
+            return 0
+        if action == "set":
+            scope = None
+            if args.field == "api-key":
+                if args.value is not None:
+                    parser.error("API key values must be entered interactively or through --stdin")
+                value = _key_from_input(args.stdin)
+                validate_key(value)
+                saved, credential = store.workspace_snapshot()
+                url = saved.get("api_url")
+                if url is None:
+                    raise ConfigError("API_URL_REQUIRED")
+                if not no_check:
+                    scope = _verify_key(url, value, saved.get("workspace_id"), saved.get("project_id"))
+            elif args.field == "api-url":
+                if args.stdin:
+                    parser.error("this field does not support --stdin")
+                value = args.value if args.value is not None else DEFAULT_BASE_URL
+            else:
+                if args.value is None or args.stdin:
+                    parser.error("this field requires a value and does not support --stdin")
+                value = args.value
+            if args.field == "api-key":
+                if scope is not None:
+                    store.configure(url, value, expected_saved=saved, expected_credential=credential, scope=scope)
+                else:
+                    store.update(args.field, value, expected_url=url, expected_saved=saved, expected_credential=credential)
+            else:
+                store.update(args.field, value)
+            if args.field == "api-key":
+                print("Saved. API key check: " + ("not_checked (offline)" if no_check else "authentication_confirmed"))
+            else:
+                print("Saved.")
+            print("Environment variables override saved configuration.")
+            return 0
+        if action == "unset":
+            store.update(args.field, remove=True)
+            print("Saved value removed locally. Server keys are not revoked; environment variables still apply.")
+            if "ENVLOOP_API_KEY" in os.environ:
+                print("ENVLOOP_API_KEY still overrides saved credentials.")
+            return 0
+        if action == "get":
+            saved, configured = store.inspect()
+            value = ("configured" if configured else "missing") if args.field == "api-key" else saved.get(args.field.replace("-", "_"))
+            if value is not None:
+                print(value)
+            return 0
+        if action is None or action == "init":
+            if not sys.stdin.isatty():
+                raise ConfigError("AUTH_INTERACTIVE_REQUIRED")
+            saved, credential = store.workspace_snapshot(DEFAULT_BASE_URL)
+            default = saved.get("api_url", DEFAULT_BASE_URL)
+            url = normalize_url(default)
+            print(f"Base URL: {url}")
+            key = _key_from_input()
+            key = key or store.credential(url, saved.get("workspace_id"), saved.get("project_id"))
+            if key is None:
+                raise ConfigError("API_KEY_REQUIRED")
+            store.inspect()
+            scope = None if no_check else _verify_key(url, key, saved.get("workspace_id"), saved.get("project_id"))
+            remembered = None
+            if scope is not None:
+                from .auth_workspace import select_project
+
+                remembered = (scope["workspace_id"], scope["project_id"], key)
+                key, scope = select_project(url, key, scope, credential.get("project_keys", {}))
+            store.configure(url, key, expected_saved=saved, expected_credential=credential,
+                            scope=scope, remembered=remembered)
+            print(f"Saved configuration in {store.path}. Environment variables override saved configuration.")
+            print("Saved key check: " + ("not_checked (offline)" if no_check else "authentication_confirmed"))
+            report, connection = _report(args, store)
+            if not no_check and connection.api_url == url and connection.api_key == key:
+                report["check"] = "authentication_confirmed"
+            _print(report)
+            return 0
+    if command == "logout":
+        store.update("api-key", remove=True)
+        print("Saved default API key removed locally. The server key has not been revoked.")
+        if "ENVLOOP_API_KEY" in os.environ:
+            print("ENVLOOP_API_KEY remains active; unset it separately.")
+        return 0
+    report, connection = _report(args, store)
+    if command == "status":
+        if args.check:
+            from .config import require_remote
+            from .http import HttpService, RemoteError
+
+            try:
+                require_remote(connection)
+                HttpService(connection.api_url, api_key=connection.api_key,
+                            workspace_id=connection.workspace_id, project_id=connection.project_id,
+                            config=False, environment=False).list_jobs(limit=1)
+                report["check"] = "access_confirmed" if connection.api_key else "reachable_anonymous"
+            except (ConfigError, RemoteError) as error:
+                report["check"] = {401: "authentication_rejected", 403: "authorization_denied"}.get(
+                    getattr(error, "status_code", None), error.code)
+                _print(report, args.json)
+                return 1
+    _print(report, getattr(args, "json", False))
+    return 0

envloop/auth_login.py

@@ -0,0 +1,127 @@
+"""Browser authorization using a CLI-owned key and bounded anonymous polling."""
+import hashlib
+import json
+import secrets
+import time
+import webbrowser
+from http.client import InvalidURL
+from urllib.error import HTTPError, URLError
+from urllib.parse import parse_qs, urlsplit
+from urllib.request import ProxyHandler, Request, build_opener
+
+from .auth_workspace import _identity
+from .config import ConfigError, normalize_url
+from .http import NoRedirect
+
+
+def _request(url, action, body, timeout):
+    request = Request(url + '/v1/auth/cli/' + action, data=json.dumps(body).encode(),
+                      headers={'Content-Type': 'application/json'}, method='POST')
+    try:
+        with build_opener(ProxyHandler(), NoRedirect()).open(request, timeout=timeout) as response:
+            raw = response.read(8193)
+            if len(raw) > 8192:
+                raise ConfigError('AUTH_LOGIN_INVALID_RESPONSE')
+            result = json.loads(raw)
+            if not isinstance(result, dict):
+                raise ConfigError('AUTH_LOGIN_INVALID_RESPONSE')
+            return result
+    except HTTPError as error:
+        code = {403: 'AUTHORIZATION_DENIED', 409: 'AUTH_LOGIN_UNAVAILABLE', 410: 'AUTH_LOGIN_EXPIRED',
+                429: 'AUTH_LOGIN_BUSY', 503: 'AUTH_LOGIN_UNAVAILABLE'}.get(error.code, 'AUTH_LOGIN_HTTP_ERROR')
+        raise ConfigError(code) from None
+    except (URLError, TimeoutError, OSError, InvalidURL):
+        raise ConfigError('NETWORK_ERROR') from None
+    except (ValueError, UnicodeError):
+        raise ConfigError('AUTH_LOGIN_INVALID_RESPONSE') from None
+
+
+def _verification_url(url, response):
+    import re
+
+    identifier = response.get('grant_id')
+    uri = response.get('verification_uri')
+    if not isinstance(identifier, str) or not re.fullmatch(r'[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}', identifier):
+        raise ConfigError('AUTH_LOGIN_INVALID_RESPONSE')
+    if not isinstance(uri, str):
+        raise ConfigError('AUTH_LOGIN_INVALID_RESPONSE')
+    try:
+        page, api = urlsplit(uri), urlsplit(url)
+        normalized = normalize_url(f'{page.scheme}://{page.netloc}')
+        expected = 'https://console.envloop.ai' if url == 'https://api.envloop.ai' else f'{api.scheme}://{api.netloc}'
+        if (f'{page.scheme}://{page.netloc}' != expected or page.path != '/sign-in' or page.fragment or
+                parse_qs(page.query, strict_parsing=True) != {'cli_login': [identifier]} or
+                normalized != expected):
+            raise ConfigError('AUTH_LOGIN_INVALID_RESPONSE')
+    except (ValueError, ConfigError):
+        raise ConfigError('AUTH_LOGIN_INVALID_RESPONSE') from None
+    return identifier, uri
+
+
+def login(args, store):
+    from .auth_cli import DEFAULT_BASE_URL
+    from .cli import resolve_cli_connection
+
+    saved, credential = store.workspace_snapshot()
+    url = normalize_url(args.base_url or resolve_cli_connection().api_url or DEFAULT_BASE_URL)
+    deadline = time.monotonic() + args.timeout
+    key, poll_token = 'epk_' + secrets.token_hex(32), secrets.token_urlsafe(32)
+    code = ''.join(secrets.choice('ABCDEFGHJKLMNPQRSTUVWXYZ23456789') for _ in range(8))
+    def digest(value):
+        return hashlib.sha256(value.encode()).hexdigest()
+    response = _request(url, 'start', {'key_hash': digest(key), 'poll_hash': digest(poll_token),
+                                    'code_hash': digest(code)}, min(5, args.timeout))
+    identifier, uri = _verification_url(url, response)
+    interval, expires = response.get('interval'), response.get('expires_in')
+    if (isinstance(interval, bool) or not isinstance(interval, (int, float)) or not 0 < interval <= 10 or
+            isinstance(expires, bool) or not isinstance(expires, int) or not 1 <= expires <= 600):
+        raise ConfigError('AUTH_LOGIN_INVALID_RESPONSE')
+    deadline = min(deadline, time.monotonic() + expires)
+    body = {'grant_id': identifier, 'poll_token': poll_token}
+    saved_successfully = False
+    try:
+        print(f'Base URL: {url}\nConfirmation code: {code}\nOpen: {uri}', flush=True)
+        print('Sign in with Clerk, enter this code, and authorize your workspace/project.', flush=True)
+        if not args.no_browser:
+            try:
+                opened = webbrowser.open(uri, new=1)
+            except webbrowser.Error:
+                opened = False
+            if not opened:
+                print('Browser could not be opened. Copy the link above into your browser.', flush=True)
+        while True:
+            remaining = deadline - time.monotonic()
+            if remaining <= 0:
+                raise ConfigError('AUTH_LOGIN_TIMEOUT')
+            try:
+                result = _request(url, 'poll', body, min(5, remaining))
+            except ConfigError as error:
+                if error.code != 'NETWORK_ERROR':
+                    raise
+                # The server returns the same non-secret receipt after a lost
+                # response, while inserting the credential only once.
+                time.sleep(min(interval, max(0, deadline - time.monotonic())))
+                continue
+            if result.get('status') == 'approved':
+                # Verify the exact scope before committing the saved connection.
+                scope = _identity(url, key, result.get('workspace_id'), result.get('project_id'), details=True)
+                if (not result.get('workspace_id') or not result.get('project_id') or
+                        scope.get('project_id') != result['project_id']):
+                    raise ConfigError('AUTH_LOGIN_INVALID_RESPONSE')
+                store.configure(url, key, expected_saved=saved,
+                                expected_credential=credential if saved.get('api_url') == url else None, scope=scope)
+                saved_successfully = True
+                print('Signed in. Verified project credentials saved for CLI and SDK (expires in 30 days).')
+                print('Environment variables override saved configuration. auth logout removes local credentials only.')
+                return 0
+            if result.get('status') in {'denied', 'cancelled'}:
+                raise ConfigError('AUTH_LOGIN_DENIED')
+            if result.get('status') != 'pending':
+                raise ConfigError('AUTH_LOGIN_INVALID_RESPONSE')
+            time.sleep(min(interval, max(0, deadline - time.monotonic())))
+    finally:
+        if not saved_successfully:
+            try:
+                _request(url, 'cancel', body, 2)
+            except ConfigError:
+                pass