Browser Automation with playwright-cli

Validated against the installed playwright-cli binary on this machine (0.0.62). Treat the installed CLI help and live runtime behavior as the primary authority. Prefer this skill's documented + tested workflow over copied snippets from older skills.

How playwright-cli actually works

playwright-cli gives you a browser session controlled through terminal commands. The key object model is:

pages/tabs you navigate and inspect,
refs like e5 from snapshot,
artifact files from snapshot --filename, screenshot, console, and network.

Snapshots are not magical live DOM handles. They are point-in-time accessibility-tree dumps. Saved snapshots are markdown-style outline files in the current .playwright-cli/ artifact area.

Bootstrap (run once before browser work)

Use the documented CLI first:

which playwright-cli || npm install -g @anthropic-ai/playwright-cli@latest
playwright-cli install --browser=chrome
playwright-cli session-stop 2>/dev/null
playwright-cli config --browser=chrome --isolated

If you intentionally use named sessions, stop the specific one:

playwright-cli session-stop my-session 2>/dev/null

When all work is done, clean up deliberately:

playwright-cli session-stop-all

The default workflow: observe → act → snapshot again

Do not trust implicit snapshots from command output. Some commands print one, some do not, and some site changes are subtle.

Use this control loop instead:

open <url>
snapshot
screenshot --filename=step-1.png
[decide]
click / fill / select / check / press / open
snapshot
screenshot --filename=step-2.png
[repeat]

Rule: after any meaningful UI change, run snapshot before reusing refs. Proof rule: when correctness matters, pair the interaction with browser truth (eval) and visual evidence (screenshot), not just optimistic command output.

Refs are disposable

Refs die when page state changes in ways that matter:

navigation (open, go-back, go-forward, reload)
tab switches (tab-select)
some clicks/selects that re-render UI
any run-code that mutates page state

Treat refs as disposable. If in doubt, snapshot again.

CLI-first principle

Prefer direct CLI commands for:

navigation: open, go-back, go-forward, reload
observation: snapshot, screenshot, pdf
interaction: click, fill, select, check, uncheck, press
tab/session management: tab-new, tab-list, tab-select, tab-close, session-*
diagnostics: console, network

Use run-code only when the CLI does not express the step cleanly:

waits (waitForSelector, waitForResponse, waitForURL)
popups / downloads / file chooser edge cases
media emulation, cookies, geolocation
hidden-input fallback or page-level atomic operations

After run-code, assume the page may have changed and re-enter the normal loop:

snapshot
screenshot --filename=after-run-code.png

Essential commands

Navigation

open <url>
go-back
go-forward
reload

Observation

snapshot
snapshot --filename=page-state.md
screenshot --filename=view.png
screenshot --full-page --filename=page.png
screenshot <ref> --filename=element.png
pdf --filename=page.pdf

Interaction

click <ref>
fill <ref> "text"
fill <ref> "text" --submit
type "text"
select <ref> "value"
check <ref>
uncheck <ref>
hover <ref>
dblclick <ref>
drag <source-ref> <target-ref>
press Enter
keydown Shift
keyup Shift

Uploads

# 1. trigger a file chooser first by clicking the visible upload control or file input
click <upload-trigger-ref>

# 2. only after the page reports a file-chooser modal state:
upload /absolute/path/to/file
upload /absolute/path/to/file-a /absolute/path/to/file-b

JavaScript / Playwright API

eval "() => document.title"
eval "() => window.location.href"
eval "(el) => el.value" <ref>
run-code 'async (page) => { ... }'

Tabs and sessions

tab-new
tab-list
tab-select <index>
tab-close <index>

playwright-cli --session=my-session open https://example.com
playwright-cli session-list
playwright-cli session-stop my-session
playwright-cli session-delete my-session

Critical validated gotchas

1. `tab-new [url]` is not trustworthy in practice

The installed help advertises tab-new [url], but on this machine's installed CLI the runtime still opened about:blank during testing.

Safest pattern:

tab-new
open https://example.com

2. Quote URLs in zsh

Unquoted URLs with ?, &, or similar shell-sensitive characters can fail before they ever reach the CLI.

open "https://www.amazon.com/s?k=fidget+spinner"

3. Snapshots are not live form state

A snapshot may show the field in the tree, but not the live value you need to trust.

fill <ref> "hello@example.com"
eval "(el) => el.value" <ref>

4. `upload` is modal-driven, not ref-driven

Current tested behavior:

upload <ref> ... is wrong for this installed CLI.
upload /absolute/path only works after a file chooser is active.
paths outside allowed roots are rejected.

5. `check` works for radios too

Older lore said to use click for radios. On the installed CLI, check <ref> worked on a radio input in testing.

Prefer check when you want idempotent "selected" behavior.

6. Do not trust stale session/profile lore

Current docs/help support:

--session=name
session-stop [name]
session-delete [name]

The older -s=name, --persistent, and --profile guidance in this repo was stale and should not be copied forward.

7. The printed page header can be stale across tab operations

In testing, eval "() => window.location.href" was more trustworthy than the surrounding command header when tab state got odd.

Use eval for URL truth when it matters.

8. Console and network return artifact files, not inline diagnosis

The CLI returns log artifacts you must inspect. They can also be empty.

console error
network

Then open the generated files before claiming the page is clean or broken.

9. Artifact paths are implementation details

Do not build workflow assumptions around where .playwright-cli/... ends up relative to your current repo. Use the path the CLI returns.

10. `run-code` is a bridge, not a new default workflow

Use it for the one hard step, then go back to:

snapshot
screenshot --filename=evidence.png

11. `select` should use the option value

Inspect the select options first, then pass the option value, not the visible label you hope will work.

12. Public-site logs are evidence, not automatic blame

Large public sites can emit telemetry, anti-bot, or graphics noise. Capture it, inspect it, and interpret it carefully.

13. Commerce/search/filter flows need URL proof and visual proof

For stateful list pages, do not trust motion alone. Pair the interaction with:

snapshot
eval "() => window.location.href"
screenshot --filename=search-after.png

Verification patterns

Page health check

open <url>
snapshot
screenshot --filename=initial.png
console error
network

Form verification

fill <ref> "value"
eval "(el) => el.value" <ref>
click <submit-ref>
snapshot
eval "() => window.location.href"

Upload verification

click <upload-trigger-ref>
upload /absolute/path/to/file
eval "() => [...document.querySelector('input[type=file]').files].map(f => f.name)"

Search / filter / sort verification

open "https://www.amazon.com/s?k=fidget+spinner"
snapshot
screenshot --filename=search-before.png
# inspect refs / option values
select <sort-ref> "review-rank"
click <filter-ref>
snapshot
eval "() => window.location.href"
screenshot --filename=search-after.png

Multi-tab verification

open https://example.com
snapshot

tab-new
open https://example.org
snapshot

tab-select 0
snapshot
eval "() => window.location.href"

Sub-agent rules (shared-session work)

If you are a tab tenant inside a shared browser session:

tab-new → open <url> → [work] → tab-close <index>

Never create ad-hoc browser processes outside the shared CLI unless explicitly asked.
Never use close if other agents depend on the same session.
Prefer explicit tab-close <index> even though the command can omit the index.
Re-run snapshot after tab-select.
Re-check your tab index with tab-list before closing if other agents may have changed tab order.
Keep upload test files inside allowed roots and verify file names with eval after upload.

Reference files

Command reference — validated syntax and behavior notes for the installed CLI
Form and data extraction — forms, eval, radios, uploads, and extraction patterns
Session and tabs — tabs, sessions, cleanup, and stale-lore removals
Visual testing — screenshots, responsive checks, and comparison patterns
Debugging — console/network artifacts, troubleshooting, tracing, and run-code
Async and advanced recipes — waits, popups, downloads, and safe re-entry after advanced steps
Orchestrator guide — shared-session coordination for multiple agents

playwright-cli