sibyl-memory-cli 0.1.0__py3-none-any.whl

sibyl_memory_cli/__init__.py

@@ -0,0 +1,18 @@
+"""sibyl-memory-cli — Command-line interface for the Sibyl Memory Plugin.
+
+Entry point: `sibyl` (installed via [project.scripts] in pyproject).
+
+Commands:
+    sibyl init          activate the plugin — opens browser SIWE flow, writes ~/.sibyl-memory/credentials.json
+    sibyl upgrade       open the upgrade flow — stake $SIBYL or subscribe in USDC
+    sibyl status        show current tier, DB size, expiry, account
+    sibyl health        provider self-check (mirrors SibylMemoryProvider.health())
+
+Browser pages live at sibyllabs.org/plugin/{activate,upgrade}.
+All HTTP calls target https://api.sibyllabs.org/api/plugin/*.
+"""
+from .cli import main
+
+__version__ = "0.1.0"
+
+__all__ = ["main", "__version__"]

sibyl_memory_cli/cli.py

@@ -0,0 +1,572 @@
+"""`sibyl` command-line interface.
+
+Stdlib only. The CLI is a thin wrapper around HTTP calls to
+https://api.sibyllabs.org/api/plugin/* and the local SibylMemoryProvider.
+
+Design pillars:
+  - Zero non-stdlib deps in this file. urllib is enough.
+  - Credentials are written atomically with 0600 perms.
+  - session_token is never printed in full — display short slice only.
+  - Polling has explicit timeouts; no infinite loops.
+  - Every command exits with a clear status code (0 ok, 1 user error, 2 server error).
+"""
+from __future__ import annotations
+
+import argparse
+import hashlib
+import json
+import os
+import secrets
+import sys
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+import uuid
+import webbrowser
+from pathlib import Path
+from typing import Any
+
+# ---- Defaults ----------------------------------------------------------
+
+API_BASE = os.environ.get("SIBYL_API_BASE", "https://api.sibyllabs.org")
+ACTIVATE_BASE = os.environ.get("SIBYL_ACTIVATE_BASE", "https://sibyllabs.org/plugin/activate")
+UPGRADE_BASE = os.environ.get("SIBYL_UPGRADE_BASE", "https://sibyllabs.org/plugin/upgrade")
+
+DEFAULT_CRED_PATH = Path("~/.sibyl-memory/credentials.json").expanduser()
+DEFAULT_DB_PATH = Path("~/.sibyl-memory/memory.db").expanduser()
+DEFAULT_TIER_CACHE_PATH = Path("~/.sibyl-memory/tier_cache.json").expanduser()
+
+POLL_INTERVAL_SEC = 3
+INIT_TIMEOUT_SEC = 10 * 60      # 10 minutes for /init activation
+UPGRADE_TIMEOUT_SEC = 15 * 60   # 15 minutes for upgrade — wallet ux can be slow
+
+# ---- Color / output ----------------------------------------------------
+
+_NO_COLOR = bool(os.environ.get("NO_COLOR")) or not sys.stdout.isatty()
+
+
+def c(code: str, s: str) -> str:
+    if _NO_COLOR:
+        return s
+    return f"\033[{code}m{s}\033[0m"
+
+
+def dim(s: str) -> str: return c("2", s)
+def bold(s: str) -> str: return c("1", s)
+def green(s: str) -> str: return c("32", s)
+def yellow(s: str) -> str: return c("33", s)
+def red(s: str) -> str: return c("31", s)
+def cyan(s: str) -> str: return c("36", s)
+
+
+def _detect_os_family() -> str | None:
+    p = sys.platform
+    if p == "darwin": return "macos"
+    if p.startswith("linux"): return "linux"
+    if p.startswith("win"): return "windows"
+    return None
+
+
+def short(token: str | None) -> str:
+    if not token:
+        return "—"
+    if len(token) <= 12:
+        return token
+    return f"{token[:8]}…{token[-4:]}"
+
+
+def print_status(label: str, value: str) -> None:
+    print(f"  {dim(label.ljust(18))} {value}")
+
+
+# ---- HTTP --------------------------------------------------------------
+
+class HttpError(Exception):
+    def __init__(self, status: int, body: Any, url: str) -> None:
+        super().__init__(f"HTTP {status} for {url}: {body}")
+        self.status = status
+        self.body = body
+        self.url = url
+
+
+def http_request(
+    method: str,
+    path: str,
+    *,
+    body: dict | None = None,
+    timeout: float = 15.0,
+    headers: dict | None = None,
+) -> dict:
+    """Single source of truth for HTTP calls. Returns parsed JSON or raises HttpError."""
+    url = f"{API_BASE}{path}"
+    data = None
+    full_headers = {"Accept": "application/json", "User-Agent": "sibyl-memory-cli/0.1.0"}
+    if body is not None:
+        data = json.dumps(body).encode("utf-8")
+        full_headers["Content-Type"] = "application/json"
+    if headers:
+        full_headers.update(headers)
+    req = urllib.request.Request(url, data=data, method=method, headers=full_headers)
+    try:
+        with urllib.request.urlopen(req, timeout=timeout) as resp:
+            return json.loads(resp.read().decode("utf-8"))
+    except urllib.error.HTTPError as e:
+        try:
+            err_body = json.loads(e.read().decode("utf-8"))
+        except Exception:
+            err_body = {"error": "unparseable response body"}
+        raise HttpError(e.code, err_body, url) from None
+    except urllib.error.URLError as e:
+        raise HttpError(0, {"error": str(e.reason)}, url) from None
+
+
+# ---- Credentials I/O ---------------------------------------------------
+
+def write_credentials_atomic(creds: dict, path: Path = DEFAULT_CRED_PATH) -> Path:
+    """Write credentials.json atomically at mode 0600."""
+    path = path.expanduser()
+    path.parent.mkdir(parents=True, exist_ok=True, mode=0o700)
+    tmp = path.with_suffix(path.suffix + ".tmp")
+    tmp.write_text(json.dumps(creds, indent=2), encoding="utf-8")
+    os.chmod(tmp, 0o600)
+    tmp.replace(path)
+    return path
+
+
+def read_credentials(path: Path = DEFAULT_CRED_PATH) -> dict | None:
+    path = path.expanduser()
+    if not path.exists():
+        return None
+    return json.loads(path.read_text(encoding="utf-8"))
+
+
+def invalidate_tier_cache(path: Path = DEFAULT_TIER_CACHE_PATH) -> None:
+    """Drop the local tier cache so the next write refreshes against the server."""
+    path = path.expanduser()
+    if path.exists():
+        path.unlink()
+
+
+# ---- `sibyl init` ------------------------------------------------------
+
+def _gen_pairing_code() -> str:
+    """6-digit cryptographic pairing code. Uniform across 000000-999999."""
+    return f"{secrets.randbelow(1_000_000):06d}"
+
+
+def _hash_pairing_code(code: str, session: str) -> str:
+    return hashlib.sha256(f"{code}:{session}".encode("utf-8")).hexdigest()
+
+
+def cmd_init(args: argparse.Namespace) -> int:
+    """Activation flow. Generate session UUID + pairing code, register with
+    server, open activation page in browser, poll /check until bound.
+
+    The pairing code is printed in the terminal. If the user picks the
+    email path in the browser, they type both their email and this code.
+    No external email service is required."""
+    cred_path = Path(args.credentials).expanduser()
+    if cred_path.exists() and not args.force:
+        existing = read_credentials(cred_path) or {}
+        print(yellow("Already activated.") + " Use --force to re-activate.")
+        print_status("Account", short(existing.get("account_id")))
+        print_status("Tier", (existing.get("tier") or "free").upper())
+        print_status("Credentials", str(cred_path))
+        return 0
+
+    session_token = str(uuid.uuid4())
+    pairing_code = _gen_pairing_code()
+    code_hash = _hash_pairing_code(pairing_code, session_token)
+    activate_url = f"{ACTIVATE_BASE}?session={session_token}"
+
+    # Pre-register the session + pairing code hash with the server.
+    # The code itself never leaves the user's machine until they type it
+    # into the browser.
+    try:
+        http_request(
+            "POST",
+            "/api/plugin/session-init",
+            body={
+                "session": session_token,
+                "pairing_code_hash": code_hash,
+                "env": {
+                    "os_family": _detect_os_family(),
+                    "install_method": "cli",
+                    "client_version": __import__("sibyl_memory_cli").__version__,
+                },
+            },
+            timeout=10.0,
+        )
+    except HttpError as e:
+        # Non-fatal: SIWE path doesn't need the pairing code. If session-init
+        # fails the user can still complete SIWE. Surface the warning.
+        print(yellow(f"Warning: session-init failed ({e.status}). Wallet path still works; email path may not."))
+
+    print()
+    print(bold("Sibyl Memory Plugin · activation"))
+    print()
+    print(f"  {dim('Session:')}     {short(session_token)}")
+    # Format the code with a visual break to make it easier to read off the screen
+    print(f"  {dim('Code:')}        {bold(pairing_code[:3] + ' ' + pairing_code[3:])}   {dim('(use this in the email panel)')}")
+    print(f"  {dim('Opening:')}     {activate_url}")
+    print()
+    print(dim("Pick wallet (SIWE) or email + the code above. This terminal will pick up automatically."))
+    print()
+
+    try:
+        webbrowser.open(activate_url, new=2)
+    except Exception:
+        pass
+
+    # Poll /api/plugin/check
+    deadline = time.time() + INIT_TIMEOUT_SEC
+    last_status = ""
+    spinner = "⠋⠙⠹⠸⠼⠴⠦⠧⠇⠏"
+    spin_i = 0
+
+    while time.time() < deadline:
+        try:
+            resp = http_request("GET", f"/api/plugin/check?session={urllib.parse.quote(session_token)}", timeout=10.0)
+        except HttpError as e:
+            if e.status in (404, 503, 0):
+                # Session not yet created server-side, or transient — keep polling
+                pass
+            else:
+                print(red(f"\nUnexpected error: {e.body}"))
+                return 2
+            resp = {"bound": False}
+
+        if resp.get("bound") and resp.get("credentials"):
+            creds = resp["credentials"]
+            # Sanity check: the server's session_token field MUST match what we sent
+            if creds.get("session_token") and creds["session_token"] != session_token:
+                print(red("\nSession token mismatch — refusing to write credentials."))
+                return 2
+            # If server didn't echo session_token, inject our locally-generated one
+            creds.setdefault("session_token", session_token)
+            path = write_credentials_atomic(creds, cred_path)
+            print(f"\r{' ' * 80}\r", end="")  # clear spinner line
+            print(green("✓ Activated."))
+            print_status("Account", short(creds.get("account_id")))
+            print_status("Tier", (creds.get("tier") or "free").upper())
+            print_status("Wallet", creds.get("wallet") or "—")
+            print_status("Email", creds.get("email") or "—")
+            print_status("Credentials", str(path))
+            print()
+            print(dim("Wire the provider into Hermes:"))
+            print(dim("    from sibyl_memory_hermes import SibylMemoryProvider"))
+            print(dim("    agent = Agent(memory=SibylMemoryProvider())"))
+            return 0
+
+        # Spinner tick
+        spin_i = (spin_i + 1) % len(spinner)
+        remaining = int(deadline - time.time())
+        status = f"\r  {cyan(spinner[spin_i])} waiting for browser activation … {dim(f'{remaining // 60}:{remaining % 60:02d} left')}"
+        if status != last_status:
+            sys.stdout.write(status)
+            sys.stdout.flush()
+            last_status = status
+        time.sleep(POLL_INTERVAL_SEC)
+
+    print(red("\nActivation timed out. Re-run `sibyl init` to try again."))
+    return 1
+
+
+# ---- `sibyl upgrade` ---------------------------------------------------
+
+def cmd_upgrade(args: argparse.Namespace) -> int:
+    """Upgrade flow. Read existing creds → open upgrade page → poll /access until tier flips."""
+    creds = read_credentials(Path(args.credentials).expanduser())
+    if not creds:
+        print(red("Not activated.") + " Run `sibyl init` first.")
+        return 1
+
+    account_id = creds.get("account_id")
+    session_token = creds.get("session_token")
+    current_tier = (creds.get("tier") or "free").lower()
+
+    if not account_id or not session_token:
+        print(red("credentials.json is missing account_id or session_token. Re-run `sibyl init`."))
+        return 1
+
+    upgrade_url = f"{UPGRADE_BASE}?session={session_token}"
+
+    print()
+    print(bold("Sibyl Memory Plugin · upgrade"))
+    print()
+    print_status("Account", short(account_id))
+    print_status("Current tier", current_tier.upper())
+    print_status("Opening", upgrade_url)
+    print()
+    print(dim("Two paths in your browser:"))
+    print(dim("  1. Stake $SIBYL on Base (free unlimited if you qualify)"))
+    print(dim("  2. Subscribe in USDC (monthly / quarterly / annual)"))
+    print()
+
+    try:
+        webbrowser.open(upgrade_url, new=2)
+    except Exception:
+        pass
+
+    # Poll /api/plugin/access until tier changes
+    deadline = time.time() + UPGRADE_TIMEOUT_SEC
+    last_status = ""
+    spinner = "⠋⠙⠹⠸⠼⠴⠦⠧⠇⠏"
+    spin_i = 0
+
+    while time.time() < deadline:
+        try:
+            resp = http_request(
+                "POST",
+                "/api/plugin/access",
+                body={"account_id": account_id, "session_token": session_token},
+                timeout=10.0,
+            )
+        except HttpError as e:
+            if e.status == 401:
+                print(red("\nSession expired. Re-run `sibyl init`."))
+                return 1
+            # Transient — keep polling
+            resp = {}
+
+        new_tier = (resp.get("tier") or current_tier).lower()
+        source = resp.get("source")
+
+        if new_tier != current_tier and source in ("subscription", "staker"):
+            # Tier changed. Refresh credentials.
+            creds["tier"] = new_tier
+            if resp.get("staker") and resp["staker"].get("wallet"):
+                creds["wallet"] = resp["staker"]["wallet"]
+            write_credentials_atomic(creds, Path(args.credentials).expanduser())
+            invalidate_tier_cache()
+
+            print(f"\r{' ' * 80}\r", end="")
+            print(green(f"✓ Upgraded to {new_tier.upper()} via {source}."))
+            print_status("Source", source)
+            if resp.get("expires_at"):
+                print_status("Expires", resp["expires_at"])
+            if resp.get("cap_bytes") is None:
+                print_status("Storage cap", "unlimited")
+            else:
+                print_status("Storage cap", f"{resp['cap_bytes']:,} bytes")
+            if resp.get("staker"):
+                s = resp["staker"]
+                print_status("Wallet", s.get("wallet", "—"))
+                print_status("$SIBYL held", s.get("total_sibyl", "—"))
+            print()
+            print(dim("Local tier cache cleared. Your next write will sync the new tier."))
+            return 0
+
+        spin_i = (spin_i + 1) % len(spinner)
+        remaining = int(deadline - time.time())
+        status = f"\r  {cyan(spinner[spin_i])} waiting for browser upgrade … current: {current_tier.upper()}  {dim(f'{remaining // 60}:{remaining % 60:02d} left')}"
+        if status != last_status:
+            sys.stdout.write(status)
+            sys.stdout.flush()
+            last_status = status
+        time.sleep(POLL_INTERVAL_SEC)
+
+    print(red("\nUpgrade timed out. Tier unchanged. Re-run `sibyl upgrade` to retry."))
+    return 1
+
+
+# ---- `sibyl status` ----------------------------------------------------
+
+def cmd_status(args: argparse.Namespace) -> int:
+    """Show local + server-side state without modifying anything."""
+    cred_path = Path(args.credentials).expanduser()
+    creds = read_credentials(cred_path)
+
+    print()
+    print(bold("Sibyl Memory Plugin · status"))
+    print()
+
+    if not creds:
+        print(yellow("Not activated.") + " Run `sibyl init`.")
+        return 0
+
+    # Local view
+    print(dim("LOCAL"))
+    print_status("Credentials", str(cred_path))
+    print_status("Account", short(creds.get("account_id")))
+    print_status("Tier", (creds.get("tier") or "free").upper())
+    print_status("Wallet", creds.get("wallet") or "—")
+    print_status("Email", creds.get("email") or "—")
+    print_status("Issued", creds.get("issued_at") or "—")
+
+    db_path = Path(args.db).expanduser()
+    if db_path.exists():
+        size = db_path.stat().st_size
+        print_status("DB path", str(db_path))
+        print_status("DB size", f"{size:,} bytes ({size / (1024 * 1024):.2f} MB)")
+    else:
+        print_status("DB path", f"{db_path} (not created)")
+
+    tier_cache = Path(args.tier_cache).expanduser()
+    if tier_cache.exists():
+        cache = json.loads(tier_cache.read_text(encoding="utf-8"))
+        print_status("Tier cache", f"{cache.get('tier','?')} (checked {cache.get('checked_at','?')[:19]})")
+    else:
+        print_status("Tier cache", "—")
+
+    # Server view (only if account_id + session_token are present)
+    if creds.get("account_id") and creds.get("session_token"):
+        print()
+        print(dim("SERVER"))
+        try:
+            resp = http_request(
+                "POST",
+                "/api/plugin/access",
+                body={"account_id": creds["account_id"], "session_token": creds["session_token"]},
+                timeout=10.0,
+            )
+            print_status("Tier", (resp.get("tier") or "free").upper())
+            print_status("Source", resp.get("source") or "—")
+            print_status("Cap bytes", "unlimited" if resp.get("cap_bytes") is None else f"{resp['cap_bytes']:,}")
+            if resp.get("expires_at"):
+                print_status("Expires", resp["expires_at"])
+            if resp.get("staker"):
+                s = resp["staker"]
+                print_status("$SIBYL held", s.get("total_sibyl", "—"))
+                print_status("Threshold", str(s.get("threshold_sibyl", "—")))
+                print_status("Qualified", "yes" if s.get("qualified") else "no")
+            # Detect server/local drift
+            srv_tier = (resp.get("tier") or "free").lower()
+            loc_tier = (creds.get("tier") or "free").lower()
+            if srv_tier != loc_tier:
+                print()
+                print(yellow(f"⚠ Local tier ({loc_tier}) differs from server tier ({srv_tier})."))
+                print(dim("  Run `sibyl upgrade` to refresh, or remove credentials.json + `sibyl init` to re-activate."))
+        except HttpError as e:
+            print_status("Tier", red(f"server error: {e.status}"))
+
+    print()
+    return 0
+
+
+# ---- `sibyl dashboard` (placeholder, today routes to status) -----------
+
+def cmd_dashboard(args: argparse.Namespace) -> int:
+    """Open the web account dashboard. In v0.1.0, the dashboard at
+    account.sibyllabs.org is not yet live (queued post-V1-ship per the
+    operator design memo). Until then, `sibyl dashboard` delegates to
+    `sibyl status` so the command surface exists from day one and users
+    who muscle-memory it get a real result.
+
+    When account.sibyllabs.org ships, this will flip to
+    `webbrowser.open(...)` with no UX disruption — same command, real
+    web dashboard."""
+    DASHBOARD_BASE = os.environ.get("SIBYL_DASHBOARD_BASE")
+    if DASHBOARD_BASE:
+        # If env var is set, open the web dashboard with the session token.
+        creds = read_credentials(Path(args.credentials).expanduser())
+        if creds and creds.get("session_token"):
+            url = f"{DASHBOARD_BASE}?session={creds['session_token']}"
+            print()
+            print(bold("Sibyl Memory Plugin · dashboard"))
+            print(f"  {dim('Opening:')}     {url}")
+            print()
+            try:
+                webbrowser.open(url, new=2)
+            except Exception:
+                pass
+            return 0
+    # Fall through: account.sibyllabs.org isn't live yet, run status instead.
+    return cmd_status(args)
+
+
+# ---- `sibyl logout` ----------------------------------------------------
+
+def cmd_logout(args: argparse.Namespace) -> int:
+    """Delete credentials.json + tier_cache.json. memory.db stays — that's your data."""
+    cred_path = Path(args.credentials).expanduser()
+    tier_cache = Path(args.tier_cache).expanduser()
+
+    deleted = []
+    if cred_path.exists():
+        cred_path.unlink()
+        deleted.append(str(cred_path))
+    if tier_cache.exists():
+        tier_cache.unlink()
+        deleted.append(str(tier_cache))
+
+    print()
+    if not deleted:
+        print(yellow("Nothing to remove.") + " Already logged out.")
+    else:
+        print(green("✓ Logged out."))
+        for path in deleted:
+            print(f"  {dim('removed')} {path}")
+        print()
+        print(dim("Your memory.db file is untouched — that's your data."))
+        print(dim("Run `sibyl init` to activate a fresh account."))
+    print()
+    return 0
+
+
+# ---- `sibyl health` ----------------------------------------------------
+
+def cmd_health(args: argparse.Namespace) -> int:
+    """SibylMemoryProvider.health() — minimal self-check."""
+    try:
+        from sibyl_memory_hermes import SibylMemoryProvider
+    except ImportError:
+        print(red("sibyl-memory-hermes not installed."))
+        return 1
+    provider = SibylMemoryProvider(db_path=args.db)
+    h = provider.health()
+    print(json.dumps(h, indent=2))
+    return 0 if h.get("ok") else 1
+
+
+# ---- Dispatch ----------------------------------------------------------
+
+def build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(
+        prog="sibyl",
+        description="Command-line interface for the Sibyl Memory Plugin.",
+    )
+    p.add_argument("--credentials", default=str(DEFAULT_CRED_PATH),
+                   help="Path to credentials.json (default: ~/.sibyl-memory/credentials.json)")
+    p.add_argument("--db", default=str(DEFAULT_DB_PATH),
+                   help="Path to memory.db (default: ~/.sibyl-memory/memory.db)")
+    p.add_argument("--tier-cache", default=str(DEFAULT_TIER_CACHE_PATH),
+                   help="Path to tier_cache.json (default: ~/.sibyl-memory/tier_cache.json)")
+
+    sub = p.add_subparsers(dest="cmd", required=True)
+
+    p_init = sub.add_parser("init", help="Activate the plugin in your browser")
+    p_init.add_argument("--force", action="store_true", help="Re-activate even if credentials.json exists")
+    p_init.set_defaults(func=cmd_init)
+
+    p_up = sub.add_parser("upgrade", help="Open the upgrade flow (stake or subscribe)")
+    p_up.set_defaults(func=cmd_upgrade)
+
+    p_st = sub.add_parser("status", help="Show local + server tier / DB stats")
+    p_st.set_defaults(func=cmd_status)
+
+    p_dash = sub.add_parser("dashboard", help="Open the account dashboard (delegates to status until account.sibyllabs.org ships)")
+    p_dash.set_defaults(func=cmd_dashboard)
+
+    p_lo = sub.add_parser("logout", help="Remove local credentials (memory.db stays)")
+    p_lo.set_defaults(func=cmd_logout)
+
+    p_h = sub.add_parser("health", help="Run the provider self-check")
+    p_h.set_defaults(func=cmd_health)
+
+    return p
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    try:
+        return args.func(args)
+    except KeyboardInterrupt:
+        print(red("\nInterrupted."))
+        return 130
+
+
+if __name__ == "__main__":
+    sys.exit(main())

sibyl_memory_cli-0.1.0.dist-info/METADATA

@@ -0,0 +1,128 @@
+Metadata-Version: 2.4
+Name: sibyl-memory-cli
+Version: 0.1.0
+Summary: Command-line interface for the Sibyl Memory Plugin. `sibyl init` activates, `sibyl upgrade` runs the staker / subscription flow, `sibyl status` shows current tier and DB stats.
+Author-email: Sibyl Labs <sibyl@sibyllabs.org>
+License: MIT
+Project-URL: Homepage, https://sibyllabs.org/plugin
+Project-URL: Documentation, https://docs.sibyllabs.org/memory/
+Keywords: sibyl,memory,cli,agent,hermes
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Environment :: Console
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: sibyl-memory-client>=0.3.0
+Requires-Dist: sibyl-memory-hermes>=0.2.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+
+# sibyl-memory-cli
+
+Command-line interface for the **Sibyl Memory Plugin**.
+
+```bash
+pip install sibyl-memory-cli
+```
+
+This pulls in `sibyl-memory-client` (the local SDK) and `sibyl-memory-hermes` (the Hermes provider) automatically.
+
+## Commands
+
+```
+sibyl init                  Open the browser activation page. Writes ~/.sibyl-memory/credentials.json.
+sibyl upgrade               Open the upgrade page. Stake $SIBYL or subscribe in USDC.
+sibyl status                Show local credentials, DB size, and the server's view of your tier.
+sibyl health                Run the SibylMemoryProvider self-check (schema version, DB path, tenant).
+```
+
+## Activation
+
+```bash
+$ sibyl init
+
+  Sibyl Memory Plugin · activation
+
+  Session:     a1b2c3d4…e5f6
+  Opening:     https://sibyllabs.org/plugin/activate?session=a1b2c3d4-…
+
+  Sign in with your wallet in the browser. This terminal will pick up automatically.
+
+  ⠹ waiting for browser activation … 9:42 left
+```
+
+The browser opens. Sign a SIWE message with your wallet. The terminal picks up the moment the binding lands. Credentials are written to `~/.sibyl-memory/credentials.json` at mode 0600.
+
+## Upgrade
+
+```bash
+$ sibyl upgrade
+
+  Sibyl Memory Plugin · upgrade
+
+  Account            a1b2c3d4…e5f6
+  Current tier       FREE
+  Opening            https://sibyllabs.org/plugin/upgrade?session=…
+
+  Two paths in your browser:
+    1. Stake $SIBYL on Base (free unlimited if you qualify)
+    2. Subscribe in USDC (monthly / quarterly / annual)
+```
+
+In the browser:
+- **Stake** — connect your wallet (browser or Coinbase Smart Wallet), sign to bind, and the page checks your `$SIBYL` balance on Base. If you hold the threshold (default 100,000 $SIBYL liquid+staked, configurable), the local cap lifts.
+- **Subscribe** — pick monthly ($29) / quarterly ($79) / annual ($290) USDC, sign the transfer, the server records the subscription. Tier flips immediately.
+
+On either path, the CLI sees the tier change, rewrites `credentials.json`, and clears `tier_cache.json` so your next write picks up the new entitlement without delay.
+
+## Status
+
+```bash
+$ sibyl status
+
+  Sibyl Memory Plugin · status
+
+  LOCAL
+    Credentials       ~/.sibyl-memory/credentials.json
+    Account           a1b2c3d4…e5f6
+    Tier              FREE
+    DB size           1,247,300 bytes (1.19 MB)
+    Tier cache        free (checked 2026-05-16T18:12:03)
+
+  SERVER
+    Tier              FREE
+    Source            free
+    Cap bytes         2,097,152
+    $SIBYL held       0
+    Threshold         100,000
+    Qualified         no
+```
+
+If `LOCAL` and `SERVER` tiers diverge, run `sibyl upgrade`.
+
+## Environment overrides
+
+For internal testing only:
+
+```bash
+SIBYL_API_BASE=https://staging.api.sibyllabs.org sibyl init
+SIBYL_ACTIVATE_BASE=https://staging.sibyllabs.org/plugin/activate sibyl init
+SIBYL_UPGRADE_BASE=https://staging.sibyllabs.org/plugin/upgrade sibyl upgrade
+```
+
+## Security
+
+- `credentials.json` is written atomically at mode 0600.
+- `session_token` is never printed in full — only a short slice.
+- No memory content ever transits these endpoints. The CLI never reads `memory.db` content; it only checks file size.
+- Wallet operations happen in the browser. The CLI sees only the resulting tier change.
+
+## License
+
+MIT.

sibyl_memory_cli-0.1.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+sibyl_memory_cli/__init__.py,sha256=oHw0S-aW8QNMtrEBp3sGR4WJz992RvLpxys5qP9Chz4,715
+sibyl_memory_cli/cli.py,sha256=QWAND-QRKGuyYPC--BqAnFGm2KeSdPQejWhcbFkFEts,21959
+sibyl_memory_cli-0.1.0.dist-info/METADATA,sha256=fqn_o95ikWj0F3iRIvtc9nJBw4TV4HZnH5GJFBquFrA,4395
+sibyl_memory_cli-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+sibyl_memory_cli-0.1.0.dist-info/entry_points.txt,sha256=1QQ9SGFZYipdcWk2QTS_vaayvbQeFAnu88btGt7PRaY,52
+sibyl_memory_cli-0.1.0.dist-info/top_level.txt,sha256=WzJRDcCaFHLUdX7HxrrX27776Y5Y_9P_nR1ZVX0qRxg,17
+sibyl_memory_cli-0.1.0.dist-info/RECORD,,

sibyl_memory_cli-0.1.0.dist-info/WHEEL

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

sibyl_memory_cli-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+sibyl = sibyl_memory_cli.cli:main

sibyl_memory_cli-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+sibyl_memory_cli