dev

playwright-cli

Playwright CLI with SKILLS

Playwright CLI vs Playwright MCP

This package provides CLI interface into Playwright. If you are using coding agents, that is the best fit.

• CLI: Modern coding agents increasingly favor CLI–based workflows exposed as SKILLs over MCP because CLI invocations are more token-efficient: they avoid loading large tool schemas and verbose accessibility trees into the model context, allowing agents to act through concise, purpose-built commands. This makes CLI + SKILLs better suited for high-throughput coding agents that must balance browser automation with large codebases, tests, and reasoning within limited context windows.

• MCP: MCP remains relevant for specialized agentic loops that benefit from persistent state, rich introspection, and iterative reasoning over page structure, such as exploratory automation, self-healing tests, or long-running autonomous workflows where maintaining continuous browser context outweighs token cost concerns. Learn more about Playwright MCP.

Key Features

• Token-efficient. Does not force page data into LLM.

Requirements

• Node.js 18 or newer
• Claude Code, GitHub Copilot, or any other coding agent.

Getting Started

Installation

npm install -g @playwright/cli@latest
playwright-cli --help

Installing skills

Claude Code, GitHub Copilot and others will use the locally installed skills.

playwright-cli install --skills

Skills-less operation

Point your agent at the CLI and let it cook. It'll read the skill off playwright-cli --help on its own:

Test the "add todo" flow on https://demo.playwright.dev/todomvc using playwright-cli.
Check playwright-cli --help for available commands.

Demo

> Use playwright skills to test https://demo.playwright.dev/todomvc/.
  Take screenshots for all successful and failing scenarios.

Your agent will be running commands, but it does not mean you can't play with it manually:

playwright-cli open https://demo.playwright.dev/todomvc/ --headed
playwright-cli type "Buy groceries"
playwright-cli press Enter
playwright-cli type "Water flowers"
playwright-cli press Enter
playwright-cli check e21
playwright-cli check e35
playwright-cli screenshot

Headed operation

Playwright CLI is headless by default. If you'd like to see the browser, pass --headed to open:

playwright-cli open https://playwright.dev --headed

Sessions

Playwright CLI keeps the browser profile in memory by default. Your cookies and storage state are preserved between CLI calls within the session, but lost when the browser closes. Use --persistent to save the profile to disk for persistence across browser restarts.

You can use different instances of the browser for different projects with sessions. Pass -s= to the invocation to talk to a specific browser.

playwright-cli open https://playwright.dev
playwright-cli -s=example open https://example.com --persistent
playwright-cli list

You can run your coding agent with the PLAYWRIGHT_CLI_SESSION environment variable:

PLAYWRIGHT_CLI_SESSION=todo-app claude .

Or instruct it to prepend -s= to the calls.

A headless session shuts down on its own after an hour without commands; run open again to start a new one. Headed browsers stay open. Use open --idle-timeout=<ms> to change the timeout, or 0 to disable it.

Manage your sessions as follows:

playwright-cli list                     # list all sessions
playwright-cli close-all                # close all browsers
playwright-cli kill-all                 # forcefully kill all browser processes

Monitoring

Use playwright-cli show to open a visual dashboard that lets you see and control all running browser sessions. This is useful when your coding agents are running browser automation in the background and you want to observe their progress or step in to help.

playwright-cli show

The dashboard opens a window with two views:

• Session grid — shows all active sessions grouped by workspace, each with a live screencast preview, session name, current URL, and page title. Click any session to zoom in.
• Session detail — shows a live view of the selected session with a tab bar, navigation controls (back, forward, reload, address bar), and full remote control. Click into the viewport to take over mouse and keyboard input; press Escape to release.

From the grid you can also close running sessions or delete data for inactive ones.

Commands

Core

playwright-cli open [url]               # open browser, optionally navigate to url
playwright-cli goto <url>               # navigate to a url
playwright-cli close                    # close the page
playwright-cli type <text>              # type text into editable element
playwright-cli click <ref> [button]     # perform click on a web page
playwright-cli dblclick <ref> [button]  # perform double click on a web page
playwright-cli fill <ref> <text>        # fill text into editable element
playwright-cli fill <ref> <text> --submit # fill and press Enter
playwright-cli drag <startRef> <endRef> # perform drag and drop between two elements
playwright-cli drop <ref> --path=<file> # drop files onto an element (from outside the page)
playwright-cli drop <ref> --data="k=v"  # drop data onto an element
playwright-cli hover <ref>              # hover over element on page
playwright-cli select <ref> <val>       # select an option in a dropdown
playwright-cli upload <file>            # upload one or multiple files
playwright-cli check <ref>              # check a checkbox or radio button
playwright-cli uncheck <ref>            # uncheck a checkbox or radio button
playwright-cli snapshot                 # capture page snapshot to obtain element ref
playwright-cli snapshot --filename=f    # save snapshot to specific file
playwright-cli snapshot <ref>           # snapshot a specific element
playwright-cli snapshot --depth=N       # limit snapshot depth for efficiency
playwright-cli find <text>              # search the snapshot for text, returns matching nodes
playwright-cli find --regex <pattern>   # search the snapshot with a regexp
playwright-cli find <text> --filename=f # save matches to a file
playwright-cli eval <func> [ref]        # evaluate javascript expression on page or element
playwright-cli dialog-accept [prompt]   # accept a dialog
playwright-cli dialog-dismiss           # dismiss a dialog
playwright-cli resize <w> <h>           # resize the browser window

Navigation

playwright-cli go-back                  # go back to the previous page
playwright-cli go-forward               # go forward to the next page
playwright-cli reload                   # reload the current page

Keyboard

playwright-cli press <key>              # press a key on the keyboard, `a`, `arrowleft`
playwright-cli keydown <key>            # press a key down on the keyboard
playwright-cli keyup <key>              # press a key up on the keyboard

Mouse

playwright-cli mousemove <x> <y>        # move mouse to a given position
playwright-cli mousedown [button]       # press mouse down
playwright-cli mouseup [button]         # press mouse up
playwright-cli mousewheel <dx> <dy>     # scroll mouse wheel

Save as

playwright-cli screenshot [ref]         # screenshot of the current page or element
playwright-cli screenshot --filename=f  # save screenshot with specific filename
playwright-cli screenshot --hires       # capture at full device pixel ratio
playwright-cli pdf                      # save page as pdf
playwright-cli pdf --filename=page.pdf  # save pdf with specific filename

Tabs

playwright-cli tab-list