1---
2name: playwright-cli
3description: Automate browser interactions, test web pages and work with Playwright tests.
4allowed-tools: Bash(playwright-cli:*) Bash(npx:*) Bash(npm:*)
5---
6 
7# Browser Automation with playwright-cli
8 
9## Quick start
10 
11```bash
12# open new browser
13playwright-cli open
14# navigate to a page
15playwright-cli goto https://playwright.dev
16# interact with the page using refs from the snapshot
17playwright-cli click e15
18playwright-cli type "page.click"
19playwright-cli press Enter
20# take a screenshot (rarely used, as snapshot is more common)
21playwright-cli screenshot
22# close the browser
23playwright-cli close
24```
25 
26## Commands
27 
28### Core
29 
30```bash
31playwright-cli open
32# open and navigate right away
33playwright-cli open https://example.com/
34playwright-cli goto https://playwright.dev
35playwright-cli type "search query"
36playwright-cli click e3
37playwright-cli dblclick e7
38# --submit presses Enter after filling the element
39playwright-cli fill e5 "[email protected]"  --submit
40playwright-cli drag e2 e8
41# drop files or data onto an element (from outside the page)
42playwright-cli drop e4 --path=./image.png
43playwright-cli drop e4 --data="text/plain=hello world"
44playwright-cli hover e4
45playwright-cli select e9 "option-value"
46playwright-cli upload ./document.pdf
47playwright-cli check e12
48playwright-cli uncheck e12
49playwright-cli snapshot
50playwright-cli eval "document.title"
51playwright-cli eval "el => el.textContent" e5
52# get element id, class, or any attribute not visible in the snapshot
53playwright-cli eval "el => el.id" e5
54playwright-cli eval "el => el.getAttribute('data-testid')" e5
55playwright-cli dialog-accept
56playwright-cli dialog-accept "confirmation text"
57playwright-cli dialog-dismiss
58playwright-cli resize 1920 1080
59playwright-cli close
60```
61 
62### Navigation
63 
64```bash
65playwright-cli go-back
66playwright-cli go-forward
67playwright-cli reload
68```
69 
70### Keyboard
71 
72```bash
73playwright-cli press Enter
74playwright-cli press ArrowDown
75playwright-cli keydown Shift
76playwright-cli keyup Shift
77```
78 
79### Mouse
80 
81```bash
82playwright-cli mousemove 150 300
83playwright-cli mousedown
84playwright-cli mousedown right
85playwright-cli mouseup
86playwright-cli mouseup right
87playwright-cli mousewheel 0 100
88```
89 
90### Save as
91 
92```bash
93playwright-cli screenshot
94playwright-cli screenshot e5
95playwright-cli screenshot --filename=page.png
96playwright-cli pdf --filename=page.pdf
97```
98 
99### Tabs
100 
101```bash
102playwright-cli tab-list
103playwright-cli tab-new
104playwright-cli tab-new https://example.com/page
105playwright-cli tab-close
106playwright-cli tab-close 2
107playwright-cli tab-select 0
108```
109 
110### Storage
111 
112```bash
113playwright-cli state-save
114playwright-cli state-save auth.json
115playwright-cli state-load auth.json
116 
117# Cookies
118playwright-cli cookie-list
119playwright-cli cookie-list --domain=example.com
120playwright-cli cookie-get session_id
121playwright-cli cookie-set session_id abc123
122playwright-cli cookie-set session_id abc123 --domain=example.com --httpOnly --secure
123playwright-cli cookie-delete session_id
124playwright-cli cookie-clear
125 
126# LocalStorage
127playwright-cli localstorage-list
128playwright-cli localstorage-get theme
129playwright-cli localstorage-set theme dark
130playwright-cli localstorage-delete theme
131playwright-cli localstorage-clear
132 
133# SessionStorage
134playwright-cli sessionstorage-list
135playwright-cli sessionstorage-get step
136playwright-cli sessionstorage-set step 3
137playwright-cli sessionstorage-delete step
138playwright-cli sessionstorage-clear
139```
140 
141### Network
142 
143```bash
144playwright-cli route "**/*.jpg" --status=404
145playwright-cli route "https://api.example.com/**" --body='{"mock": true}'
146playwright-cli route-list
147playwright-cli unroute "**/*.jpg"
148playwright-cli unroute
149```
150 
151### DevTools
152 
153```bash
154playwright-cli console
155playwright-cli console warning
156playwright-cli requests
157playwright-cli request 5
158playwright-cli run-code "async page => await page.context().grantPermissions(['geolocation'])"
159playwright-cli run-code --filename=script.js
160playwright-cli tracing-start
161playwright-cli tracing-stop
162playwright-cli video-start video.webm
163playwright-cli video-chapter "Chapter Title" --description="Details" --duration=2000
164playwright-cli video-stop
165 
166# annotate each subsequent action (click, type, ...) with a callout naming the action and highlighting the target
167playwright-cli video-show-actions --duration=600 --position=top-right
168playwright-cli video-hide-actions
169 
170# launch the dashboard for UI review / design feedback — user annotates the page, you receive the annotated screenshot, snapshot, and notes
171playwright-cli show --annotate
172 
173# generate a Playwright locator for an element from its ref or selector
174playwright-cli generate-locator e5 --raw
175 
176# show a persistent highlight overlay for an element, optionally with a custom style
177playwright-cli highlight e5
178playwright-cli highlight e5 --style="outline: 3px dashed red"
179# hide a single element highlight, or all page highlights when no target is given
180playwright-cli highlight e5 --hide
181playwright-cli highlight --hide
182```
183 
184## Raw output
185 
186The global `--raw` option strips page status, generated code, and snapshot sections from the output, returning only the result value. Use it to pipe command output into other tools. Commands that don't produce output return nothing.
187 
188```bash
189playwright-cli --raw eval "JSON.stringify(performance.timing)" | jq '.loadEventEnd - .navigationStart'
190playwright-cli --raw eval "JSON.stringify([...document.querySelectorAll('a')].map(a => a.href))" > links.json
191playwright-cli --raw snapshot > before.yml
192playwright-cli click e5
193playwright-cli --raw snapshot > after.yml
194diff before.yml after.yml
195TOKEN=$(playwright-cli --raw cookie-get session_id)
196playwright-cli --raw localstorage-get theme
197```
198 
199For structured output wrapping every reply as JSON, pass --json
200```bash
201playwright-cli list --json
202```
203 
204## Open parameters
205```bash
206# Use specific browser when creating session
207playwright-cli open --browser=chrome
208playwright-cli open --browser=firefox
209playwright-cli open --browser=webkit
210playwright-cli open --browser=msedge
211 
212# Use persistent profile (by default profile is in-memory)
213playwright-cli open --persistent
214# Use persistent profile with custom directory
215playwright-cli open --profile=/path/to/profile
216 
217# Connect to browser via Playwright Extension
218playwright-cli attach --extension=chrome
219 
220# Connect to a running Chrome or Edge by channel name
221playwright-cli attach --cdp=chrome
222playwright-cli attach --cdp=msedge
223 
224# Connect to a running browser via CDP endpoint
225playwright-cli attach --cdp=http://localhost:9222
226 
227# Start with config file
228playwright-cli open --config=my-config.json
229 
230# Close the browser
231playwright-cli close
232# Detach from an attached browser (leaves the external browser running)
233playwright-cli -s=msedge detach
234# Delete user data for the default session
235playwright-cli delete-data
236```
237 
238## URLs with `&` on Windows
239 
240On Windows, `cmd.exe` and PowerShell treat `&` as a command separator, so URLs with multiple query parameters get truncated before `playwright-cli` runs. Escape `&` with `^&` in `cmd.exe`, or use `--%` in PowerShell:
241 
242```batch
243playwright-cli goto "https://example.com/?a=1^&b=2"
244```
245 
246```powershell
247playwright-cli --% goto "https://example.com/?a=1&b=2"
248```
249 
250## Snapshots
251 
252After each command, playwright-cli provides a snapshot of the current browser state.
253 
254```bash
255> playwright-cli goto https://example.com
256### Page
257- Page URL: https://example.com/
258- Page Title: Example Domain
259### Snapshot
260[Snapshot](.playwright-cli/page-2026-02-14T19-22-42-679Z.yml)
261```
262 
263You can also take a snapshot on demand using `playwright-cli snapshot` command. All the options below can be combined as needed.
264 
265```bash
266# default - save to a file with timestamp-based name
267playwright-cli snapshot
268 
269# save to file, use when snapshot is a part of the workflow result
270playwright-cli snapshot --filename=after-click.yaml
271 
272# snapshot an element instead of the whole page
273playwright-cli snapshot "#main"
274 
275# limit snapshot depth for efficiency, take a partial snapshot afterwards
276playwright-cli snapshot --depth=4
277playwright-cli snapshot e34
278 
279# include each element's bounding box as [box=x,y,width,height]
280playwright-cli snapshot --boxes
281```
282 
283## Targeting elements
284 
285By default, use refs from the snapshot to interact with page elements.
286 
287```bash
288# get snapshot with refs
289playwright-cli snapshot
290 
291# interact using a ref
292playwright-cli click e15
293```
294 
295You can also use css selectors or Playwright locators.
296 
297```bash
298# css selector
299playwright-cli click "#main > button.submit"
300 
301# role locator
302playwright-cli click "getByRole('button', { name: 'Submit' })"
303 
304# test id
305playwright-cli click "getByTestId('submit-button')"
306```
307 
308## Browser Sessions
309 
310```bash
311# create new browser session named "mysession" with persistent profile
312playwright-cli -s=mysession open example.com --persistent
313# same with manually specified profile directory (use when requested explicitly)
314playwright-cli -s=mysession open example.com --profile=/path/to/profile
315playwright-cli -s=mysession click e6
316playwright-cli -s=mysession close  # stop a named browser
317playwright-cli -s=mysession delete-data  # delete user data for persistent session
318 
319playwright-cli list
320# Close all browsers
321playwright-cli close-all
322# Forcefully kill all browser processes
323playwright-cli kill-all
324```
325 
326## Installation
327 
328If global `playwright-cli` command is not available, try a local version via `npx playwright-cli`:
329 
330```bash
331npx --no-install playwright-cli --version
332```
333 
334When local version is available, use `npx playwright-cli` in all commands. Otherwise, install `playwright-cli` as a global command:
335 
336```bash
337npm install -g @playwright/cli@latest
338```
339 
340## Example: Form submission
341 
342```bash
343playwright-cli open https://example.com/form
344playwright-cli snapshot
345 
346playwright-cli fill e1 "[email protected]"
347playwright-cli fill e2 "password123"
348playwright-cli click e3
349playwright-cli snapshot
350playwright-cli close
351```
352 
353## Example: Multi-tab workflow
354 
355```bash
356playwright-cli open https://example.com
357playwright-cli tab-new https://example.com/other
358playwright-cli tab-list
359playwright-cli tab-select 0
360playwright-cli snapshot
361playwright-cli close
362```
363 
364## Example: Debugging with DevTools
365 
366```bash
367playwright-cli open https://example.com
368playwright-cli click e4
369playwright-cli fill e7 "test"
370playwright-cli console
371playwright-cli requests
372playwright-cli close
373```
374 
375```bash
376playwright-cli open https://example.com
377playwright-cli tracing-start
378playwright-cli click e4
379playwright-cli fill e7 "test"
380playwright-cli tracing-stop
381playwright-cli close
382```
383 
384## Example: Interactive session
385 
386Ask the user for UI review or design feedback. The user draws boxes on the live page and types comments; you receive the annotated screenshot, the snapshot of the marked region, and the user's notes. Use this whenever the user asks for "UI review", "design feedback", or to "ask the user what they think / want / mean":
387 
388```bash
389playwright-cli open https://example.com
390playwright-cli show --annotate
391```
392 
393## Specific tasks
394 
395* **Running and Debugging Playwright tests** [references/playwright-tests.md](references/playwright-tests.md)
396* **Request mocking** [references/request-mocking.md](references/request-mocking.md)
397* **Running Playwright code** [references/running-code.md](references/running-code.md)
398* **Browser session management** [references/session-management.md](references/session-management.md)
399* **Spec-driven testing (plan / generate / heal)** [references/spec-driven-testing.md](references/spec-driven-testing.md)
400* **Storage state (cookies, localStorage)** [references/storage-state.md](references/storage-state.md)
401* **Test generation** [references/test-generation.md](references/test-generation.md)
402* **Tracing** [references/tracing.md](references/tracing.md)
403* **Video recording** [references/video-recording.md](references/video-recording.md)
404* **Inspecting element attributes** [references/element-attributes.md](references/element-attributes.md)
405