patchright-cli 0.5.0__py3-none-any.whl → 0.6.0__py3-none-any.whl

patchright_cli/__init__.py

@@ -1,3 +1,3 @@
 """patchright-cli — Undetected browser automation CLI using Patchright."""
 
-__version__ = "0.5.0"
+__version__ = "0.6.0"

patchright_cli/_skills/patchright-cli/SKILL.md

@@ -58,6 +58,8 @@ These go before the command:
 --timeout-action=10000  # Default action timeout (ms)
 --timeout-navigation=30000 # Default navigation timeout (ms)
 --show-port=9322        # Dashboard port (default: 9322)
+--raw                   # Strip page/snapshot decorations from output
+--json                  # Wrap full response as JSON ({success, output, ...})
 ```
 
 ---
@@ -71,7 +73,8 @@ open [url]                    # Launch browser (optionally navigate)
 open --persistent             # Keep cookies/storage between runs
 open --headless               # Headless mode
 attach --cdp=<url>            # Attach to existing Chrome via CDP
-close                         # Close session
+close                         # Close session (closes the browser)
+detach                        # Detach an attached session (keeps external browser running)
 ```
 
 ### Navigation
@@ -91,6 +94,7 @@ snapshot                      # Full page snapshot
 snapshot <ref>                # Subtree of a specific element
 snapshot --depth=N            # Limit depth
 snapshot -i                   # Interactive elements only
+snapshot --boxes              # Append [box=x,y,w,h] to each [ref=eN] line
 ```
 
 ### Interaction
@@ -102,6 +106,8 @@ click <ref> --modifiers=Alt   # Click with modifier keys
 dblclick <ref>                # Double-click
 hover <ref>                   # Hover
 drag <ref> <target-ref>       # Drag element to target
+drop <ref> --path=./file.png  # Drop file onto element (HTML5 drop from outside)
+drop <ref> --data="text/plain=hello"  # Drop arbitrary MIME data
 ```
 
 ### Form input
@@ -170,8 +176,14 @@ dialog-dismiss                # Dismiss next dialog
 ```bash
 console                       # Show console messages
 console warning               # Filter by level
-network                       # Show network requests
+network                       # Show network requests (each line is `#<id> METHOD STATUS URL`)
+requests                      # Alias for `network`
 network --static              # Include static assets
+request <id>                  # Full detail for one request (headers + body)
+request <id> --body           # Also fetch response body
+generate-locator <ref>        # Emit Playwright locator string for a ref
+highlight <ref>               # Persistent overlay on element [--style=CSS]
+highlight <ref> --hide        # Remove overlay; `highlight --hide` clears all
 ```
 
 ### Recording and capture
@@ -312,30 +324,20 @@ pip install patchright-cli
 
 ### Skill (for AI coding agents)
 
-Install the skill so your agent knows how to use patchright-cli. The same command also works to update to the latest version.
-
-**macOS / Linux (bash/zsh):**
-
-| Agent | Install / update command |
-|-------|--------------------------|
-| **Claude Code** | `mkdir -p ~/.claude/skills/patchright-cli && curl -sL https://raw.githubusercontent.com/AhaiMk01/patchright-cli/main/skills/patchright-cli/SKILL.md -o ~/.claude/skills/patchright-cli/SKILL.md` |
-| **Gemini CLI** | `mkdir -p ~/.gemini/skills/patchright-cli && curl -sL https://raw.githubusercontent.com/AhaiMk01/patchright-cli/main/skills/patchright-cli/SKILL.md -o ~/.gemini/skills/patchright-cli/SKILL.md` |
-| **Codex CLI** | `mkdir -p ~/.codex/skills/patchright-cli && curl -sL https://raw.githubusercontent.com/AhaiMk01/patchright-cli/main/skills/patchright-cli/SKILL.md -o ~/.codex/skills/patchright-cli/SKILL.md` |
-| **OpenCode** | `mkdir -p ~/.opencode/skills/patchright-cli && curl -sL https://raw.githubusercontent.com/AhaiMk01/patchright-cli/main/skills/patchright-cli/SKILL.md -o ~/.opencode/skills/patchright-cli/SKILL.md` |
-
-**Windows (PowerShell):**
+```bash
+# Install for all detected agents (Claude Code, Cursor, Gemini, Codex, 40+ more)
+npx skills add AhaiMk01/patchright-cli
+```
 
-| Agent | Install / update command |
-|-------|--------------------------|
-| **Claude Code** | `New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.claude\skills\patchright-cli" | Out-Null; Invoke-WebRequest -Uri "https://raw.githubusercontent.com/AhaiMk01/patchright-cli/main/skills/patchright-cli/SKILL.md" -OutFile "$env:USERPROFILE\.claude\skills\patchright-cli\SKILL.md"` |
-| **Gemini CLI** | `New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.gemini\skills\patchright-cli" | Out-Null; Invoke-WebRequest -Uri "https://raw.githubusercontent.com/AhaiMk01/patchright-cli/main/skills/patchright-cli/SKILL.md" -OutFile "$env:USERPROFILE\.gemini\skills\patchright-cli\SKILL.md"` |
-| **Codex CLI** | `New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.codex\skills\patchright-cli" | Out-Null; Invoke-WebRequest -Uri "https://raw.githubusercontent.com/AhaiMk01/patchright-cli/main/skills/patchright-cli/SKILL.md" -OutFile "$env:USERPROFILE\.codex\skills\patchright-cli\SKILL.md"` |
-| **OpenCode** | `New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.opencode\skills\patchright-cli" | Out-Null; Invoke-WebRequest -Uri "https://raw.githubusercontent.com/AhaiMk01/patchright-cli/main/skills/patchright-cli/SKILL.md" -OutFile "$env:USERPROFILE\.opencode\skills\patchright-cli\SKILL.md"` |
+Other methods:
 
-**IDE-based agents (Cursor / Windsurf / Aider):** Copy `SKILL.md` to `.<tool>/skills/patchright-cli/` in your project.
+```bash
+# Via patchright-cli itself
+pip install patchright-cli && patchright-cli install --skills
 
-**Or just tell your agent:**
-> Install patchright-cli skill from https://raw.githubusercontent.com/AhaiMk01/patchright-cli/main/skills/patchright-cli/SKILL.md
+# Or just tell your agent:
+# "Install patchright-cli skill from https://raw.githubusercontent.com/AhaiMk01/patchright-cli/main/skills/patchright-cli/SKILL.md"
+```
 
 ## Specific tasks
 

patchright_cli/cli.py

@@ -180,12 +180,14 @@ COMMANDS_HELP = {
     "select": "select <ref> <value> Select dropdown option",
     "check": "check <ref>          Check checkbox/radio",
     "uncheck": "uncheck <ref>        Uncheck checkbox/radio",
-    "snapshot": "snapshot [ref]        Take accessibility snapshot [--filename=F] [--depth=N] [-i]",
+    "snapshot": "snapshot [ref]        Take accessibility snapshot [--filename=F] [--depth=N] [-i] [--boxes]",
     "eval": "eval <expr> [ref]     Evaluate JavaScript [--file=F or stdin]",
     "text": "text <ref|selector>  Get text content of element",
     "screenshot": "screenshot [ref]     Save screenshot [--full-page] [--filename=F]",
     "drag": "drag <from> <to>     Drag element to target",
+    "drop": "drop <ref> [--path=F] [--data=mime=value]  Drop file/data onto element",
     "close": "close                Close browser session",
+    "detach": "detach               Detach attached session (keep external browser running)",
     # Navigation
     "go-back": "go-back              Go back",
     "go-forward": "go-forward           Go forward",
@@ -260,6 +262,10 @@ COMMANDS_HELP = {
     # DevTools
     "console": "console [level]      Show console messages [--clear]",
     "network": "network              Show network requests [--static] [--clear]",
+    "requests": "requests             Alias for `network`",
+    "request": "request <id>         Show full detail for a network request [--body]",
+    "generate-locator": "generate-locator <ref>  Emit Playwright locator expression for a ref",
+    "highlight": "highlight <ref>      Show overlay on element [--style=CSS] [--hide]",
     # Session
     "list": "list                 List sessions",
     "close-all": "close-all            Close all sessions",
@@ -300,6 +306,7 @@ def _print_help():
     click.echo("  --cdp=<url>         Attach to Chrome via CDP endpoint")
     click.echo("  --show-port=N       Dashboard port (default: 9322)")
     click.echo("  --raw               Raw output (strip page/snapshot decorations)")
+    click.echo("  --json              Wrap response as JSON ({success, output, ...})")
     click.echo("  --version           Show version")
     click.echo("  --help              Show this help\n")
     click.echo("Commands:")
@@ -324,7 +331,9 @@ def _print_help():
                 "text",
                 "screenshot",
                 "drag",
+                "drop",
                 "close",
+                "detach",
             ],
         ),
         ("Navigation", ["go-back", "go-forward", "reload", "url", "title"]),
@@ -363,7 +372,7 @@ def _print_help():
         ("Tracing", ["tracing-start", "tracing-stop"]),
         ("Video", ["video-start", "video-stop", "video-chapter"]),
         ("PDF", ["pdf"]),
-        ("DevTools", ["console", "network"]),
+        ("DevTools", ["console", "network", "requests", "request", "generate-locator", "highlight"]),
         ("Session", ["list", "close-all", "kill-all", "delete-data"]),
         ("Dashboard", ["show"]),
         ("Codegen", ["codegen", "codegen-stop"]),
@@ -390,6 +399,7 @@ def main():
     port = DEFAULT_PORT
     extra_opts: dict = {}
     raw = False
+    as_json = False
 
     # Extract options
     remaining = []
@@ -484,6 +494,8 @@ def main():
             extra_opts["show-port"] = argv[i]
         elif arg == "--raw":
             raw = True
+        elif arg == "--json":
+            as_json = True
         elif arg in ("-i", "--interactive"):
             extra_opts["interactive"] = True
         elif arg in ("--version", "-v"):
@@ -579,13 +591,20 @@ def main():
 
     # Print output
     output = response.get("output", "")
-    if output:
-        if raw:
-            output = _strip_raw_output(output)
+    success = response.get("success", True)
+
+    if as_json:
+        payload = dict(response)
+        if raw and isinstance(payload.get("output"), str):
+            payload["output"] = _strip_raw_output(payload["output"])
+        click.echo(json.dumps(payload, default=str))
+    else:
         if output:
-            click.echo(output)
+            if raw:
+                output = _strip_raw_output(output)
+            if output:
+                click.echo(output)
 
-    success = response.get("success", True)
     if not success:
         sys.exit(1)
 

patchright_cli/daemon.py

@@ -54,9 +54,11 @@ def register(name: str):
 class Session:
     """A single browser session (one persistent context, multiple pages/tabs)."""
 
-    def __init__(self, name: str, context, pages: list | None = None):
+    def __init__(self, name: str, context, pages: list | None = None, browser=None, is_attached: bool = False):
         self.name = name
         self.context = context
+        self.browser = browser  # Browser handle for CDP-connected sessions (None for launch_persistent_context)
+        self.is_attached = is_attached  # True if created via `attach --cdp=...`
         self.pages: list = pages or []
         self.current_tab: int = 0
         self.ref_registry: RefRegistry | None = None
@@ -106,19 +108,51 @@ class Session:
             self._cdp_sessions[id(page)] = cdp
         except Exception:
             pass
-        page.on(
-            "request",
-            lambda req: self.network_log.append(
-                {
-                    "method": req.method,
-                    "url": req.url,
-                    "resource": req.resource_type,
-                    "ts": time.time(),
-                }
-            ),
-        )
+        page.on("request", lambda req: self._on_request(req))
+        page.on("response", lambda resp: asyncio.ensure_future(self._on_response(resp)))
         page.on("dialog", lambda dialog: self._handle_dialog(dialog))
 
+    def _on_request(self, req):
+        try:
+            entry = {
+                "id": len(self.network_log),
+                "method": req.method,
+                "url": req.url,
+                "resource": req.resource_type,
+                "ts": time.time(),
+                "request_headers": dict(req.headers or {}),
+                "post_data": req.post_data,
+                "_request": req,
+            }
+        except Exception:
+            entry = {
+                "id": len(self.network_log),
+                "method": getattr(req, "method", "?"),
+                "url": getattr(req, "url", "?"),
+                "resource": getattr(req, "resource_type", "?"),
+                "ts": time.time(),
+                "request_headers": {},
+                "post_data": None,
+                "_request": req,
+            }
+        self.network_log.append(entry)
+
+    async def _on_response(self, resp):
+        try:
+            req = resp.request
+        except Exception:
+            return
+        for entry in reversed(self.network_log):
+            if entry.get("_request") is req:
+                try:
+                    entry["status"] = resp.status
+                    entry["status_text"] = resp.status_text
+                    entry["response_headers"] = dict(resp.headers or {})
+                except Exception:
+                    pass
+                entry["_response"] = resp
+                return
+
     def _handle_dialog(self, dialog):
         """Auto-handle dialogs based on pending action or auto-dismiss."""
         import asyncio
@@ -235,11 +269,12 @@ class DaemonState:
             perms = [p.strip() for p in grant_permissions.split(",") if p.strip()]
             context_options["permissions"] = list(set(context_options.get("permissions", []) + perms))
 
+        attached_browser = None
         if cdp_endpoint:
-            browser = await self.playwright.chromium.connect_over_cdp(
+            attached_browser = await self.playwright.chromium.connect_over_cdp(
                 cdp_endpoint, headers=cdp_headers, timeout=cdp_timeout
             )
-            context = await browser.new_context(**context_options)
+            context = await attached_browser.new_context(**context_options)
             pages = context.pages or []
             if not pages:
                 page = await context.new_page()
@@ -279,7 +314,13 @@ class DaemonState:
         if url:
             await pages[0].goto(url)
 
-        session = Session(name, context, list(pages))
+        session = Session(
+            name,
+            context,
+            list(pages),
+            browser=attached_browser,
+            is_attached=cdp_endpoint is not None,
+        )
         await session.setup_listeners()
         self.sessions[name] = session
         self.profile_dirs[name] = profile_dir
@@ -487,6 +528,68 @@ async def cmd_drag(session: Session, page, args: list, options: dict, cwd: str |
     return await _page_info(session, cwd)
 
 
+@register("drop")
+async def cmd_drop(session: Session, page, args: list, options: dict, cwd: str | None, state: DaemonState) -> dict:
+    """Drop files or data onto an element (simulates HTML5 drop from outside)."""
+    if not args:
+        return {"success": False, "output": "Usage: drop <ref> --path=F | --data=mime=value"}
+    elem = await _resolve_ref(session, page, args[0])
+
+    path_opt = options.get("path")
+    data_opt = options.get("data")
+    if not path_opt and not data_opt:
+        return {"success": False, "output": "drop requires --path=<file> or --data=<mime=value>"}
+
+    files: list[dict] = []
+    if path_opt:
+        import base64
+        import mimetypes
+
+        paths = [path_opt] if isinstance(path_opt, str) else list(path_opt)
+        for p in paths:
+            fp = Path(p)
+            if not fp.exists():
+                return {"success": False, "output": f"File not found: {p}"}
+            mime = mimetypes.guess_type(fp.name)[0] or "application/octet-stream"
+            files.append(
+                {
+                    "name": fp.name,
+                    "type": mime,
+                    "b64": base64.b64encode(fp.read_bytes()).decode("ascii"),
+                }
+            )
+
+    data_entries: list[tuple[str, str]] = []
+    if data_opt:
+        raw_list = [data_opt] if isinstance(data_opt, str) else list(data_opt)
+        for raw in raw_list:
+            if "=" not in raw:
+                return {"success": False, "output": f"Invalid --data (need mime=value): {raw}"}
+            mime, value = raw.split("=", 1)
+            data_entries.append((mime, value))
+
+    js = """
+    async (target, { files, dataEntries }) => {
+      const dt = new DataTransfer();
+      for (const f of files) {
+        const bytes = Uint8Array.from(atob(f.b64), c => c.charCodeAt(0));
+        dt.items.add(new File([bytes], f.name, { type: f.type }));
+      }
+      for (const [mime, value] of dataEntries) {
+        dt.setData(mime, value);
+      }
+      const evt = (type) => new DragEvent(type, {
+        bubbles: true, cancelable: true, dataTransfer: dt,
+      });
+      target.dispatchEvent(evt('dragenter'));
+      target.dispatchEvent(evt('dragover'));
+      target.dispatchEvent(evt('drop'));
+    }
+    """
+    await elem.evaluate(js, {"files": files, "dataEntries": data_entries})
+    return await _page_info(session, cwd)
+
+
 # -- Snapshot ----------------------------------------------------------------
 
 
@@ -504,6 +607,8 @@ async def cmd_snapshot(session: Session, page, args: list, options: dict, cwd: s
         snapshot_text, session.ref_registry = await take_snapshot(
             page, max_depth=max_depth, interactive_only=interactive_only
         )
+    if options.get("boxes"):
+        snapshot_text = await _annotate_with_boxes(page, snapshot_text, session.ref_registry)
     fn = options.get("filename")
     if fn:
         Path(fn).parent.mkdir(parents=True, exist_ok=True)
@@ -526,6 +631,111 @@ async def cmd_snapshot(session: Session, page, args: list, options: dict, cwd: s
     return {"success": True, "output": "\n".join(output_lines), "snapshot_path": snap_path}
 
 
+async def _annotate_with_boxes(page, snapshot_text: str, registry) -> str:
+    """Append `[box=x,y,w,h]` to each `[ref=eN]` line in snapshot_text.
+
+    Refs whose locator can't be measured are left unchanged.
+    """
+    if registry is None:
+        return snapshot_text
+    import re
+
+    ref_re = re.compile(r"\[ref=(e\d+)\]")
+    boxes: dict[str, str] = {}
+    for ref in registry.entries:
+        try:
+            loc = registry.resolve(page, ref)
+            box = await loc.bounding_box()
+            if box:
+                boxes[ref] = f"[box={int(box['x'])},{int(box['y'])},{int(box['width'])},{int(box['height'])}]"
+        except Exception:
+            continue
+
+    out = []
+    for line in snapshot_text.splitlines():
+        m = ref_re.search(line)
+        if m and m.group(1) in boxes:
+            line = line.rstrip() + " " + boxes[m.group(1)]
+        out.append(line)
+    return "\n".join(out)
+
+
+@register("generate-locator")
+async def cmd_generate_locator(
+    session: Session, page, args: list, options: dict, cwd: str | None, state: DaemonState
+) -> dict:
+    """Emit a Playwright locator expression for a ref."""
+    if not args:
+        return {"success": False, "output": "Usage: generate-locator <ref>"}
+    if session.ref_registry is None:
+        return {"success": False, "output": "No snapshot taken yet. Run `snapshot` first."}
+    ref = args[0].lstrip("@")
+    entry = session.ref_registry.entries.get(ref)
+    if entry is None:
+        return {"success": False, "output": f"Ref @{ref} not found. Re-run `snapshot`."}
+
+    name_part = ""
+    if entry.name:
+        escaped = entry.name.replace("\\", "\\\\").replace("'", "\\'")
+        name_part = f", {{ name: '{escaped}', exact: true }}"
+    expr = f"getByRole('{entry.role}'{name_part})"
+    if entry.nth > 0:
+        expr += f".nth({entry.nth})"
+    return {"success": True, "output": expr}
+
+
+@register("highlight")
+async def cmd_highlight(session: Session, page, args: list, options: dict, cwd: str | None, state: DaemonState) -> dict:
+    """Draw or remove a persistent overlay over an element.
+
+    `highlight <ref>` shows it; `highlight <ref> --hide` hides it; `highlight --hide`
+    clears all highlights on the page.
+    """
+    hide = bool(options.get("hide"))
+    style = options.get("style") or "outline: 2px solid #ff3366; outline-offset: 2px;"
+
+    if hide and not args:
+        await page.evaluate("() => document.querySelectorAll('[data-patchright-highlight]').forEach(el => el.remove())")
+        return {"success": True, "output": "All highlights cleared."}
+
+    if not args:
+        return {"success": False, "output": "Usage: highlight <ref> [--style=...] [--hide]"}
+    elem = await _resolve_ref(session, page, args[0])
+
+    if hide:
+        await elem.evaluate(
+            "el => { const id = el.getAttribute('data-patchright-hl-id');"
+            " if (id) {"
+            '   const o = document.querySelector(`[data-patchright-highlight="${id}"]`);'
+            "   if (o) o.remove();"
+            "   el.removeAttribute('data-patchright-hl-id');"
+            " } }"
+        )
+        return {"success": True, "output": f"Hid highlight on {args[0]}."}
+
+    js = """
+    (el, { style }) => {
+      const rect = el.getBoundingClientRect();
+      const id = el.getAttribute('data-patchright-hl-id') || ('h' + Math.random().toString(36).slice(2));
+      el.setAttribute('data-patchright-hl-id', id);
+      let overlay = document.querySelector(`[data-patchright-highlight="${id}"]`);
+      if (!overlay) {
+        overlay = document.createElement('div');
+        overlay.setAttribute('data-patchright-highlight', id);
+        overlay.style.cssText = 'position: fixed; pointer-events: none; z-index: 2147483647;';
+        document.documentElement.appendChild(overlay);
+      }
+      overlay.style.left = rect.left + 'px';
+      overlay.style.top = rect.top + 'px';
+      overlay.style.width = rect.width + 'px';
+      overlay.style.height = rect.height + 'px';
+      overlay.style.cssText += '; ' + style;
+    }
+    """
+    await elem.evaluate(js, {"style": style})
+    return {"success": True, "output": f"Highlighted {args[0]}."}
+
+
 # -- Eval / Screenshot -------------------------------------------------------
 
 
@@ -857,12 +1067,67 @@ async def cmd_network(session: Session, page, args: list, options: dict, cwd: st
     for r in session.network_log[-50:]:
         if not include_static and r["resource"] in static_types:
             continue
-        lines.append(f"{r['method']} {r['url']} [{r['resource']}]")
+        status = r.get("status")
+        status_part = f" {status}" if status is not None else ""
+        lines.append(f"#{r['id']} {r['method']}{status_part} {r['url']} [{r['resource']}]")
     if options.get("clear"):
         session.network_log.clear()
     return {"success": True, "output": "\n".join(lines) or "(no network requests)"}
 
 
+@register("request")
+async def cmd_request(session: Session, page, args: list, options: dict, cwd: str | None, state: DaemonState) -> dict:
+    if not args:
+        return {"success": False, "output": "Usage: request <id>"}
+    try:
+        req_id = int(args[0])
+    except ValueError:
+        return {"success": False, "output": f"Invalid request id: {args[0]}"}
+
+    entry = next((e for e in session.network_log if e["id"] == req_id), None)
+    if entry is None:
+        return {"success": False, "output": f"No request with id {req_id}. Use `network` to list."}
+
+    lines = [
+        f"### Request #{entry['id']}",
+        f"- {entry['method']} {entry['url']}",
+        f"- Resource: {entry['resource']}",
+    ]
+    status = entry.get("status")
+    if status is not None:
+        status_text = entry.get("status_text") or ""
+        lines.append(f"- Status: {status} {status_text}".rstrip())
+
+    req_headers = entry.get("request_headers") or {}
+    if req_headers:
+        lines.append("### Request Headers")
+        for k, v in req_headers.items():
+            lines.append(f"- {k}: {v}")
+
+    post_data = entry.get("post_data")
+    if post_data:
+        lines.append("### Request Body")
+        lines.append(post_data if len(post_data) < 4000 else post_data[:4000] + "\n... (truncated)")
+
+    resp_headers = entry.get("response_headers") or {}
+    if resp_headers:
+        lines.append("### Response Headers")
+        for k, v in resp_headers.items():
+            lines.append(f"- {k}: {v}")
+
+    if options.get("body"):
+        resp = entry.get("_response")
+        if resp is not None:
+            try:
+                body = await resp.text()
+                lines.append("### Response Body")
+                lines.append(body if len(body) < 8000 else body[:8000] + "\n... (truncated)")
+            except Exception as e:
+                lines.append(f"### Response Body\n(could not read: {e})")
+
+    return {"success": True, "output": "\n".join(lines)}
+
+
 @register("network-state-set")
 async def cmd_network_state_set(
     session: Session, page, args: list, options: dict, cwd: str | None, state: DaemonState
@@ -1392,6 +1657,10 @@ async def handle_command(state: DaemonState, msg: dict) -> dict:
     options = dict(msg.get("options", {}))
     cwd = msg.get("cwd")
 
+    # `requests` is an alias for `network` (matches playwright-cli naming).
+    if cmd == "requests":
+        cmd = "network"
+
     session_name = options.pop("session", "default") or "default"
 
     try:
@@ -1482,6 +1751,25 @@ async def handle_command(state: DaemonState, msg: dict) -> dict:
             closed = await state.close_session(session_name)
             return {"success": True, "output": f"Session '{session_name}' closed." if closed else "Session not found."}
 
+        if cmd == "detach":
+            target = state.sessions.get(session_name)
+            if target is None:
+                return {"success": False, "output": f"Session '{session_name}' not found."}
+            if not target.is_attached:
+                return {
+                    "success": False,
+                    "output": f"Session '{session_name}' was not attached. Use `close` for sessions created via `open`.",
+                }
+            state.sessions.pop(session_name, None)
+            # Disconnect from external Chrome without killing it. For CDP-attached
+            # sessions, browser.close() only severs the connection.
+            try:
+                if target.browser is not None:
+                    await target.browser.close()
+            except Exception:
+                pass
+            return {"success": True, "output": f"Detached from '{session_name}' (external browser kept running)."}
+
         if cmd == "close-all":
             names = list(state.sessions.keys())
             for n in names:

{patchright_cli-0.5.0.dist-info → patchright_cli-0.6.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: patchright-cli
-Version: 0.5.0
+Version: 0.6.0
 Summary: Anti-detect browser automation CLI using Patchright (undetected Playwright fork)
 Project-URL: Homepage, https://github.com/AhaiMk01/patchright-cli
 Project-URL: Repository, https://github.com/AhaiMk01/patchright-cli
@@ -331,74 +331,41 @@ patchright-cli --port=9322 open        # Custom daemon port
 
 ---
 
-## Snapshots
-
-After each state-changing command, the CLI outputs page info and a YAML snapshot:
-
-```
-### Page
-- Page URL: https://example.com/
-- Page Title: Example Domain
-### Snapshot
-[Snapshot](.patchright-cli/page-1774376207818.yml)
-```
-
-The snapshot lists interactive elements with refs you can use in commands:
-
-```yaml
-- ref: e1
-  role: heading
-  name: Example Domain
-  level: 1
-- ref: e2
-  role: link
-  name: Learn more
-  url: "https://iana.org/domains/example"
-```
-
-> [!NOTE]
-> Use refs directly: `patchright-cli click e2`, `patchright-cli fill e5 "text"`
-
----
-
-## Anti-Detect Features
-
-> [!CAUTION]
-> This tool is for **authorized testing, security research, and legitimate automation** only.
-
-- :white_check_mark: Real Chrome browser (not Chromium)
-- :white_check_mark: Patchright patches `navigator.webdriver` and other detection vectors
-- :white_check_mark: Persistent profiles maintain cookies/sessions across runs
-- :white_check_mark: No custom user-agent or headers (natural fingerprint)
-- :white_check_mark: Headed by default (headless is more detectable)
-
----
-
 ## Agent Integration
 
-Works with any AI coding agent that supports SKILL.md skills:
+Works with Claude Code, Cursor, Gemini CLI, Codex, and [40+ other agents](https://github.com/vercel-labs/skills).
 
-| Agent | Install skill |
-|-------|--------------|
-| **Claude Code** | `mkdir -p ~/.claude/skills/patchright-cli && curl -sL https://raw.githubusercontent.com/AhaiMk01/patchright-cli/main/skills/patchright-cli/SKILL.md -o ~/.claude/skills/patchright-cli/SKILL.md` |
-| **OpenClaw** | `mkdir -p ~/.openclaw/skills/patchright-cli && curl -sL https://raw.githubusercontent.com/AhaiMk01/patchright-cli/main/skills/patchright-cli/SKILL.md -o ~/.openclaw/skills/patchright-cli/SKILL.md` |
-| **Codex CLI** | `mkdir -p ~/.codex/skills/patchright-cli && curl -sL https://raw.githubusercontent.com/AhaiMk01/patchright-cli/main/skills/patchright-cli/SKILL.md -o ~/.codex/skills/patchright-cli/SKILL.md` |
-| **Gemini CLI** | `mkdir -p ~/.gemini/skills/patchright-cli && curl -sL https://raw.githubusercontent.com/AhaiMk01/patchright-cli/main/skills/patchright-cli/SKILL.md -o ~/.gemini/skills/patchright-cli/SKILL.md` |
-| **OpenCode** | `mkdir -p ~/.opencode/skills/patchright-cli && curl -sL https://raw.githubusercontent.com/AhaiMk01/patchright-cli/main/skills/patchright-cli/SKILL.md -o ~/.opencode/skills/patchright-cli/SKILL.md` |
-| **Cursor** | Copy SKILL.md to `.cursor/skills/patchright-cli/` in your project |
-| **Windsurf** | Copy SKILL.md to `.windsurf/skills/patchright-cli/` in your project |
-| **Aider** | Copy SKILL.md to `.aider/skills/patchright-cli/` in your project |
+```bash
+# Install skill for all detected agents (recommended)
+npx skills add AhaiMk01/patchright-cli
+```
 
-Or auto-install for all detected agents:
+<details>
+<summary><b>Other install methods</b></summary>
 
 ```bash
+# Via patchright-cli itself
 pip install patchright-cli
 patchright-cli install --skills
+
+# Or just tell your agent:
+# "Install patchright-cli skill from https://raw.githubusercontent.com/AhaiMk01/patchright-cli/main/skills/patchright-cli/SKILL.md"
 ```
 
-Or just tell your agent:
+</details>
 
-> Install patchright-cli skill from https://raw.githubusercontent.com/AhaiMk01/patchright-cli/main/skills/patchright-cli/SKILL.md
+### Skill docs
+
+| File | Topic |
+|------|-------|
+| [`SKILL.md`](skills/patchright-cli/SKILL.md) | Main skill — commands, options, patterns |
+| [`snapshot-refs.md`](skills/patchright-cli/references/snapshot-refs.md) | Snapshots, element refs, `-i` flag |
+| [`session-management.md`](skills/patchright-cli/references/session-management.md) | Named sessions, profiles, CDP, dashboard |
+| [`request-mocking.md`](skills/patchright-cli/references/request-mocking.md) | Route mocking, network state |
+| [`storage-state.md`](skills/patchright-cli/references/storage-state.md) | Cookies, localStorage, sessionStorage |
+| [`running-code.md`](skills/patchright-cli/references/running-code.md) | eval, run-code, `--file`, stdin |
+| [`tracing.md`](skills/patchright-cli/references/tracing.md) | Trace recording and debugging |
+| [`video-recording.md`](skills/patchright-cli/references/video-recording.md) | Video, codegen, screenshot, PDF |
 
 ---
 

{patchright_cli-0.5.0.dist-info → patchright_cli-0.6.0.dist-info}/RECORD

@@ -1,11 +1,11 @@
-patchright_cli/__init__.py,sha256=cIPq7urEd7-daD-_CugdNI-L9GyVZrZn5YDVRFZkX1M,100
+patchright_cli/__init__.py,sha256=4B_Y2Xe4HCJQN3uKjxIYZvB8oR5SUT1RgfhxGLX1fnI,100
 patchright_cli/__main__.py,sha256=iVuBuI_rPOENLhffOEHoS7JWCDBQciqT1kPXjRuhbZ4,127
-patchright_cli/cli.py,sha256=HMGKFWqJGmZ9Tbs3idLud7xqs9-az5Bqwz0fdo1v8MI,22986
-patchright_cli/daemon.py,sha256=WoknT_CE1TrfdoFr1zY1sQjmrSAMj0w2VI4Xy_x8ix8,63864
+patchright_cli/cli.py,sha256=2oSTctMLENzI_CrXDN8iZTl4f24VlcX0HzhxE6pI9iA,24038
+patchright_cli/daemon.py,sha256=YvaWLWPz2z2H6-fpyQzOKSCPIy_M-5ikJIe6NEDuGDo,75305
 patchright_cli/dashboard.py,sha256=aQHujW9tHTOQhbyqm4M6OknShLaJSnRFHFZRRfs3l20,4022
 patchright_cli/ref_registry.py,sha256=XLqHePO7iOHlnFeNdoQAMrAkTBnvkrnhxkn7f6Vc1pU,2945
 patchright_cli/snapshot.py,sha256=J3oc429_LpOgpYqaJaQJkN_oezoCBChoUDsvAX0z-Qg,1570
-patchright_cli/_skills/patchright-cli/SKILL.md,sha256=8Ch9LTls_O9NOA7o6hJ0K1NKdMP0H0Yd6PKW--MjPsQ,13554
+patchright_cli/_skills/patchright-cli/SKILL.md,sha256=h0EQQ4FPv7Ys0tml9yopR5TosnhAZY3YUUiNzuJkJaU,12183
 patchright_cli/_skills/patchright-cli/references/request-mocking.md,sha256=x4t_5gPxSsYvm0BlrZqbdM3MHqGVzNY_ac6Awg6PToc,2901
 patchright_cli/_skills/patchright-cli/references/running-code.md,sha256=Ls0HhV8gxT5XOHfiv9-B8eBvYn-RR21wZ7Iyh3uskuk,3242
 patchright_cli/_skills/patchright-cli/references/session-management.md,sha256=hsqbDHv0C-BUlId5lymBBCR9DxGUyzRwyaQOhcpR324,3495
@@ -13,8 +13,8 @@ patchright_cli/_skills/patchright-cli/references/snapshot-refs.md,sha256=VFz6_Ps
 patchright_cli/_skills/patchright-cli/references/storage-state.md,sha256=qfL_2v_WHHyVUIPj4efMU46KOMbYyvtLll4ha84mOHw,3348
 patchright_cli/_skills/patchright-cli/references/tracing.md,sha256=6IwbGDsrtuB3bckB_7noyjpU37mdemIC435IuLilBZk,1931
 patchright_cli/_skills/patchright-cli/references/video-recording.md,sha256=x6xnssw3ASrRlKg45Qo6yiOhIDcirWXBxw3UOfq4K5Y,2576
-patchright_cli-0.5.0.dist-info/METADATA,sha256=kXazUmF8JnUzteHJIEpYVNEivVt6jXfz1BPKv_yAJTI,16738
-patchright_cli-0.5.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
-patchright_cli-0.5.0.dist-info/entry_points.txt,sha256=Syh904eOQA8ylakyqIvG4LmIHx3LMjgeNcnFap3O0NQ,59
-patchright_cli-0.5.0.dist-info/licenses/LICENSE,sha256=adszqL4YR4pQUrc7LeAFxeg5Mc2cvljXp7QPlzKVWm8,10760
-patchright_cli-0.5.0.dist-info/RECORD,,
+patchright_cli-0.6.0.dist-info/METADATA,sha256=k6c4sA-g39iP5uvXvO_TAnOaVEMsuI6ufGtz7q2_JRk,15435
+patchright_cli-0.6.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+patchright_cli-0.6.0.dist-info/entry_points.txt,sha256=Syh904eOQA8ylakyqIvG4LmIHx3LMjgeNcnFap3O0NQ,59
+patchright_cli-0.6.0.dist-info/licenses/LICENSE,sha256=adszqL4YR4pQUrc7LeAFxeg5Mc2cvljXp7QPlzKVWm8,10760
+patchright_cli-0.6.0.dist-info/RECORD,,