botu-cli 0.1.0__tar.gz → 0.2.0__tar.gz

{botu_cli-0.1.0 → botu_cli-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: botu-cli
-Version: 0.1.0
+Version: 0.2.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
@@ -19,7 +19,7 @@ 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: paradigx-cli-core<0.2,>=0.1
 Requires-Dist: typer<1.0,>=0.15
 Provides-Extra: dev
 Requires-Dist: pytest-mock>=3.14; extra == 'dev'
@@ -49,7 +49,6 @@ botu login                                          # OAuth device-flow, opens b
 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
 ```
 
@@ -63,28 +62,45 @@ output that's friendly to agents and CI.
 | `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 keys create\|list\|revoke --site <id>` | Manage site embed API keys |
+| `botu tokens create\|list\|revoke` | Account access tokens (PATs) for CI |
 | `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
+## Non-interactive use (CI / headless agents)
 
-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.
+`botu login` needs a browser. For CI or headless agents, create an account
+**access token** once and pass it via the `BOTU_TOKEN` env var — no login,
+no browser:
+
+```bash
+botu tokens create --name ci --json     # → {"token": "bpat_...", ...}  shown ONCE
+export BOTU_TOKEN=bpat_...
+botu sites list                         # uses BOTU_TOKEN, no ~/.paradigx needed
+```
+
+Interactive sessions don't need this — the device-flow JWT is cached and
+**auto-refreshed**, so `botu login` is a one-time step per machine.
+
+### About embed keys vs account tokens
+
+- `pk_live_*` / `pk_test_*` — **site embed keys**, go in the `<script>` tag.
+- `bpat_*` — **account access tokens**, authenticate the CLI itself.
+
+Both plaintexts are shown **once**, at creation. `botu embed` can't retrieve
+an existing site's key — pass `--key` or use `--new-key` to mint a fresh one.
 
 ## Configuration
 
 | Env var | Default | Purpose |
 |---|---|---|
-| `BOTU_API_URL` | `https://botu.io` | Target deployment (set to `https://qa.botu.io` for QA) |
+| `BOTU_API_URL` | `https://botu.io` | Target deployment (`https://qa.botu.io` for QA) |
+| `BOTU_TOKEN` | — | Account access token — skips login (CI / agents) |
 | `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.
+Paradigx product CLIs (e.g. `tokenroute`) — log in once, reuse everywhere.
 
 ## Exit codes
 

{botu_cli-0.1.0 → botu_cli-0.2.0}/README.md

@@ -21,7 +21,6 @@ botu login                                          # OAuth device-flow, opens b
 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
 ```
 
@@ -35,28 +34,45 @@ output that's friendly to agents and CI.
 | `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 keys create\|list\|revoke --site <id>` | Manage site embed API keys |
+| `botu tokens create\|list\|revoke` | Account access tokens (PATs) for CI |
 | `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
+## Non-interactive use (CI / headless agents)
 
-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.
+`botu login` needs a browser. For CI or headless agents, create an account
+**access token** once and pass it via the `BOTU_TOKEN` env var — no login,
+no browser:
+
+```bash
+botu tokens create --name ci --json     # → {"token": "bpat_...", ...}  shown ONCE
+export BOTU_TOKEN=bpat_...
+botu sites list                         # uses BOTU_TOKEN, no ~/.paradigx needed
+```
+
+Interactive sessions don't need this — the device-flow JWT is cached and
+**auto-refreshed**, so `botu login` is a one-time step per machine.
+
+### About embed keys vs account tokens
+
+- `pk_live_*` / `pk_test_*` — **site embed keys**, go in the `<script>` tag.
+- `bpat_*` — **account access tokens**, authenticate the CLI itself.
+
+Both plaintexts are shown **once**, at creation. `botu embed` can't retrieve
+an existing site's key — pass `--key` or use `--new-key` to mint a fresh one.
 
 ## Configuration
 
 | Env var | Default | Purpose |
 |---|---|---|
-| `BOTU_API_URL` | `https://botu.io` | Target deployment (set to `https://qa.botu.io` for QA) |
+| `BOTU_API_URL` | `https://botu.io` | Target deployment (`https://qa.botu.io` for QA) |
+| `BOTU_TOKEN` | — | Account access token — skips login (CI / agents) |
 | `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.
+Paradigx product CLIs (e.g. `tokenroute`) — log in once, reuse everywhere.
 
 ## Exit codes
 

{botu_cli-0.1.0 → botu_cli-0.2.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "botu-cli"
-version = "0.1.0"
+version = "0.2.0"
 description = "Agent-first CLI for botu — embeddable AI agent for any website"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -21,9 +21,9 @@ classifiers = [
 ]
 
 dependencies = [
+    "paradigx-cli-core>=0.1,<0.2",
     "typer>=0.15,<1.0",
     "httpx>=0.28",
-    "rich>=13.0",
 ]
 
 [project.optional-dependencies]

botu_cli-0.2.0/src/botu_cli/__init__.py

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

{botu_cli-0.1.0 → botu_cli-0.2.0}/src/botu_cli/__main__.py

@@ -1,28 +1,23 @@
 """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 login / logout / whoami
+  botu sites create|list|get|delete|verify
+  botu keys create|list|revoke
+  botu tokens create|list|revoke          # account-level PATs (CI / headless)
+  botu embed --site <id>
   botu usage [--site <id>]
-  botu test --site <id> [--key <k>]
+  botu test --site <id>
 
-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.
+All commands accept `--json` (or env BOTU_JSON=1). Auth: `botu login`
+(device-flow, cached + auto-refreshed in ~/.paradigx/auth.json), or set
+`BOTU_TOKEN` to an account PAT for non-interactive use. See
+docs/specs/agent-first-cli.md and docs/specs/cli-phase-b.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
@@ -37,12 +32,22 @@ if sys.platform == "win32":
 
 import httpx
 import typer
+from paradigx_cli_core import (
+    ApiError,
+    clear_credentials,
+    do_login,
+    emit,
+    error,
+    exit_code_for,
+    info,
+    is_json_mode,
+    open_browser,
+    set_json_mode,
+    success,
+)
 
 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
+from .product import api, api_url, discovery_url
 
 app = typer.Typer(
     name="botu",
@@ -52,8 +57,12 @@ app = typer.Typer(
 )
 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)
+tokens_app = typer.Typer(
+    name="tokens", help="Manage account access tokens (PATs).", no_args_is_help=True
+)
 app.add_typer(sites_app, name="sites")
 app.add_typer(keys_app, name="keys")
+app.add_typer(tokens_app, name="tokens")
 
 
 def _global_callback(
@@ -62,7 +71,7 @@ def _global_callback(
     ),
 ) -> None:
     if json_output or os.environ.get("BOTU_JSON") == "1":
-        os.environ["_BOTU_OUTPUT_JSON"] = "1"
+        set_json_mode(True)
 
 
 app.callback()(_global_callback)
@@ -88,50 +97,31 @@ def _confirm(prompt: str, yes: bool) -> None:
 @app.command()
 def login() -> None:
     """Log in via OAuth device-flow (opens browser)."""
+
+    def on_code(code) -> None:
+        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:
-        disc = fetch_discovery()
+        do_login(discovery_url(), api_url(), on_code=on_code)
     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
+    except httpx.RequestError as e:
         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():
+    if clear_credentials(api_url()):
         success("logged out")
     else:
         info("(no stored credentials)")
@@ -141,7 +131,7 @@ def logout() -> None:
 def whoami() -> None:
     """Show the current logged-in identity."""
     try:
-        body = request("GET", "/api/user/me")
+        body = api("GET", "/api/user/me")
     except ApiError as e:
         _fail(e)
     emit(body.get("user", body))
@@ -154,20 +144,17 @@ def whoami() -> None:
 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)."
-    ),
+    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)
+        out = api("POST", "/api/sites", body)
     except ApiError as e:
         _fail(e)
     emit(out)
@@ -182,7 +169,7 @@ def sites_create(
 def sites_list() -> None:
     """List your sites."""
     try:
-        out = request("GET", "/api/sites")
+        out = api("GET", "/api/sites")
     except ApiError as e:
         _fail(e)
     sites = out.get("sites", []) if isinstance(out, dict) else out
@@ -203,7 +190,7 @@ def sites_list() -> None:
 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}")
+        out = api("GET", f"/api/sites/{site_id}")
     except ApiError as e:
         _fail(e)
     emit(out)
@@ -217,7 +204,7 @@ def sites_delete(
     """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}")
+        out = api("DELETE", f"/api/sites/{site_id}")
     except ApiError as e:
         _fail(e)
     emit(out or {"ok": True})
@@ -234,9 +221,7 @@ def sites_verify(
     """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}
-            )
+            out = api("POST", f"/api/sites/{site_id}/verify-domain/check", {"domain": domain})
         except ApiError as e:
             _fail(e)
         emit(out)
@@ -245,9 +230,7 @@ def sites_verify(
         return
 
     try:
-        out = request(
-            "POST", f"/api/sites/{site_id}/verify-domain/init", json_body={"domain": domain}
-        )
+        out = api("POST", f"/api/sites/{site_id}/verify-domain/init", {"domain": domain})
     except ApiError as e:
         _fail(e)
     emit(out)
@@ -272,9 +255,7 @@ def keys_create(
 ) -> 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}
-        )
+        out = api("POST", f"/api/sites/{site_id}/keys", {"label": label, "test": test})
     except ApiError as e:
         _fail(e)
     emit(out)
@@ -288,7 +269,7 @@ def keys_list(
 ) -> None:
     """List a site's API keys (raw values never shown)."""
     try:
-        out = request("GET", f"/api/sites/{site_id}")
+        out = api("GET", f"/api/sites/{site_id}")
     except ApiError as e:
         _fail(e)
     emit(
@@ -313,9 +294,69 @@ def keys_revoke(
     """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}
-        )
+        out = api("POST", f"/api/sites/{site_id}/keys/revoke", {"keyId": key_id})
+    except ApiError as e:
+        _fail(e)
+    emit(out or {"ok": True})
+
+
+# ─── tokens (account-level PATs) ─────────────────────────────────────
+
+
+@tokens_app.command("create")
+def tokens_create(
+    name: str = typer.Option(..., "--name", "-n", help="Token label."),
+    expires_days: int = typer.Option(
+        None, "--expires-days", help="Expire after N days (default: never)."
+    ),
+) -> None:
+    """Create an account access token (PAT). The plaintext is shown ONCE.
+
+    Use it non-interactively via the BOTU_TOKEN env var — for CI / agents.
+    """
+    body: dict = {"name": name}
+    if expires_days is not None:
+        body["expiresInDays"] = expires_days
+    try:
+        out = api("POST", "/api/tokens", body)
+    except ApiError as e:
+        _fail(e)
+    emit(out)
+    if not is_json_mode():
+        info("\n[yellow]Save the `token` — the plaintext is shown only once.[/yellow]")
+        info("[dim]Use it as: export BOTU_TOKEN=<token>[/dim]")
+
+
+@tokens_app.command("list")
+def tokens_list() -> None:
+    """List your account access tokens (plaintext never shown)."""
+    try:
+        out = api("GET", "/api/tokens")
+    except ApiError as e:
+        _fail(e)
+    emit(
+        out.get("tokens", []),
+        table_columns=[
+            ("ID", "id"),
+            ("Name", "name"),
+            ("Prefix", "token_prefix"),
+            ("Last used", "last_used_at"),
+            ("Revoked", "revoked_at"),
+            ("Expires", "expires_at"),
+            ("Created", "created_at"),
+        ],
+    )
+
+
+@tokens_app.command("revoke")
+def tokens_revoke(
+    token_id: str = typer.Argument(..., help="Token id (uuid, from `tokens list`)."),
+    yes: bool = typer.Option(False, "--yes", "-y", help="Skip confirmation."),
+) -> None:
+    """Revoke an account access token."""
+    _confirm(f"Revoke token {token_id}?", yes)
+    try:
+        out = api("POST", f"/api/tokens/{token_id}/revoke")
     except ApiError as e:
         _fail(e)
     emit(out or {"ok": True})
@@ -381,11 +422,10 @@ def embed(
     """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).
+    uses a `<YOUR_API_KEY>` placeholder.
     """
     try:
-        detail = request("GET", f"/api/sites/{site_id}")
+        detail = api("GET", f"/api/sites/{site_id}")
     except ApiError as e:
         _fail(e)
     site = detail.get("site") or {}
@@ -393,9 +433,7 @@ def embed(
     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}
-            )
+            out = api("POST", f"/api/sites/{site_id}/keys", {"label": "embed", "test": False})
         except ApiError as e:
             _fail(e)
         api_key = out.get("apiKey")
@@ -413,7 +451,11 @@ def embed(
             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
+                r"</body>",
+                lambda _m: f"{snippet}\n{_m.group(0)}",
+                html,
+                count=1,
+                flags=re.IGNORECASE,
             )
             action = "injected"
         else:
@@ -451,7 +493,7 @@ def usage(
     """Per-site quota and usage."""
     path = "/api/usage" + (f"?site={site_id}" if site_id else "")
     try:
-        out = request("GET", path)
+        out = api("GET", path)
     except ApiError as e:
         _fail(e)
     if is_json_mode():
@@ -484,11 +526,7 @@ def test(
     minted = False
     if not api_key:
         try:
-            out = request(
-                "POST",
-                f"/api/sites/{site_id}/keys",
-                json_body={"label": "cli-test", "test": True},
-            )
+            out = api("POST", f"/api/sites/{site_id}/keys", {"label": "cli-test", "test": True})
         except ApiError as e:
             _fail(e)
         api_key = out.get("apiKey")

botu_cli-0.2.0/src/botu_cli/product.py

@@ -0,0 +1,56 @@
+"""botu-specific glue around paradigx-cli-core.
+
+Holds the values that distinguish botu from other Paradigx CLIs (API URL,
+discovery path, the trailingSlash quirk, the PAT env var) and the auth
+resolution policy.
+"""
+from __future__ import annotations
+
+import os
+
+from paradigx_cli_core import ApiError, NeedLogin, request, valid_access_token
+
+from . import __version__
+
+DEFAULT_API_URL = "https://botu.io"
+API_URL_ENV = "BOTU_API_URL"
+TOKEN_ENV = "BOTU_TOKEN"  # account-level PAT for CI / headless agents
+DISCOVERY_PATH = "/api/auth/discovery/"
+TRAILING_SLASH = True  # botu-web is a Next.js app with trailingSlash:true
+
+
+def api_url() -> str:
+    """Target botu-web deployment. Override with BOTU_API_URL for qa / local."""
+    return os.environ.get(API_URL_ENV, DEFAULT_API_URL).rstrip("/")
+
+
+def discovery_url() -> str:
+    return f"{api_url()}{DISCOVERY_PATH}"
+
+
+def resolve_token() -> str:
+    """Bearer token for an API call.
+
+    1. ``BOTU_TOKEN`` env (account-level PAT) — CI / headless, no login.
+    2. else the cached device-flow JWT, auto-refreshed when near expiry.
+    """
+    env = os.environ.get(TOKEN_ENV)
+    if env and env.strip():
+        return env.strip()
+    try:
+        return valid_access_token(api_url())
+    except NeedLogin as e:
+        raise ApiError(401, str(e)) from e
+
+
+def api(method: str, path: str, json_body=None):
+    """Call a botu-web console endpoint with the resolved bearer token."""
+    return request(
+        method,
+        api_url(),
+        path,
+        token=resolve_token(),
+        json_body=json_body,
+        trailing_slash=TRAILING_SLASH,
+        user_agent=f"botu-cli/{__version__}",
+    )