Terminal-native browser control

What is playwright-cli?

playwright-cli is how AI coding agents interact with a live browser. Click, navigate, capture locators, and document what you find for real test implementation.
All from the terminal.

Try Hands-On Sandbox Command reference

~/project$playwright-cli open https://playwright-cli.com/hands-on --headed

Page URL: https://playwright-cli.com/hands-on · Hands-On Sandbox

~/project$playwright-cli snapshot

- button "Sign in" [ref=e6]

- button "Add to cart" [ref=e18]

~/project$playwright-cli click e6

✓getByRole('button', { name: 'Sign in' })

Playwright vs playwright-cli vs MCP

Three related tools, three different jobs. Keep them distinct so your agent uses the right one.

Tool	Purpose	Best fit
npx playwright ...	Project lifecycle: install, test, reports, traces	Building and running tests
playwright-cli ...	Live browser control from the terminal	Demos, AI agents, locator discovery, debugging
Playwright MCP	Browser control through MCP tools	Same as playwright-cli, but older approach (not recommended)

npx playwright ...

Purpose: Project lifecycle: install, test, reports, traces

Best fit: Building and running tests

playwright-cli ...

Purpose: Live browser control from the terminal

Best fit: Demos, AI agents, locator discovery, debugging

Playwright MCP

Purpose: Browser control through MCP tools

Best fit: Same as playwright-cli, but older approach (not recommended)

playwright-cli and Playwright MCP complement Playwright. They do not replace it.

How It Works

open → snapshot → act → snapshot → inspect → document

Open

Start a browser session. Headless by default; add --headed if you want to watch.

$playwright-cli open https://playwright-cli.com/hands-on --headed

Snapshot

Capture the accessibility tree. Every element gets a stable ref like e12. The agent reads this as plain text.

$playwright-cli snapshot

- button "Sign in" [ref=e6]

- button "Add to cart" [ref=e18]

Act

Click, fill, and navigate using refs from the latest snapshot. Each command can output the equivalent Playwright locator.

$playwright-cli fill e8 "demo@shiori-market.jp"

$playwright-cli click e6

✓ getByRole('button', { name: 'Sign in' })

Verify

Snapshot again after each meaningful action so the agent sees the new page state instead of guessing.

$playwright-cli snapshot

- heading "Cart" [ref=e22]

Inspect

Check cookies, storage, and network requests when the flow depends on session state or APIs.

$playwright-cli requests

$playwright-cli cookie-list

$playwright-cli generate-locator e18 --raw

Document

Capture stable locators and flow notes in a handoff file (for example locators.md) so another engineer or agent can write reliable tests.

# locators.md — login, cart, network, automation notes

Core Capabilities

Agent-Native Browser Control

Point your AI coding agent at any URL, and it converts the page into structured, machine-readable data. Every button, input, and link gets a stable ref so your agent can click, fill, navigate, and extract data while you supervise.

$ playwright-cli open https://playwright-cli.com/hands-on

$ playwright-cli snapshot

- textbox "Email" [ref=e8]

- button "Sign In" [ref=e12]

$ playwright-cli fill e8 "demo@shiori-market.jp"

✓ Filled email field

Inspect Browser State, Not Just the UI

Real automation needs more than visible elements. Check network requests, cookies, and storage when login or cart flows depend on session state. Convert snapshot refs into Playwright locators for your handoff notes.

$ playwright-cli requests

$ playwright-cli cookie-list

$ playwright-cli generate-locator e18 --raw

✓ getByRole('button', { name: 'Add to cart' })

Language & Framework Agnostic

Your agent explores the live app through playwright-cli, captures locators and page behavior, then writes tests in your preferred language and framework. Playwright, Selenium, Cypress, or anything else—your stack stays the same.

# Agent explores with playwright-cli…

$ playwright-cli snapshot

- button "Add to cart" [ref=e21]

# …then writes tests in your stack

// Playwright (TypeScript)

await page.getByRole('button', { name: 'Add to cart' }).click();

# Cypress

cy.contains('button', 'Add to cart').click()

Up and Running in 3 Steps

No config files, no server to run, no MCP setup. Install globally, add skills, and tell your agent where to find them.

1
Install the CLI
Install playwright-cli globally. One command, works with Node.js 18+.
2
Install Skills
Skills are markdown files your coding agent reads at the start of every task. They describe every playwright-cli command so your agent knows how to use it without you explaining each time.
3
Update your AGENTS.md
Keep these three names distinct in AGENTS.md:
- Playwright— the test framework you write tests in
- Playwright MCP— MCP-based browser tools for agent loops
- playwright-cli— terminal control for live browser work with coding agents