playwright-repl

Interactive terminal REPL for browser automation powered by Playwright. Supports keyword commands and JavaScript.

npm install -g playwright-repl
playwright-repl

pw> goto https://demo.playwright.dev/todomvc/
pw> fill "What needs to be done?" Buy groceries
pw> press Enter
pw> await page.title()
pw> verify text 1 item left
pw> screenshot

Install

npm install -g playwright-repl

# Install Chromium
npx playwright install chromium

AI Skills

playwright-repl includes an AI skill file that teaches agents (Claude Code, Cursor, etc.) how to use pw-cli via Bash — no MCP needed.

Claude Code

# Project-level (this project only)
mkdir -p .claude/skills/playwright-repl
cp node_modules/playwright-repl/skills/SKILL.md .claude/skills/playwright-repl/SKILL.md

# Or global (all projects)
mkdir -p ~/.claude/skills/playwright-repl
cp node_modules/playwright-repl/skills/SKILL.md ~/.claude/skills/playwright-repl/SKILL.md

Then invoke with /playwright-repl or let Claude auto-detect it from the skill description.

Cursor

mkdir -p .cursor/skills/playwright-repl
cp node_modules/playwright-repl/skills/SKILL.md .cursor/skills/playwright-repl/SKILL.md

The skill defines allowed-tools: Bash(pw-cli:*) so the agent can run browser commands directly.

Connection Modes

| Mode | Flag | How it works | |------|------|--------------| | Launch | (default) | Launches Chromium directly — keyword + JS, full Playwright API | | Connect | --connect [port] | Connects to existing Chrome via CDP — cookies and logins intact |

Launch (default)

Launches Chromium with full Playwright API. Headed by default — use --headless for CI/scripting. Supports both keyword commands and JavaScript.

playwright-repl                          # headed (default)
playwright-repl --headless               # headless for CI/scripting
playwright-repl --command "snapshot"     # run one command and exit

Connect

Connect to an existing Chrome instance via CDP. Your cookies, logins, and extensions are available.

# Start Chrome with debugging enabled:
# chrome --remote-debugging-port=9222

playwright-repl --connect                # connect to Chrome on port 9222
playwright-repl --connect 9333           # custom port
playwright-repl --connect --replay examples/  # replay scripts against existing Chrome

HTTP Mode

Add --http to any mode to start an HTTP server alongside the REPL. This lets other processes send commands without starting a new browser session — ideal for AI tools, scripts, and CI.

# Terminal 1: Start REPL with HTTP server
playwright-repl --http                        # launch + HTTP (port 9223)
playwright-repl --http --http-port 9224       # custom port

# Terminal 2: Send commands via HTTP (fast — reuses existing session)
playwright-repl --http --command "snapshot"
playwright-repl --http --command "click e5"

The HTTP server exposes:

• GET /health — check if server is alive
• POST /run — run a command: {"command": "snapshot"}
• POST /run-script — run a multi-line script: {"script": "...", "language": "pw"}

Works with curl too:

curl -X POST http://localhost:9223/run -d '{"command":"snapshot"}'

pw-cli — Quick Command Shorthand

pw-cli is a shorthand for playwright-repl --http --command. When given arguments, it sends the command via HTTP to a running session (REPL, MCP, or VS Code):

pw-cli "snapshot"                # → playwright-repl --http --command "snapshot"
pw-cli "click e5"                # → playwright-repl --http --command "click e5"
pw-cli "await page.title()"     # JavaScript works too
pw-cli                           # no args → starts interactive REPL

Requires a running --http server (or MCP server) on port 9223. Start one first:

# Option 1: REPL with HTTP
playwright-repl --http

# Option 2: MCP server (HTTP starts automatically)
# (launched by Claude Desktop / Claude Code)

Usage

# Interactive REPL
playwright-repl [options]

# Replay a recorded session
playwright-repl --replay session.pw

# Replay all .pw files in a folder
playwright-repl --replay examples/

# Replay multiple files
playwright-repl --replay a.pw b.pw c.pw

# Step through replay (pause between commands)
playwright-repl --replay session.pw --step

# Start REPL with recording enabled
playwright-repl --record my-test.pw

# Run a single command and exit
playwright-repl --command "snapshot"

# Pipe commands
echo -e "goto https://example.com\nsnapshot" | playwright-repl

Input Modes

| Mode | Description | |------|-------------| | Keyword — click "Sign in", goto https://... | Playwright commands in natural syntax | | JavaScript — await page.title(), 1 + 1 | Full Playwright API |

The REPL auto-detects keyword commands and JavaScript expressions. For DOM access use await page.evaluate(() => document.title). For keyword commands, see Command Reference.

CLI Options

| Option | Description | |--------|-------------| | --headless | Run browser in headless mode (default: headed) | | --connect [port] | Connect to existing Chrome via CDP (default: 9222) | | --http | Start HTTP server for external command access (port 9223) | | --http-port <port> | HTTP server port (default: 9223) | | --command <cmd> | Run a single command, print output, and exit | | --config <file> | Path to config file | | --replay <files...> | Replay .pw or .js file(s) or folder(s) | | --record <file> | Start REPL with recording to file | | --step | Pause between commands during replay | | -q, --silent | Suppress banner and status messages | | -h, --help | Show help |

REPL Meta-Commands

| Command | Description | |---------|-------------| | .help | Show available commands | | .aliases | Show all command aliases | | .status | Show connection status | | .reconnect | Restart browser | | .record [file] | Start recording commands | | .save | Stop recording and save to file | | .pause | Pause/resume recording | | .discard | Discard current recording | | .replay <file> | Replay a recorded session | | .history | Show session command history | | .clear | Clear the console output | | .exit | Exit REPL (also Ctrl+D) |

Recording & Replay

Record browser interactions and replay them later — great for regression tests, onboarding demos, or CI smoke tests.

Record

# From CLI flag
playwright-repl --record my-test.pw --headed

# Or inside the REPL
pw> .record my-test
⏺ Recording to my-test.pw
pw> goto https://demo.playwright.dev/todomvc/
pw> fill "What needs to be done?" Buy groceries
pw> press Enter
pw> verify text 1 item left
pw> .save
✓ Saved 4 commands to my-test.pw

Replay

# Full speed
playwright-repl --replay my-test.pw

# Step-through (press Enter between commands)
playwright-repl --replay my-test.pw --step --headed

# Replay all .pw files in a folder
playwright-repl --replay examples/ --silent

# Inside the REPL
pw> .replay my-test.pw

Multi-file replay runs all files sequentially, writes a replay-<timestamp>.log, and prints a pass/fail summary. Exit code 0 if all pass, 1 if any fail.

.pw File Format

Plain text — human-readable, diffable, version-controllable:

# CI smoke test
# App: https://demo.playwright.dev/todomvc/

goto https://demo.playwright.dev/todomvc/
fill "What needs to be done?" Buy groceries
press Enter
verify text Buy groceries
verify text 1 item left

Examples

| File | Description | |------|-------------| | 01-add-todos.pw | Add todos and verify with assertions | | 02-complete-and-filter.pw | Complete todos, use filters | | 03-record-session.pw | Record a test session | | 04-replay-session.pw | Replay with step-through | | 05-ci-pipe.pw | CI smoke test | | 06-edit-todo.pw | Double-click to edit a todo | | 07-test-click-nth.pw | --nth disambiguation | | 08-localstorage.pw | localStorage commands | | 09-inspection-commands.pw | Inspection commands | | 10-video-recording.pw | Video recording with chapters |

playwright-repl --replay examples/01-add-todos.pw --headed
playwright-repl --replay examples/ --silent

Requirements

• Node.js >= 20
• playwright >= 1.59

Command Reference

Short aliases are CLI-only.

Navigation

| Command | Alias | Description | |---------|-------|-------------| | goto <url> | g | Navigate to a URL | | open [url] | o | Open browser (optionally navigate) | | go-back | back | Go back in history | | go-forward | fwd | Go forward in history | | reload | r | Reload page |

Interaction

| Command | Alias | Description | |---------|-------|-------------| | click <ref> | c | Click an element | | dblclick <ref> | dc | Double-click an element | | fill <ref> <text> | f | Fill a form field | | type <text> | t | Type text key by key | | press <key> | p | Press a keyboard key | | hover <ref> | h | Hover over element | | select <ref> <value> | sel | Select dropdown option | | check <ref> | chk | Check a checkbox | | uncheck <ref> | unchk | Uncheck a checkbox | | upload <ref> <file> | — | Upload a file | | drag <from> <to> | — | Drag and drop |

Locator Flags

All text-based interaction commands support these flags:

| Flag | Description | |------|-------------| | --nth <n> | Select the nth visible match (0-indexed) | | --exact | Exact text match only — skip the fallback chain | | --in <text> | Scope command to a container matching text | | --frame <selector> | Target an element inside an iframe |

pw> click "Submit" --nth 0           # click the first "Submit"
pw> click "Submit" --exact           # only exact text match, no fuzzy fallback
pw> fill "Email" "test" --exact      # fill only if label is exactly "Email"
pw> highlight "npm"                  # show all matches (returns count)
→ Highlighted 24 elements
pw> highlight "npm" --exact          # only exact "npm", not "pnpm"
→ Highlighted 2 elements
pw> highlight "npm" --nth 0          # highlight just the first match
→ Highlighted 1 of 24
pw> highlight --clear                # dismiss the highlight overlay
→ Cleared
pw> click "Delete" --in listitem "reading"   # click within a specific container
pw> click "Submit" --frame "#my-iframe"      # click inside an iframe

Inspection

| Command | Alias | Description | |---------|-------|-------------| | snapshot | s | Accessibility tree with element refs | | screenshot | ss | Take a screenshot (saved to file) | | highlight <text\|role\|css> | hl | Highlight matching elements on page | | eval <expr> | e | Evaluate JavaScript in browser context | | console | con | Browser console messages | | network | net | Network requests log | | run-code <code> | — | Run Playwright code with page object |

Assertions

| Command | Alias | Description | |---------|-------|-------------| | verify text <text> | vt | Verify text is visible on page | | verify no-text <text> | vnt | Verify text is not visible | | verify element <role> <name> | ve | Verify element exists by role and name | | verify value <ref> <value> | vv | Verify input/select/checkbox value | | verify list <ref> <items> | vl | Verify list contains expected items |

Tabs

| Command | Alias | Description | |---------|-------|-------------| | tab-list | tl | List open tabs | | tab-new [url] | tn | Open a new tab | | tab-close [index] | tc | Close a tab | | tab-select <index> | ts | Switch to a tab |

Storage & Cookies

| Command | Description | |---------|-------------| | state-save [file] | Save auth state (cookies + storage) | | state-load <file> | Load auth state | | cookie-list | List all cookies | | cookie-get <name> | Get a specific cookie | | cookie-set <name> <value> | Set a cookie | | cookie-delete <name> | Delete a cookie | | cookie-clear | Clear all cookies | | localstorage-list | List all localStorage | | localstorage-get <key> | Get localStorage value | | localstorage-set <key> <value> | Set localStorage value | | localstorage-delete <key> | Delete localStorage key | | localstorage-clear | Clear all localStorage | | sessionstorage-list | List all sessionStorage | | sessionstorage-get <key> | Get sessionStorage value | | sessionstorage-set <key> <value> | Set sessionStorage value | | sessionstorage-delete <key> | Delete sessionStorage key | | sessionstorage-clear | Clear all sessionStorage |

Network Routing

| Command | Description | |---------|-------------| | route <pattern> | Intercept network requests | | route-list | List active routes | | unroute [pattern] | Remove route(s) |

Dialogs & Layout

| Command | Description | |---------|-------------| | dialog-accept [text] | Accept a browser dialog | | dialog-dismiss | Dismiss a browser dialog | | resize <w> <h> | Resize browser window | | pdf | Save page as PDF |

Video Recording

| Command | Description | |---------|-------------| | video-start [--size WxH] | Start video recording | | video-stop | Stop recording and save video | | video-chapter <title> | Add chapter marker to recording |

Video uses Playwright's screencast API and saves to ~/pw-videos/.

Browser Control

| Command | Alias | Description | |---------|-------|-------------| | close | q | Close the browser | | config-print | — | Print browser config |