# Playwright Cli Cdp

> CDP-only browser control with playwright-cli. Use for launching Chrome in remote debugging mode, attaching exclusively through --cdp endpoints, driving attached pages, inspecting console/network/storage, and sending raw Chrome DevTools Protocol commands. Do not use playwright-cli open, non-CDP browser launches, extension attach, or Playwright test debug attach workflows from this skill.

- **Type:** Skill
- **Install:** `agentstack add skill-betterlmy-agent-skills-playwright-cli-cdp`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [betterlmy](https://agentstack.voostack.com/s/betterlmy)
- **Installs:** 0
- **Category:** [Web & Browser](https://agentstack.voostack.com/c/web-and-browser)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [betterlmy](https://github.com/betterlmy)
- **Source:** https://github.com/betterlmy/agent-skills/tree/main/skills/playwright-cli-cdp

## Install

```sh
agentstack add skill-betterlmy-agent-skills-playwright-cli-cdp
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# playwright-cli CDP

## Default behavior

This skill is CDP-only. All browser work must happen through a Chrome DevTools Protocol endpoint and `playwright-cli attach --cdp=...`.

Do not use `playwright-cli open`, `--browser=...`, Firefox/WebKit launches, extension attach, or Playwright test debug attach workflows in this skill. If a CDP endpoint is already reachable, reuse it as-is. If no CDP endpoint exists, start Chrome remote debugging on `127.0.0.1:9222`, attach `playwright-cli` to that endpoint, and use the session name `cdp`.

Keep CDP local. Do not bind the debugging endpoint to `0.0.0.0` or a public interface unless the user explicitly requests it and accepts the security risk.

Never close, kill, restart, detach, or otherwise clean up an existing CDP endpoint or browser just because the task is done. Leave Chrome and the debugging port running unless the user explicitly asks to close it. If the user asks to clean up, prefer `bash scripts/playwright-cdp.sh -s= detach` first; only terminate browser processes when the user explicitly asks to close/kill Chrome.

Use a 15 second page/navigation timeout by default. Run `playwright-cli` through the bundled wrapper so every command inherits `PLAYWRIGHT_MCP_TIMEOUT_NAVIGATION=15000` for URL opens, `goto`, tab navigation, reloads, and other navigation waits:

- Bash/macOS/Linux/WSL2: `bash scripts/playwright-cdp.sh ...`
- Windows PowerShell: `powershell -ExecutionPolicy Bypass -File scripts\playwright-cdp.ps1 ...`

Override the page/navigation timeout only when needed with `PLAYWRIGHT_CLI_CDP_PAGE_TIMEOUT_MS=`. If navigation times out, report the timeout and inspect the current page state through the existing CDP session; do not close or restart the endpoint unless the user asks.

The wrapper redirects playwright-cli output (console logs `console-*.log`, page snapshots `page-*.yml`) to a dedicated temp directory (`$TMPDIR/playwright-cli-cdp` on macOS/Linux/WSL2, `%TEMP%\playwright-cli-cdp` on Windows) so the working directory stays clean. playwright-cli always writes snapshot/console output to files in skill mode and only returns a link, so `read` that linked path when the page snapshot content is needed. A built-in size budget (`PLAYWRIGHT_MCP_OUTPUT_MAX_SIZE`, default 50 MiB) automatically reclaims the oldest files across runs; files written by the current command are never deleted. Override either with `PLAYWRIGHT_MCP_OUTPUT_DIR` or `PLAYWRIGHT_MCP_OUTPUT_MAX_SIZE`.

## Quick start

Resolve bundled scripts relative to this skill directory before running them.
先阅读 [CLI 兼容性契约](references/cli-compatibility.md)；环境检查会报告版本漂移并验证必需命令。

macOS, Linux, or WSL2 with a Linux browser:

```bash
bash scripts/check-environment.sh
bash scripts/open-chrome-remote.sh
```

Windows PowerShell:

```powershell
powershell -ExecutionPolicy Bypass -File scripts\check-environment.ps1
powershell -ExecutionPolicy Bypass -File scripts\open-chrome-remote.ps1
```

WSL2 with Windows Chrome:

```bash
win_script="$(wslpath -w scripts/open-chrome-remote.ps1)"
powershell.exe -NoProfile -ExecutionPolicy Bypass -File "$win_script"
```

When the PowerShell script is stored in the WSL filesystem, do not guess a `C:\Users\...` path. Prefer `wslpath -w`; if you must pass a literal `\\wsl.localhost\...` path, wrap the PowerShell command in Bash single quotes so Bash does not consume the UNC backslashes.

Attach and drive the CDP session:

```bash
bash scripts/playwright-cdp.sh -s=cdp attach --cdp=http://127.0.0.1:9222
bash scripts/playwright-cdp.sh -s=cdp goto https://example.com
bash scripts/playwright-cdp.sh -s=cdp snapshot
bash scripts/playwright-cdp.sh -s=cdp click e15
bash scripts/playwright-cdp.sh -s=cdp eval "document.title"
```

Windows PowerShell equivalent:

```powershell
powershell -ExecutionPolicy Bypass -File scripts\playwright-cdp.ps1 -s=cdp attach --cdp=http://127.0.0.1:9222
powershell -ExecutionPolicy Bypass -File scripts\playwright-cdp.ps1 -s=cdp goto https://example.com
powershell -ExecutionPolicy Bypass -File scripts\playwright-cdp.ps1 -s=cdp snapshot
```

Start at a URL when useful:

macOS, Linux, or WSL2 with a Linux browser:

```bash
bash scripts/check-environment.sh
bash scripts/open-chrome-remote.sh https://example.com
```

Windows PowerShell:

```powershell
powershell -ExecutionPolicy Bypass -File scripts\check-environment.ps1
powershell -ExecutionPolicy Bypass -File scripts\open-chrome-remote.ps1 https://example.com
```

WSL2 with Windows Chrome:

```bash
win_script="$(wslpath -w scripts/open-chrome-remote.ps1)"
powershell.exe -NoProfile -ExecutionPolicy Bypass -File "$win_script" https://example.com
```

Then attach:

```bash
bash scripts/playwright-cdp.sh -s=cdp attach --cdp=http://127.0.0.1:9222
```

```powershell
powershell -ExecutionPolicy Bypass -File scripts\playwright-cdp.ps1 -s=cdp attach --cdp=http://127.0.0.1:9222
```

If the user gives an endpoint, use it directly and do not launch another browser:

```bash
bash scripts/playwright-cdp.sh -s=cdp attach --cdp=http://127.0.0.1:9223
bash scripts/playwright-cdp.sh -s=prod attach --cdp=https://debug.example.internal
```

## Endpoint checks

Run the environment check before starting or attaching unless the task is already in a known-good active CDP session:

```bash
bash scripts/check-environment.sh
```

```powershell
powershell -ExecutionPolicy Bypass -File scripts\check-environment.ps1
```

Before attaching, verify the endpoint when possible:

```bash
curl -fsS http://127.0.0.1:9222/json/version
curl -fsS http://127.0.0.1:9222/json/list
```

If the endpoint is down, start Chrome remote mode with the bundled Bash or PowerShell script for the current platform. If the port is already used by a non-CDP process, inspect it and choose another port via `CDP_PORT`.

macOS, Linux, or WSL2 with a Linux browser:

```bash
lsof -iTCP:9222 -sTCP:LISTEN
CDP_PORT=9333 bash scripts/open-chrome-remote.sh
```

Windows PowerShell:

```powershell
netstat -ano | findstr :9222
$env:CDP_PORT = "9333"
powershell -ExecutionPolicy Bypass -File scripts\open-chrome-remote.ps1
```

Then attach:

```bash
bash scripts/playwright-cdp.sh -s=cdp attach --cdp=http://127.0.0.1:9333
```

```powershell
powershell -ExecutionPolicy Bypass -File scripts\playwright-cdp.ps1 -s=cdp attach --cdp=http://127.0.0.1:9333
```

## Core commands after attach

Use snapshot refs for normal page interaction.

```bash
bash scripts/playwright-cdp.sh -s=cdp snapshot
bash scripts/playwright-cdp.sh -s=cdp snapshot --boxes
bash scripts/playwright-cdp.sh -s=cdp snapshot --depth=4
bash scripts/playwright-cdp.sh -s=cdp snapshot e34
bash scripts/playwright-cdp.sh -s=cdp snapshot --filename=after-click.yaml
bash scripts/playwright-cdp.sh -s=cdp goto https://playwright.dev
bash scripts/playwright-cdp.sh -s=cdp click e3
bash scripts/playwright-cdp.sh -s=cdp dblclick e7
bash scripts/playwright-cdp.sh -s=cdp fill e5 "user@example.com" --submit
bash scripts/playwright-cdp.sh -s=cdp type "search query"
bash scripts/playwright-cdp.sh -s=cdp press Enter
bash scripts/playwright-cdp.sh -s=cdp hover e4
bash scripts/playwright-cdp.sh -s=cdp select e9 "option-value"
bash scripts/playwright-cdp.sh -s=cdp upload ./document.pdf
bash scripts/playwright-cdp.sh -s=cdp drop e4 --path=./image.png
bash scripts/playwright-cdp.sh -s=cdp drop e4 --data="text/plain=hello world"
bash scripts/playwright-cdp.sh -s=cdp check e12
bash scripts/playwright-cdp.sh -s=cdp uncheck e12
bash scripts/playwright-cdp.sh -s=cdp screenshot --filename=page.png
```

Use selectors or Playwright locators when refs are not stable:

```bash
bash scripts/playwright-cdp.sh -s=cdp click "#main > button.submit"
bash scripts/playwright-cdp.sh -s=cdp click "getByRole('button', { name: 'Submit' })"
bash scripts/playwright-cdp.sh -s=cdp click "getByTestId('submit-button')"
```

普通 `click` 对可见、启用元素持续等待，或组合框、弹窗等复合组件的键盘行为不一致时，按 [交互失败排查与验收边界](references/interaction-troubleshooting.md) 检查活动页面、命中区域、动画和替代交互路径。不要用 DOM 提交或直接请求接口掩盖指针交互失败。

## Tabs and navigation

```bash
bash scripts/playwright-cdp.sh -s=cdp tab-list
bash scripts/playwright-cdp.sh -s=cdp tab-new https://example.com/page
bash scripts/playwright-cdp.sh -s=cdp tab-select 0
bash scripts/playwright-cdp.sh -s=cdp tab-close 1
bash scripts/playwright-cdp.sh -s=cdp go-back
bash scripts/playwright-cdp.sh -s=cdp go-forward
bash scripts/playwright-cdp.sh -s=cdp reload
bash scripts/playwright-cdp.sh -s=cdp resize 1440 1000
bash scripts/playwright-cdp.sh -s=cdp pdf --filename=page.pdf
```

## Console, network, and storage

```bash
bash scripts/playwright-cdp.sh -s=cdp console
bash scripts/playwright-cdp.sh -s=cdp console error
bash scripts/playwright-cdp.sh -s=cdp requests
bash scripts/playwright-cdp.sh -s=cdp request 3

bash scripts/playwright-cdp.sh -s=cdp cookie-list
bash scripts/playwright-cdp.sh -s=cdp cookie-get session_id
bash scripts/playwright-cdp.sh -s=cdp cookie-set session_id abc123 --domain=example.com --httpOnly --secure
bash scripts/playwright-cdp.sh -s=cdp localstorage-list
bash scripts/playwright-cdp.sh -s=cdp localstorage-get token
bash scripts/playwright-cdp.sh -s=cdp sessionstorage-list

bash scripts/playwright-cdp.sh -s=cdp state-save auth.json
bash scripts/playwright-cdp.sh -s=cdp state-load auth.json
```

Use `--raw` for machine-readable pipelines:

```bash
bash scripts/playwright-cdp.sh -s=cdp --raw eval "document.title"
bash scripts/playwright-cdp.sh -s=cdp --raw snapshot > page.yml
bash scripts/playwright-cdp.sh -s=cdp --raw cookie-get session_id
TOKEN=$(bash scripts/playwright-cdp.sh -s=cdp --raw cookie-get session_id)
```

Use `--json` for structured JSON output:

```bash
bash scripts/playwright-cdp.sh -s=cdp list --json
```

## Keyboard and mouse

```bash
bash scripts/playwright-cdp.sh -s=cdp keydown Shift
bash scripts/playwright-cdp.sh -s=cdp keyup Shift
bash scripts/playwright-cdp.sh -s=cdp mousemove 150 300
bash scripts/playwright-cdp.sh -s=cdp mousedown
bash scripts/playwright-cdp.sh -s=cdp mousedown right
bash scripts/playwright-cdp.sh -s=cdp mouseup
bash scripts/playwright-cdp.sh -s=cdp mousewheel 0 100
```

## Dialog handling

```bash
bash scripts/playwright-cdp.sh -s=cdp dialog-accept
bash scripts/playwright-cdp.sh -s=cdp dialog-accept "confirmation text"
bash scripts/playwright-cdp.sh -s=cdp dialog-dismiss
```

## Request routing

```bash
bash scripts/playwright-cdp.sh -s=cdp route "**/*.jpg" --status=404
bash scripts/playwright-cdp.sh -s=cdp route "**/api/users" --body='[{"id":1}]' --content-type=application/json
bash scripts/playwright-cdp.sh -s=cdp route-list
bash scripts/playwright-cdp.sh -s=cdp unroute "**/*.jpg"
bash scripts/playwright-cdp.sh -s=cdp unroute
```

See [references/request-mocking.md](references/request-mocking.md) for advanced mocking with `run-code`.

## Tracing and video

```bash
bash scripts/playwright-cdp.sh -s=cdp tracing-start
bash scripts/playwright-cdp.sh -s=cdp tracing-stop

bash scripts/playwright-cdp.sh -s=cdp video-start recording.webm
bash scripts/playwright-cdp.sh -s=cdp video-chapter "Chapter Title" --description="Details" --duration=2000
bash scripts/playwright-cdp.sh -s=cdp video-stop
```

See [references/tracing.md](references/tracing.md) and [references/video-recording.md](references/video-recording.md) for detail.

## Debug tools

```bash
bash scripts/playwright-cdp.sh -s=cdp highlight e5
bash scripts/playwright-cdp.sh -s=cdp highlight e5 --style="outline: 3px dashed red"
bash scripts/playwright-cdp.sh -s=cdp highlight e5 --hide
bash scripts/playwright-cdp.sh -s=cdp highlight --hide
bash scripts/playwright-cdp.sh -s=cdp generate-locator e5 --raw
bash scripts/playwright-cdp.sh -s=cdp show --annotate
```

## Raw CDP commands

Use `run-code` when the task requires a Chrome DevTools Protocol domain or command that the CLI does not expose directly. Create a CDP session from the active page, enable the needed domain, send commands, and return serializable data.

```bash
bash scripts/playwright-cdp.sh -s=cdp run-code "async page => {
  const cdp = await page.context().newCDPSession(page);
  return await cdp.send('Browser.getVersion');
}"
```

```bash
bash scripts/playwright-cdp.sh -s=cdp run-code "async page => {
  const cdp = await page.context().newCDPSession(page);
  await cdp.send('Network.enable');
  return await cdp.send('Runtime.evaluate', {
    expression: 'navigator.userAgent',
    returnByValue: true
  });
}"
```

CDP command and parameter names are case-sensitive. Use protocol commands for browser internals, performance metrics, emulation, coverage, security state, and low-level network diagnostics. After the session is attached through `--cdp`, use `playwright-cli` page commands for interaction.

## Session lifecycle

For CDP-attached browsers, leave the external Chrome and CDP port running after the requested task. Do not run `detach`, `close`, `close-all`, `kill-all`, or process-kill commands as normal cleanup.

Only detach or close when the user explicitly asks. If cleanup is requested, prefer `bash scripts/playwright-cdp.sh -s= detach` because it leaves the browser and CDP endpoint running.

When multiple CDP endpoints are in use, name sessions by endpoint or purpose:

```bash
bash scripts/playwright-cdp.sh -s=local attach --cdp=http://127.0.0.1:9222
bash scripts/playwright-cdp.sh -s=staging attach --cdp=http://127.0.0.1:9333
```

## Installation fallback

If the global command is unavailable, try a local version first:

```bash
npx --no-install playwright-cli --version
bash scripts/playwright-cdp.sh -s=cdp attach --cdp=http://127.0.0.1:9222
```

The wrapper automatically falls back to `npx --no-install playwright-cli` when a global `playwright-cli` binary is unavailable.

If no local version exists, install the CLI:

```bash
npm install -g @playwright/cli@0.1.17
```

`0.1.17` 是本机验证基线。使用其他版本前必须运行环境与能力检查；安装成功不代表本 Skill 的全部命令都兼容。

## References

- CDP startup and troubleshooting: [references/cdp-startup.md](references/cdp-startup.md)
- CLI 版本与能力契约：[references/cli-compatibility.md](references/cli-compatibility.md)
- CDP protocol recipes: [references/cdp-recipes.md](references/cdp-recipes.md)
- Element attribute inspection: [references/element-attributes.md](references/element-attributes.md)
- 交互失败排查与验收边界：[references/interaction-troubleshooting.md](references/interaction-troubleshooting.md)
- Request mocking: [references/request-mocking.md](references/request-mocking.md)
- Custom Playwright code: [references/running-code.md](references/running-code.md)
- Storage management: [references/storage-state.md](references/storage-state.md)
- Test code generation: [references/test-generation.md](references/test-generation.md)
- Tracing: [references/tracing.md](references/tracing.md)
- Video recording: [references/video-recording.md](references/video-recording.md)

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [betterlmy](https://github.com/betterlmy)
- **Source:** [betterlmy/agent-skills](https://github.com/betterlmy/agent-skills)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-betterlmy-agent-skills-playwright-cli-cdp
- Seller: https://agentstack.voostack.com/s/betterlmy
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.