The Playwright CLI: Browser Control for Coding Agents
Updated Jul 2026
Why This Chapter Exists
In early 2026 Microsoft shipped a standalone command-line tool — @playwright/cli — built specifically for AI coding agents, and then did something remarkable: they started recommending it over their own MCP server for coding-agent workflows. Microsoft's published benchmark: a typical browser automation task consumes ~114,000 tokens through Playwright MCP versus ~27,000 tokens through the CLI — roughly a 4x reduction, with some teams reporting 10x savings on long sessions.
This validated the central thesis of this entire module: for agents that do more than just browser work, CLI commands taught via a skill file beat protocol-level tool integration on token economics. The vendor with the most popular MCP server in the world reached the same conclusion.
Installation and Skill Setup
npm install -g @playwright/cli@latest
# Initialize the workspace (creates .playwright-cli/ for sessions and artifacts)
playwright-cli install
# For skill-aware agents (Claude Code, Cursor, etc.):
playwright-cli install --skills
The --skills flag generates a SKILL.md file — the same mechanism you learned in Foundations. The agent reads one markdown file to learn every command, instead of loading dozens of tool schemas into context on every conversation.
The Disk-First Architecture
The key design decision — and the reason for the token savings — is where browser state goes:
| Playwright MCP | Playwright CLI | |
|---|---|---|
| Page snapshot | Streamed into LLM context on every action | Saved to disk as YAML; agent gets a file path |
| Screenshots | Returned inline (base64 in tool response) | Saved to .playwright-cli/; read only if needed |
| Who decides what the LLM sees | The protocol (everything, always) | The agent (reads files on demand) |
| Context growth per step | Thousands of tokens | Dozens of tokens |
The agent decides what it needs to read. A 20-step flow where the agent only inspects the page twice costs two snapshot reads — not twenty.
Element References, Not Selectors
Snapshots are compact YAML accessibility summaries with stable references:
- textbox "What needs to be done?" [ref=e8]
- checkbox "Toggle Todo" [ref=e21]
- generic [ref=e22]: Write Playwright tests
The agent interacts by reference — no CSS selector authoring, no XPath debugging:
playwright-cli open https://demo.playwright.dev/todomvc/ --headed
playwright-cli snapshot
playwright-cli fill e8 "Write Playwright tests"
playwright-cli press Enter
playwright-cli check e21
playwright-cli screenshot
Each command returns a minimal response (often just a file path). Contrast this with the selector-first CLI tools of the 2025 generation — the ref model means the snapshot carries the semantics, and the agent reasons over an accessibility-tree summary rather than raw DOM.
Command Surface
| Category | Commands |
|---|---|
| Core | open, close, goto, click, dblclick, fill, type, snapshot, eval |
| Navigation | go-back, go-forward, reload |
| Keyboard | press, keydown, keyup |
| Input | drag, hover, select, upload, check, uncheck |
| Storage/state | state-save, state-load, cookie-*, localstorage-* |
Under the hood this is the same battle-tested Playwright engine: auto-waiting, actionability checks, cross-browser support — you give up nothing on reliability by taking the CLI path.
Named Sessions
Parallel browser contexts come free via named sessions:
playwright-cli -s=admin open https://your-app.com/admin
playwright-cli -s=customer open https://your-app.com/shop
playwright-cli list
Two personas, two isolated sessions, one agent orchestrating both — the classic "admin changes a price, customer sees the new price" scenario without writing a single line of test-framework code.
When CLI, When MCP
Microsoft's own guidance reduces to one question: does the agent have filesystem access?
- Agent has a filesystem (Claude Code, Cursor, CI runners): use the CLI. The disk is the context-overflow valve.
- Agent is sandboxed with no filesystem (hosted chat, some web agents): use MCP. Inline state is the only option.
- High-throughput coding agents balancing browser work with codebases, tests, and reasoning: CLI + skills, explicitly per Microsoft's positioning.
There is one honest trade-off, though: reading state from disk adds round-trips, so CLI sessions can be slower in wall-clock time than MCP streaming even while being far cheaper in tokens. Token efficiency and latency are different axes — an architect should name both.
Interview Talking Point
"We drive browsers through the Playwright CLI rather than Playwright MCP. Microsoft's own benchmark shows about 4x fewer tokens — roughly 27k versus 114k for a typical task — because snapshots and screenshots land on disk as YAML and the agent reads only what it needs, instead of every page state being streamed into context. Same Playwright engine underneath, same auto-waiting and actionability. We keep MCP available for sandboxed environments that lack filesystem access."