/playwright-cli-cloakbrowser

name: playwright-cli-cloakbrowser
description: Drive CloakBrowser Manager stealth profiles with @playwright/cli over CDP. Use for browser automation that needs a persistent logged-in session, anti-detect fingerprints, or to pass Cloudflare - attach reuses the profile's cookies and stealth where a fresh browser does not.
metadata:
  version: "0.3.2"
  upstream: "@playwright/cli@0.1.15"
  openclaw:
    homepage: https://github.com/tenequm/skills/tree/main/skills/playwright-cli-cloakbrowser
    emoji: "🎭"
    requires:
      bins:
        - playwright-cli
    install:
      - kind: node
        package: "@playwright/cli"
        bins:
          - playwright-cli
    envVars:
      - name: AUTH_TOKEN
        required: false
        description: Optional bearer token protecting the CloakBrowser Manager API
allowed-tools: Bash(playwright-cli:*) Bash(curl:*) Bash(docker:*)

playwright-cli on CloakBrowser stealth profiles

[CloakBrowser Manager](https://github.com/CloakHQ/CloakBrowser-Manager) runs isolated stealth Chromium profiles - unique fingerprint, optional proxy, persistent cookies, built-in noVNC live view - in a single Docker container. Every running profile exposes a CDP endpoint. `playwright-cli attach` connects to the profile's **persistent context** (`contexts[0]`), so automation inherits the profile's logins and stealth fingerprint; `playwright-cli open` would launch a plain local browser with neither. Always `attach` for this setup.

No Manager running yet? See [Setting up the Manager](#setting-up-the-manager-local-laptop) below.

For the **full command reference**, run `playwright-cli --help` and open the `Agent skill:` path it prints (the official skill bundled with `@playwright/cli`). This file only covers the CloakBrowser-specific setup and gotchas.

Connect

# generic: attach to any CDP endpoint
playwright-cli attach --cdp=<CDP_URL>

# CloakBrowser Manager: per-profile CDP endpoint (shown via the toolbar
# code icon while a profile is running)
playwright-cli attach --cdp=http://localhost:8080/api/profiles/<profile-id>/cdp

# then drive normally
playwright-cli goto https://example.com
playwright-cli snapshot                       # a11y tree with refs (e3, e15, ...)
playwright-cli snapshot --depth=6             # bound the tree on huge pages
playwright-cli click e15
playwright-cli --raw eval "document.title"    # --raw = return value only (JSON-serialized), no snapshot noise
playwright-cli detach                         # leave the browser running for next time

• The profile must be **running** first - click Launch in the Manager GUI, or `curl -X POST http://localhost:8080/api/profiles/<profile-id>/launch`.
• `--cdp=<url>` and `--cdp <url>` both work.
• `attach` creates an implicit session named `default` and prints a `--s=default` hint - that flag is only needed when juggling multiple sessions; plain commands use the default session. `-s=<name>` opens a second isolated session on the **same** CDP (e.g. `-s=probe` for in-page fetch checks while `default` drives the page).
• playwright-cli writes a `.playwright-cli/` scratch dir (snapshot `.yml` files, console logs) into the cwd - run from a scratch directory or gitignore it.
• **Never `close` / `close-all` / `kill-all`** on an attached stealth profile - that can stop the shared browser and its session. Use **`detach`** to leave it running.

Logging into a site

The profile persists cookies, localStorage, and cache across restarts. To establish a login: open the Manager GUI at `http://localhost:8080`, view the running profile in the built-in noVNC viewer, and sign in there once. playwright-cli then drives the same session logged-in - the VNC view and the CDP connection share one browser.

**Importing an existing login** (two limits worth knowing):

• Anti-automation sites (Google, Facebook) may **flag the CDP-driven login and not persist a durable session** even though the form submits. Bypass: import a real-browser session as Playwright storage-state (`playwright-cli state-save`/`state-load`, or capture with `npx playwright codegen --save-storage=auth.json <url>`) instead of logging in through VNC.
• A session is often **IP-bound**: a cookie/state minted at your real location, replayed from a profile whose proxy egress is a different geo, gets forced back to login + 2FA. Transfer only works when the profile's proxy geo matches where the session was created.

Gotchas (all observed in practice)

1. **`attach` hangs ~30 s, then times out** - the profile has a stale or heavy pre-existing tab that never finishes Playwright's `connectOverCDP` page-init handshake. Fix: close extra tabs via the noVNC view (or stop/relaunch the profile), then re-attach - drops to under a second. A clean `about:blank` profile attaches instantly. 2. **New-tab creation can be rejected** ("Failed to open a new tab") - the stealth browser may forbid `Target.createTarget` in some states. **Prefer navigating the current tab (`goto`) over `tab-new`.** If a page closes or replaces its own tab (challenge redirects, heavy detail pages), the driver desyncs - just re-`attach` and continue. 3. **JS-rendered content** (prices, dynamic cards) often is not in the a11y `snapshot` - scrape the DOM with `eval`: `playwright-cli --raw eval "[...document.querySelectorAll('[data-card]')].map(e=>e.innerText)"`. 4. **Heavy detail pages are slow through a profile proxy** and can timeout or desync. Read what you need from the list/results page when possible; treat opening detail pages as best-effort. 5. **Cookie/consent overlays** block clicks ("element covered"). Dismiss via JS: `playwright-cli eval "document.querySelector('#onetrust-accept-btn-handler')?.click()"`. 6. **Use `--raw`** whenever scraping or piping - without it output is wrapped in markdown header blocks (`### Result`, `### Page`, `### Snapshot` - varies by command), which mangles piping. Even with `--raw`, eval values come back JSON-serialized (strings quoted). 7. **"Logged in" can