docs/src/getting-started-cli.md
Playwright comes with playwright-cli, a command-line interface for browser automation designed for coding agents. It provides token-efficient browser control through concise CLI commands and installable skills, making it ideal for agents that need to balance browser automation with large codebases and reasoning within limited context windows.
playwright-cli vs Playwright MCPplaywright-cli is best for coding agents (Claude Code, GitHub Copilot, etc.) that favor token-efficient, skill-based workflows. CLI commands avoid loading large tool schemas and verbose accessibility trees into the model context.Before you begin, make sure you have the following installed:
Install playwright-cli globally:
npm install -g @playwright/cli@latest
playwright-cli --help
Alternatively, install @playwright/cli as a local dependency and use npx:
npx playwright-cli --help
Coding agents like Claude Code and GitHub Copilot can use locally installed skills for richer context about available commands:
playwright-cli install --skills
You can also point your agent at the CLI directly and let it discover commands on its own:
Test the "add todo" flow on https://demo.playwright.dev/todomvc using playwright-cli.
Check playwright-cli --help for available commands.
Try asking your coding agent:
Use playwright skills to test https://demo.playwright.dev/todomvc/.
Take screenshots for all successful and failing scenarios.
You can also run commands manually to see how the CLI works:
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 screenshot
After each command, the CLI outputs a snapshot of the current page state:
### Page
- Page URL: https://demo.playwright.dev/todomvc/#/
- Page Title: React • TodoMVC
### Snapshot
[Snapshot](.playwright-cli/page-2026-02-14T19-22-42-679Z.yml)
playwright-cli open [url] # open browser, optionally navigate to url
playwright-cli goto <url> # navigate to a url
playwright-cli click <ref> [button] # click an element
playwright-cli type <text> # type text into editable element
playwright-cli fill <ref> <text> # fill text into editable element
playwright-cli select <ref> <value> # select an option in a dropdown
playwright-cli check <ref> # check a checkbox or radio button
playwright-cli uncheck <ref> # uncheck a checkbox
playwright-cli hover <ref> # hover over element
playwright-cli drag <startRef> <endRef> # drag and drop between elements
playwright-cli upload <file> # upload files
playwright-cli close # close the page
Use element refs from snapshots to target elements:
playwright-cli snapshot # get snapshot with element refs
playwright-cli click e15 # click using a ref
You can also use CSS or role selectors:
playwright-cli click "#main > button.submit"
playwright-cli click "role=button[name=Submit]"
playwright-cli click "#footer >> role=button[name=Submit]"
playwright-cli snapshot # capture page snapshot
playwright-cli snapshot --filename=f # save snapshot to specific file
playwright-cli screenshot # screenshot of the current page
playwright-cli screenshot [ref] # screenshot of a specific element
playwright-cli screenshot --filename=f # save with specific filename
playwright-cli pdf # save page as PDF
playwright-cli go-back # go back
playwright-cli go-forward # go forward
playwright-cli reload # reload the page
playwright-cli press <key> # press a key (e.g. Enter, ArrowLeft)
playwright-cli keydown <key> # key down
playwright-cli keyup <key> # key up
playwright-cli mousemove <x> <y> # move mouse
playwright-cli mousedown [button] # mouse button down
playwright-cli mouseup [button] # mouse button up
playwright-cli mousewheel <dx> <dy> # scroll
playwright-cli tab-list # list all tabs
playwright-cli tab-new [url] # create a new tab
playwright-cli tab-select <index> # select a tab
playwright-cli tab-close [index] # close a tab
playwright-cli network # list network requests since page load
playwright-cli route <pattern> [opts] # mock network requests
playwright-cli route-list # list active routes
playwright-cli unroute [pattern] # remove routes
playwright-cli state-save [filename] # save storage state (cookies, localStorage)
playwright-cli state-load <filename> # load storage state
# Cookies
playwright-cli cookie-list [--domain] # list cookies
playwright-cli cookie-get <name> # get a cookie
playwright-cli cookie-set <name> <val> # set a cookie
playwright-cli cookie-delete <name> # delete a cookie
playwright-cli cookie-clear # clear all cookies
# localStorage
playwright-cli localstorage-list # list entries
playwright-cli localstorage-get <key> # get value
playwright-cli localstorage-set <k> <v> # set value
playwright-cli localstorage-delete <k> # delete entry
playwright-cli localstorage-clear # clear all
playwright-cli console [min-level] # list console messages
playwright-cli eval <func> [ref] # evaluate JavaScript on page
playwright-cli run-code <code> # run Playwright code snippet
playwright-cli tracing-start # start trace recording
playwright-cli tracing-stop # stop trace recording
playwright-cli video-start # start video recording
playwright-cli video-chapter <title> # add chapter marker to video
playwright-cli video-stop --filename=f # stop video recording
The CLI keeps the browser profile in memory by default — cookies and storage state are preserved between calls within a session but lost when the browser closes. Use --persistent to save the profile to disk.
Run multiple browser instances for different projects:
playwright-cli open https://playwright.dev
playwright-cli -s=example open https://example.com --persistent
playwright-cli list # list all sessions
You can configure your coding agent to use a specific session:
PLAYWRIGHT_CLI_SESSION=todo-app claude .
playwright-cli list # list all sessions
playwright-cli close-all # close all browsers
playwright-cli kill-all # forcefully kill all browser processes
playwright-cli -s=name delete-data # delete user data for a named session
Use playwright-cli show to open a visual dashboard for observing and controlling all running browser sessions:
playwright-cli show
The dashboard provides:
The CLI runs headless by default. To see the browser:
playwright-cli open https://playwright.dev --headed
playwright-cli open --browser=chrome # use specific browser
playwright-cli open --browser=firefox
playwright-cli open --browser=webkit
playwright-cli open --browser=msedge
For advanced settings, use a JSON config file:
playwright-cli --config path/to/config.json open example.com
The CLI also loads .playwright/cli.config.json automatically if present. The config file supports browser options, context options, network rules, timeouts, and more. Run playwright-cli --help for the full list of options.
Connect to your existing browser tabs instead of launching a new browser:
playwright-cli open --extension
This requires the Playwright MCP Bridge browser extension to be installed.
| Action | Command |
|---|---|
| Install CLI | npm install -g @playwright/cli@latest |
| Install skills | playwright-cli install --skills |
| Open a page | playwright-cli open https://example.com |
| Click an element | playwright-cli click e15 |
| Type text | playwright-cli type "hello world" |
| Take a screenshot | playwright-cli screenshot |
| Get page snapshot | playwright-cli snapshot |
| Run headed | playwright-cli open https://example.com --headed |
| Use Firefox | playwright-cli open --browser=firefox |
| Monitor sessions | playwright-cli show |