playwright-cli 是面向 shell 的 Playwright 浏览器自动化接口，适合需要跨命令保持浏览器状态、检查快照并复用元素引用的任务。它输出页面快照，元素引用形如 e15，并显示实际执行的 Playwright 代码，便于将交互转为测试。
基本用法：用 playwright-cli open https://example.com 打开页面，playwright-cli snapshot 获取快照，playwright-cli click e15、playwright-cli fill e5 "user@example.com"、playwright-cli press Enter 操作，playwright-cli close 关闭。默认使用最近快照的引用，导航、DOM 大改或引用操作失败后应重新快照；引用不可用或不稳定时再用 CSS 选择器或 Playwright 定位器。
常用能力包括：指定浏览器打开、限制快照深度、截图、查看控制台警告、按过滤条件查看请求、查看请求头、运行自定义代码、启停 tracing，以及使用 -s=<name> 命名会话进行并发或长时任务；需要持久化 Cookie/存储时用 open --persistent；需要复用现有会话时可用 attach --cdp=chrome、attach --cdp=msedge 或 attach --cdp=http://127.0.0.1:9222。结束后及时关闭会话，close-all 和 kill-all 仅用于清理陈旧会话。
调试 Playwright 测试时可用 PLAYWRIGHT_HTML_OPEN=never npx playwright test --debug=cli，等待调试说明后通过 playwright-cli attach tw-abcdef 接入暂停会话。
使用限制：具体语法请以 playwright-cli --help 和各子命令 --help 为准，CLI 变化较快；--raw 适合把值传给其他工具，--json 仅在已安装版本支持时使用。更完整命令可参考 references/cli-reference.md 等按需加载的参考文件。