bilinc 2.2.0__tar.gz → 2.3.1__tar.gz

{bilinc-2.2.0/src/bilinc.egg-info → bilinc-2.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: bilinc
-Version: 2.2.0
+Version: 2.3.1
 Summary: Cloud-only memory SDK and MCP adapter for autonomous agents
 Author: Bilinc Team
 License-Expression: BUSL-1.1
@@ -56,7 +56,7 @@ Dynamic: license-file
 
 Retrieval answers *"what is similar to this?"*. Long-running agents also need to answer *"who wrote this state, was it verified, did it contradict what we already knew, and can we undo it?"* — that is the layer Bilinc provides.
 
-Bilinc 2.2.0 on PyPI is the public cloud-only package: a thin Python SDK, CLI, and MCP adapter for Bilinc Cloud. It does not ship the local StatePlane, storage backends, eval, observability, integrations, or server runtime internals.
+Bilinc 2.3.1 on PyPI is the public cloud-only package: a thin Python SDK, CLI, and MCP adapter for Bilinc Cloud. It does not ship the local StatePlane, storage backends, eval, observability, integrations, or server runtime internals.
 
 > **Frozen regression receipt** — LongMemEval-s cleaned retrieval fixture, 500 questions: **Hit@5 98.0%**, **NDCG@5 0.913**, no LLM reranker, no paid API. This is an isolated retrieval guardrail, not a current hosted SLA, end-to-end agent score, or competitor ranking — see [Benchmark receipt](#benchmark-receipt) for the full scope and qualification.
 
@@ -102,31 +102,28 @@ storage runtime.
 
 ```bash
 pip install -U bilinc
-bilinc start
+bilinc login
+bilinc quicktest
 ```
 
-`bilinc start` is the first-run guide. The activation target is simple: reach a
-passing `bilinc quicktest`, which performs one hosted commit, one hosted recall,
-and one Cloud status check.
-
-1. Start the 7-day Bilinc Cloud trial at https://bilinc.space/signup.
-2. Confirm email.
-3. Create one hosted API key in the Cloud dashboard.
-4. Connect the CLI:
+`bilinc login` opens your browser. Sign in with Google, GitHub, or email (free,
+no card required) and approve this computer; the CLI saves its own API key with
+owner-only permissions. The key never appears in a URL or your terminal.
+`bilinc quicktest` then performs one hosted commit, one hosted recall, and one
+Cloud status check.
 
-```bash
-bilinc login --api-key bil_live_...
-bilinc quicktest
-```
+- **No browser on this machine** (SSH, servers, containers): `bilinc login --device`
+  prints a short code to approve from any browser.
+- **CI and scripts:** `bilinc login --api-key bil_live_...`, or set `BILINC_API_KEY`.
 
 To reproduce this release exactly:
 
 ```bash
-pip install -U bilinc==2.2.0
+pip install -U bilinc==2.3.1
 ```
 
 If you prefer a browser guide, open https://bilinc.space/install and follow the
-same four-step path.
+same three-step path.
 
 ## MCP Adapter
 
@@ -134,18 +131,28 @@ Bilinc exposes a standard Model Context Protocol server over **stdio**, so any
 MCP-compatible client can connect — Claude Code, Codex, Cursor, Hermes-Agent,
 opencode, and others.
 
+After `bilinc login`, let the CLI write the setup for your client:
+
+```bash
+bilinc mcp install --client claude-code     # prints a ready `claude mcp add ...` command
+bilinc mcp install --client claude-desktop  # prints the config and where Claude Desktop keeps it
+bilinc mcp install                          # plain mcpServers JSON for any other client
+```
+
 ```json
 {
   "mcpServers": {
     "bilinc": {
-      "command": "python",
-      "args": ["-m", "bilinc.cloud_mcp"],
-      "env": { "BILINC_API_KEY": "bil_live_..." }
+      "command": "/path/to/python3",
+      "args": ["-m", "bilinc.cloud_mcp"]
     }
   }
 }
 ```
 
+`command` is the interpreter that has Bilinc installed, and the adapter reads the key saved by `bilinc login`, so
+the config carries no key. On a machine without a saved key, add `"env": { "BILINC_API_KEY": "bil_live_..." }`.
+
 Eight tools — the core memory lifecycle, and nothing else:
 
 | Tool | What it does |
@@ -227,10 +234,10 @@ bilinc rollback execute --snapshot snap_... --reason "undo bad agent run" \
 Useful first-run commands:
 
 ```bash
-bilinc start
-bilinc login --api-key bil_live_...
+bilinc login              # browser sign-in; --device without a browser
 bilinc quicktest
 bilinc mcp install
+bilinc start              # prints the first-run guide
 ```
 
 ## Hosted Endpoints

{bilinc-2.2.0 → bilinc-2.3.1}/README.md

@@ -14,7 +14,7 @@
 
 Retrieval answers *"what is similar to this?"*. Long-running agents also need to answer *"who wrote this state, was it verified, did it contradict what we already knew, and can we undo it?"* — that is the layer Bilinc provides.
 
-Bilinc 2.2.0 on PyPI is the public cloud-only package: a thin Python SDK, CLI, and MCP adapter for Bilinc Cloud. It does not ship the local StatePlane, storage backends, eval, observability, integrations, or server runtime internals.
+Bilinc 2.3.1 on PyPI is the public cloud-only package: a thin Python SDK, CLI, and MCP adapter for Bilinc Cloud. It does not ship the local StatePlane, storage backends, eval, observability, integrations, or server runtime internals.
 
 > **Frozen regression receipt** — LongMemEval-s cleaned retrieval fixture, 500 questions: **Hit@5 98.0%**, **NDCG@5 0.913**, no LLM reranker, no paid API. This is an isolated retrieval guardrail, not a current hosted SLA, end-to-end agent score, or competitor ranking — see [Benchmark receipt](#benchmark-receipt) for the full scope and qualification.
 
@@ -60,31 +60,28 @@ storage runtime.
 
 ```bash
 pip install -U bilinc
-bilinc start
+bilinc login
+bilinc quicktest
 ```
 
-`bilinc start` is the first-run guide. The activation target is simple: reach a
-passing `bilinc quicktest`, which performs one hosted commit, one hosted recall,
-and one Cloud status check.
-
-1. Start the 7-day Bilinc Cloud trial at https://bilinc.space/signup.
-2. Confirm email.
-3. Create one hosted API key in the Cloud dashboard.
-4. Connect the CLI:
+`bilinc login` opens your browser. Sign in with Google, GitHub, or email (free,
+no card required) and approve this computer; the CLI saves its own API key with
+owner-only permissions. The key never appears in a URL or your terminal.
+`bilinc quicktest` then performs one hosted commit, one hosted recall, and one
+Cloud status check.
 
-```bash
-bilinc login --api-key bil_live_...
-bilinc quicktest
-```
+- **No browser on this machine** (SSH, servers, containers): `bilinc login --device`
+  prints a short code to approve from any browser.
+- **CI and scripts:** `bilinc login --api-key bil_live_...`, or set `BILINC_API_KEY`.
 
 To reproduce this release exactly:
 
 ```bash
-pip install -U bilinc==2.2.0
+pip install -U bilinc==2.3.1
 ```
 
 If you prefer a browser guide, open https://bilinc.space/install and follow the
-same four-step path.
+same three-step path.
 
 ## MCP Adapter
 
@@ -92,18 +89,28 @@ Bilinc exposes a standard Model Context Protocol server over **stdio**, so any
 MCP-compatible client can connect — Claude Code, Codex, Cursor, Hermes-Agent,
 opencode, and others.
 
+After `bilinc login`, let the CLI write the setup for your client:
+
+```bash
+bilinc mcp install --client claude-code     # prints a ready `claude mcp add ...` command
+bilinc mcp install --client claude-desktop  # prints the config and where Claude Desktop keeps it
+bilinc mcp install                          # plain mcpServers JSON for any other client
+```
+
 ```json
 {
   "mcpServers": {
     "bilinc": {
-      "command": "python",
-      "args": ["-m", "bilinc.cloud_mcp"],
-      "env": { "BILINC_API_KEY": "bil_live_..." }
+      "command": "/path/to/python3",
+      "args": ["-m", "bilinc.cloud_mcp"]
     }
   }
 }
 ```
 
+`command` is the interpreter that has Bilinc installed, and the adapter reads the key saved by `bilinc login`, so
+the config carries no key. On a machine without a saved key, add `"env": { "BILINC_API_KEY": "bil_live_..." }`.
+
 Eight tools — the core memory lifecycle, and nothing else:
 
 | Tool | What it does |
@@ -185,10 +192,10 @@ bilinc rollback execute --snapshot snap_... --reason "undo bad agent run" \
 Useful first-run commands:
 
 ```bash
-bilinc start
-bilinc login --api-key bil_live_...
+bilinc login              # browser sign-in; --device without a browser
 bilinc quicktest
 bilinc mcp install
+bilinc start              # prints the first-run guide
 ```
 
 ## Hosted Endpoints

{bilinc-2.2.0 → bilinc-2.3.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "bilinc"
-version = "2.2.0"
+version = "2.3.1"
 description = "Cloud-only memory SDK and MCP adapter for autonomous agents"
 readme = "README.md"
 license = "BUSL-1.1"

{bilinc-2.2.0 → bilinc-2.3.1}/src/bilinc/__init__.py

@@ -1,4 +1,4 @@
-"""Bilinc 2.2.0: cloud-only SDK for agent memory."""
+"""Bilinc 2.3.1: cloud-only SDK for agent memory."""
 
 from bilinc.client import (
     ACTIVATION_SIGNUP_URL,
@@ -25,7 +25,7 @@ from bilinc.client import (
     CloudClient,
 )
 
-__version__ = "2.2.0"
+__version__ = "2.3.1"
 version = __version__
 
 __all__ = [

bilinc-2.3.1/src/bilinc/cli/login.py

@@ -0,0 +1,241 @@
+"""One-click ``bilinc login``.
+
+The default flow opens the browser and hands a one-time code back to a
+listener on ``127.0.0.1`` (an OAuth-style loopback redirect with PKCE, RFC 8252
+and RFC 7636). The CLI then exchanges that code, plus the PKCE verifier only it
+knows, for an API key it saves locally. Machines without a browser use a device
+code instead (RFC 8628): the CLI prints a short code, the user approves it in
+any browser, and the CLI polls until it is approved.
+
+The API key only ever travels in the body of an HTTPS response; it never
+appears in a URL, the browser, or a log line.
+"""
+
+from __future__ import annotations
+
+import base64
+import hashlib
+import html
+import http.server
+import json
+import os
+import re
+import secrets
+import socket
+import sys
+import time
+import urllib.parse
+import webbrowser
+from typing import Any, Callable, TextIO
+
+from bilinc.client import BilincCloudError, _default_transport
+
+LOOPBACK_TIMEOUT_SECONDS = 600
+CALLBACK_PATH = "/callback"
+_HOSTNAME_PATTERN = re.compile(r"^[A-Za-z0-9][A-Za-z0-9._-]{0,62}$")
+
+
+class LoginError(Exception):
+    """The sign-in did not complete; the message says what to do next."""
+
+
+def pkce_pair() -> tuple[str, str]:
+    """Return a PKCE (verifier, S256 challenge) pair."""
+
+    verifier = secrets.token_urlsafe(64)[:96]
+    digest = hashlib.sha256(verifier.encode("ascii")).digest()
+    challenge = base64.urlsafe_b64encode(digest).rstrip(b"=").decode("ascii")
+    return verifier, challenge
+
+
+def machine_name() -> str:
+    """A display name for this computer, shown on the approval page and in the key name."""
+
+    name = socket.gethostname().split(".")[0].strip()
+    return name if _HOSTNAME_PATTERN.match(name) else "bilinc-cli"
+
+
+def is_headless() -> bool:
+    """True when no local browser can be opened (SSH sessions, servers, containers)."""
+
+    has_display = bool(os.environ.get("DISPLAY") or os.environ.get("WAYLAND_DISPLAY"))
+    if os.environ.get("SSH_CONNECTION") or os.environ.get("SSH_TTY"):
+        return not has_display
+    if sys.platform.startswith("linux"):
+        return not has_display
+    return False
+
+
+def _post(
+    transport: Callable[..., dict[str, Any]],
+    base_url: str,
+    path: str,
+    payload: dict[str, Any],
+    timeout: float,
+) -> dict[str, Any]:
+    from bilinc import __version__
+
+    return transport(
+        "POST",
+        f"{base_url.rstrip('/')}{path}",
+        headers={
+            "Content-Type": "application/json",
+            "Accept": "application/json",
+            "User-Agent": f"bilinc-cli/{__version__}",
+        },
+        body=json.dumps(payload).encode("utf-8"),
+        timeout=timeout,
+    )
+
+
+_DONE_PAGE = """<!doctype html><html><head><meta charset="utf-8"><title>Bilinc CLI</title>
+<style>body{{background:#02040f;color:#e0f0ff;font:16px/1.5 ui-monospace,Menlo,monospace;
+display:grid;place-items:center;min-height:100vh;margin:0}}main{{max-width:34rem;padding:2rem}}
+h1{{color:#00f0ff;font-size:1.25rem}}</style></head><body><main><h1>{title}</h1><p>{body}</p></main></body></html>"""
+
+
+class _CallbackServer(http.server.HTTPServer):
+    result: dict[str, str] | None = None
+
+
+class _CallbackHandler(http.server.BaseHTTPRequestHandler):
+    server: _CallbackServer
+
+    def do_GET(self) -> None:  # noqa: N802 - http.server API
+        parsed = urllib.parse.urlsplit(self.path)
+        if parsed.path != CALLBACK_PATH:
+            self.send_error(404)
+            return
+        params = {key: values[0] for key, values in urllib.parse.parse_qs(parsed.query).items() if values}
+        if self.server.result is None:
+            self.server.result = params
+        if params.get("code"):
+            title, body = "Bilinc CLI is signed in", "You can close this tab and return to your terminal."
+        else:
+            title, body = "Sign-in was not completed", "Return to your terminal for details."
+        page = _DONE_PAGE.format(title=html.escape(title), body=html.escape(body)).encode("utf-8")
+        self.send_response(200)
+        self.send_header("Content-Type", "text/html; charset=utf-8")
+        self.send_header("Content-Length", str(len(page)))
+        self.send_header("Cache-Control", "no-store")
+        self.send_header("Referrer-Policy", "no-referrer")
+        self.end_headers()
+        self.wfile.write(page)
+
+    def log_message(self, format: str, *args: Any) -> None:  # noqa: A002 - http.server API
+        return
+
+
+def loopback_login(
+    base_url: str,
+    *,
+    timeout: float = 30.0,
+    open_browser: bool = True,
+    transport: Callable[..., dict[str, Any]] = _default_transport,
+    browser_open: Callable[[str], bool] = webbrowser.open,
+    stderr: TextIO = sys.stderr,
+    wait_seconds: float = LOOPBACK_TIMEOUT_SECONDS,
+    on_listening: Callable[[str], None] | None = None,
+) -> dict[str, Any]:
+    """Sign in through the browser and return the token response (``api_key``, ``key_name``)."""
+
+    verifier, challenge = pkce_pair()
+    state = secrets.token_urlsafe(24)
+    server = _CallbackServer(("127.0.0.1", 0), _CallbackHandler)
+    server.timeout = 0.5
+    try:
+        port = server.server_address[1]
+        query = urllib.parse.urlencode(
+            {
+                "port": port,
+                "state": state,
+                "code_challenge": challenge,
+                "code_challenge_method": "S256",
+                "hostname": machine_name(),
+            }
+        )
+        url = f"{base_url.rstrip('/')}/cli/authorize?{query}"
+        opened = False
+        if open_browser:
+            print("Opening your browser to sign in to Bilinc Cloud...", file=stderr)
+            try:
+                opened = bool(browser_open(url))
+            except Exception:  # noqa: BLE001 - any browser failure falls back to the printed URL
+                opened = False
+        if not opened:
+            print(f"Open this URL in a browser on this computer to continue:\n\n  {url}\n", file=stderr)
+        if on_listening is not None:
+            on_listening(url)
+
+        deadline = time.monotonic() + wait_seconds
+        while server.result is None and time.monotonic() < deadline:
+            server.handle_request()
+        result = server.result
+    finally:
+        server.server_close()
+
+    if result is None:
+        raise LoginError("Timed out waiting for the browser. Run bilinc login again, or bilinc login --device.")
+    if not secrets.compare_digest(result.get("state", ""), state):
+        raise LoginError("The browser returned an unexpected sign-in response. Run bilinc login again.")
+    if result.get("error"):
+        raise LoginError("Sign-in was denied in the browser.")
+    code = result.get("code")
+    if not code:
+        raise LoginError("The browser did not return a sign-in code. Run bilinc login again.")
+
+    try:
+        return _post(transport, base_url, "/api/cli/token", {"code": code, "code_verifier": verifier}, timeout)
+    except BilincCloudError as exc:
+        raise LoginError(_explain(exc)) from exc
+
+
+def device_login(
+    base_url: str,
+    *,
+    timeout: float = 30.0,
+    transport: Callable[..., dict[str, Any]] = _default_transport,
+    stderr: TextIO = sys.stderr,
+    sleep: Callable[[float], None] = time.sleep,
+    clock: Callable[[], float] = time.monotonic,
+) -> dict[str, Any]:
+    """Sign in with a code approved in any browser and return the token response."""
+
+    try:
+        start = _post(transport, base_url, "/api/cli/device/code", {"hostname": machine_name()}, timeout)
+    except BilincCloudError as exc:
+        raise LoginError(_explain(exc)) from exc
+
+    print(
+        "To sign in, open this page in any browser:\n\n"
+        f"  {start['verification_uri_complete']}\n\n"
+        f"and confirm the code {start['user_code']}. Waiting for approval...",
+        file=stderr,
+    )
+    interval = max(1, int(start.get("interval", 5)))
+    deadline = clock() + int(start.get("expires_in", 600))
+    while clock() < deadline:
+        sleep(interval)
+        try:
+            return _post(transport, base_url, "/api/cli/device/token", {"device_code": start["device_code"]}, timeout)
+        except BilincCloudError as exc:
+            if exc.code == "authorization_pending":
+                continue
+            if exc.code == "slow_down":
+                interval += 5
+                continue
+            raise LoginError(_explain(exc)) from exc
+    raise LoginError("The code expired before it was approved. Run bilinc login --device again.")
+
+
+def _explain(exc: BilincCloudError) -> str:
+    return {
+        "access_denied": "Sign-in was denied in the browser.",
+        "expired_token": "The code expired before it was approved. Run bilinc login again.",
+        "invalid_grant": "The sign-in code was already used or has expired. Run bilinc login again.",
+        "api_key_limit_reached": (
+            "Your plan has no free API key slot. Revoke an unused key at https://bilinc.space/api-keys, "
+            "then run bilinc login again."
+        ),
+        "rate_limited": "Too many sign-in attempts. Wait a few minutes and run bilinc login again.",
+    }.get(exc.code or "", f"Sign-in failed: {exc}")

{bilinc-2.2.0 → bilinc-2.3.1}/src/bilinc/cli/main.py

@@ -6,6 +6,8 @@ from __future__ import annotations
 import argparse
 import json
 import os
+import shlex
+import subprocess
 import sys
 import time
 import webbrowser
@@ -23,6 +25,7 @@ from bilinc.client import (
     load_config_api_key,
     save_config_api_key,
 )
+from bilinc.cli.login import LoginError, device_login, is_headless, loopback_login
 
 
 def _parse_value(value: str) -> Any:
@@ -47,14 +50,15 @@ def _has_key(args: argparse.Namespace) -> bool:
 def _print_start_guide(*, opened: bool = False) -> None:
     _print(
         {
-            "next": "Run the 60-second Bilinc Cloud activation path",
-            "goal": "Connect one hosted API key and finish with bilinc quicktest.",
+            "next": "Connect this computer to Bilinc Cloud",
+            "goal": "Sign in once from the terminal and finish with bilinc quicktest.",
             "steps": [
-                "1. Start the 7-day Cloud trial and confirm email",
-                "2. After confirmation, copy the first hosted API key from onboarding",
-                "3. Run: bilinc login --api-key <key>",
-                "4. Run: bilinc quicktest",
+                "1. Run: bilinc login  (opens your browser; sign in with Google, GitHub, or email)",
+                "2. Run: bilinc quicktest",
             ],
+            "no_browser_on_this_machine": "bilinc login --device",
+            "ci": "bilinc login --api-key <key>, or set BILINC_API_KEY",
+            "pricing": "Free, no card required",
             "signup": ACTIVATION_SIGNUP_URL,
             "install_guide": INSTALL_URL,
             "opened_browser": opened,
@@ -62,16 +66,38 @@ def _print_start_guide(*, opened: bool = False) -> None:
     )
 
 
+MCP_KEY_PLACEHOLDER = "bil_live_..."
+
+
+def _mcp_server_entry() -> dict[str, Any]:
+    # The absolute interpreter works where a bare `python` does not: macOS ships
+    # only python3, and Claude Desktop launches servers without the shell PATH.
+    entry: dict[str, Any] = {"command": sys.executable, "args": ["-m", "bilinc.cloud_mcp"]}
+    if not load_config_api_key():
+        # With a key saved by `bilinc login` the adapter reads it itself, so the
+        # client config carries no key at all. Without one, the client must pass it.
+        entry["env"] = {"BILINC_API_KEY": MCP_KEY_PLACEHOLDER}
+    return entry
+
+
 def _mcp_config() -> dict[str, Any]:
-    return {
-        "mcpServers": {
-            "bilinc": {
-                "command": "python",
-                "args": ["-m", "bilinc.cloud_mcp"],
-                "env": {"BILINC_API_KEY": "${BILINC_API_KEY}"},
-            }
-        }
-    }
+    return {"mcpServers": {"bilinc": _mcp_server_entry()}}
+
+
+def _claude_code_command() -> str:
+    argv = ["claude", "mcp", "add", "--scope", "user", "bilinc"]
+    if not load_config_api_key():
+        argv += ["-e", f"BILINC_API_KEY={MCP_KEY_PLACEHOLDER}"]
+    argv += ["--", sys.executable, "-m", "bilinc.cloud_mcp"]
+    return subprocess.list2cmdline(argv) if os.name == "nt" else shlex.join(argv)
+
+
+def _claude_desktop_config_path() -> str:
+    if sys.platform == "darwin":
+        return "~/Library/Application Support/Claude/claude_desktop_config.json"
+    if os.name == "nt":
+        return r"%APPDATA%\Claude\claude_desktop_config.json"
+    return "~/.config/Claude/claude_desktop_config.json"
 
 
 def build_parser() -> argparse.ArgumentParser:
@@ -89,9 +115,22 @@ def build_parser() -> argparse.ArgumentParser:
     start = sub.add_parser("start", help="Open the simplest path from install to first memory")
     start.add_argument("--open", action="store_true", help="Open the Bilinc signup page in a browser")
 
-    login = sub.add_parser("login", help="Save a Bilinc Cloud API key for local CLI use")
-    login.add_argument("--api-key", help="Bilinc Cloud API key to save locally")
-    login.add_argument("--open", action="store_true", help="Open the Bilinc signup page in a browser")
+    login = sub.add_parser(
+        "login",
+        help="Sign in from your browser and save an API key for this computer",
+    )
+    login.add_argument("--api-key", help="Save this API key instead of signing in (for CI)")
+    login.add_argument(
+        "--device",
+        action="store_true",
+        help="Sign in with a code approved in any browser (for SSH sessions and servers)",
+    )
+    login.add_argument(
+        "--no-browser",
+        action="store_true",
+        help="Print the sign-in URL instead of opening a browser",
+    )
+    login.add_argument("--open", action="store_true", help=argparse.SUPPRESS)
 
     commit = sub.add_parser("commit", help="Commit a memory entry to Bilinc Cloud")
     commit.add_argument("--key", required=True)
@@ -159,9 +198,16 @@ def build_parser() -> argparse.ArgumentParser:
 
     mcp = sub.add_parser("mcp", help="Print hosted Cloud MCP adapter configuration")
     mcp_sub = mcp.add_subparsers(dest="mcp_command")
-    mcp_sub.add_parser("install", help="Print MCP config for agent runtimes")
+    mcp_install = mcp_sub.add_parser("install", help="Print MCP config for agent runtimes")
+    mcp_install.add_argument(
+        "--client",
+        choices=["json", "claude-code", "claude-desktop"],
+        default="json",
+        help="json: mcpServers config (default); claude-code: a `claude mcp add` command; "
+        "claude-desktop: the config plus where Claude Desktop keeps it",
+    )
 
-    sub.add_parser("signup", help="Print signup URL for a 7-day trial")
+    sub.add_parser("signup", help="Print the signup URL (free, no card required)")
 
     return parser
 
@@ -193,18 +239,37 @@ def main(argv: list[str] | None = None) -> int:
         return 0
 
     if args.command == "login":
-        opened = False
-        if args.open:
-            opened = webbrowser.open(ACTIVATION_SIGNUP_URL)
-        if not args.api_key:
-            _print_start_guide(opened=opened)
+        if args.api_key:
+            try:
+                path = save_config_api_key(args.api_key, base_url=args.base_url)
+            except BilincApiKeyRequired as exc:
+                print(f"bilinc: error: {exc}", file=sys.stderr)
+                return 1
+            _print({"saved": True, "config": str(path), "next": "Run bilinc quicktest"})
             return 0
         try:
-            path = save_config_api_key(args.api_key, base_url=args.base_url)
-        except BilincApiKeyRequired as exc:
+            if args.device or is_headless():
+                result = device_login(args.base_url, timeout=args.timeout)
+            else:
+                result = loopback_login(args.base_url, timeout=args.timeout, open_browser=not args.no_browser)
+            api_key = result.get("api_key")
+            if not isinstance(api_key, str) or not api_key:
+                raise LoginError("Bilinc Cloud did not return an API key. Run bilinc login again.")
+            path = save_config_api_key(api_key, base_url=args.base_url)
+        except (LoginError, BilincApiKeyRequired, BilincCloudError) as exc:
             print(f"bilinc: error: {exc}", file=sys.stderr)
             return 1
-        _print({"saved": True, "config": str(path), "next": "Run bilinc quicktest"})
+        except KeyboardInterrupt:
+            print("bilinc: login cancelled", file=sys.stderr)
+            return 130
+        _print(
+            {
+                "saved": True,
+                "config": str(path),
+                "api_key_name": result.get("key_name"),
+                "next": "Run bilinc quicktest",
+            }
+        )
         return 0
 
     if args.command == "signup":
@@ -212,13 +277,28 @@ def main(argv: list[str] | None = None) -> int:
             {
                 "signup": ACTIVATION_SIGNUP_URL,
                 "base_signup": SIGNUP_URL,
-                "trial": "7 days",
-                "next": "Confirm email, copy the first API key, run bilinc login, then bilinc quicktest",
+                "pricing": "Free, no card required",
+                "next": "Run bilinc login to sign in from your browser, then bilinc quicktest",
             }
         )
         return 0
     if args.command == "mcp" and args.mcp_command == "install":
-        _print(_mcp_config())
+        # stdout stays copy-paste clean; guidance goes to stderr.
+        if args.client == "claude-code":
+            print(_claude_code_command())
+        else:
+            _print(_mcp_config())
+        if args.client == "claude-desktop":
+            print(
+                f'Merge the "bilinc" entry into mcpServers in {_claude_desktop_config_path()}, '
+                "then restart Claude Desktop.",
+                file=sys.stderr,
+            )
+        if not load_config_api_key():
+            print(
+                f"No saved key yet: run `bilinc login` first, or replace {MCP_KEY_PLACEHOLDER} with your API key.",
+                file=sys.stderr,
+            )
         return 0
     if args.command is None:
         parser.print_help()

{bilinc-2.2.0 → bilinc-2.3.1}/src/bilinc/client.py

@@ -1,6 +1,6 @@
 """Bilinc Cloud client.
 
-Bilinc 2.2.0 is cloud-only: the PyPI package is a thin SDK and MCP adapter for
+Bilinc 2.3.1 is cloud-only: the PyPI package is a thin SDK and MCP adapter for
 https://bilinc.space. Local self-hosted StatePlane internals are no longer
 shipped in the public package.
 """
@@ -18,10 +18,10 @@ from dataclasses import dataclass
 from pathlib import Path
 from typing import Any, Callable
 
-__version__ = "2.2.0"
+__version__ = "2.3.1"
 DEFAULT_BASE_URL = "https://bilinc.space"
 SIGNUP_URL = "https://bilinc.space/signup"
-ACTIVATION_CAMPAIGN = "activation_2_2_0"
+ACTIVATION_CAMPAIGN = "activation_2_3_0"
 ACTIVATION_SIGNUP_URL = (
     f"{SIGNUP_URL}?utm_source=pypi&utm_medium=cli&utm_campaign={ACTIVATION_CAMPAIGN}"
 )
@@ -381,15 +381,20 @@ def save_config_api_key(api_key: str, *, base_url: str = DEFAULT_BASE_URL) -> Pa
     key = api_key.strip()
     if not key:
         raise BilincApiKeyRequired(
-            "Bilinc requires a Bilinc Cloud API key. "
-            f"Start a 7-day trial at {ACTIVATION_SIGNUP_URL}, "
-            "then run bilinc login --api-key <key> and bilinc quicktest."
+            "No Bilinc Cloud API key is configured. "
+            "Run bilinc login to sign in from your browser (free, no card required; "
+            f"new here? {ACTIVATION_SIGNUP_URL}), "
+            "or set BILINC_API_KEY. Then run bilinc quicktest."
         )
 
     path = config_path()
-    path.parent.mkdir(parents=True, exist_ok=True)
+    path.parent.mkdir(mode=0o700, parents=True, exist_ok=True)
     payload = {"api_key": key, "base_url": base_url.rstrip("/") or DEFAULT_BASE_URL}
-    path.write_text(json.dumps(payload, indent=2), encoding="utf-8")
+    # Create the file owner-only from the start, so the key is never briefly
+    # readable by other users between the write and a later chmod.
+    fd = os.open(path, os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o600)
+    with os.fdopen(fd, "w", encoding="utf-8") as handle:
+        handle.write(json.dumps(payload, indent=2))
     try:
         path.chmod(0o600)
     except OSError:
@@ -452,9 +457,10 @@ class CloudClient:
             self.api_key = os.environ.get("BILINC_API_KEY") or load_config_api_key()
         if not self.api_key:
             raise BilincApiKeyRequired(
-                "Bilinc requires a Bilinc Cloud API key. "
-                f"Start a 7-day trial at {ACTIVATION_SIGNUP_URL}, "
-                "then run bilinc login --api-key <key> and bilinc quicktest."
+                "No Bilinc Cloud API key is configured. "
+                "Run bilinc login to sign in from your browser (free, no card required; "
+                f"new here? {ACTIVATION_SIGNUP_URL}), "
+                "or set BILINC_API_KEY. Then run bilinc quicktest."
             )
         if self.base_url == DEFAULT_BASE_URL:
             self.base_url = os.environ.get("BILINC_BASE_URL", self.base_url)

{bilinc-2.2.0 → bilinc-2.3.1/src/bilinc.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: bilinc
-Version: 2.2.0
+Version: 2.3.1
 Summary: Cloud-only memory SDK and MCP adapter for autonomous agents
 Author: Bilinc Team
 License-Expression: BUSL-1.1
@@ -56,7 +56,7 @@ Dynamic: license-file
 
 Retrieval answers *"what is similar to this?"*. Long-running agents also need to answer *"who wrote this state, was it verified, did it contradict what we already knew, and can we undo it?"* — that is the layer Bilinc provides.
 
-Bilinc 2.2.0 on PyPI is the public cloud-only package: a thin Python SDK, CLI, and MCP adapter for Bilinc Cloud. It does not ship the local StatePlane, storage backends, eval, observability, integrations, or server runtime internals.
+Bilinc 2.3.1 on PyPI is the public cloud-only package: a thin Python SDK, CLI, and MCP adapter for Bilinc Cloud. It does not ship the local StatePlane, storage backends, eval, observability, integrations, or server runtime internals.
 
 > **Frozen regression receipt** — LongMemEval-s cleaned retrieval fixture, 500 questions: **Hit@5 98.0%**, **NDCG@5 0.913**, no LLM reranker, no paid API. This is an isolated retrieval guardrail, not a current hosted SLA, end-to-end agent score, or competitor ranking — see [Benchmark receipt](#benchmark-receipt) for the full scope and qualification.
 
@@ -102,31 +102,28 @@ storage runtime.
 
 ```bash
 pip install -U bilinc
-bilinc start
+bilinc login
+bilinc quicktest
 ```
 
-`bilinc start` is the first-run guide. The activation target is simple: reach a
-passing `bilinc quicktest`, which performs one hosted commit, one hosted recall,
-and one Cloud status check.
-
-1. Start the 7-day Bilinc Cloud trial at https://bilinc.space/signup.
-2. Confirm email.
-3. Create one hosted API key in the Cloud dashboard.
-4. Connect the CLI:
+`bilinc login` opens your browser. Sign in with Google, GitHub, or email (free,
+no card required) and approve this computer; the CLI saves its own API key with
+owner-only permissions. The key never appears in a URL or your terminal.
+`bilinc quicktest` then performs one hosted commit, one hosted recall, and one
+Cloud status check.
 
-```bash
-bilinc login --api-key bil_live_...
-bilinc quicktest
-```
+- **No browser on this machine** (SSH, servers, containers): `bilinc login --device`
+  prints a short code to approve from any browser.
+- **CI and scripts:** `bilinc login --api-key bil_live_...`, or set `BILINC_API_KEY`.
 
 To reproduce this release exactly:
 
 ```bash
-pip install -U bilinc==2.2.0
+pip install -U bilinc==2.3.1
 ```
 
 If you prefer a browser guide, open https://bilinc.space/install and follow the
-same four-step path.
+same three-step path.
 
 ## MCP Adapter
 
@@ -134,18 +131,28 @@ Bilinc exposes a standard Model Context Protocol server over **stdio**, so any
 MCP-compatible client can connect — Claude Code, Codex, Cursor, Hermes-Agent,
 opencode, and others.
 
+After `bilinc login`, let the CLI write the setup for your client:
+
+```bash
+bilinc mcp install --client claude-code     # prints a ready `claude mcp add ...` command
+bilinc mcp install --client claude-desktop  # prints the config and where Claude Desktop keeps it
+bilinc mcp install                          # plain mcpServers JSON for any other client
+```
+
 ```json
 {
   "mcpServers": {
     "bilinc": {
-      "command": "python",
-      "args": ["-m", "bilinc.cloud_mcp"],
-      "env": { "BILINC_API_KEY": "bil_live_..." }
+      "command": "/path/to/python3",
+      "args": ["-m", "bilinc.cloud_mcp"]
     }
   }
 }
 ```
 
+`command` is the interpreter that has Bilinc installed, and the adapter reads the key saved by `bilinc login`, so
+the config carries no key. On a machine without a saved key, add `"env": { "BILINC_API_KEY": "bil_live_..." }`.
+
 Eight tools — the core memory lifecycle, and nothing else:
 
 | Tool | What it does |
@@ -227,10 +234,10 @@ bilinc rollback execute --snapshot snap_... --reason "undo bad agent run" \
 Useful first-run commands:
 
 ```bash
-bilinc start
-bilinc login --api-key bil_live_...
+bilinc login              # browser sign-in; --device without a browser
 bilinc quicktest
 bilinc mcp install
+bilinc start              # prints the first-run guide
 ```
 
 ## Hosted Endpoints

{bilinc-2.2.0 → bilinc-2.3.1}/src/bilinc.egg-info/SOURCES.txt

@@ -14,5 +14,6 @@ src/bilinc.egg-info/requires.txt
 src/bilinc.egg-info/top_level.txt
 src/bilinc/cli/__init__.py
 src/bilinc/cli/__main__.py
+src/bilinc/cli/login.py
 src/bilinc/cli/main.py
 tests/test_cloud_only_package.py

{bilinc-2.2.0 → bilinc-2.3.1}/tests/test_cloud_only_package.py

@@ -12,9 +12,9 @@ import pytest
 def test_public_api_is_cloud_only():
     import bilinc
 
-    assert bilinc.__version__ == "2.2.0"
-    assert bilinc.version == "2.2.0"
-    assert "utm_campaign=activation_2_2_0" in bilinc.ACTIVATION_SIGNUP_URL
+    assert bilinc.__version__ == "2.3.1"
+    assert bilinc.version == "2.3.1"
+    assert "utm_campaign=activation_2_3_0" in bilinc.ACTIVATION_SIGNUP_URL
     assert hasattr(bilinc, "Bilinc")
     assert hasattr(bilinc, "CloudClient")
     assert not hasattr(bilinc, "StatePlane")
@@ -110,9 +110,9 @@ def test_cloud_client_commit_posts_to_hosted_api():
             "headers": {
                 "Authorization": "Bearer bil_live_test",
                 "Content-Type": "application/json",
-                "User-Agent": "bilinc-python/2.2.0",
+                "User-Agent": "bilinc-python/2.3.1",
                 "X-Bilinc-Client": "python-sdk",
-                "X-Bilinc-Client-Version": "2.2.0",
+                "X-Bilinc-Client-Version": "2.3.1",
             },
             "body": json.dumps(
                 {
@@ -188,7 +188,7 @@ def test_cloud_client_status_reads_the_authenticated_status_endpoint():
             "url": "https://bilinc.space/api/cloud/status",
             "headers": {
                 "Authorization": "Bearer bil_live_test",
-                "User-Agent": "bilinc-python/2.2.0",
+                "User-Agent": "bilinc-python/2.3.1",
             },
             "body": None,
             "timeout": 30.0,
@@ -261,7 +261,7 @@ def test_cli_signup_and_missing_key_failure(monkeypatch, capsys):
     assert main(["signup"]) == 0
     signup_out = capsys.readouterr()
     assert "https://bilinc.space/signup" in signup_out.out
-    assert "activation_2_2_0" in signup_out.out
+    assert "activation_2_3_0" in signup_out.out
     assert "quicktest" in signup_out.out
 
     assert main(["commit", "--key", "smoke_key", "--value", "hello"]) == 1
@@ -305,7 +305,7 @@ def test_cli_start_login_doctor_quicktest_and_mcp_config(monkeypatch, capsys, tm
     assert "bilinc login --api-key <key>" in start_out.out
     assert "bilinc quicktest" in start_out.out
     assert "install_guide" in start_out.out
-    assert "activation_2_2_0" in start_out.out
+    assert "activation_2_3_0" in start_out.out
 
     assert cli_main.main(["login", "--api-key", "bil_live_cli_test"]) == 0
     login_out = capsys.readouterr()
@@ -327,6 +327,56 @@ def test_cli_start_login_doctor_quicktest_and_mcp_config(monkeypatch, capsys, tm
     assert "bil_live_cli_test" not in mcp_out.out
 
 
+def test_mcp_install_uses_the_login_key_and_a_real_interpreter(monkeypatch, capsys, tmp_path):
+    import sys
+
+    from bilinc.cli import main as cli_main
+
+    monkeypatch.delenv("BILINC_API_KEY", raising=False)
+    monkeypatch.setenv("BILINC_CONFIG_DIR", str(tmp_path))
+    assert cli_main.main(["login", "--api-key", "bil_live_saved_key"]) == 0
+    capsys.readouterr()
+
+    # Default JSON: absolute interpreter, and no env block — the adapter reads the saved key.
+    assert cli_main.main(["mcp", "install"]) == 0
+    out = capsys.readouterr()
+    server = json.loads(out.out)["mcpServers"]["bilinc"]
+    assert server == {"command": sys.executable, "args": ["-m", "bilinc.cloud_mcp"]}
+    assert "bil_live_saved_key" not in out.out + out.err
+    assert "${BILINC_API_KEY}" not in out.out
+
+    # Claude Code: one runnable command, user scope, no key on the command line.
+    assert cli_main.main(["mcp", "install", "--client", "claude-code"]) == 0
+    out = capsys.readouterr()
+    assert out.out.startswith("claude mcp add --scope user bilinc -- ")
+    assert out.out.rstrip().endswith("-m bilinc.cloud_mcp")
+    assert "BILINC_API_KEY" not in out.out
+    assert "bil_live_saved_key" not in out.out + out.err
+
+    # Claude Desktop: clean JSON on stdout, the config location on stderr.
+    assert cli_main.main(["mcp", "install", "--client", "claude-desktop"]) == 0
+    out = capsys.readouterr()
+    assert json.loads(out.out)["mcpServers"]["bilinc"]["command"] == sys.executable
+    assert "claude_desktop_config.json" in out.err
+    assert "bil_live_saved_key" not in out.out + out.err
+
+
+def test_mcp_install_without_a_saved_key_asks_for_one(monkeypatch, capsys, tmp_path):
+    from bilinc.cli import main as cli_main
+
+    monkeypatch.delenv("BILINC_API_KEY", raising=False)
+    monkeypatch.setenv("BILINC_CONFIG_DIR", str(tmp_path))
+
+    assert cli_main.main(["mcp", "install"]) == 0
+    out = capsys.readouterr()
+    assert json.loads(out.out)["mcpServers"]["bilinc"]["env"] == {"BILINC_API_KEY": "bil_live_..."}
+    assert "bilinc login" in out.err
+
+    assert cli_main.main(["mcp", "install", "--client", "claude-code"]) == 0
+    out = capsys.readouterr()
+    assert "-e BILINC_API_KEY=bil_live_..." in out.out
+
+
 def _forbidden_package_prefixes(root: str = "") -> tuple[str, ...]:
     return tuple(
         f"{root}{prefix}"