playwright-cli: a token-efficient Playwright CLI for coding agents

Why a CLI instead of an MCP server for browser work

The README frames this as a choice about context windows. MCP servers expose tool schemas and accessibility trees that get loaded into the model before any work happens. Playwright CLI avoids that by making each action a short shell invocation. The README's own wording is that CLI invocations "avoid loading large tool schemas and verbose accessibility trees into the model context".

That matters when the agent is also holding a large codebase, tests and reasoning in the same window. A page snapshot is still requested, but only when the agent asks for one with playwright-cli snapshot, and it can be trimmed with --depth=N. The project is explicit that MCP is still the better fit for loops that need persistent state, rich introspection and iterative reasoning over page structure: exploratory automation, self-healing tests, long-running autonomous workflows. So this is not a replacement argument. It is a split by workload.

The target user is narrow and clear. You need Node.js 18 or newer and a coding agent such as Claude Code or GitHub Copilot. If you are writing a conventional Playwright test suite by hand, this CLI is not the tool you are looking for.

Sessions, profiles and the in-memory default

The mechanism is a browser process that persists between CLI calls. Cookies and storage state survive from one command to the next inside a session, which is what makes a sequence like type, press Enter, check, screenshot work at all. The default profile lives in memory, so that state disappears when the browser closes. Passing --persistent writes the profile to disk so it survives restarts.

Sessions let you keep separate browsers for separate projects. The README shows opening the default session on playwright.dev and a named session on example.com with -s=example, then listing both. An agent can be pointed at a session through the PLAYWRIGHT_CLI_SESSION environment variable, so the session name does not have to be repeated in every call.

There is an idle policy worth knowing before you build on it. A headless session shuts itself down after an hour without commands, and you restart it with open. Headed browsers stay open. open --idle-timeout=<ms> changes the timeout, and 0 disables it. That default is a reasonable guard against orphaned processes, but it also means a long pause in an agent run can leave the next command talking to a session that no longer exists.

Installing playwright-cli and running a first flow

Installation is a global npm package. Node.js 18 or newer is required. The README gives these two commands and expects --help to print the command list.

npm install -g @playwright/cli@latest
playwright-cli --help

If you use Claude Code, GitHub Copilot or another agent that reads locally installed skills, install them next. The README states that these agents will use the locally installed skills.

playwright-cli install --skills

A first real flow is the TodoMVC demo. The browser is headless unless you pass --headed to open. Element references such as e21 come from a snapshot, so the sequence below assumes you have run snapshot and read the refs it returned.

playwright-cli open https://demo.playwright.dev/todomvc/ --headed
playwright-cli type "Buy groceries"
playwright-cli press Enter
playwright-cli check e21
playwright-cli screenshot

The README also documents a skills-less path: point the agent at the CLI and let it read the skill from playwright-cli --help on its own. The example instruction in the README is to test the add todo flow on the TodoMVC demo and check playwright-cli --help for available commands. That is the fallback when you do not want to install skills at all.

The show dashboard and watching an agent work

playwright-cli show opens a visual dashboard over all running browser sessions. The README describes two views. The session grid groups active sessions by workspace and shows a live screencast preview, session name, current URL and page title; clicking a session zooms in. The session detail view adds a tab bar, back, forward, reload and an address bar, plus full remote control: clicking into the viewport takes over mouse and keyboard, and Escape releases it. From the grid you can close running sessions or delete data for inactive ones.

This is the part of the design that addresses the obvious objection to headless agent automation, which is that nobody can see what the agent is doing. The dashboard is read-and-control, not just read. That means a human can step into a stuck flow without killing the process.

Session management has its own commands alongside it: list, close-all and kill-all. The distinction between close-all and kill-all matters when a browser process is unresponsive, since the latter is described as forcefully killing all browser processes.

Where playwright-cli is the wrong tool

The strongest limitation is stated by the project itself rather than discovered by users. If your workflow depends on maintaining continuous browser context, this CLI is the wrong layer. The README sends exploratory automation, self-healing tests and long-running autonomous workflows to Playwright MCP, where persistent state and iterative reasoning over page structure outweigh the token cost.

The in-memory default profile is a second constraint. Anything that depends on login state surviving a browser restart needs --persistent, and the README does not document what happens to an in-memory profile on an unclean shutdown. The headless idle timeout is a third: an hour of silence ends the session, and that is a default you may need to override with open --idle-timeout=<ms>.

There is also a version caveat in package.json. The package depends on playwright and playwright-core at 1.64.0-alpha-1789764292000, an alpha build, while the published CLI itself is at 0.1.21. If your environment pins Playwright to a stable release, check how that interacts with the CLI's own dependency before you rely on it in a shared pipeline.

playwright-cli against Playwright MCP

The real alternative is Playwright MCP, and the difference is architectural rather than cosmetic. MCP keeps a server process that holds browser state and exposes tools the model calls directly, which is why it can support introspection and iterative reasoning over page structure. The CLI keeps no schema in the model context and instead asks the agent to compose shell commands, requesting a snapshot only when it needs element references.

That produces a concrete trade. With the CLI, every action is a command the agent must get right, and refs must be re-read from a snapshot when the page changes. With MCP, the browser context is continuous but the cost is paid up front in context. Neither is a strict improvement; they sit at different points on the same curve.

A second, less obvious difference is observability. The CLI's show dashboard gives a human a live view and remote control over running sessions. Whether an MCP setup offers an equivalent is outside what this repository documents, so treat that as something to check on your own rather than assume.

Licence, maintenance and upgrade cost

The package is licensed Apache-2.0 and published as @playwright/cli, authored by Microsoft Corporation. Apache-2.0 permits commercial use and modification and includes a patent grant; it also carries notice and attribution obligations. That is a description of the licence text, not legal advice, and if you redistribute the package or a modified version you should read the terms yourself.

The repository is not archived, and the last push was on 2026-09-18. Releases have moved quickly: v0.1.19 on 2026-09-01, v0.1.20 on 2026-09-14 and v0.1.21 on 2026-09-18. A 0.1.x line publishing several times a month means upgrade cost is real. Commands and flags can change between minor versions, and anything an agent learned from a previous --help output may be stale after an upgrade.

The dependency pin is the part to watch. Because playwright and playwright-core are pinned to an alpha build, upgrading the CLI can pull a different Playwright core with it. If you depend on a specific Playwright behaviour, test after each bump rather than assuming the CLI version is the only thing that moved.

Editorial conclusion

Adopt playwright-cli if you drive browser work from Claude Code, GitHub Copilot, Codex or a similar agent and want each step to cost a short command instead of a loaded tool schema. Skip it for exploratory automation that needs continuous browser context and rich introspection; the README points that work at Playwright MCP instead. Before committing, verify the skills install path with playwright-cli install --skills, confirm your agent picks up the commands from playwright-cli --help, and decide whether you need --persistent, since the default profile lives in memory and is lost when the browser closes.

Frequently asked questions

Official sources

1. License: Apache-2.0
2. microsoft/playwright-cli on GitHub
3. Project website
4. README
5. Releases