playwright-cli

Browser Automation via playwright-cli

Use playwright-cli (also aliased as playwright and puppeteer) via the bash tool for all browser automation.

Every tab-operating command requires --tab=<targetId>. There is no implicit "current tab". Always specify which tab you're operating on.

playwright-cli <command> --help prints that command's usage and does nothing else — safe to run before any action.

Quick Start

# 1. Open a page — note the targetId in the output
playwright-cli open https://example.com
# Output: Opened https://example.com in new tab [targetId: E9A3F...]

# 2. Take a snapshot to see the page structure and get element refs
playwright-cli snapshot --tab=E9A3F

# 3. Interact using refs from the snapshot (e.g. e5, e12)
playwright-cli click --tab=E9A3F e5
playwright-cli fill --tab=E9A3F e12 "hello world"

# 4. Each action prints "Snapshot: <path>" — read it to see what changed
playwright-cli snapshot --tab=E9A3F

Tab IDs

• tab-list shows all tabs with their targetIds and a stable (tab N) number. In the extension the user's active tab is marked (active); standalone Chrome does not report it.
• tab-new / open return the new tab's targetId — capture it for subsequent commands.
• Use --tab=<targetId> on ALL commands that operate on a tab.

Frame IDs

• frames --tab=<targetId> lists frame IDs. A frame ID is not a tab target ID; never pass it to --tab.
• Use --tab=<targetId> --frame=<frameId> with eval, eval-file, or snapshot to target a child frame, including cross-origin frames.
• A frame-scoped snapshot prints only that frame's accessibility subtree. Its frame-prefixed refs (f1e5) work with every ref command except drag, screenshot, and snapshot --boxes; do not pass --frame to those commands.

Common Failure Modes

• --tab <targetId> is required — you forgot --tab=<id>. Run tab-list to get IDs.
• is a frame ID, not a tab target ID — keep the owning tab's targetId in --tab and pass the frame ID with --frame.
• No snapshot available — run snapshot --tab=<id> before using refs.
• unknown flag "--x" / unexpected argument "y" — every subcommand rejects arguments it does not support, so an exit code of 0 means everything you passed was honoured. Check <verb> --help.
• For free-text payloads that start with - (e.g. fill/type/eval), put -- before the text: fill --tab=<id> e1 -- --dash-looking.
• is not an element ref — a screenshot's positional is a main-frame element ref (e5); the output path is --filename=<path>. Frame-prefixed refs (f1e5) clip only with click-family commands.
• Unknown ref / is no longer on the page — that element was removed or renamed, or the page navigated. Re-run snapshot for current refs; a ref is never re-pointed at a different element.
• Refs are tied to one tab + one page load. They do not carry across tabs, navigations, or reloads.