Playwright CLI: Every Command, Plus the New playwright-cli for AI Coding Agents

What Is the Playwright CLI?

The Playwright CLI is the command-line interface you use to run, record, debug and report on Playwright tests, invoked with npx playwright. The term now also refers to playwright-cli, a separate Microsoft tool (@playwright/cli) that lets AI coding agents like Claude Code and GitHub Copilot drive a browser through short shell commands.

They solve different problems, so pick by who is at the keyboard.

In Playwright 1.64.0 the test package reaches both tools. Its help output lists a cli subcommand ("run playwright cli commands from terminal") and an mcp subcommand ("run the Playwright MCP server"), and npx playwright cli --help prints the same 100 commands as the standalone package.

Versions used here, from the npm registry: @playwright/test 1.64.0, published 7 October 2026, and @playwright/cli 0.1.22, published 28 September 2026. The Playwright installation docs list Node.js 22.x, 24.x and 26.x as supported.

Playwright CLI Commands: The Complete Cheat Sheet

Every test-runner command starts with npx playwright in a Node.js project. Playwright 1.64.0 has 21 of them, and npx playwright --help prints the list.

The three agent definitions that init-agents writes are described in the Playwright test agents docs and walked through in the guide to Playwright Agents.

Setup and browsers

Each Playwright version needs its own browser builds, so run npx playwright install again after every upgrade. For a first-time setup on Windows, macOS or Linux, see how to install Playwright.

npx playwright test: Flags for Running Tests

npx playwright test runs every test in the configured test directory. It runs headless, uses workers equal to half of your logical CPU cores (the help text gives 50% as the --workers default), and exits with code 1 when a test fails, which fails the CI job.

Playwright 1.64.0 accepts 40 command line options here, and all 40 appear in this section or under debugging and reports. A flag on the command line overrides the same setting in playwright.config.ts: with timeout: 1 in the config a test failed with "Test timeout of 1ms exceeded", and adding --timeout=30000 to the command made it pass.

The examples use one spec, run against Playwright's TodoMVC demo:

// tests/smoke.spec.ts
import { test, expect } from '@playwright/test';

test('todo page loads', async ({ page }) => {
  await page.goto('https://demo.playwright.dev/todomvc/');
  await expect(page).toHaveTitle(/TodoMVC/);
});

A passing run looks like this. The config sets channel: 'chrome', so the test used the Chrome already on the machine:

$ npx playwright test

Running 1 test using 1 worker

  ✓  1 tests/smoke.spec.ts:3:5 › todo page loads (1.7s)

  1 passed (2.5s)

Choosing which tests run

Controlling the run

--shard is how one suite gets split across CI machines. For how to set that up, see the guide to Playwright sharding.

Debugging, Traces and Reports From the Command Line

--ui, --debug and --trace are flags on npx playwright test. Traces and reports also have their own subcommands.

Debugging and traces

npx playwright trace reads a trace without opening a window, and its install-skill command writes a SKILL.md so a coding agent can read traces the same way. For the interactive route, see the walkthrough of Playwright UI Mode.

Reports, snapshots and utilities

Recording Tests With npx playwright codegen

npx playwright codegen opens a browser and writes test code as you click and type. The output is a Playwright Test file unless you change --target, whose default is playwright-test.

open and screenshot accept the same browser, device and viewport flags. For a recording walkthrough, read the guide to the Playwright recorder.

Playwright CLI in Python, Java and .NET

Python, Java and .NET reach the CLI through their own entry points. In Playwright for Python 1.60.0, playwright --help lists 13 commands: open, codegen, install, uninstall, install-deps, cr, ff, wk, screenshot, pdf, show-trace, trace and help. It has no test, show-report or merge-reports, because pytest runs the tests.

The Java and .NET commands are from each binding's docs on playwright.dev. In Python, the pytest-playwright plugin adds --headed and --browser to pytest, and it installs with pip install pytest-playwright playwright -U.

playwright-cli: Playwright's Command Line for AI Coding Agents

playwright-cli (@playwright/cli) is a separate Microsoft package that turns browser automation into short shell commands an AI coding agent can call, such as playwright-cli open, click and screenshot. The playwright-cli docs describe it as "token-efficient browser control through concise CLI commands and installable skills", for agents that have to fit browser work, a large codebase and reasoning into one context window.

Your test suite still runs on npx playwright test. playwright-cli is what an agent uses to explore a page and act on it.

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

# or per project
npm install -D @playwright/cli@latest
npx playwright-cli --help

# only if the machine has no Chrome, or you want another browser
playwright-cli install-browser
playwright-cli install-browser firefox

The docs ask for Node.js 20 or newer. open uses the Chrome channel when you pass no --browser flag: on a Mac with Google Chrome installed, it launched that Chrome with no download.

Skills are local instruction files that tell Claude Code, GitHub Copilot and similar agents which commands exist and when to use them.

# this project
playwright-cli install --skills

# every project (writes to ~/.claude/skills)
playwright-cli install --skills -g

# agents that read ~/.agents/skills
playwright-cli install --skills=agents -g

Then prompt the agent in natural language, for example: Use playwright-cli to open the staging site, add two todo items and take a screenshot of the result. Without skills, the docs suggest telling the agent to read playwright-cli --help first.

If Claude Code also wrote the app, see testing apps built with Claude Code for checking it in a real browser with Kane CLI.

This session ran on @playwright/cli 0.1.22 on macOS on 11 October 2026, against Playwright's TodoMVC demo. The shell had PLAYWRIGHT_CLI_SESSION=blogdemo set, which names the session.

playwright-cli open https://demo.playwright.dev/todomvc/ --browser=chrome
playwright-cli snapshot
playwright-cli fill e8 "Write Playwright tests"
playwright-cli press Enter
playwright-cli snapshot
playwright-cli check e21
playwright-cli screenshot
playwright-cli close

Every command prints what happened and the Playwright code it ran. The open command returned this:

### Browser `blogdemo` opened with pid 72532.
### Ran Playwright code
```js
await page.goto('https://demo.playwright.dev/todomvc/');
```
### Page
- Page URL: https://demo.playwright.dev/todomvc/#/
- Page Title: React • TodoMVC
### Snapshot
- [Snapshot](.playwright-cli/page-2026-10-11T13-31-43-421Z.yml)

snapshot returns the page as an accessibility tree in YAML, with a short ref on every element. After the first todo was added, the input and the new item looked like this (other nodes trimmed):

- textbox "What needs to be done?" [active] [ref=e8]
- list [ref=e18]:
  - listitem [ref=e19]:
    - generic [ref=e20]:
      - checkbox "Toggle Todo" [ref=e21]
      - generic [ref=e22]: Write Playwright tests

The agent passes a ref to the next command, here check e21, and the CLI answers with the locator it resolved:

$ playwright-cli check e21
### Ran Playwright code
await page.getByRole('checkbox', { name: 'Toggle Todo' }).check();

That echoed line is ordinary Playwright code, so an agent can paste it into a spec file. Per the docs, CSS and role selectors also work as targets, for example playwright-cli click "role=button[name=Submit]".

playwright-cli --help in 0.1.22 lists 100 commands. Put a command name after --help, as in playwright-cli --help open, to see that command's options. A target is an element ref from a snapshot, or a CSS or role selector.

open takes --headed, --browser (chrome, firefox, webkit, msedge), --device, --mobile, --persistent, --profile, --config and --idle-timeout. The CLI runs headless unless you add --headed.

Sessions for parallel agents

Each named session is its own browser. Pass -s=name on a command or set PLAYWRIGHT_CLI_SESSION in the agent's environment, then run playwright-cli list to see what is open:

$ playwright-cli list
### Browsers
- blogdemo:
  - status: open
  - browser-type: chrome
  - user-data-dir: <in-memory>
  - headed: false

The profile lives in memory unless you add --persistent. Per the docs, a headless session shuts itself down after an hour without commands, so a session an agent forgot to close does not keep a browser running, while headed and attached browsers stay up. playwright-cli show opens a dashboard with a live view of every session.

npx playwright test --debug=cli pauses the test before its first action and prints an attach command for playwright-cli:

$ npx playwright test --debug=cli

Running 1 test using 1 worker

### The test is currently paused at the start

### Debugging Instructions
- Run "playwright-cli attach tw-64343c" to attach to this test

From a second terminal, or from the coding agent, attach and step through. Each step prints the page state and the call the test makes next (output trimmed):

$ playwright-cli attach tw-64343c
### Session `tw-64343c` created, attached to `tw-64343c`.
Run commands with: playwright-cli -s=tw-64343c <command>
### Paused
- Navigate demo.playwright.dev/todomvc/ at tests/smoke.spec.ts:4

$ playwright-cli -s=tw-64343c step-over
### Page
- Page URL: https://demo.playwright.dev/todomvc/#/
- Page Title: React • TodoMVC
### Paused
- Expect "toHaveTitle" at tests/smoke.spec.ts:5

$ playwright-cli -s=tw-64343c resume

The pause message says to "use any tools to explore and interact", so snapshot, eval and console work on the test's page while it waits, and pause-at tests/smoke.spec.ts:5 runs to a given line. After resume the runner finished the test and reported 1 passed. This ran on Playwright 1.64.0 with @playwright/cli 0.1.22.

npx playwright vs playwright-cli vs Playwright MCP

Use npx playwright to run tests you own, playwright-cli when a coding agent with a shell needs a browser, and Playwright MCP when the agent reaches its tools over MCP. The Playwright docs call playwright-cli best for coding agents such as Claude Code and GitHub Copilot, because CLI commands avoid loading large tool schemas and verbose accessibility trees into the model context. They call MCP best for agentic loops that benefit from persistent state and iterative reasoning over page structure.

The MCP server starts with npx playwright mcp in Playwright 1.64.0, or from the @playwright/mcp package. Neither agent tool reports whether a user flow passed, so the agent ends up judging its own work.

For token cost per call against turns per task, and how each behaves in CI, read Playwright CLI vs MCP vs Kane CLI. The comparison hub is the place to compare Kane CLI with other tools.

Testing a Flow Without Writing Playwright: Kane CLI

Kane CLI is TestMu AI's agent for CLI browser testing. You give it one objective in natural language and it drives Chrome. Its product page lists typed exit codes for the result (0 pass, 1 fail, 2 setup error, 3 timeout) and export of runs to Python Playwright.

npm install -g @testmuai/kane-cli
kane-cli login
kane-cli run --url https://ecommerce-playground.lambdatest.io/ \
  "search for a laptop, add the first result to the cart and verify the cart shows one item"

The Kane CLI cookbook has runs that check network calls, console output, cookies and storage. The command-by-command comparison is in Playwright CLI vs Kane CLI, and other runners are in the roundup of Playwright CLI alternatives. The product page currently lists 10,000 Kane CLI credits, free for a month: Get Kane CLI.

Running npx playwright test on a Cloud

npx playwright test launches browsers on your own machine by default. To run the same suite on TestMu AI, point connectOptions at the cloud's WebSocket endpoint in the config:

// pw-cloud.config.ts
import { defineConfig } from '@playwright/test';

const capabilities = {
  browserName: 'Chrome',
  browserVersion: 'latest',
  'LT:Options': {
    platform: 'Windows 11',
    build: 'playwright-cli blog check',
    name: 'todo page loads',
    user: process.env.LT_USERNAME,
    accessKey: process.env.LT_ACCESS_KEY,
  },
};

export default defineConfig({
  testDir: './tests',
  use: {
    connectOptions: {
      wsEndpoint: `wss://cdp.lambdatest.com/playwright?capabilities=${encodeURIComponent(JSON.stringify(capabilities))}`,
    },
  },
});

The command does not change. With LT_USERNAME and LT_ACCESS_KEY exported, the same spec ran on Chrome on Windows 11 with Playwright 1.64.0 on 11 October 2026:

$ npx playwright test -c pw-cloud.config.ts

Running 1 test using 1 worker

  ✓  1 tests/smoke.spec.ts:3:5 › todo page loads (1.6s)

  1 passed (17.6s)

The runner applies filters, sharding and the worker count before it connects, so --project, --grep, --shard and --workers behave as they do locally. The Playwright testing docs list the browser names and capabilities the cloud accepts, and HyperExecute splits a large suite into parallel tasks when one runner is too slow.

Playwright CLI Errors and How to Fix Them

Most Playwright CLI failures come from browser builds that do not match the installed Playwright version, missing system libraries in CI, or a filter that matches nothing. On Playwright 1.64.0 with no browsers installed, npx playwright test fails like this (output trimmed):

$ npx playwright test
Running 1 test using 1 worker

  1) tests/smoke.spec.ts:3:5 › todo page loads

    Error: browserType.launch: Executable doesn't exist at ~/Library/Caches/ms-playwright/chromium_headless_shell-1248/chrome-headless-shell-mac-arm64/chrome-headless-shell
    Looks like Playwright was just installed or updated.
    Please run the following command to download new browsers:

        npx playwright install

  1 failed