Why CLI — and how to drive it

Playwright ships two ways to connect to the agent world: an MCP server and a CLI with a skill.

For a while, picking one was easy. In early 2026 the Playwright team made the case for the CLI, and the deciding factor was token usage. The same task could cost roughly 4× more tokens when using the MCP server. That number is outdated because two things changed:

• Agent harnesses now defer MCP tool loading. Claude Code keeps only the tool names in context and pulls in a tool definition when the tool is called. That's how skills worked all along.
• Playwright MCP stopped inlining snapshots. It writes them to disk and returns a link, exactly like the CLI.

These days, playwright-cli commands call the MCP tools under the hood (click runs browser_click). I compared the token consumption by running the same task three times:

$ playwright-cli route "**/*.jpg"
$ playwright-cli tracing-start
$ playwright-cli attach tw-abcdef

$ npx @playwright/mcp \
    --caps=devtools,network,storage
# core tools only unless you opt in

Token usage is a tie (here's the full comparison), so features make the difference. And even with a shared backend, the two don't have feature parity:

• The CLI ships with the full toolbox. Network mocking, cookies and storage state, tracing, video, and attaching to a paused test run work out of the box. MCP starts with the core browsing tools, and everything else is opt-in via --caps.
• The skill ships with how-to guides. Reference docs for test generation, request mocking, tracing, and debugging are loaded on demand. MCP hands your agent tools, but the skill also explains how to use them.
• You can type every command yourself. Whatever your agent does, you can replay it, take over, or debug it in your terminal.

I recommend @playwright/cli if you use coding agents. If you're building your own agentic loop or your agent has no shell, MCP is still the way to go.

That's why we'll focus on the CLI and how you can use it to automate your daily Playwright tasks.

Three pieces make this work:

• The skill teaches your agent the CLI commands. The agent reads commands and conventions from disk, so they don't have to be in your prompt.
• The CLI is the thin layer between agent and browser. Each command does one thing and prints the equivalent page.* call.
• The browser holds session state. It stays alive across commands so the agent doesn't have to track cookies, URLs, or DOM in its own context.

Let's have a look at how these components work together.

Understand the agent flow by doing it

You installed @playwright/cli and the skill in the prep lesson.

Open a terminal in your workshop project and point it at the workshop store:

$ playwright-cli open https://www.playwright-workshop.online/
### Browser `default` opened with pid 15970.
### Ran Playwright code
```js
await page.goto('https://www.playwright-workshop.online/');
```
### Page
- Page URL: https://www.playwright-workshop.online/
- Page Title: PWT Workshop
### Snapshot
- [Snapshot](.playwright-cli/page-2026-09-18T14-46-06-540Z.yml)
### Events
- New console entries: .playwright-cli/console-2026-09-18T14-46-05-785Z.log#L1

The CLI prints a few lines: the browser pid, the equivalent page.goto() call, the page URL and title, and a path to a snapshot file on disk. That's almost no tokens at all.

If you (or your agent) want to understand the page structure, ask the CLI for a snapshot. Call snapshot to print the YAML accessibility snapshot inline instead of saving it to disk:

$ playwright-cli snapshot
### Page
- Page URL: https://www.playwright-workshop.online/
- Page Title: PWT Workshop
### Snapshot
```yaml
- generic [active] [ref=e1]:
  - navigation "Main" [ref=e2]:
    - generic [ref=e3]:
      - generic [ref=e4]:
        - link "Go to home" [ref=e5] [cursor=pointer]:
          - /url: /
          - img "pwt logo" [ref=e7]
        - list [ref=e8]:
        ...
        ...

The YAML lists every interactive element with a stable ref like e3, e15, e21. That's how the CLI addresses elements without dumping the full DOM into your context. Pick a ref from the snapshot and click it:

$ playwright-cli click e34
### Ran Playwright code
```js
await page.getByTestId('hero-product-grid').getByRole('link', { name: 'The Collection Snowboard:' }).click();
```
### Page
- Page URL: https://www.playwright-workshop.online/product/the-collection-snowboard-liquid/
- Page Title: The Collection Snowboard: Liquid | PWT Workshop
### Snapshot
- [Snapshot](.playwright-cli/page-2026-09-18T14-47-43-103Z.yml)

The CLI returns the action it ran as Playwright code, the resulting page context and snapshot.

Every CLI command prints the equivalent page.* call. Drive a flow once and you have the body of a test, line by line. Close the browser when you're done:

$ playwright-cli close
Browser 'default' closed

Hand the keyboard to your agent

Now let the agent drive. Open your coding agent in your workshop project and prompt:

Watch what happens. The agent reads .claude/skills/playwright-cli/SKILL.md first to learn the commands and the ref system. Then it runs the same loop you just did by hand: open, snapshot, fill, click.

Every response carries the same two things you saw in your terminal: the Playwright code that just ran and the state of the resulting page. For the search flow, the agent collected these lines along the way:

await page.goto("https://www.playwright-workshop.online/");
await page
  .getByRole("textbox", { name: "Search for products..." })
  .fill("snowboard");
await page.getByRole("button", { name: "Search" }).click();
await page
  .getByRole("link", { name: "The Collection Snowboard: Oxygen" })
  .click();

That's everything an agent needs to write a Playwright test script. The printed code covers the actions, and the snapshots tell it what to assert on.