Playwright CLI

Use @anthropic-ai/playwright-cli to drive a live browser from the terminal. Keep this file focused on trigger logic, workflow, guardrails, and reference routing. Use references/ for detailed commands, edge cases, and larger patterns.

Invocation model — read this first. Every command below (snapshot, click e0, fill e1 "text", etc.) is typed at the playwright-cli interactive prompt, not as standalone shell commands. You launch playwright-cli from bash, then enter commands at its > prompt. Do not prefix them with playwright-cli inside the session.

Trigger boundary

Use this skill when the task requires a real browser session and interactive CLI control:

• open pages, navigate, and verify what actually rendered
• fill forms, upload files, submit flows, and prove the result
• manage tabs, popups, or session state during a live run
• collect screenshots, console logs, network logs, or traces as evidence
• use short run-code snippets only when the CLI lacks a direct command

Do not use this skill when:

• the job is writing or reviewing Playwright test code instead of driving the CLI
• plain HTTP fetching or static scraping is enough
• the site needs Browserbase-style hosted browsing, anti-bot bypass, or remote browser routing; prefer run-agent-browser

Non-negotiable rules

1. Prefer the current browser context when it already has the right state. Do not reset sessions or reinstall tools just because a browser exists.
2. Prefer a new tab over a new window. Use a popup or new window only when the site forces one, such as OAuth or target=_blank flows.
3. Keep a running tab map in your notes: index -> purpose -> expected URL/state. Refresh it after every tab-new, tab-close, tab-select, or popup event.
4. Verify the active tab before every action. Use tab-list, tab-select if needed, eval "() => window.location.href", then snapshot.
5. Follow observe -> act -> verify. Never chain blind actions across unknown state.
6. Treat refs as disposable. Re-snapshot after navigation, SPA rerender, submission, tab switch, popup handling, or run-code.
7. Use CLI commands first. Reach for run-code only for waits, popups, downloads, iframes/shadow DOM, or missing primitives; then immediately re-enter the snapshot loop.
8. Treat screenshots as evidence, not default observation. Use snapshot for structure, eval for truth, screenshots for visual proof.
9. Clean up only what you created. Close transient tabs and temporary sessions, but do not destroy shared or pre-existing contexts.

Recommended workflow

1) Attach or bootstrap

Only bootstrap when the CLI or browser support is missing:

which playwright-cli || npm install -g @anthropic-ai/playwright-cli@latest
playwright-cli install --browser=chrome   # always run — ensures browser binary exists

Steering experience: Always run playwright-cli install --browser=chrome even if the CLI is already installed. It is a no-op when the binary exists, but skipping it causes cryptic "browser not found" errors when the binary is missing. This is a one-second check that prevents a five-minute debug session.

When you need an isolated session (parallel work, risky experiments), add to bootstrap:

playwright-cli config --isolated

• If an existing session or tab already contains the needed login or state, inspect it first instead of resetting everything.
• Start a named session or isolated browser only when you need clean-room state, parallel isolation, or risky experimentation; use references/tabs.md for the exact bootstrap patterns.
• For isolated sessions, also add session-stop <name> at the end of your cleanup to avoid leaking browser processes.
• Do not begin with session-stop-all unless you intentionally want to discard every active browser.

2) Establish tab and session ground truth

• Run tab-list.
• Decide whether to reuse the current tab or open a temporary work tab.
• When you need a new work surface, use tab-new first and open <url> second.

Steering experience: Do NOT use tab-new <url>. It is documented but unreliable — in testing it frequently opens about:blank instead of the requested URL. The safe two-step pattern is tab-new then open <url>.

• Record the tab map before you continue.
• If a popup or forced new window is expected, route to references/tabs.md before acting.

3) Observe before touching the page

Steering experience: snapshot writes a YAML accessibility-tree file to .playwright-cli/page-<timestamp>.yml and prints the file path, not the tree content. You must cat the file to read the actual refs. Example flow:

snapshot          # prints: Snapshot saved to .playwright-cli/page-1710456789.yml
cat .playwright-cli/page-1710456789.yml   # read the YAML to find refs like e0, e1, e5

Use the cheapest command that gives trustworthy state:

snapshot
eval "() => window.location.href"

Add only the extra proof you need:

• screenshot --filename=... for layout, visual regressions, or before/after evidence
• eval "() => document.title" or more specific eval checks when correctness matters
• console error and network when diagnosing failures or proving backend behavior

4) Act with the smallest direct command

The CLI has far more commands than just click and fill. Here is the complete reference:

Use direct commands with these rules:

• use check for radios and checkboxes when possible; it is safer than blind click
• after fill, select, or check, verify the live value with eval
• for uploads, trigger the file chooser first, then call upload
• if the page needs a wait, wait for a selector, URL, or response with run-code, then snapshot

Steering experience: The mousewheel <deltaX> <deltaY> parameter order may be swapped in some CLI versions (deltaY first, deltaX second). Always test with a small value first and verify with eval "() => window.scrollY" before relying on large scroll distances. See references/screenshots.md for details.

5) Verify immediately after each meaningful action

Steering experience: All artifact commands (console, network, snapshot, screenshot) write results to files, not to stdout. The CLI prints the file path; you must cat or inspect that file to see actual content. Never assume the page is clean or broken based on command output alone — always read the artifact file.

Use the lightest proof that actually confirms success:

Steering experience: console --clear and network --clear produce no visible output — they succeed silently. This is expected behavior, not an error. Do not re-run them thinking they failed.

Use progressively stronger evidence when risk increases:

1. State proof — snapshot + eval
2. Behavior proof — state proof + action-specific assertion
3. Visual proof — behavior proof + screenshot(s)
4. Diagnosis proof — visual/state proof + console, network, or tracing artifacts

Do this, not that

Recovery rules

If the workflow drifts, recover in this order:

1. Unsure which tab is active — tab-list, tab-select, eval "() => window.location.href", snapshot
2. Ref not found or action did nothing — re-snapshot (snapshot → cat <file>), then retry with fresh refs
3. SPA or lazy UI did not settle — use run-code to wait for a selector, URL, or response, then snapshot
4. Popup or new window appeared — handle it via references/tabs.md, then re-verify the main tab before continuing
5. Form or upload state is unclear — eval live values or files; do not infer from command success
6. Bug evidence is weak — console --clear (silent), network --clear (silent), reproduce once, cat artifact files, then capture a screenshot
7. You used run-code — assume refs are dead and rebuild state with snapshot
8. mousewheel scrolled wrong direction — try swapping deltaX/deltaY parameters; verify with eval "() => window.scrollY"
9. --clear seemed to fail — it didn't; --clear produces no output by design

Reference routing

Read only what matches the current job:

Common starting points

• Navigate and verify a page — references/navigation.md
• Fill, submit, and prove a form — references/forms.md and references/debugging.md if submit is flaky
• Work across multiple tabs or popups — references/tabs.md
• Collect visual proof — references/screenshots.md
• Diagnose why something failed — references/debugging.md
• Run a full workflow such as login or download — references/patterns.md

Cleanup

When browser work ends:

• close transient tabs you opened for the task
• stop or delete only the scratch named sessions you created — use session-stop <name> for isolated sessions to avoid leaking browser processes
• keep shared or preexisting sessions alive unless the user asked for teardown
• if you collected evidence, preserve the returned artifact paths in your answer