real-browser-cli 0.14.2__py3-none-any.whl

browser_cli/commands/navigate.py

@@ -0,0 +1,96 @@
+import click
+from browser_cli.commands import client_from_ctx, handle_errors, tab_option
+from rich.console import Console
+
+console = Console()
+
+@click.group("nav")
+def nav_group():
+    """Navigate — open URLs, reload, go back/forward, focus tabs."""
+
+@nav_group.command("open")
+@click.argument("url")
+@click.option("--focus", is_flag=True, help="Bring the opened tab/window to the front")
+@click.option("--window", "window_name", default=None, help="Open in named window")
+@click.option("--group", "group_name", default=None, help="Open directly into a tab group (name or ID)")
+@click.option("--reuse", is_flag=True, help="Reuse an existing tab with exactly this URL")
+@click.option("--reuse-domain", is_flag=True, help="Reuse an existing tab with the same domain")
+@click.option("--reuse-title", default=None, metavar="TEXT", help="Reuse an existing tab whose title contains TEXT")
+@handle_errors
+def cmd_open(url, focus, window_name, group_name, reuse, reuse_domain, reuse_title):
+    """Open URL in a new tab without stealing focus by default."""
+    client_from_ctx().nav.open(url, focus=focus, window=window_name, group=group_name, reuse=reuse, reuse_domain=reuse_domain, reuse_title=reuse_title)
+    suffix = ""
+    if group_name:
+        suffix = f" in group '{group_name}'"
+    elif window_name:
+        suffix = f" in window '{window_name}'"
+    console.print(f"[green]Opened:[/green] {url}{suffix}")
+
+@nav_group.command("reload")
+@click.argument("tab_id", type=int, required=False)
+@handle_errors
+def cmd_reload(tab_id):
+    """Reload the active (or specified) tab."""
+    client_from_ctx().nav.reload(tab_id)
+    console.print("[green]Reloaded[/green]")
+
+@nav_group.command("hard-reload")
+@click.argument("tab_id", type=int, required=False)
+@handle_errors
+def cmd_hard_reload(tab_id):
+    """Hard reload (bypass cache) the active (or specified) tab."""
+    client_from_ctx().nav.hard_reload(tab_id)
+    console.print("[green]Hard reloaded[/green]")
+
+@nav_group.command("back")
+@click.argument("tab_id", type=int, required=False)
+@handle_errors
+def cmd_back(tab_id):
+    """Navigate back in the active (or specified) tab."""
+    client_from_ctx().nav.back(tab_id)
+    console.print("[green]Navigated back[/green]")
+
+@nav_group.command("forward")
+@click.argument("tab_id", type=int, required=False)
+@handle_errors
+def cmd_forward(tab_id):
+    """Navigate forward in the active (or specified) tab."""
+    client_from_ctx().nav.forward(tab_id)
+    console.print("[green]Navigated forward[/green]")
+
+@nav_group.command("focus")
+@click.argument("pattern")
+@handle_errors
+def cmd_focus(pattern):
+    """Jump to a tab by URL pattern or tab ID."""
+    result = client_from_ctx().nav.focus(pattern)
+    if result:
+        console.print(f"[green]Focused:[/green] {result.get('url', result)}")
+    else:
+        console.print(f"[yellow]No tab found matching:[/yellow] {pattern}")
+
+@nav_group.command("open-wait")
+@click.argument("url")
+@click.option("--timeout", type=float, default=30.0, show_default=True, help="Max seconds to wait for load")
+@click.option("--focus", is_flag=True, help="Bring the opened tab/window to the front")
+@click.option("--window", "window_name", default=None, help="Open in named window")
+@click.option("--group", "group_name", default=None, help="Open in tab group")
+@click.option("--reuse", is_flag=True, help="Reuse an existing tab with exactly this URL")
+@click.option("--reuse-domain", is_flag=True, help="Reuse an existing tab with the same domain")
+@click.option("--reuse-title", default=None, metavar="TEXT", help="Reuse an existing tab whose title contains TEXT")
+@handle_errors
+def cmd_open_wait(url, timeout, focus, window_name, group_name, reuse, reuse_domain, reuse_title):
+    """Open URL in a new tab and wait until fully loaded."""
+    tab = client_from_ctx().nav.open_wait(url, timeout=timeout, focus=focus, window=window_name, group=group_name, reuse=reuse, reuse_domain=reuse_domain, reuse_title=reuse_title)
+    console.print(f"[green]Loaded:[/green] {url}" + (f" — {tab.title}" if tab.title else ""))
+
+@nav_group.command("wait")
+@tab_option
+@click.option("--timeout", type=float, default=30.0, show_default=True, help="Max seconds to wait")
+@click.option("--ready-state", type=click.Choice(["complete", "interactive"]), default="complete", show_default=True, help="Target ready state")
+@handle_errors
+def cmd_wait(tab_id, timeout, ready_state):
+    """Wait until tab finishes loading."""
+    tab = client_from_ctx().tabs.wait_for_load(tab_id, timeout=timeout, ready_state=ready_state)
+    console.print(f"[green]Ready:[/green] {tab.url} — {tab.title}")

browser_cli/commands/page.py

@@ -0,0 +1,26 @@
+import click
+from browser_cli.commands import client_from_ctx, handle_errors
+from rich.console import Console
+from rich.table import Table
+
+console = Console()
+
+@click.group("page")
+def page_group():
+    """Inspect current page metadata."""
+
+@page_group.command("info")
+@handle_errors
+def page_info():
+    """Show title, URL, readyState, language, and meta tags of the active tab."""
+    info = client_from_ctx().page.info()
+    table = Table(show_header=False)
+    table.add_column("Field", style="bold cyan", no_wrap=True)
+    table.add_column("Value")
+    table.add_row("Title",      info.get("title") or "")
+    table.add_row("URL",        info.get("url") or "")
+    table.add_row("Ready",      info.get("readyState") or "")
+    table.add_row("Lang",       info.get("lang") or "")
+    for key, val in (info.get("meta") or {}).items():
+        table.add_row(f"meta:{key}", val)
+    console.print(table)

browser_cli/commands/perf.py

@@ -0,0 +1,47 @@
+import click
+from rich.console import Console
+from rich.table import Table
+from browser_cli.commands import client_from_ctx, handle_errors
+
+console = Console()
+
+@click.group("perf")
+def perf_group():
+    """Inspect and tune browser-cli performance behavior."""
+
+@perf_group.command("status")
+@handle_errors
+def perf_status():
+    """Show performance profile, throttle and running jobs."""
+    result = client_from_ctx().perf.status()
+    console.print(f"Profile: [bold]{result.get('performanceProfile', 'auto')}[/bold]")
+    console.print(f"Audible tabs: {'yes' if result.get('audible') else 'no'}")
+    throttle = result.get("throttle") or {}
+    console.print(f"Throttle: batch={throttle.get('batchSize')} pause={throttle.get('pauseMs')}ms mode={throttle.get('mode')}")
+
+    jobs = result.get("jobs") or []
+    if not jobs:
+        console.print("[yellow]No running jobs[/yellow]")
+        return
+
+    table = Table(show_header=True, header_style="bold cyan")
+    table.add_column("Job")
+    table.add_column("Command")
+    table.add_column("Status")
+    table.add_column("Progress", justify="right")
+    table.add_column("Phase")
+    for job in jobs:
+        total = job.get("total")
+        current = job.get("current") or 0
+        percent = job.get("percent") or 0
+        progress = f"{current}/{total} ({percent}%)" if total else f"{percent}%"
+        table.add_row(job.get("id", ""), job.get("command", ""), job.get("status", ""), progress, job.get("phase", ""))
+    console.print(table)
+
+@perf_group.command("profile")
+@click.argument("profile", type=click.Choice(["auto", "normal", "gentle", "ultra"]))
+@handle_errors
+def perf_profile(profile):
+    """Set global performance profile."""
+    result = client_from_ctx().perf.set_profile(profile)
+    console.print(f"[green]Performance profile set to {result.get('performanceProfile', profile)}[/green]")

browser_cli/commands/raw.py

@@ -0,0 +1,23 @@
+from __future__ import annotations
+
+import json
+
+import click
+
+from browser_cli.command_security import CommandPolicy, assert_command_allowed
+from browser_cli.commands import client_from_ctx, handle_errors
+
+@click.command("command")
+@click.argument("name")
+@click.argument("args_json", required=False, default="{}")
+@click.option("--allow-read-page", is_flag=True, help="Allow page-content read commands such as extract.* and dom.text")
+@click.option("--allow-control", is_flag=True, help="Allow browser-control commands such as nav.*, tabs.close, dom.click")
+@click.option("--allow-dangerous", is_flag=True, help="Allow high-risk commands such as dom.eval, storage.*, screenshots")
+@handle_errors
+def cmd_command(name, args_json, allow_read_page, allow_control, allow_dangerous):
+    """Send a raw browser-cli wire command and print JSON."""
+    policy = CommandPolicy(allow_read_page=allow_read_page, allow_control=allow_control, allow_dangerous=allow_dangerous)
+    assert_command_allowed(name, policy)
+    args = json.loads(args_json) if args_json else {}
+    result = client_from_ctx().command(name, args)
+    click.echo(json.dumps(result, indent=2, default=str))

browser_cli/commands/remote.py

@@ -0,0 +1,68 @@
+from __future__ import annotations
+
+import json
+
+import click
+from rich.console import Console
+from rich.table import Table
+
+from browser_cli import BrowserCLI
+from browser_cli.commands import handle_errors
+from browser_cli.remote.registry import REMOTE_REGISTRY_PATH, load_remotes, save_remote_key
+
+console = Console()
+
+@click.group("remote")
+def remote_group():
+    """Manage remembered browser-cli remote endpoints."""
+
+@remote_group.command("status")
+@click.argument("endpoint")
+@click.option("--key", default=None, help="Key spec/path to use for this probe")
+@handle_errors
+def remote_status(endpoint, key):
+    """Probe a remote endpoint and show server/client status."""
+    client = BrowserCLI(remote=endpoint, key=key)
+    clients = client.clients()
+    table = Table(show_header=True, header_style="bold cyan")
+    table.add_column("Profile")
+    table.add_column("Browser")
+    table.add_column("Extension")
+    for item in clients:
+        table.add_row(str(item.get("profile", "")), str(item.get("name", "")), str(item.get("extensionVersion", "")))
+    console.print(table)
+
+@remote_group.command("trust")
+@click.argument("endpoint")
+@click.argument("key_spec")
+def remote_trust(endpoint, key_spec):
+    """Remember which key spec to use for ENDPOINT."""
+    save_remote_key(endpoint, key_spec)
+    console.print(f"[green]Trusted remote {endpoint} with key {key_spec}[/green]")
+
+@remote_group.command("keys")
+def remote_keys():
+    """List remembered remote key specs."""
+    remotes = load_remotes()
+    if not remotes:
+        console.print("[yellow]No remembered remotes[/yellow]")
+        return
+    table = Table(show_header=True, header_style="bold cyan")
+    table.add_column("Endpoint")
+    table.add_column("Key")
+    for endpoint, cfg in sorted(remotes.items()):
+        table.add_row(endpoint, str(cfg.get("key", "")))
+    console.print(table)
+
+@remote_group.command("revoke")
+@click.argument("endpoint")
+def remote_revoke(endpoint):
+    """Remove remembered key/config for ENDPOINT."""
+    remotes = load_remotes()
+    if endpoint not in remotes:
+        console.print(f"[yellow]Remote {endpoint} not remembered[/yellow]")
+        return
+    del remotes[endpoint]
+    REMOTE_REGISTRY_PATH.parent.mkdir(parents=True, exist_ok=True)
+    REMOTE_REGISTRY_PATH.write_text(json.dumps(remotes, indent=2, sort_keys=True) + "\n", encoding="utf-8")
+    console.print(f"[green]Revoked {endpoint}[/green]")

browser_cli/commands/script.py

@@ -0,0 +1,68 @@
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import click
+from rich.console import Console
+
+from browser_cli.command_security import CommandPolicy, assert_command_allowed
+from browser_cli.commands import client_from_ctx, handle_errors
+
+console = Console()
+
+def _load_steps(path: Path):
+    text = path.read_text(encoding="utf-8")
+    if path.suffix.lower() in {".yaml", ".yml"}:
+        try:
+            import yaml  # type: ignore
+        except Exception as exc:
+            raise click.ClickException("YAML scripts require PyYAML; use JSON or install PyYAML") from exc
+        return yaml.safe_load(text)
+    return json.loads(text)
+
+def _parse_step(step):
+    if isinstance(step, str):
+        return step, {}
+    if isinstance(step, dict):
+        if "command" in step:
+            return step["command"], step.get("args") or {}
+        if len(step) == 1:
+            command, args = next(iter(step.items()))
+            return command, args or {}
+    raise click.ClickException(f"Invalid script step: {step!r}")
+
+@click.command("script")
+@click.argument("file", type=click.Path(exists=True, dir_okay=False, path_type=Path))
+@click.option("--json", "json_output", is_flag=True, help="Print all step results as JSON")
+@click.option("--continue-on-error", is_flag=True, help="Continue after failed steps")
+@click.option("--allow-read-page", is_flag=True, help="Allow page-content read commands such as extract.* and dom.text")
+@click.option("--allow-control", is_flag=True, help="Allow browser-control commands such as nav.*, tabs.close, dom.click")
+@click.option("--allow-dangerous", is_flag=True, help="Allow high-risk commands such as dom.eval, storage.*, screenshots")
+@handle_errors
+def cmd_script(file: Path, json_output: bool, continue_on_error: bool, allow_read_page: bool, allow_control: bool, allow_dangerous: bool):
+    """Run a JSON/YAML batch script of browser-cli wire commands."""
+    steps = _load_steps(file)
+    if not isinstance(steps, list):
+        raise click.ClickException("Script root must be a list")
+    client = client_from_ctx()
+    policy = CommandPolicy(allow_read_page=allow_read_page, allow_control=allow_control, allow_dangerous=allow_dangerous)
+    results = []
+    for index, step in enumerate(steps, start=1):
+        command, args = _parse_step(step)
+        try:
+            assert_command_allowed(command, policy)
+            result = client.command(command, args)
+            results.append({"index": index, "command": command, "ok": True, "result": result})
+            if not json_output:
+                console.print(f"[green]✓[/green] {index}: {command}")
+        except Exception as exc:
+            results.append({"index": index, "command": command, "ok": False, "error": str(exc)})
+            if not continue_on_error:
+                if json_output:
+                    click.echo(json.dumps(results, indent=2, default=str))
+                raise
+            if not json_output:
+                console.print(f"[red]✗[/red] {index}: {command}: {exc}")
+    if json_output:
+        click.echo(json.dumps(results, indent=2, default=str))

browser_cli/commands/search.py

@@ -0,0 +1,79 @@
+import click
+from browser_cli.commands import client_from_ctx, handle_errors
+from rich.console import Console
+
+console = Console()
+
+ENGINES = {
+    "google":        "https://www.google.com/search?q={query}",
+    "brave":         "https://search.brave.com/search?q={query}",
+    "duckduckgo":    "https://duckduckgo.com/?q={query}",
+    "ddg":           "https://duckduckgo.com/?q={query}",
+    "youtube":       "https://www.youtube.com/results?search_query={query}",
+    "yt":            "https://www.youtube.com/results?search_query={query}",
+    "spotify":       "https://open.spotify.com/search/{query}",
+    "amazon":        "https://www.amazon.com/s?k={query}",
+    "ecosia":        "https://www.ecosia.org/search?q={query}",
+    "furaffinity":   "https://www.furaffinity.net/search/?q={query}",
+    "fa":            "https://www.furaffinity.net/search/?q={query}",
+    "bing":          "https://www.bing.com/search?q={query}",
+    "github":        "https://github.com/search?q={query}",
+    "wikipedia":     "https://en.wikipedia.org/wiki/Special:Search?search={query}",
+    "wiki":          "https://en.wikipedia.org/wiki/Special:Search?search={query}",
+    "reddit":        "https://www.reddit.com/search/?q={query}",
+    "stackoverflow": "https://stackoverflow.com/search?q={query}",
+    "so":            "https://stackoverflow.com/search?q={query}",
+}
+
+_DISPLAY_NAMES = {
+    "google": "Google", "brave": "Brave Search", "duckduckgo": "DuckDuckGo",
+    "ddg": "DuckDuckGo", "youtube": "YouTube", "yt": "YouTube",
+    "spotify": "Spotify", "amazon": "Amazon", "ecosia": "Ecosia",
+    "furaffinity": "FurAffinity", "fa": "FurAffinity", "bing": "Bing",
+    "github": "GitHub", "wikipedia": "Wikipedia", "wiki": "Wikipedia",
+    "reddit": "Reddit", "stackoverflow": "Stack Overflow", "so": "Stack Overflow",
+}
+
+_SUBCOMMANDS = [
+    ("google",        "Search with Google."),
+    ("brave",         "Search with Brave Search."),
+    ("duckduckgo",    "Search with DuckDuckGo."),
+    ("ddg",           "Search with DuckDuckGo (alias for duckduckgo)."),
+    ("youtube",       "Search YouTube videos."),
+    ("yt",            "Search YouTube (alias for youtube)."),
+    ("spotify",       "Search Spotify."),
+    ("amazon",        "Search Amazon."),
+    ("ecosia",        "Search with Ecosia."),
+    ("furaffinity",   "Search FurAffinity."),
+    ("fa",            "Search FurAffinity (alias for furaffinity)."),
+    ("bing",          "Search with Bing."),
+    ("github",        "Search GitHub."),
+    ("wikipedia",     "Search Wikipedia."),
+    ("wiki",          "Search Wikipedia (alias for wikipedia)."),
+    ("reddit",        "Search Reddit."),
+    ("stackoverflow", "Search Stack Overflow."),
+    ("so",            "Search Stack Overflow (alias for stackoverflow)."),
+]
+
+
+@click.group("search")
+def search_group():
+    """Search the web — open a query in a search engine."""
+
+def _build_command(engine_key: str, help_text: str) -> click.Command:
+    @click.command(engine_key, help=help_text)
+    @click.argument("query", nargs=-1, required=True)
+    @click.option("--window", "window", default=None, help="Open in named window")
+    @click.option("--group", "group", default=None, help="Open in tab group (name or ID)")
+    @handle_errors
+    def _cmd(query, window, group):
+        terms = " ".join(query)
+        client_from_ctx().nav.search(engine_key, terms, window=window, group=group)
+        suffix = f" in group '{group}'" if group else (f" in window '{window}'" if window else "")
+        display = _DISPLAY_NAMES.get(engine_key, engine_key.capitalize())
+        console.print(f"[green]Searching[/green] [cyan]{display}[/cyan]: {terms}{suffix}")
+
+    return _cmd
+
+for _name, _help in _SUBCOMMANDS:
+    search_group.add_command(_build_command(_name, _help))

browser_cli/commands/serve.py

@@ -0,0 +1,117 @@
+"""Click command for exposing a browser over TCP."""
+from __future__ import annotations
+
+import asyncio
+import sys
+from pathlib import Path
+
+import click
+
+from browser_cli import transport
+from browser_cli.serve.runtime import (
+    _async_framed_send,
+    _async_handle_client,
+    _async_recv_all,
+    _handle_client,
+    _serve_async,
+    console,
+)
+from browser_cli.version_manager import get_installed_version
+
+__all__ = [
+    "_async_framed_send",
+    "_async_handle_client",
+    "_async_recv_all",
+    "_handle_client",
+    "_serve_async",
+    "cmd_serve",
+]
+
+@click.command("serve")
+@click.option("--host", default="127.0.0.1", show_default=True, help="Address to bind.")
+@click.option("--port", default=8765, show_default=True, type=int, help="TCP port to listen on.")
+@click.option("--no-auth", is_flag=True, default=False, help="Disable authentication (dangerous).")
+@click.option(
+    "--authorized-keys",
+    "auth_keys_file",
+    default=None,
+    metavar="FILE",
+    help="File of trusted Ed25519 public keys (one hex per line). Required unless --no-auth.",
+)
+@click.option(
+    "--no-compress",
+    "no_compress",
+    is_flag=True,
+    default=False,
+    help="Disable response compression / msgpack even for clients that support it.",
+)
+@click.pass_context
+def cmd_serve(ctx, host, port, no_auth, auth_keys_file, no_compress):
+    """Expose this browser over TCP so remote hosts can control it."""
+    profile = ctx.obj.get("browser") if ctx.obj else None
+    compress = not no_compress
+
+    if host in ("0.0.0.0", "::"):
+        console.print(
+            "[yellow]Warning:[/yellow] Binding to all interfaces — "
+            "anyone who can reach this port controls your browser."
+        )
+
+    auth_keys_path = _resolve_auth_keys_path(auth_keys_file, no_auth)
+    if auth_keys_path is False:
+        sys.exit(1)
+
+    _print_startup(host, port, profile, auth_keys_path, compress)
+
+    try:
+        asyncio.run(_serve_async(host, port, profile, auth_keys_path, compress))
+    except OSError as e:
+        console.print(f"[red]Cannot bind to {host}:{port}:[/red] {e}")
+        sys.exit(1)
+    except KeyboardInterrupt:
+        console.print("[yellow]Stopped.[/yellow]")
+
+def _resolve_auth_keys_path(auth_keys_file: str | None, no_auth: bool) -> Path | None | bool:
+    if auth_keys_file:
+        from browser_cli.auth import load_authorized_keys
+
+        auth_keys_path = Path(auth_keys_file)
+        if not load_authorized_keys(auth_keys_path):
+            console.print(f"[yellow]Warning:[/yellow] No authorized keys found in {auth_keys_path}")
+        return auth_keys_path
+    if no_auth:
+        return None
+    console.print(
+        "[red]Error:[/red] --authorized-keys FILE is required. "
+        "Use --no-auth to explicitly disable auth (dangerous)."
+    )
+    return False
+
+def _print_startup(host: str, port: int, profile: str | None, auth_keys_path: Path | None, compress: bool) -> None:
+    current_ver = get_installed_version()
+    browser_hint = f" (browser: {profile})" if profile else ""
+    console.print(f"[green]Serving browser{browser_hint} →[/green] [cyan]{host}:{port}[/cyan]  [dim]v{current_ver}[/dim]")
+
+    if auth_keys_path is not None:
+        from browser_cli.auth import load_authorized_keys
+
+        n = len(load_authorized_keys(auth_keys_path))
+        console.print(f"  Auth:   [bold green]Ed25519 pubkey[/bold green] ({n} trusted key{'s' if n != 1 else ''})")
+    else:
+        console.print("[yellow]  Auth disabled (--no-auth)[/yellow]")
+
+    console.print(f"  CLI:    [dim]browser-cli --remote {host}:{port} tabs list[/dim]")
+    console.print(f"  Python: [dim]BrowserCLI(remote=\"{host}:{port}\").tabs.list()[/dim]")
+    _print_encoding_status(compress)
+    console.print("Ctrl-C to stop.\n")
+
+def _print_encoding_status(compress: bool) -> None:
+    if not compress:
+        console.print("  Encode: [yellow]off (--no-compress)[/yellow]")
+        return
+    codecs = "+".join(transport.supported_compression())
+    sers = "+".join(transport.supported_serialization())
+    console.print(
+        "  Encode: [green]on[/green] "
+        f"[dim](compression: {codecs}; serialization: {sers}; per-client negotiated)[/dim]"
+    )

browser_cli/commands/serve_http.py

@@ -0,0 +1,115 @@
+from __future__ import annotations
+
+import json
+import secrets
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+from urllib.parse import urlparse
+
+import click
+from rich.console import Console
+
+from browser_cli import BrowserCLI
+from browser_cli.command_security import CommandPolicy, assert_command_allowed
+
+console = Console()
+
+def _is_loopback(host: str) -> bool:
+  return host in {"127.0.0.1", "localhost", "::1"}
+
+class _Handler(BaseHTTPRequestHandler):
+  client: BrowserCLI
+  token: str | None = None
+  policy: CommandPolicy = CommandPolicy()
+
+  def _authorized(self) -> bool:
+    if self.token is None:
+      return True
+    if self.headers.get("Authorization", "") == f"Bearer {self.token}":
+      return True
+    return self.headers.get("X-Browser-CLI-Token") == self.token
+
+  def _require_auth(self) -> bool:
+    if self._authorized():
+      return True
+    self._send(401, {"error": "missing or invalid token"})
+    return False
+
+  def _send(self, status: int, payload):
+    raw = json.dumps(payload, default=str).encode("utf-8")
+    self.send_response(status)
+    self.send_header("Content-Type", "application/json")
+    self.send_header("Content-Length", str(len(raw)))
+    self.end_headers()
+    self.wfile.write(raw)
+
+  def do_GET(self):
+    path = urlparse(self.path).path
+    try:
+      if path != "/health" and not self._require_auth():
+        return
+      if path == "/tabs":
+        self._send(200, [t.__dict__ for t in self.client.tabs.list()])
+      elif path == "/clients":
+        self._send(200, self.client.clients())
+      elif path == "/health":
+        self._send(200, {"ok": True})
+      else:
+        self._send(404, {"error": "not found"})
+    except Exception as exc:
+      self._send(500, {"error": str(exc)})
+
+  def do_POST(self):
+    path = urlparse(self.path).path
+    try:
+      length = int(self.headers.get("Content-Length", "0"))
+      body = json.loads(self.rfile.read(length) or b"{}")
+      if path == "/command":
+        if not self._require_auth():
+          return
+        command = body.get("command")
+        assert_command_allowed(command, self.policy)
+        self._send(200, {"result": self.client.command(command, body.get("args") or {})})
+      else:
+        self._send(404, {"error": "not found"})
+    except PermissionError as exc:
+      self._send(403, {"error": str(exc)})
+    except Exception as exc:
+      self._send(500, {"error": str(exc)})
+
+  def log_message(self, fmt, *args):
+    console.print(f"[dim]http[/dim] {self.address_string()} {fmt % args}")
+
+@click.command("serve-http")
+@click.option("--host", default="127.0.0.1", show_default=True)
+@click.option("--port", type=int, default=8766, show_default=True)
+@click.option("--browser", default=None, help="Browser alias to target")
+@click.option("--remote", default=None, help="Remote endpoint to target")
+@click.option("--key", default=None, help="Remote auth key spec")
+@click.option("--token", default=None, help="Bearer token required for HTTP access (generated by default)")
+@click.option("--no-auth", is_flag=True, help="Disable HTTP auth (only allowed on loopback hosts)")
+@click.option("--allow-read-page", is_flag=True, help="Allow /command to run page-content read commands")
+@click.option("--allow-control", is_flag=True, help="Allow /command to run browser-control commands")
+@click.option("--allow-dangerous", is_flag=True, help="Allow /command to run high-risk commands")
+def cmd_serve_http(host, port, browser, remote, key, token, no_auth, allow_read_page, allow_control, allow_dangerous):
+  """Expose a tiny local HTTP JSON gateway (/tabs, /clients, /command).
+
+  Auth is enabled by default. Pass the printed token as either
+  ``Authorization: Bearer <token>`` or ``X-Browser-CLI-Token: <token>``.
+  """
+  if no_auth and not _is_loopback(host):
+    raise click.ClickException("--no-auth is only allowed on loopback hosts")
+  auth_token = None if no_auth else (token or secrets.token_urlsafe(32))
+  policy = CommandPolicy(allow_read_page=allow_read_page, allow_control=allow_control, allow_dangerous=allow_dangerous)
+  handler = type(
+    "BrowserCLIHTTPHandler",
+    (_Handler,),
+    {"client": BrowserCLI(browser=browser, remote=remote, key=key), "token": auth_token, "policy": policy},
+  )
+  server = ThreadingHTTPServer((host, port), handler)
+  console.print(f"[green]HTTP gateway listening on http://{host}:{port}[/green]")
+  if auth_token:
+    console.print(f"[yellow]Token:[/yellow] {auth_token}")
+  try:
+    server.serve_forever()
+  except KeyboardInterrupt:
+    console.print("\n[yellow]Stopping HTTP gateway[/yellow]")