speakeasy-api Browser Automation with Playwright CLI in Gram
Quick start
# open new browser
mise run playwright open
# navigate to a page
mise run playwright goto https://playwright.dev
# interact with the page using refs from the snapshot
mise run playwright click e15
mise run playwright type "page.click"
mise run playwright press Enter
# take a screenshot (rarely used, as snapshot is more common)
mise run playwright screenshot
# close the browser
mise run playwright close
Commands
Core
mise run playwright open
# open and navigate right away
mise run playwright open https://example.com/
mise run playwright goto https://playwright.dev
mise run playwright type "search query"
mise run playwright click e3
mise run playwright dblclick e7
# --submit presses Enter after filling the element
mise run playwright fill e5 "user@example.com" --submit
mise run playwright drag e2 e8
# drop files or data onto an element (from outside the page)
mise run playwright drop e4 --path=./image.png
mise run playwright drop e4 --data="text/plain=hello world"
mise run playwright hover e4
mise run playwright select e9 "option-value"
mise run playwright upload ./document.pdf
mise run playwright check e12
mise run playwright uncheck e12
mise run playwright snapshot
# search the snapshot for text or a regexp, returns matching nodes with surrounding context
mise run playwright find "Sign in"
mise run playwright find --regex "Sign (in|up)"
# wrap the regexp in slashes to add flags, e.g. /i for case-insensitive
mise run playwright find --regex "/sign (in|up)/i"
mise run playwright eval "document.title"
mise run playwright eval "el => el.textContent" e5
# get element id, class, or any attribute not visible in the snapshot
mise run playwright eval "el => el.id" e5
mise run playwright eval "el => el.getAttribute('data-testid')" e5
mise run playwright dialog-accept
mise run playwright dialog-accept "confirmation text"
mise run playwright dialog-dismiss
mise run playwright resize 1920 1080
mise run playwright close
Navigation
mise run playwright go-back
mise run playwright go-forward
mise run playwright reload
Keyboard
mise run playwright press Enter
mise run playwright press ArrowDown
mise run playwright keydown Shift
mise run playwright keyup Shift
Mouse
mise run playwright mousemove 150 300
mise run playwright mousedown
mise run playwright mousedown right
mise run playwright mouseup
mise run playwright mouseup right
mise run playwright mousewheel 0 100
Save as
mise run playwright screenshot
mise run playwright screenshot e5
mise run playwright screenshot --filename=page.png
mise run playwright screenshot --hires
mise run playwright pdf --filename=page.pdf
Tabs
mise run playwright tab-list
mise run playwright tab-new
mise run playwright tab-new https://example.com/page
mise run playwright tab-close
mise run playwright tab-close 2
mise run playwright tab-select 0
Storage
mise run playwright state-save
mise run playwright state-save auth.json
mise run playwright state-load auth.json
# Cookies
mise run playwright cookie-list
mise run playwright cookie-list --domain=example.com
mise run playwright cookie-get session_id
mise run playwright cookie-set session_id abc123
mise run playwright cookie-set session_id abc123 --domain=example.com --httpOnly --secure
mise run playwright cookie-delete session_id
mise run playwright cookie-clear
# LocalStorage
mise run playwright localstorage-list
mise run playwright localstorage-get theme
mise run playwright localstorage-set theme dark
mise run playwright localstorage-delete theme
mise run playwright localstorage-clear
# SessionStorage
mise run playwright sessionstorage-list
mise run playwright sessionstorage-get step
mise run playwright sessionstorage-set step 3
mise run playwright sessionstorage-delete step
mise run playwright sessionstorage-clear
Network
mise run playwright route "**/*.jpg" --status=404
mise run playwright route "https://api.example.com/**" --body='{"mock": true}'
mise run playwright route-list
mise run playwright unroute "**/*.jpg"
mise run playwright unroute
DevTools
mise run playwright console
mise run playwright console warning
mise run playwright requests
mise run playwright request 5
mise run playwright run-code "async page => await page.context().grantPermissions(['geolocation'])"
mise run playwright run-code --filename=script.js
mise run playwright tracing-start
mise run playwright tracing-stop
mise run playwright video-start video.webm
mise run playwright video-chapter "Chapter Title" --description="Details" --duration=2000
mise run playwright video-stop
# annotate each subsequent action (click, type, ...) with a callout naming the action and highlighting the target
# --cursor accepts pointer (the default) or none
mise run playwright video-show-actions --duration=600 --position=top-right --cursor=pointer
mise run playwright video-hide-actions
# launch the dashboard for UI review / design feedback — user annotates the page, you receive the annotated screenshot, snapshot, and notes
mise run playwright show --annotate
# generate a Playwright locator for an element from its ref or selector
mise run playwright generate-locator e5 --raw
# show a persistent highlight overlay for an element, optionally with a custom style
mise run playwright highlight e5
mise run playwright highlight e5 --style="outline: 3px dashed red"
# hide a single element highlight, or all page highlights when no target is given
mise run playwright highlight e5 --hide
mise run playwright highlight --hide
Raw output
The 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.
mise run playwright --raw eval "JSON.stringify(performance.timing)" | jq '.loadEventEnd - .navigationStart'
mise run playwright --raw eval "JSON.stringify([...document.querySelectorAll('a')].map(a => a.href))" > links.json
mise run playwright --raw snapshot > before.yml
mise run playwright click e5
mise run playwright --raw snapshot > after.yml
diff before.yml after.yml
TOKEN=$(mise run playwright --raw cookie-get session_id)
mise run playwright --raw localstorage-get theme
For structured output wrapping every reply as JSON, pass --json
mise run playwright list --json
Open parameters
# Use specific browser when creating session
mise run playwright open --browser=chrome
mise run playwright open --browser=firefox
mise run playwright open --browser=webkit
mise run playwright open --browser=msedge
# Emulate a generic mobile device (Pixel 10 for Chromium, iPhone 17 for WebKit).
# Prefer this when a mobile layout is acceptable: mobile pages are usually
# lighter, so snapshots are smaller and cheaper.
mise run playwright open --mobile
mise run playwright open --device="iPhone 15"
# Use persistent profile (by default profile is in-memory)
mise run playwright open --persistent
# Use persistent profile with custom directory
mise run playwright open --profile=/path/to/profile
# Connect to browser via Playwright Extension
mise run playwright attach --extension=chrome
# Connect to a running Chrome or Edge by channel name
mise run playwright attach --cdp=chrome
mise run playwright attach --cdp=msedge
# Connect to a running browser via CDP endpoint
mise run playwright attach --cdp=http://localhost:9222
# Start with config file
mise run playwright open --config=my-config.json
# Close the browser
mise run playwright close
# Detach from an attached browser (leaves the external browser running)
mise run playwright -s=msedge detach
# Delete user data for the default session
mise run playwright delete-data
URLs with & on Windows
On Windows, cmd.exe and PowerShell treat & as a command separator, so URLs with multiple query parameters get truncated before mise run playwright runs. Escape & with ^& in cmd.exe, or use --% in PowerShell:
mise run playwright goto "https://example.com/?a=1^&b=2"
mise run playwright --% goto "https://example.com/?a=1&b=2"
Snapshots
After each command, mise run playwright provides a snapshot of the current browser state.
> mise run playwright goto https://example.com
### Page
- Page URL: https://example.com/
- Page Title: Example Domain
### Snapshot
[Snapshot](.playwright-cli/page-2026-02-14T19-22-42-679Z.yml)
You can also take a snapshot on demand using mise run playwright snapshot command. All the options below can be combined as needed.
# default - save to a file with timestamp-based name
mise run playwright snapshot
# save to file, use when snapshot is a part of the workflow result
mise run playwright snapshot --filename=after-click.yaml
# snapshot an element instead of the whole page
mise run playwright snapshot "#main"
# limit snapshot depth for efficiency, take a partial snapshot afterwards
mise run playwright snapshot --depth=4
mise run playwright snapshot e34
# include each element's bounding box as [box=x,y,width,height]
mise run playwright snapshot --boxes
# search a large snapshot instead of capturing it all — returns matching nodes
# with 3 lines of context around each match (like grep -C)
mise run playwright find "Add to cart"
mise run playwright find --regex "\\$[0-9]+\\.[0-9]{2}"
Targeting elements
By default, use refs from the snapshot to interact with page elements.
# get snapshot with refs
mise run playwright snapshot
# interact using a ref
mise run playwright click e15
You can also use css selectors or Playwright locators.
# css selector
mise run playwright click "#main > button.submit"
# role locator
mise run playwright click "getByRole('button', { name: 'Submit' })"
# test id
mise run playwright click "getByTestId('submit-button')"
Browser Sessions
# create new browser session named "mysession" with persistent profile
mise run playwright -s=mysession open example.com --persistent
# same with manually specified profile directory (use when requested explicitly)
mise run playwright -s=mysession open example.com --profile=/path/to/profile
mise run playwright -s=mysession click e6
mise run playwright -s=mysession close # stop a named browser
mise run playwright -s=mysession delete-data # delete user data for persistent session
mise run playwright list
# Close all browsers
mise run playwright close-all
# Forcefully kill all browser processes
mise run playwright kill-all
Gram repository setup
Run browser automation through mise run playwright; the task supplies the repository config and installs Chromium on first use. Use existing aube package scripts for repository checks. Gram does not install @playwright/test, so do not bootstrap a Playwright test suite unless the user explicitly asks.
mise run playwright --help
mise run playwright:install-browser --help
Do not use npm, npx, or yarn in this repository.
Example: Form submission
mise run playwright open https://example.com/form
mise run playwright snapshot
mise run playwright fill e1 "user@example.com"
mise run playwright fill e2 "password123"
mise run playwright click e3
mise run playwright snapshot
mise run playwright close
Example: Multi-tab workflow
mise run playwright open https://example.com
mise run playwright tab-new https://example.com/other
mise run playwright tab-list
mise run playwright tab-select 0
mise run playwright snapshot
mise run playwright close
Example: Debugging with DevTools
mise run playwright open https://example.com
mise run playwright click e4
mise run playwright fill e7 "test"
mise run playwright console
mise run playwright requests
mise run playwright close
mise run playwright open https://example.com
mise run playwright tracing-start
mise run playwright click e4
mise run playwright fill e7 "test"
mise run playwright tracing-stop
mise run playwright close
Example: Interactive session
Ask 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":
mise run playwright open https://example.com
mise run playwright show --annotate
Specific tasks
- Request mocking references/request-mocking.md
- Running Playwright code references/running-code.md
- Browser session management references/session-management.md
- Storage state (cookies, localStorage) references/storage-state.md
- Tracing references/tracing.md
- Video recording references/video-recording.md
- Inspecting element attributes references/element-attributes.md