botu-cli 0.1.0__py3-none-any.whl

botu_cli/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

botu_cli/__main__.py

@@ -0,0 +1,535 @@
+"""botu CLI entry point — agent-first provisioning for the botu embed agent.
+
+  botu login                                  # OAuth device-flow
+  botu logout
+  botu whoami
+  botu sites create --name <n> --domain <d>
+  botu sites list | get <id> | delete <id>
+  botu sites verify <id> --domain <d> [--check]
+  botu keys create --site <id> [--test]
+  botu keys list --site <id>
+  botu keys revoke <key-id> --site <id>
+  botu embed --site <id> [--key <k> | --new-key] [--write <file>]
+  botu usage [--site <id>]
+  botu test --site <id> [--key <k>]
+
+All commands accept `--json` (or env BOTU_JSON=1) for machine-parseable
+output. Auth: `botu login` writes ~/.paradigx/auth.json (shared across
+Paradigx CLIs); later commands reuse it. See docs/specs/agent-first-cli.md.
+"""
+from __future__ import annotations
+
+import os
+import re
+import sys
+import time
+import uuid
+
+# Force UTF-8 on Windows so rich's coloured / unicode output doesn't crash on
+# legacy GBK / CP936 consoles. errors='replace' degrades gracefully.
+if sys.platform == "win32":
+    for _stream in (sys.stdout, sys.stderr):
+        if hasattr(_stream, "reconfigure"):
+            try:
+                _stream.reconfigure(encoding="utf-8", errors="replace")
+            except Exception:
+                pass
+
+import httpx
+import typer
+
+from . import __version__
+from .client import ApiError, exit_code_for, request
+from .config import Credentials, api_url, clear_credentials, save_credentials
+from .device_flow import fetch_discovery, open_browser, poll_for_token, request_device_code
+from .output import emit, error, info, is_json_mode, success
+
+app = typer.Typer(
+    name="botu",
+    help="Agent-first CLI for botu — embeddable AI agent for any website.",
+    add_completion=False,
+    no_args_is_help=True,
+)
+sites_app = typer.Typer(name="sites", help="Manage your botu sites.", no_args_is_help=True)
+keys_app = typer.Typer(name="keys", help="Manage site embed API keys.", no_args_is_help=True)
+app.add_typer(sites_app, name="sites")
+app.add_typer(keys_app, name="keys")
+
+
+def _global_callback(
+    json_output: bool = typer.Option(
+        False, "--json", help="Machine-parseable JSON output (for agents / scripts)."
+    ),
+) -> None:
+    if json_output or os.environ.get("BOTU_JSON") == "1":
+        os.environ["_BOTU_OUTPUT_JSON"] = "1"
+
+
+app.callback()(_global_callback)
+
+
+def _fail(e: ApiError) -> None:
+    error(e.message, code=exit_code_for(e))
+
+
+def _confirm(prompt: str, yes: bool) -> None:
+    """Abort unless confirmed. In --json / non-interactive mode --yes is required."""
+    if yes:
+        return
+    if is_json_mode() or not sys.stdin.isatty():
+        error("refusing without --yes (non-interactive)", code=1)
+    if not typer.confirm(prompt):
+        error("aborted", code=1)
+
+
+# ─── login / logout / whoami ─────────────────────────────────────────
+
+
+@app.command()
+def login() -> None:
+    """Log in via OAuth device-flow (opens browser)."""
+    try:
+        disc = fetch_discovery()
+    except httpx.HTTPStatusError as e:
+        if e.response.status_code == 503:
+            error("CLI login is not enabled on this botu deployment yet", code=3)
+        error(f"discovery failed: {e}", code=3)
+    except Exception as e:  # noqa: BLE001
+        error(f"could not reach botu API: {e}", code=2)
+
+    try:
+        code = request_device_code(disc)
+    except Exception as e:  # noqa: BLE001
+        error(f"device-flow init failed: {e}", code=3)
+
+    info(f"\nVisit: [bold cyan]{code.verification_uri}[/bold cyan]")
+    info(f"And enter code: [bold yellow]{code.user_code}[/bold yellow]\n")
+    info("(opening browser automatically — if it doesn't, use the URL above)")
+    open_browser(code.verification_uri_complete)
+
+    info("Waiting for authorization...")
+    try:
+        token = poll_for_token(disc, code)
+    except RuntimeError as e:
+        error(str(e), code=3)
+
+    expires_at = int(time.time()) + int(token.get("expires_in", 3600))
+    save_credentials(
+        Credentials(
+            access_token=token["access_token"],
+            refresh_token=token.get("refresh_token"),
+            expires_at=expires_at,
+            issuer=disc.issuer,
+            client_id=disc.client_id,
+            resource=disc.resource,
+            api_url=api_url(),
+        )
+    )
+    success(f"logged in ({api_url()})")
+
+
+@app.command()
+def logout() -> None:
+    """Forget locally stored credentials for this deployment."""
+    if clear_credentials():
+        success("logged out")
+    else:
+        info("(no stored credentials)")
+
+
+@app.command()
+def whoami() -> None:
+    """Show the current logged-in identity."""
+    try:
+        body = request("GET", "/api/user/me")
+    except ApiError as e:
+        _fail(e)
+    emit(body.get("user", body))
+
+
+# ─── sites ───────────────────────────────────────────────────────────
+
+
+@sites_app.command("create")
+def sites_create(
+    name: str = typer.Option(..., "--name", "-n", help="Site name."),
+    domain: str = typer.Option(None, "--domain", "-d", help="Primary domain (verify later)."),
+    origin: list[str] = typer.Option(
+        None, "--origin", "-o", help="Allowed origin (repeatable)."
+    ),
+    description: str = typer.Option("", "--description", help="Optional description."),
+    test: bool = typer.Option(False, "--test", help="Issue a pk_test_ key instead of pk_live_."),
+) -> None:
+    """Create a site. Returns the site + its first embed key (shown ONCE)."""
+    origins = list(origin or [])
+    # A domain is also a natural allowed origin — fold it in if not given.
+    if domain and not origins:
+        origins = [f"https://{domain}"]
+    body = {"name": name, "description": description, "allowedOrigins": origins, "test": test}
+    try:
+        out = request("POST", "/api/sites", json_body=body)
+    except ApiError as e:
+        _fail(e)
+    emit(out)
+    if not is_json_mode():
+        info("\n[yellow]Save the `apiKey` — the plaintext is shown only once.[/yellow]")
+        if domain:
+            sid = out.get("site", {}).get("id")
+            info(f"[dim]Next: botu sites verify {sid} --domain {domain}[/dim]")
+
+
+@sites_app.command("list")
+def sites_list() -> None:
+    """List your sites."""
+    try:
+        out = request("GET", "/api/sites")
+    except ApiError as e:
+        _fail(e)
+    sites = out.get("sites", []) if isinstance(out, dict) else out
+    emit(
+        sites,
+        table_columns=[
+            ("ID", "id"),
+            ("Name", "name"),
+            ("Domain", "primary_domain"),
+            ("Status", "status"),
+            ("Key", "primaryKeyMasked"),
+            ("Created", "created_at"),
+        ],
+    )
+
+
+@sites_app.command("get")
+def sites_get(site_id: str = typer.Argument(..., help="Site id (uuid).")) -> None:
+    """Show one site with all its (masked) keys."""
+    try:
+        out = request("GET", f"/api/sites/{site_id}")
+    except ApiError as e:
+        _fail(e)
+    emit(out)
+
+
+@sites_app.command("delete")
+def sites_delete(
+    site_id: str = typer.Argument(..., help="Site id (uuid)."),
+    yes: bool = typer.Option(False, "--yes", "-y", help="Skip confirmation."),
+) -> None:
+    """Delete a site (cascades to its keys, users and usage)."""
+    _confirm(f"Delete site {site_id} and all its keys?", yes)
+    try:
+        out = request("DELETE", f"/api/sites/{site_id}")
+    except ApiError as e:
+        _fail(e)
+    emit(out or {"ok": True})
+
+
+@sites_app.command("verify")
+def sites_verify(
+    site_id: str = typer.Argument(..., help="Site id (uuid)."),
+    domain: str = typer.Option(..., "--domain", "-d", help="Domain to verify."),
+    check: bool = typer.Option(
+        False, "--check", help="Poll verification result instead of starting it."
+    ),
+) -> None:
+    """Verify domain ownership. Without --check: start it and print DNS instructions."""
+    if check:
+        try:
+            out = request(
+                "POST", f"/api/sites/{site_id}/verify-domain/check", json_body={"domain": domain}
+            )
+        except ApiError as e:
+            _fail(e)
+        emit(out)
+        if not is_json_mode() and not out.get("verified"):
+            info("[yellow]Not verified yet — add the DNS record, then retry --check.[/yellow]")
+        return
+
+    try:
+        out = request(
+            "POST", f"/api/sites/{site_id}/verify-domain/init", json_body={"domain": domain}
+        )
+    except ApiError as e:
+        _fail(e)
+    emit(out)
+    if not is_json_mode():
+        rec = (out.get("instructions") or {}).get("dns_record") or {}
+        if rec:
+            info(
+                f"\nAdd this DNS record, then run "
+                f"[bold]botu sites verify {site_id} --domain {domain} --check[/bold]:"
+            )
+            info(f"  [cyan]{rec.get('type')} {rec.get('name')} -> {rec.get('value')}[/cyan]")
+
+
+# ─── keys ────────────────────────────────────────────────────────────
+
+
+@keys_app.command("create")
+def keys_create(
+    site_id: str = typer.Option(..., "--site", "-s", help="Site id (uuid)."),
+    label: str = typer.Option("default", "--label", "-l", help="Human-friendly key label."),
+    test: bool = typer.Option(False, "--test", help="Issue a pk_test_ key instead of pk_live_."),
+) -> None:
+    """Create a new embed API key. The plaintext key is shown ONCE."""
+    try:
+        out = request(
+            "POST", f"/api/sites/{site_id}/keys", json_body={"label": label, "test": test}
+        )
+    except ApiError as e:
+        _fail(e)
+    emit(out)
+    if not is_json_mode():
+        info("\n[yellow]Save the `apiKey` — the plaintext is shown only once.[/yellow]")
+
+
+@keys_app.command("list")
+def keys_list(
+    site_id: str = typer.Option(..., "--site", "-s", help="Site id (uuid)."),
+) -> None:
+    """List a site's API keys (raw values never shown)."""
+    try:
+        out = request("GET", f"/api/sites/{site_id}")
+    except ApiError as e:
+        _fail(e)
+    emit(
+        out.get("keys", []),
+        table_columns=[
+            ("ID", "id"),
+            ("Label", "label"),
+            ("Key", "keyMasked"),
+            ("Revoked", "revokedAt"),
+            ("Last used", "lastUsedAt"),
+            ("Created", "createdAt"),
+        ],
+    )
+
+
+@keys_app.command("revoke")
+def keys_revoke(
+    key_id: int = typer.Argument(..., help="Key id (integer, from `keys list`)."),
+    site_id: str = typer.Option(..., "--site", "-s", help="Site id (uuid)."),
+    yes: bool = typer.Option(False, "--yes", "-y", help="Skip confirmation."),
+) -> None:
+    """Revoke an API key. Calls embedding it will then fail."""
+    _confirm(f"Revoke key {key_id} on site {site_id}?", yes)
+    try:
+        out = request(
+            "POST", f"/api/sites/{site_id}/keys/revoke", json_body={"keyId": key_id}
+        )
+    except ApiError as e:
+        _fail(e)
+    emit(out or {"ok": True})
+
+
+# ─── embed ───────────────────────────────────────────────────────────
+
+
+def _theme_data_attrs(strategy: dict | None) -> list[str]:
+    """Port of botu-web themeStrategyToDataAttrs (ThemeStrategyPicker.jsx)."""
+    s = strategy or {}
+    attrs: list[str] = []
+    mode = s.get("mode")
+    if mode == "fixed" and s.get("fixedTheme") in ("dark", "light"):
+        attrs.append(f'data-theme-fixed="{s["fixedTheme"]}"')
+    elif mode == "attr" and s.get("attr"):
+        attrs.append(f'data-theme-attr="{s["attr"]}"')
+        if s.get("attrDark"):
+            attrs.append(f'data-theme-attr-dark="{s["attrDark"]}"')
+        if s.get("target") == "body":
+            attrs.append('data-theme-target="body"')
+    elif mode == "class" and s.get("class"):
+        attrs.append(f'data-theme-class="{s["class"]}"')
+        if s.get("target") == "body":
+            attrs.append('data-theme-target="body"')
+    return attrs
+
+
+def _build_snippet(site: dict, api_key: str | None) -> str:
+    """Port of botu-web buildEmbedSnippet (site-detail-view.jsx)."""
+    key_value = api_key or "<YOUR_API_KEY>"
+    tenant_line = ""
+    if site.get("primary_domain") and site.get("domain_verified_at"):
+        tenant_line = f'\n  data-tenant="{site["primary_domain"]}"'
+    theme_attrs = _theme_data_attrs(site.get("theme_strategy"))
+    theme_lines = ("\n  " + "\n  ".join(theme_attrs)) if theme_attrs else ""
+    return (
+        "<script\n"
+        f"  src=\"{api_url()}/v1.js\"\n"
+        f'  data-api-key="{key_value}"{tenant_line}\n'
+        f'  data-user-id="OPTIONAL_USER_ID"{theme_lines}\n'
+        "  async></script>"
+    )
+
+
+_SNIPPET_RE = re.compile(
+    r"<script\b[^>]*\bsrc=[\"'][^\"']*v1\.js[\"'][^>]*>\s*</script>",
+    re.IGNORECASE | re.DOTALL,
+)
+
+
+@app.command()
+def embed(
+    site_id: str = typer.Option(..., "--site", "-s", help="Site id (uuid)."),
+    key: str = typer.Option(None, "--key", "-k", help="Embed key to put in the snippet."),
+    new_key: bool = typer.Option(
+        False, "--new-key", help="Mint a fresh embed key and use it in the snippet."
+    ),
+    write: str = typer.Option(
+        None, "--write", "-w", help="HTML file to inject the snippet into (before </body>)."
+    ),
+) -> None:
+    """Print the <script> embed snippet — or inject it into an HTML file.
+
+    Key resolution: --key wins; else --new-key mints one; else the snippet
+    uses a `<YOUR_API_KEY>` placeholder (the plaintext of existing keys is
+    never retrievable — mint a new one or pass --key).
+    """
+    try:
+        detail = request("GET", f"/api/sites/{site_id}")
+    except ApiError as e:
+        _fail(e)
+    site = detail.get("site") or {}
+
+    api_key = key
+    if not api_key and new_key:
+        try:
+            out = request(
+                "POST", f"/api/sites/{site_id}/keys", json_body={"label": "embed", "test": False}
+            )
+        except ApiError as e:
+            _fail(e)
+        api_key = out.get("apiKey")
+
+    snippet = _build_snippet(site, api_key)
+
+    if write:
+        try:
+            with open(write, "r", encoding="utf-8") as f:
+                html = f.read()
+        except OSError as e:
+            error(f"cannot read {write}: {e}", code=1)
+        if _SNIPPET_RE.search(html):
+            new_html = _SNIPPET_RE.sub(lambda _m: snippet, html, count=1)
+            action = "replaced"
+        elif re.search(r"</body>", html, re.IGNORECASE):
+            new_html = re.sub(
+                r"</body>", lambda _m: f"{snippet}\n{_m.group(0)}", html, count=1, flags=re.IGNORECASE
+            )
+            action = "injected"
+        else:
+            new_html = f"{html}\n{snippet}\n"
+            action = "appended"
+        try:
+            with open(write, "w", encoding="utf-8") as f:
+                f.write(new_html)
+        except OSError as e:
+            error(f"cannot write {write}: {e}", code=1)
+        if is_json_mode():
+            emit({"ok": True, "action": action, "file": write, "snippet": snippet})
+        else:
+            success(f"{action} embed snippet in {write}")
+        return
+
+    if is_json_mode():
+        emit({"snippet": snippet, "has_key": bool(api_key)})
+    else:
+        info(snippet)
+        if not api_key:
+            info(
+                "\n[dim]No key in snippet. Pass --key <pk_...> or --new-key, "
+                "or run `botu keys create --site <id>`.[/dim]"
+            )
+
+
+# ─── usage / test ────────────────────────────────────────────────────
+
+
+@app.command()
+def usage(
+    site_id: str = typer.Option(None, "--site", "-s", help="Limit to one site id."),
+) -> None:
+    """Per-site quota and usage."""
+    path = "/api/usage" + (f"?site={site_id}" if site_id else "")
+    try:
+        out = request("GET", path)
+    except ApiError as e:
+        _fail(e)
+    if is_json_mode():
+        emit(out)
+    else:
+        if out.get("note"):
+            info(f"[dim]{out['note']}[/dim]")
+        emit(
+            out.get("sites", []),
+            table_columns=[
+                ("Site", "site_id"),
+                ("Name", "name"),
+                ("Quota/mo", "monthly_quota_msgs"),
+                ("Consumed", "consumed_msgs"),
+                ("Status", "status"),
+            ],
+        )
+
+
+@app.command()
+def test(
+    site_id: str = typer.Option(..., "--site", "-s", help="Site id (uuid)."),
+    key: str = typer.Option(None, "--key", "-k", help="Embed key to test (default: mint one)."),
+) -> None:
+    """Verify an embed key works by running the loader's auth exchange.
+
+    Without --key a disposable pk_test_ key is minted for the check.
+    """
+    api_key = key
+    minted = False
+    if not api_key:
+        try:
+            out = request(
+                "POST",
+                f"/api/sites/{site_id}/keys",
+                json_body={"label": "cli-test", "test": True},
+            )
+        except ApiError as e:
+            _fail(e)
+        api_key = out.get("apiKey")
+        minted = True
+
+    # trailing slash — botu-web Next.js trailingSlash:true
+    url = f"{api_url()}/api/auth/exchange/"
+    payload = {"apiKey": api_key, "anonId": f"cli_{uuid.uuid4().hex[:16]}"}
+    try:
+        with httpx.Client(timeout=20.0, follow_redirects=True) as c:
+            r = c.post(url, json=payload)
+    except httpx.RequestError as e:
+        error(f"network error: {e}", code=2)
+    if not r.is_success:
+        error(
+            f"auth exchange failed ({r.status_code}): {r.text}",
+            code=1 if r.status_code < 500 else 3,
+        )
+    data = r.json()
+    ok = bool(data.get("token"))
+    result = {
+        "ok": ok,
+        "site_id": site_id,
+        "session_id": data.get("sessionId"),
+        "minted_test_key": minted,
+    }
+    if is_json_mode():
+        emit(result)
+    elif ok:
+        success(f"embed key valid — auth exchange OK (session {data.get('sessionId')})")
+        if minted:
+            info("[dim]A disposable pk_test_ key was minted for this check.[/dim]")
+    else:
+        error("auth exchange returned no token", code=3)
+
+
+@app.command()
+def version() -> None:
+    """Print CLI version."""
+    emit({"version": __version__})
+
+
+if __name__ == "__main__":
+    app()

botu_cli/client.py

@@ -0,0 +1,96 @@
+"""Thin httpx wrapper for the botu-web console API.
+
+Every console endpoint (`/api/sites*`, `/api/user/me`, `/api/usage`) is
+authenticated with the saved Logto JWT as a Bearer token. The public
+`/api/auth/exchange` endpoint (used by `botu test`) does NOT need a JWT and
+is called directly, not through `request()`.
+"""
+from __future__ import annotations
+
+from typing import Any
+
+import httpx
+
+from . import __version__
+from .config import Credentials, api_url, load_credentials
+
+
+class ApiError(RuntimeError):
+    def __init__(self, status: int, message: str, body: Any = None):
+        super().__init__(f"HTTP {status}: {message}")
+        self.status = status
+        self.message = message
+        self.body = body
+
+
+def _default_headers() -> dict[str, str]:
+    return {
+        "User-Agent": f"botu-cli/{__version__}",
+        "Accept": "application/json",
+    }
+
+
+def require_login() -> Credentials:
+    creds = load_credentials()
+    if creds is None or not creds.access_token:
+        raise ApiError(401, "not logged in — run `botu login` first")
+    return creds
+
+
+def with_trailing_slash(path: str) -> str:
+    """botu-web is a Next.js app with `trailingSlash: true` — every route
+    needs a `/` before the query string, else Next.js answers 308. We add it
+    so calls land directly without a redirect round-trip.
+    """
+    base, sep, query = path.partition("?")
+    if not base.endswith("/"):
+        base += "/"
+    return f"{base}{sep}{query}"
+
+
+def _raise(resp: httpx.Response) -> None:
+    if resp.is_success:
+        return
+    try:
+        body = resp.json()
+    except (ValueError, httpx.DecodingError):
+        body = resp.text
+    if isinstance(body, dict):
+        # botu-web errors are `{error, detail?}`; surface both when present.
+        msg = body.get("error") or body.get("detail") or resp.reason_phrase
+        if body.get("detail") and body.get("error"):
+            msg = f"{body['error']} ({body['detail']})"
+    else:
+        msg = resp.reason_phrase
+    raise ApiError(resp.status_code, str(msg), body)
+
+
+def request(
+    method: str,
+    path: str,
+    *,
+    json_body: Any | None = None,
+    timeout: float = 30.0,
+) -> Any:
+    """Call a botu-web console endpoint with the saved Logto JWT."""
+    creds = require_login()
+    headers = _default_headers()
+    headers["Authorization"] = f"Bearer {creds.access_token}"
+    url = f"{api_url()}{with_trailing_slash(path)}"
+    try:
+        # follow_redirects: belt-and-suspenders for the trailingSlash 308.
+        with httpx.Client(timeout=timeout, follow_redirects=True) as client:
+            resp = client.request(method, url, json=json_body, headers=headers)
+    except httpx.RequestError as e:
+        raise ApiError(0, f"network error: {e}") from e
+    _raise(resp)
+    if resp.status_code == 204 or not resp.content:
+        return None
+    return resp.json()
+
+
+def exit_code_for(err: ApiError) -> int:
+    """Map an ApiError onto a CLI exit code: 1 user / 2 network / 3 server."""
+    if err.status == 0:
+        return 2
+    return 1 if err.status < 500 else 3

botu_cli/config.py

@@ -0,0 +1,134 @@
+"""Local config + shared credential storage for the botu CLI.
+
+Token cache lives at ``~/.paradigx/auth.json`` — **shared** across every
+Paradigx product CLI (botu, tokenroute, ...). They all authenticate against
+the same Logto (auth.paradigx.com), so a single login is reused. See
+docs/specs/agent-first-cli.md §6.3.
+
+auth.json shape::
+
+    {
+      "version": 1,
+      "tokens": {
+        "<resource>": {
+          "access_token": "...", "refresh_token": "...",
+          "expires_at": 1234567890, "issuer": "...", "client_id": "...",
+          "resource": "...", "api_url": "https://botu.io"
+        }
+      }
+    }
+
+Entries are keyed by Logto resource indicator so multiple products / envs
+coexist. Retrieval picks the entry whose ``api_url`` matches the current
+target — that uniquely identifies "the credential for the deployment I'm
+talking to" (prod vs qa) without an extra discovery round-trip.
+"""
+from __future__ import annotations
+
+import json
+import os
+import stat
+from dataclasses import dataclass
+from pathlib import Path
+
+DEFAULT_API_URL = "https://botu.io"
+
+_CRED_FIELDS = (
+    "access_token",
+    "refresh_token",
+    "expires_at",
+    "issuer",
+    "client_id",
+    "resource",
+    "api_url",
+)
+
+
+def api_url() -> str:
+    """Target botu-web deployment. Override with BOTU_API_URL for qa / local."""
+    return os.environ.get("BOTU_API_URL", DEFAULT_API_URL).rstrip("/")
+
+
+def _config_dir() -> Path:
+    return Path.home() / ".paradigx"
+
+
+def _auth_path() -> Path:
+    return _config_dir() / "auth.json"
+
+
+@dataclass
+class Credentials:
+    access_token: str
+    refresh_token: str | None = None
+    expires_at: int | None = None  # unix seconds
+    issuer: str | None = None
+    client_id: str | None = None
+    resource: str | None = None
+    api_url: str | None = None
+
+
+def _read_store() -> dict:
+    p = _auth_path()
+    if not p.exists():
+        return {"version": 1, "tokens": {}}
+    try:
+        data = json.loads(p.read_text(encoding="utf-8"))
+    except (json.JSONDecodeError, OSError):
+        return {"version": 1, "tokens": {}}
+    if not isinstance(data, dict):
+        return {"version": 1, "tokens": {}}
+    if not isinstance(data.get("tokens"), dict):
+        data["tokens"] = {}
+    data.setdefault("version", 1)
+    return data
+
+
+def _write_store(store: dict) -> None:
+    d = _config_dir()
+    d.mkdir(parents=True, exist_ok=True)
+    p = _auth_path()
+    p.write_text(json.dumps(store, indent=2), encoding="utf-8")
+    # Owner-only read/write on POSIX. chmod is a near no-op on Windows but
+    # doesn't error, so we call it unconditionally.
+    try:
+        os.chmod(p, stat.S_IRUSR | stat.S_IWUSR)
+    except OSError:
+        pass
+
+
+def save_credentials(creds: Credentials) -> Path:
+    store = _read_store()
+    key = creds.resource or creds.api_url or "default"
+    store["tokens"][key] = {f: getattr(creds, f) for f in _CRED_FIELDS}
+    _write_store(store)
+    return _auth_path()
+
+
+def load_credentials() -> Credentials | None:
+    """Return the stored credential for the current ``api_url()``."""
+    store = _read_store()
+    target = api_url()
+    matches = [
+        v for v in store["tokens"].values() if isinstance(v, dict) and v.get("api_url") == target
+    ]
+    if not matches:
+        return None
+    best = max(matches, key=lambda v: v.get("expires_at") or 0)
+    return Credentials(**{f: best.get(f) for f in _CRED_FIELDS})
+
+
+def clear_credentials() -> bool:
+    """Drop credential(s) for the current ``api_url()``. True if anything removed."""
+    store = _read_store()
+    target = api_url()
+    kept = {
+        k: v
+        for k, v in store["tokens"].items()
+        if not (isinstance(v, dict) and v.get("api_url") == target)
+    }
+    if len(kept) == len(store["tokens"]):
+        return False
+    store["tokens"] = kept
+    _write_store(store)
+    return True

botu_cli/device_flow.py

@@ -0,0 +1,132 @@
+"""OIDC device-flow client — talks directly to Logto.
+
+Discovery happens via botu-web (`GET /api/auth/discovery`), so the CLI
+hardcodes no Logto URL or client_id. After polling succeeds we hand the
+token response back to the caller, who saves it via `config.save_credentials`.
+
+This is the OIDC-standard pattern: the client connects to the IdP, the
+resource server (botu-web) only validates tokens. See agent-first-cli.md §2.
+"""
+from __future__ import annotations
+
+import time
+import webbrowser
+from dataclasses import dataclass
+
+import httpx
+
+from .config import api_url
+
+# Per RFC 8628 §3.5 we honour the server's `interval`; this is a sane floor.
+_MIN_POLL_INTERVAL_SECONDS = 5
+
+
+@dataclass
+class DiscoveryInfo:
+    issuer: str
+    client_id: str
+    resource: str
+    scopes: list[str]
+    device_authorization_endpoint: str
+    token_endpoint: str
+
+
+@dataclass
+class DeviceCodeResponse:
+    device_code: str
+    user_code: str
+    verification_uri: str
+    verification_uri_complete: str
+    expires_in: int
+    interval: int
+
+
+def fetch_discovery() -> DiscoveryInfo:
+    """GET botu-web /api/auth/discovery/ (trailing slash — Next.js trailingSlash)."""
+    with httpx.Client(timeout=10.0, follow_redirects=True) as c:
+        r = c.get(f"{api_url()}/api/auth/discovery/")
+    r.raise_for_status()
+    data = r.json()
+    return DiscoveryInfo(
+        issuer=data["issuer"],
+        client_id=data["client_id"],
+        resource=data["resource"],
+        scopes=data["scopes"],
+        device_authorization_endpoint=data["device_authorization_endpoint"],
+        token_endpoint=data["token_endpoint"],
+    )
+
+
+def request_device_code(disc: DiscoveryInfo) -> DeviceCodeResponse:
+    """POST {device_authorization_endpoint} → device_code + user_code."""
+    with httpx.Client(timeout=10.0) as c:
+        r = c.post(
+            disc.device_authorization_endpoint,
+            data={
+                "client_id": disc.client_id,
+                "scope": " ".join(disc.scopes),
+                "resource": disc.resource,
+            },
+        )
+    r.raise_for_status()
+    body = r.json()
+    return DeviceCodeResponse(
+        device_code=body["device_code"],
+        user_code=body["user_code"],
+        verification_uri=body["verification_uri"],
+        verification_uri_complete=body.get(
+            "verification_uri_complete", body["verification_uri"]
+        ),
+        expires_in=body["expires_in"],
+        interval=max(body.get("interval", 5), _MIN_POLL_INTERVAL_SECONDS),
+    )
+
+
+def open_browser(url: str) -> bool:
+    """Best-effort. False on headless environments with no display."""
+    try:
+        return webbrowser.open(url)
+    except webbrowser.Error:
+        return False
+
+
+def poll_for_token(disc: DiscoveryInfo, code: DeviceCodeResponse, *, on_pending=None) -> dict:
+    """Poll {token_endpoint} until success / expired / denied.
+
+    Returns the raw token response dict. Raises RuntimeError with a
+    human-readable message on failure.
+    """
+    deadline = time.time() + code.expires_in
+    interval = code.interval
+    with httpx.Client(timeout=10.0) as client:
+        while time.time() < deadline:
+            time.sleep(interval)
+            r = client.post(
+                disc.token_endpoint,
+                data={
+                    "client_id": disc.client_id,
+                    "grant_type": "urn:ietf:params:oauth:grant-type:device_code",
+                    "device_code": code.device_code,
+                    "resource": disc.resource,
+                },
+            )
+            if r.is_success:
+                return r.json()
+            err = (
+                r.json().get("error")
+                if r.headers.get("content-type", "").startswith("application/json")
+                else None
+            )
+            if err == "authorization_pending":
+                if on_pending is not None:
+                    on_pending()
+                continue
+            if err == "slow_down":
+                interval += 5
+                continue
+            if err == "expired_token":
+                raise RuntimeError("device code expired — run `botu login` again")
+            if err == "access_denied":
+                raise RuntimeError("login denied by user")
+            raise RuntimeError(f"token exchange failed ({r.status_code}): {r.text}")
+    raise RuntimeError("device code expired before user completed login")

botu_cli/output.py

@@ -0,0 +1,66 @@
+"""Output helpers — toggle between human-friendly rich tables and --json."""
+from __future__ import annotations
+
+import json
+import os
+import sys
+from typing import Any
+
+from rich.console import Console
+from rich.table import Table
+
+_console = Console()
+_err_console = Console(stderr=True)
+
+
+def is_json_mode() -> bool:
+    """`--json` is set globally via env var (set by the Typer callback)."""
+    return os.environ.get("_BOTU_OUTPUT_JSON") == "1"
+
+
+def emit(payload: Any, *, table_columns: list[tuple[str, str]] | None = None) -> None:
+    """Print `payload` as JSON (agent mode) or a rich table / kv list (human mode).
+
+    `table_columns` is a list of `(header, dict_key)` pairs used when payload
+    is a list. Single dicts render as a key/value list; everything else falls
+    back to a plain print.
+    """
+    if is_json_mode():
+        print(json.dumps(payload, indent=2, default=str))
+        return
+
+    if isinstance(payload, list) and table_columns:
+        table = Table(show_header=True, header_style="bold")
+        for header, _ in table_columns:
+            table.add_column(header)
+        for row in payload:
+            table.add_row(*[str(row.get(k, "")) for _, k in table_columns])
+        _console.print(table)
+        return
+
+    if isinstance(payload, dict):
+        for k, v in payload.items():
+            _console.print(f"[bold]{k}[/bold]: {v}")
+        return
+
+    _console.print(payload)
+
+
+def info(msg: str) -> None:
+    if not is_json_mode():
+        _console.print(msg)
+
+
+def success(msg: str) -> None:
+    if not is_json_mode():
+        # ASCII-safe marker — Windows legacy GBK consoles can't encode U+2713.
+        _console.print(f"[green]OK[/green] {msg}")
+
+
+def error(msg: str, *, code: int = 1) -> None:
+    """Print an error and exit. code: 1 user / 2 network / 3 server."""
+    if is_json_mode():
+        print(json.dumps({"error": msg}, indent=2))
+    else:
+        _err_console.print(f"[red]error[/red]: {msg}")
+    sys.exit(code)

botu_cli-0.1.0.dist-info/METADATA

@@ -0,0 +1,95 @@
+Metadata-Version: 2.4
+Name: botu-cli
+Version: 0.1.0
+Summary: Agent-first CLI for botu — embeddable AI agent for any website
+Project-URL: Homepage, https://botu.io
+Project-URL: Repository, https://github.com/jiangjin11/botu-web
+Author: Paradigx Pte Ltd
+License: MIT
+Keywords: agent,ai,botu,cli,embed,widget
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+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: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.28
+Requires-Dist: rich>=13.0
+Requires-Dist: typer<1.0,>=0.15
+Provides-Extra: dev
+Requires-Dist: pytest-mock>=3.14; extra == 'dev'
+Requires-Dist: pytest>=8.3; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# botu (Python CLI)
+
+Agent-first CLI for [botu](https://botu.io) — the embeddable AI agent for any website.
+
+Register a site, get an embed key, verify your domain, and inject the
+`<script>` snippet — all from the command line, no web console needed.
+
+## Install
+
+```bash
+pip install botu-cli
+# or, run once without installing:
+uvx botu --help
+pipx run botu --help
+```
+
+## Quickstart
+
+```bash
+botu login                                          # OAuth device-flow, opens browser
+botu sites create --name acme --domain acme.com     # create a site + first embed key
+botu embed --site <site-id> --new-key --write index.html   # inject the <script>
+botu sites verify <site-id> --domain acme.com       # start domain verification
+botu sites verify <site-id> --domain acme.com --check   # confirm it
+botu test --site <site-id>                          # check the embed key works
+```
+
+All commands accept `--json` (or env `BOTU_JSON=1`) for machine-parseable
+output that's friendly to agents and CI.
+
+## Commands
+
+| Command | Purpose |
+|---|---|
+| `botu login` / `logout` / `whoami` | OAuth device-flow session |
+| `botu sites create\|list\|get\|delete` | Manage sites |
+| `botu sites verify <id> --domain <d> [--check]` | Domain ownership (DNS TXT) |
+| `botu keys create\|list\|revoke --site <id>` | Manage embed API keys |
+| `botu embed --site <id>` | Print / write the `<script>` embed snippet |
+| `botu usage [--site <id>]` | Per-site quota and usage |
+| `botu test --site <id>` | Verify an embed key via the loader auth exchange |
+
+### About embed keys
+
+The plaintext of an API key is shown **once** — at creation. `botu embed`
+therefore can't retrieve the key of an existing site. Either pass
+`--key pk_live_...`, or use `--new-key` to mint a fresh one and drop it
+straight into the snippet.
+
+## Configuration
+
+| Env var | Default | Purpose |
+|---|---|---|
+| `BOTU_API_URL` | `https://botu.io` | Target deployment (set to `https://qa.botu.io` for QA) |
+| `BOTU_JSON` | — | `1` forces JSON output globally |
+
+Credentials are stored in `~/.paradigx/auth.json`, **shared** with other
+Paradigx product CLIs (e.g. `tokenroute`) — they authenticate against the
+same Logto, so logging in once is reused across them.
+
+## Exit codes
+
+`0` ok · `1` user error (4xx) · `2` network error · `3` server error (5xx)
+
+---
+
+© 2026 Paradigx. All Rights Reserved.

botu_cli-0.1.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+botu_cli/__init__.py,sha256=kUR5RAFc7HCeiqdlX36dZOHkUI5wI6V_43RpEcD8b-0,22
+botu_cli/__main__.py,sha256=EpOdewe1rp_9VbKQGyCD6_JcMarFDIBdveSOS2ffApU,18410
+botu_cli/client.py,sha256=wnZk0JaVHEqeu7RpKEilVlGtVuhEBhEagUeiD3iA9o4,3061
+botu_cli/config.py,sha256=lw2JaKTDSAYyEmeA_Ldl6zNbSK1AZm7tLJ58rlQh6tc,3831
+botu_cli/device_flow.py,sha256=4KVaLI1zwC8OrtVrPPAhddtTDSdNsS2uhUNnvXvaaec,4389
+botu_cli/output.py,sha256=c24bEfJFPFgfQjfEEaH6vmAIP8iXUV39tjkcAhQLBwo,1979
+botu_cli-0.1.0.dist-info/METADATA,sha256=VK2LD_leij5RWt2qJmjulMVj1CMdj926hKqyzYrG0h8,3427
+botu_cli-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+botu_cli-0.1.0.dist-info/entry_points.txt,sha256=UYc164c40rjb3K9nm4V7TbUSFBnAOq1LqujSRR84SNw,47
+botu_cli-0.1.0.dist-info/RECORD,,

botu_cli-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

botu_cli-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+botu = botu_cli.__main__:app