Playwright CLI

Playwright CLI

Automate browsers through shell commands via the Bash tool.

Core Workflow

Every interaction follows this pattern:

1. Open a page: playwright-cli open <url>
2. Snapshot to discover elements: playwright-cli snapshot
3. Interact using refs from the snapshot: playwright-cli click <ref>
4. Verify the result: playwright-cli screenshot or playwright-cli snapshot

Always run snapshot before interacting — element refs come exclusively from snapshot output and become stale after navigation.

Command Reference

Navigation

Interaction

Output

Important: --filename resolves relative to the working directory, NOT outputDir. When using --filename, always prepend the project's outputDir value (check .playwright/cli.config.json; defaults to .playwright-cli). Example: playwright-cli screenshot --filename=<outputDir>/my-screenshot.png

Tabs

Keyboard

playwright-cli press Enter          # Enter, Tab, Escape, ArrowDown, etc.
playwright-cli keydown Shift         # Hold key down
playwright-cli keyup Shift           # Release key

Mouse

playwright-cli mousemove 150 300     # Move to coordinates
playwright-cli mousedown [button]    # Press button (left/right)
playwright-cli mouseup [button]      # Release button
playwright-cli mousewheel 0 100      # Scroll (deltaX deltaY)

Sessions

• Default session — all commands share one session automatically
• Named sessions — playwright-cli -s=<name> open <url> for parallel browsers
• List sessions — playwright-cli list
• Close one — playwright-cli -s=<name> close
• Close all — playwright-cli close-all
• Force kill — playwright-cli kill-all
• Persistent profile — playwright-cli open <url> --persistent
• Custom profile — playwright-cli open <url> --profile=/path/to/dir
• Delete data — playwright-cli delete-data or playwright-cli -s=<name> delete-data
• Environment variable — PLAYWRIGHT_CLI_SESSION=my-project

Configuration

playwright-cli open <url> --browser=chromium    # chromium (default), firefox, webkit, chrome, msedge
playwright-cli open <url> --headed              # Visible browser window
playwright-cli open <url> --config=config.json  # Custom config file
playwright-cli open <url> --extension           # Connect via browser extension

Create .playwright/cli.config.json in the project for persistent settings:

{ "browser": { "browserName": "chromium", "launchOptions": { "headless": true } }, "outputDir": ".playwright-cli", "timeouts": { "action": 5000, "navigation": 60000 } }

Other options: network.allowedOrigins, network.blockedOrigins, saveVideo. Environment variables use PLAYWRIGHT_MCP_ prefix (e.g., PLAYWRIGHT_MCP_BROWSER=firefox).

Common Pitfalls

• Interacting without snapshot — refs are unknown until snapshot runs
• Stale refs after navigation — re-run snapshot after goto, link clicks, or form submissions
• fill vs type — fill clears the field first; type appends to current content
• Stuck sessions — run playwright-cli kill-all to force-close all browsers

Resources

• EXAMPLES.md — Multi-step workflow examples
• TROUBLESHOOTING.md — Error diagnosis and fixes
• references/request-mocking.md — Intercept, mock, and block network requests
• references/running-code.md — Execute arbitrary Playwright code via run-code
• references/session-management.md — Named sessions, isolation, concurrent browsers
• references/storage-state.md — Cookies, localStorage, sessionStorage management
• references/test-generation.md — Generate Playwright test code from CLI actions
• references/tracing.md — Capture execution traces for debugging
• references/video-recording.md — Record browser sessions as WebM video