plwr

plwr (prounounced PLUR) is a Playwright CLI for browser automation using CSS selectors. Built on playwright-rs.

plwr start                     # Started session 'default'
plwr open https://example.com
plwr text h1                   # Example Domain
plwr attr a href               # https://iana.org/domains/example
plwr stop                      # Stopped session 'default'

Install

Homebrew

brew install andreasjansson/tap/plwr

Crates.io

cargo install plwr

Dependencies

Requires Playwright:

npm install -g playwright && npx playwright install chromium

For video conversion to non-webm formats, install ffmpeg.

AI Agent Skill

plwr includes a skill file that teaches AI coding agents (like Claude Code) how to automate browsers with plwr. The skill covers the full command set, selector syntax, and common patterns.

Copy the skill to your skills directory:

# Claude Code - personal (available across all your projects):
cp -r skills/plwr ~/.claude/skills/

# Claude Code - project-specific (commit to version control):
cp -r skills/plwr .claude/skills/

# OpenCode:
cp -r skills/plwr ~/.config/opencode/skills/

Usage

Start a browser session, navigate, interact, and stop:

plwr start                      # start headless browser
plwr open https://example.com   # navigate to URL
plwr text h1                    # Example Domain
plwr stop                       # shut down browser

Environment variables

All commands take -S/--session and -T/--timeout as global options, which override the environment variables.

Starting and stopping

start launches the browser. All other commands require a running session. Use --headed (or the PLAYWRIGHT_HEADED env var) to show the browser window.

plwr start                             # headless
plwr start --headed                     # visible browser window
plwr start --video recording.mp4       # record video of session
plwr start --ignore-cert-errors        # ignore TLS certificate errors
plwr stop                              # shut down (saves video if recording)

Commands that interact with page content (text, click, wait, eval, etc.) require a page to be open first via plwr open. Commands that configure the session (header, viewport) work before any page is opened.

Remote debugging (CDP)

Connect to your running Chrome instead of launching a new browser. New tabs share your existing cookies and login state.

1. In Chrome, go to chrome://inspect/#remote-debugging and enable it
2. Connect plwr:

plwr start --cdp                     # stable Chrome (default)
plwr start --cdp beta                # Chrome Beta
plwr start --cdp ~/my-profile        # custom --user-data-dir path
plwr start --cdp ws://host:9222/...  # direct WebSocket URL
plwr open https://example.com        # opens in a new tab in your Chrome
plwr text h1
plwr stop                            # closes the tab, Chrome keeps running

Chrome shows a permission dialog on each connection — click Allow. --cdp is mutually exclusive with --headed and --video.

Example: post to X/Twitter (using your logged-in session):

plwr start --cdp
plwr open https://x.com/compose/post
plwr click '[data-testid="tweetTextarea_0"] >> nth=0'
plwr type 'hello world'
plwr click '[data-testid="tweetButton"]'
plwr stop

Navigation

open navigates the current page within the existing browser context. Headers, cookies, and other state are preserved across navigations. There is no separate goto command — open always reuses the same context. If you need a fresh context, use plwr stop followed by plwr start and plwr open.

plwr open "https://example.com"
plwr reload
plwr url

Waiting

plwr wait .my-element
plwr wait-not .loading-spinner -T 10000
plwr wait-any '.success' '.error' '.timeout'   # prints first match
plwr wait-all '.header' '.sidebar' '.content'

Interaction

All interaction commands (click, fill, hover, check, etc.) auto-wait for the element to appear and become actionable before performing the action, up to the timeout (-T, default 5000ms). You rarely need an explicit plwr wait before an interaction — just use the interaction directly:

plwr click '#submit-btn'                 # waits for button, then clicks
plwr fill '#name-input' 'Alice' -T 10000 # waits up to 10s, then fills

plwr click '#submit-btn'
plwr fill '#name-input' 'Alice'
plwr type 'hello world'             # type text character by character
plwr type 'slow' --delay 100        # 100ms between keystrokes
plwr press Enter
plwr press Control+c
plwr dblclick '.editable-cell'   # double-click
plwr hover '.dropdown-trigger'   # hover (for tooltips, menus)
plwr focus '#search'             # focus an element
plwr blur '#email'               # unfocus an element
plwr scroll '.footer'            # scroll element into view

click and dblclick support modifier keys and mouse button flags:

plwr click '#item' --shift           # shift-click (e.g. range select)
plwr click '#item' --alt             # alt-click
plwr click '#item' --meta            # meta-click (Cmd on macOS)
plwr click '#item' --control         # control-click (--ctrl also works)
plwr click '#item' --alt --shift     # multiple modifiers
plwr click '#item' --right           # right-click (context menu)
plwr click '#item' --middle          # middle-click
plwr dblclick '#item' --shift        # shift-double-click

Supported keys for press: a–z, A–Z, 0–9, Backspace, Tab, Enter, Escape, Space, Delete, Insert, ArrowUp, ArrowDown, ArrowLeft, ArrowRight, Home, End, PageUp, PageDown, F1–F12, Control, Shift, Alt, Meta, and any US keyboard character (!@#$%^&*()_+-=[]{}\\|;:'",./<>?`~). Chords use +: Control+c, Shift+Enter, Meta+a.

type sends individual key events for each character in a string — use it for contenteditable elements (like Twitter's compose box) where fill doesn't work. fill sets the value of <input> and <textarea> elements directly. press sends a single keystroke and supports special keys and chords that type cannot.

Clipboard

Copy content from an element to the browser clipboard and paste it at the currently focused element. Works with text and images (<img>, <canvas>).

plwr clipboard-copy '#source'        # copy text or image to clipboard
plwr focus '#target'
plwr clipboard-paste                 # paste at focused element

Checkboxes and radios

plwr check '#agree-terms'        # check a checkbox or radio
plwr uncheck '#newsletter'       # uncheck a checkbox

Select dropdowns

plwr select '#country' us               # select by value
plwr select '#country' --label 'Canada' # select by visible text
plwr select '#colors' red green blue    # multi-select

Querying

Like interaction commands, text, attr, inner-html, and input-value auto-wait for the element to appear before reading its value.

plwr text h1                     # print textContent
plwr inner-html '.content'       # print innerHTML (preserves tags)
plwr attr a href                 # print attribute value
plwr input-value '#email'        # print value of input/textarea/select
plwr computed-style '.box' display width  # print computed CSS properties
plwr count '.list-item'          # print number of matches
plwr exists '.sidebar'           # exit 0 if found, 1 if not

Headers

Set extra HTTP headers sent with every request. Headers persist across navigations within the same session. Can be set before or after open.

plwr header CF-Access-Client-Id "$CLIENT_ID"
plwr header CF-Access-Client-Secret "$CLIENT_SECRET"
plwr open "$WORKER_URL"          # headers sent automatically
plwr header --clear              # remove all extra headers

Cookies

plwr cookie session_id abc123    # set on current page's URL
plwr cookie token xyz --url https://example.com
plwr cookie --list               # list all cookies as JSON
plwr cookie --clear              # remove all cookies

Viewport

plwr viewport 1280 720          # desktop
plwr viewport 375 667           # iPhone SE

File uploads

plwr input-files 'input[type=file]' photo.png
plwr input-files '#upload' a.txt b.txt c.txt   # multiple files
plwr input-files '#upload'                      # clear selection

Dialogs (alert, confirm, prompt)

Handle native browser dialogs. The next-dialog command registers a one-shot handler for the next dialog — call it before the action that triggers the dialog, because dialogs block page execution until handled.

plwr next-dialog accept                # click OK on the next alert or confirm
plwr next-dialog dismiss               # click Cancel on the next confirm or prompt
plwr next-dialog accept 'Alice'        # type 'Alice' into a prompt, then click OK

Typical flow:

plwr next-dialog accept           # arm the handler
plwr click '#delete-btn'          # triggers confirm() → auto-accepted
plwr text '#result'               # page updated after dialog closed

For prompt() dialogs, the text argument to accept is entered into the prompt's input field. If omitted, the prompt is accepted with an empty string. dismiss clicks Cancel, returning null to the page.

Console logs

Capture browser console output (log, warn, error, info, debug). Messages are automatically captured from page load onward, including messages logged before your code runs.

plwr console                     # print all captured messages as JSON
plwr console --clear             # clear the log buffer

Each entry includes level, ts (timestamp in ms), and args (array of stringified arguments).

Network requests

Capture all network requests made by the page. Requests are automatically captured from page load onward, including document, CSS, JS, images, fonts, fetch, XHR, and WebSocket connections. Status codes are available for all resource types.

plwr network                     # print all captured requests as JSON
plwr network --type fetch        # filter by type
plwr network --type css,js,img   # multiple types, comma-separated
plwr network --url '\.json$'     # filter by URL (regex)
plwr network --type fetch --url '/api/'  # combine type and URL filters
plwr network --type ws --include-ws-messages  # include WS send/recv log
plwr network --clear             # clear the buffer

Available types: doc, css, js, img, font, media, fetch, xhr, ws, wasm, manifest, other.

Each entry includes type, url, status (HTTP status code), method (for fetch/XHR/doc), size (transfer size in bytes), duration (ms), and ts (timestamp in ms).

WebSocket entries include type, url, status (101 on success), duration, and ts. With --include-ws-messages, a messages array is added containing each frame's dir (send/recv), data, and ts.

Computed styles

plwr computed-style h1                          # all computed styles as JSON
plwr computed-style '.box' display width color  # specific properties

JavaScript

Simple expressions are evaluated directly:

plwr eval "document.title"
plwr eval "({a: 1, b: [2, 3]})"   # returns pretty-printed JSON

For multi-statement logic, use an IIFE (immediately invoked function expression):

plwr eval "(() => {
  const rows = document.querySelectorAll('table tr');
  return Array.from(rows).map(r => r.cells[0]?.textContent);
})()"

Walk the DOM, gather computed styles, inspect layout:

plwr eval "(() => {
  const el = document.querySelector('.content');
  let node = el;
  const chain = [];
  while (node && chain.length < 6) {
    const cs = getComputedStyle(node);
    chain.push({
      tag: node.tagName,
      class: node.className,
      display: cs.display,
      width: cs.width,
    });
    node = node.parentElement;
  }
  return chain;
})()"

Objects and arrays are returned as pretty-printed JSON. Primitives (strings, numbers, booleans) are printed as plain text.

DOM tree

plwr tree              # full page tree as JSON
plwr tree '.sidebar'   # subtree rooted at selector

Screenshots

plwr screenshot
plwr screenshot --selector '.chart' --path chart.png

Video

Record a session by passing --video to start. The video is saved when stop is called. Non-webm formats (e.g. .mp4) require ffmpeg.

plwr start --video recording.mp4   # start with video recording
plwr open https://example.com
# ... do stuff ...
plwr stop                          # saves recording.mp4

Sessions

Run multiple independent browser sessions in parallel:

plwr -S session-a start
plwr -S session-b start
plwr -S session-a open https://example.com
plwr -S session-b open https://other.com
plwr -S session-a text h1   # Example Domain
plwr -S session-b text h1   # other.com's h1
plwr -S session-a stop
plwr -S session-b stop

Selectors

Playwright uses its own selector engine that extends CSS. Most standard CSS selectors work directly, but some advanced pseudo-classes need a css= prefix to bypass Playwright's parser.

Basics

plwr click '#submit-btn'                   # by id
plwr click '.btn.primary'                  # compound class
plwr click 'button'                        # by tag
plwr count 'input[type=email]'             # attribute match
plwr count 'input[type=text]'              # no quotes needed

Combinators

plwr count '#list > li'                    # child
plwr count 'h1 + p'                        # adjacent sibling
plwr count 'h1 ~ p'                        # general sibling
plwr text '.card p'                        # descendant

Attribute selectors

Unquoted attribute values work directly. For quoted values, use the css= prefix (see css= prefix below).

plwr count 'a[data-external]'             # has attribute
plwr count 'a[href^=/]'                   # starts with
plwr count 'a[href$=.pdf]'                # ends with
plwr count 'a[href*=example]'             # contains
plwr count '[data-testid=login-form]'      # exact match (no quotes)

Pseudo-classes that work without prefix

plwr click 'li:first-child'
plwr click 'li:last-child'
plwr text '#list li:nth-child(2)'          # second item
plwr count '#list li:nth-child(odd)'       # 1st, 3rd, ...
plwr count 'li:not(.done)'
plwr count '.card:has(img)'
plwr count 'div:empty'
plwr count 'input:checked'
plwr count 'input:disabled'
plwr count 'input:enabled'
plwr count 'input:required'

Playwright extensions

These are Playwright-specific and don't exist in standard CSS:

plwr click ':has-text("Sign in")'          # contains text
plwr click 'text=Sign in'                  # text shorthand
plwr click 'li.item >> nth=0'             # first match (0-based)
plwr click 'li.item >> nth=-1'            # last match
plwr text ':nth-match(li.item, 2)'         # alternative to nth=
plwr count 'button:visible'               # only visible elements
plwr text 'tr:has-text("Bob") >> td.name'  # chain with >>

The >> operator chains selectors — each segment is scoped to the previous match. You can mix CSS and Playwright engines:

plwr text '#data-table >> tr:has-text("Alice") >> td.status'

css= prefix

Playwright's selector parser auto-detects whether a string is CSS, XPath, or a Playwright selector. Some valid CSS pseudo-classes confuse the auto-detection because Playwright tries to interpret parenthesized arguments or quoted strings as its own syntax. Prefixing with css= forces native CSS evaluation.

Need css= prefix:

plwr text 'css=.mixed span:last-of-type'
plwr text 'css=li:nth-of-type(2)'
plwr count 'css=:is(.card, .sidebar)'
plwr text 'css=[data-testid="login-form"] button'

Work without prefix (Playwright recognizes these natively):

:nth-child(), :first-child, :last-child, :not(), :has(), :empty, :checked, :disabled, :enabled, :required, :visible, :has-text(), text=, >> nth=N.

Strict mode

Playwright locators are strict by default — if a selector matches multiple elements, commands like text, click, and attr will fail. Use >> nth=N or :nth-match() to pick one:

plwr text 'li.item'                        # fails if >1 match
plwr text 'li.item >> nth=0'              # first match
plwr text ':nth-match(li.item, 2)'         # second match (1-based)
plwr count 'li.item'                       # count always works
plwr exists 'li.item'                      # exists always works

Shell quoting

Watch out for shell metacharacters in selectors. The $ in $= will be interpreted by bash if not single-quoted:

plwr count "a[href$=.pdf]"                # ✗ bash eats the $
plwr count 'a[href$=.pdf]'                # ✓ single quotes

Example: cctr e2e test

Before (with raw playwright-cli run-code):

===
send a message
===
./pw --session=e2e run-code "async page => {
  const input = await page.waitForSelector('.chat-input', { timeout: 2000 });
  await input.fill('Hello agent');
  await page.keyboard.press('Enter');
  await page.waitForFunction(() => {
    const msgs = document.querySelectorAll('[data-role=assistant]');
    return Array.from(msgs).some(m => m.textContent.includes('Hi'));
  }, { timeout: 5000 });
}"
---

After (with plwr):

===
send a message
===
plwr fill '.chat-input' 'Hello agent'
plwr press Enter
---

===
agent responds
===
plwr wait '[data-role=assistant]:has-text("Hi")' -T 10000
---