Playwright CLI: Install, Commands & Skills for Claude Code (2026)

If you have used Playwright MCP with Claude Code, you know the experience: Claude drives a real browser and writes tests from what it sees. The catch is context size. Every MCP tool call returns a page snapshot, and long sessions fill Claude's context window quickly.

The Playwright CLI (playwright-cli) is Microsoft's answer for coding agents. Instead of a long-lived MCP connection, Claude Code runs short shell commands — open, snapshot, click — and reads only the output it needs. The official docs describe it as best for “coding agents (Claude Code, GitHub Copilot, etc.) that favor token-efficient, skill-based workflows.”

What Is the Playwright CLI?

The Playwright CLI is a standalone command-line browser controller published as the npm package @playwright/cli. It is listed as “CLI” in the top navigation of playwright.dev, next to MCP. It is not the same as npx playwright test (the test runner) — it is a set of commands an agent uses to explore and act on a live page.

• Short commands, short output — each command does one thing and returns a compact result.
• Element refs — snapshot labels interactive elements with refs like e21, which later commands can target.
• Skills — a bundled skill file teaches Claude Code which commands exist and how to use them.
• Sessions — the browser stays open between commands, so a multi-step flow keeps its state.

Installing the Playwright CLI

Install it globally so Claude Code can call playwright-cli from any project:

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

Or keep it local to one repository and call it through npx:

npm install -D @playwright/cli@latest
npx playwright cli --help

Playwright CLI GitHub Repo (microsoft/playwright-cli)

The Playwright CLI lives on GitHub at github.com/microsoft/playwright-cli, maintained by the Playwright team at Microsoft under the Apache-2.0 licence. It is published to npm as @playwright/cli and installs a playwright-cli binary.

• Releases: the repo's Releases page lists every version. The package is still on 0.x, so pin a version in package.json and read the release notes before upgrading.
• Issues: search existing issues before filing one, and include your playwright-cli --version, OS and the exact command.
• Skills: the README documents how to install the CLI skill for coding agents like Claude Code (covered in the next section).

Adding the Playwright CLI Skill to Claude Code

Claude Code can run any shell command, but it works much better when it knows the command set up front. The CLI ships a skill for exactly this:

# install the skill into the current project
playwright-cli install --skills

# or install it globally for every project
playwright-cli install --skills -g

Per the docs, this gives coding agents “richer context about available commands.” In practice, Claude stops guessing flags and goes straight to open → snapshot → click.

Playwright CLI Skills: What They Are and How to Install Them

A Playwright CLI skill is a folder of instructions a coding agent reads before it touches the browser. The CLI ships one skill, named playwright-cli: a SKILL.md file with the command reference, plus a references/ folder of task guides. When people search for “Playwright CLI skills”, this bundle is what they mean.

Where the skill is installed

The --skills flag on playwright-cli install takes a target. claude is the default; agents writes to the generic .agents folder used by other coding agents:

# Claude Code (default) → .claude/skills/playwright-cli/
playwright-cli install --skills

# Other agents → .agents/skills/playwright-cli/
playwright-cli install --skills=agents

# Install into your home directory instead of the project
playwright-cli install --skills --global

--global has the short alias -g, and it only works together with --skills. Commit the project-level folder if you want everyone on the team to get the same skill.

What the skill teaches the agent

Besides the core commands, the installed skill includes reference guides for common jobs:

• Running and debugging Playwright tests — run, debug and manage test suites (to do it by hand, see how to debug Playwright tests)
• Test generation — plan, generate and heal tests from a spec or from interactions
• Session management and storage state — multiple browser sessions, cookies and localStorage
• Request mocking — intercept and mock network requests
• Tracing and video recording — capture traces and session videos
• Element attributes — read ids, classes or attributes that the snapshot does not show

Keep the skill in sync with the CLI

The skill describes a specific CLI version. If the copy in .claude/skills/playwright-cli or .agents/skills/playwright-cli no longer matches the installed tool, playwright-cli prints a warning telling you to re-run the install command. Make playwright-cli install --skills part of every CLI upgrade.

Core Playwright CLI Commands

Besides refs, commands also accept CSS and role selectors:

playwright-cli click e15
playwright-cli click "#main > button.submit"
playwright-cli click "role=button[name=Submit]"

Walkthrough: Claude Code Explores a Page and Writes a Test

Here is a realistic session using the Playwright TodoMVC demo. With the skill installed, start Claude Code in your test project and give it a goal rather than steps:

Use playwright-cli to open https://demo.playwright.dev/todomvc/ in headed mode.
Add two todos, complete the first one, and check the "Active" filter shows
only the second. Then write tests/todo.spec.ts using getByRole, getByPlaceholder or getByTestId
locators (no CSS), run it with npx playwright test, and fix it until it passes.

Claude Code will typically run a sequence like this, reading each snapshot before choosing the next action:

playwright-cli open https://demo.playwright.dev/todomvc/ --headed
playwright-cli snapshot
playwright-cli click e8            # the "What needs to be done?" input
playwright-cli type "Buy groceries"
playwright-cli snapshot
playwright-cli check e21           # first todo's checkbox
playwright-cli click "role=link[name=Active]"
playwright-cli snapshot

Then it turns what it learned into a normal Playwright test:

import { test, expect } from '@playwright/test';

test('active filter hides completed todos', async ({ page }) => {
  await page.goto('https://demo.playwright.dev/todomvc/');
  const input = page.getByPlaceholder('What needs to be done?');

  await input.fill('Buy groceries');
  await input.press('Enter');
  await input.fill('Book dentist');
  await input.press('Enter');

  await page.getByTestId('todo-item').first().getByRole('checkbox').check();
  await page.getByRole('link', { name: 'Active' }).click();

  await expect(page.getByTestId('todo-item')).toHaveCount(1);
  await expect(page.getByTestId('todo-item')).toHaveText(['Book dentist']);
});

Sessions and Login State

The browser persists between commands. You can list sessions, name them, and clean up when you are done:

playwright-cli list
playwright-cli -s=example open https://example.com --persistent
PLAYWRIGHT_CLI_SESSION=todo-app claude .
playwright-cli close-all
playwright-cli kill-all

Setting PLAYWRIGHT_CLI_SESSION before launching Claude Code ties that Claude session to a named browser session — handy when you keep a logged-in browser for an app. For the test files themselves, use storageState authentication so tests do not depend on the CLI session.

Playwright CLI vs MCP: Which Should You Use?

The Playwright docs draw the line clearly: the CLI suits coding agents that favour token-efficient, skill-based workflows; MCP suits “specialized agentic loops that benefit from persistent state and iterative reasoning over page structure, such as exploratory automation or long-running autonomous workflows.”

We measured the difference in detail in Playwright MCP Server vs CLI: Token Cost Comparison. Short version: use the CLI as the default inside Claude Code, and reach for MCP when the agent itself is the product.

Prompt Patterns That Produce Stable Locators

• Name the locator strategy: “use getByRole, getByLabel or getByTestId — never CSS or XPath.” See the locators guide.
• Ask for web-first assertions: “assert with expect(...).toHaveText / toBeVisible, no fixed waits.”
• Close the loop: “run the test and fix it until it passes” — Claude Code can run npx playwright test itself.
• Point at your patterns: “follow the page objects in tests/pages/” so new tests match the POM you already have.
• Keep refs out of tests: refs like e21 are for the live session only — remind Claude to translate them into real locators.

Common Errors and Fixes

Frequently Asked Questions

Meet Your Instructor

Asim Noaman

Senior QA Automation Engineer & AI Testing Specialist

With years of hands-on experience building test automation frameworks for production applications, Asim specializes in combining traditional QA methodologies with cutting-edge AI tools. He has helped teams adopt Playwright and AI-driven testing workflows to ship faster with fewer bugs.

Udemy Instructor Published course author

Playwright + AI Expert Specialized in AI-powered QA

Production Experience Enterprise-grade frameworks

Connect on LinkedIn