Playwright CLI

https://github.com/microsoft/playwright-cli
Admin
Playwright CLI provides a token-efficient command-line interface for Playwright, specifically...
Tokens:53,341
Snippets:547
Trust Score:10
License:Apache-2.0
Update:2 weeks ago
Show doc for...
Tokens:
Raw
### Install Playwright CLI and show help

Source: https://github.com/microsoft/playwright-cli/blob/main/README.md

Install the Playwright CLI globally and verify the installation by displaying its help output.

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

--------------------------------

### Permissions examples

Source: https://github.com/microsoft/playwright-cli/blob/main/skills/playwright-cli/references/running-code.md

Two examples for permissions: granting multiple permissions and granting permissions for a specific origin. Uses `page.context().grantPermissions()`.

```bash
# Grant multiple permissions
playwright-cli run-code "async page => {
  await page.context().grantPermissions([
    'geolocation',
    'notifications',
    'camera',
    'microphone'
  ]);
}"
```

```bash
# Grant permissions for specific origin
playwright-cli run-code "async page => {
  await page.context().grantPermissions(['clipboard-read'], {
    origin: 'https://example.com'
  });
}"
```

--------------------------------

### Geolocation examples

Source: https://github.com/microsoft/playwright-cli/blob/main/skills/playwright-cli/references/running-code.md

Three examples for geolocation: granting permission and setting location to San Francisco, setting location to London, and clearing permissions. Each uses `page.context()` methods.

```bash
# Grant geolocation permission and set location
playwright-cli run-code "async page => {
  await page.context().grantPermissions(['geolocation']);
  await page.context().setGeolocation({ latitude: 37.7749, longitude: -122.4194 });
}"
```

```bash
# Set location to London
playwright-cli run-code "async page => {
  await page.context().grantPermissions(['geolocation']);
  await page.context().setGeolocation({ latitude: 51.5074, longitude: -0.1278 });
}"
```

```bash
# Clear geolocation override
playwright-cli run-code "async page => {
  await page.context().clearPermissions();
}"
```

--------------------------------

### Install playwright-cli globally

Source: https://github.com/microsoft/playwright-cli/blob/main/README.md

Install playwright-cli as a global command when the local version is not available.

```bash
npm install -g @playwright/cli@latest
```

--------------------------------

### playwright-cli video-start

Source: https://github.com/microsoft/playwright-cli/blob/main/README.md

Starts video recording.

```APIDOC
## [CLI] playwright-cli video-start

### Description
Starts video recording.

### Method
CLI command

### Endpoint
playwright-cli video-start [filename]

### Parameters
#### Positional Arguments
- **filename** (string) - Optional - The name of the video file to record to.

#### Options
- **--cursor** (boolean) - Optional - Record with an animated cursor.
- **--fps** (integer) - Optional - The frame rate for the video recording.

### Response
No response body. The command completes successfully or prints an error.
```

--------------------------------

### Bootstrap Playwright

Source: https://github.com/microsoft/playwright-cli/blob/main/skills/playwright-cli/references/test-generation.md

Initializes a new Playwright project with default settings when no existing install is found.

```bash
npm init playwright@latest
```

--------------------------------

### Install Playwright CLI skills

Source: https://github.com/microsoft/playwright-cli/blob/main/README.md

Install the local skills that coding agents like Claude Code and GitHub Copilot will use.

```bash
playwright-cli install --skills
```

--------------------------------

### Start Tracing Before the Problem

Source: https://github.com/microsoft/playwright-cli/blob/main/skills/playwright-cli/references/tracing.md

Best practice to trace the entire flow, not just the failing step, to capture all steps leading to the issue.

```bash
# Trace the entire flow, not just the failing step
playwright-cli tracing-start
playwright-cli open https://example.com
# ... all steps leading to the issue ...
playwright-cli tracing-stop
```

--------------------------------

### playwright-cli tracing-start

Source: https://github.com/microsoft/playwright-cli/blob/main/README.md

Starts trace recording.

```APIDOC
## [CLI] playwright-cli tracing-start

### Description
Starts trace recording.

### Method
CLI command

### Endpoint
playwright-cli tracing-start

### Parameters
None.

### Response
No response body. The command completes successfully or prints an error.
```

--------------------------------

### Skills-less operation prompt

Source: https://github.com/microsoft/playwright-cli/blob/main/README.md

Example prompt for an agent to use the CLI without pre-installed skills, relying on the help output.

```text
Test the "add todo" flow on https://demo.playwright.dev/todomvc using playwright-cli.
Check playwright-cli --help for available commands.
```

--------------------------------

### URL Pattern Examples for Route Matching

Source: https://github.com/microsoft/playwright-cli/blob/main/skills/playwright-cli/references/request-mocking.md

Lists the URL pattern syntax used with route commands. Shows how to match exact paths, wildcards, file extensions, and query parameters.

```text
**/api/users           - Exact path match
**/api/*/details       - Wildcard in path
**/*.{png,jpg,jpeg}    - Match file extensions
**/search?q=*          - Match query parameters
```

--------------------------------

### Build with npm run watch

Source: https://github.com/microsoft/playwright-cli/blob/main/CONTRIBUTING.md

Builds the project in watch mode, recompiling on changes. Run after cloning and installing dependencies.

```bash
npm run watch
```

--------------------------------

### Start background test and attach CLI

Source: https://github.com/microsoft/playwright-cli/blob/main/skills/playwright-cli/references/test-generation.md

Commands to start a Playwright test in the background with the CLI debugger and attach to it. The test must be run in the background to capture custom setup.

```bash
PLAYWRIGHT_HTML_OPEN=never npx playwright test <seed-file> --debug=cli   # background
playwright-cli attach tw-XXXX
# resume
```

--------------------------------

### WebMCP Tools List Output

Source: https://github.com/microsoft/playwright-cli/blob/main/skills/playwright-cli/SKILL.md

Example output from the webmcp-list command showing available page-provided tools and their schemas.

```text
- Page URL: https://example.com/
- 2 webmcp tools available on the page
```

--------------------------------

### playwright-cli video-start

Source: https://github.com/microsoft/playwright-cli/blob/main/skills/playwright-cli/references/video-recording.md

Starts recording a video of the browser session. Optionally enables an animated cursor and sets the frame rate.

```APIDOC
## playwright-cli video-start

### Description
Starts recording a video of the browser session. Optionally enables an animated cursor and sets the frame rate.

### Method
CLI Command

### Endpoint
`playwright-cli video-start <filename> [--cursor] [--fps=<fps>]`

### Parameters
#### Path Parameters
- **filename** (string) - Required - The output video file name (e.g., demo.webm).

#### Options
- **--cursor** (flag) - Optional - Renders an animated mouse cursor that travels to each action point and paces actions by 800ms.
- **--fps** (integer) - Optional - Frames per second for the video (e.g., 60).

### Request Example
```bash
playwright-cli video-start demo.webm --cursor --fps=60
```

### Response
No response body. The command starts recording in the background.

```

--------------------------------

### Launch app with seed and attach

Source: https://github.com/microsoft/playwright-cli/blob/main/skills/playwright-cli/references/test-generation.md

Starts the seed test in debug mode and attaches to the session. Waits for 'Debugging Instructions' and the session name tw-XXXX.

```bash
PLAYWRIGHT_HTML_OPEN=never npx playwright test tests/seed.spec.ts --debug=cli
# wait for "Debugging Instructions" and the session name tw-XXXX
playwright-cli attach tw-XXXX
```

--------------------------------

### Quick start workflow with playwright-cli

Source: https://github.com/microsoft/playwright-cli/blob/main/skills/playwright-cli/SKILL.md

Basic workflow: open a browser, navigate to a page, interact using snapshot refs, take a screenshot, and close. Comments show typical usage.

```bash
# open new browser
playwright-cli open
# navigate to a page
playwright-cli goto https://playwright.dev
# interact with the page using refs from the snapshot
playwright-cli click e15
playwright-cli type "page.click"
playwright-cli press Enter
# take a screenshot (rarely used, as snapshot is more common)
playwright-cli screenshot
# close the browser
playwright-cli close
```

--------------------------------

### Debugging with tracing

Source: https://github.com/microsoft/playwright-cli/blob/main/skills/playwright-cli/SKILL.md

Opens a page, starts tracing, performs actions, stops tracing, and closes.

```bash
playwright-cli open https://example.com
playwright-cli tracing-start
playwright-cli click e4
playwright-cli fill e7 "test"
playwright-cli tracing-stop
playwright-cli close
```

--------------------------------

### Interactive session with annotation

Source: https://github.com/microsoft/playwright-cli/blob/main/skills/playwright-cli/SKILL.md

Opens a page and starts an interactive session with annotation for UI review or design feedback.

```bash
playwright-cli open https://example.com
playwright-cli show --annotate
```

--------------------------------

### Session management with -s= and --persistent

Source: https://github.com/microsoft/playwright-cli/blob/main/README.md

Shows session usage: default in-memory session, a persistent session named 'example', and listing sessions. Use -s= to target a specific browser instance.

```bash
playwright-cli open https://playwright.dev
playwright-cli -s=example open https://example.com --persistent
playwright-cli list
```

--------------------------------

### Storage state file format example

Source: https://github.com/microsoft/playwright-cli/blob/main/skills/playwright-cli/references/storage-state.md

Example JSON structure of a saved storage state file. It contains a cookies array with cookie attributes (name, value, domain, path, expires, httpOnly, secure, sameSite) and an origins array with localStorage entries per origin.

```json
{
  "cookies": [
    {
      "name": "session_id",
      "value": "abc123",
      "domain": "example.com",
      "path": "/",
      "expires": 1893456000,
      "httpOnly": true,
      "secure": true,
      "sameSite": "Lax"
    }
  ],
  "origins": [
    {
      "origin": "https://example.com",
      "localStorage": [
        { "name": "theme", "value": "dark" },
        { "name": "user_id", "value": "12345" }
      ]
    }
  ]
}
```

--------------------------------

### Basic Trace Recording

Source: https://github.com/microsoft/playwright-cli/blob/main/skills/playwright-cli/references/tracing.md

Starts trace recording, performs actions, and stops recording. The trace includes DOM snapshots, screenshots, network activity, and console logs.

```bash
# Start trace recording
playwright-cli tracing-start

# Perform actions
playwright-cli open https://example.com
playwright-cli click e1
playwright-cli fill e2 "test"

# Stop trace recording
playwright-cli tracing-stop
```

--------------------------------

### Open parameters: browser, mobile, profile, attach, config, close, detach, delete-data

Source: https://github.com/microsoft/playwright-cli/blob/main/skills/playwright-cli/SKILL.md

These commands show how to open sessions with specific browsers, emulate mobile devices, use persistent profiles, attach to running browsers via extension or CDP, start with a config file, close the browser, detach from an attached browser, and delete user data.

```bash
# Use specific browser when creating session
playwright-cli open --browser=chrome
playwright-cli open --browser=firefox
playwright-cli open --browser=webkit
playwright-cli open --browser=msedge

# Emulate a generic mobile device (Pixel 10 for Chromium, iPhone 17 for WebKit).
# Prefer this when a mobile layout is acceptable: mobile pages are usually
# lighter, so snapshots are smaller and cheaper.
playwright-cli open --mobile
playwright-cli open --device="iPhone 15"

# Use persistent profile (by default profile is in-memory)
playwright-cli open --persistent
# Use persistent profile with custom directory
playwright-cli open --profile=/path/to/profile

# Connect to browser via Playwright Extension
playwright-cli attach --extension=chrome

# Connect to a running Chrome or Edge by channel name
playwright-cli attach --cdp=chrome
playwright-cli attach --cdp=msedge

# Connect to a running browser via CDP endpoint
playwright-cli attach --cdp=http://localhost:9222

# Start with config file
playwright-cli open --config=my-config.json

# Close the browser
playwright-cli close
# Detach from an attached browser (leaves the external browser running)
playwright-cli -s=msedge detach
# Delete user data for the default session
playwright-cli delete-data
```

--------------------------------

### Agent prompt for testing TodoMVC

Source: https://github.com/microsoft/playwright-cli/blob/main/README.md

Example prompt for an agent to test the TodoMVC demo with Playwright skills, capturing screenshots for all scenarios.

```text
> Use playwright skills to test https://demo.playwright.dev/todomvc/.
  Take screenshots for all successful and failing scenarios.
```

--------------------------------

### playwright-cli session: open, snapshot, fill, click

Source: https://github.com/microsoft/playwright-cli/blob/main/skills/playwright-cli/references/test-generation.md

Shows a typical playwright-cli session: starting a session, taking a snapshot to see elements, filling form fields, and clicking a button. Each action prints the generated Playwright code, which can be copied into test files.

```bash
# Start a session
playwright-cli open https://example.com/login

# Take a snapshot to see elements
playwright-cli snapshot
# Output shows: e1 [textbox "Email"], e2 [textbox "Password"], e3 [button "Sign In"]

# Fill form fields - generates code automatically
playwright-cli fill e1 "user@example.com"
# Ran Playwright code:
# await page.getByRole('textbox', { name: 'Email' }).fill('user@example.com');

playwright-cli fill e2 "password123"
# Ran Playwright code:
# await page.getByRole('textbox', { name: 'Password' }).fill('password123');

playwright-cli click e3
# Ran Playwright code:
# await page.getByRole('button', { name: 'Sign In' }).click();
```

--------------------------------

### Get all frames

Source: https://github.com/microsoft/playwright-cli/blob/main/skills/playwright-cli/references/running-code.md

Runs a script that retrieves all frames and returns their URLs.

```APIDOC
## Get all frames

### Description
Runs a script that retrieves all frames and returns their URLs.

### Command
`playwright-cli run-code "async page => { const frames = page.frames(); return frames.map(f => f.url()); }"`

### Parameters
- **page** (object) - The Playwright Page object.
- **frames** (array) - The list of Frame objects returned by `page.frames()`.

### Returns
- **urls** (array) - An array of frame URLs.

### Example
```bash
playwright-cli run-code "async page => {
  const frames = page.frames();
  return frames.map(f => f.url());
}"
```
```

--------------------------------

### Handle file download with playwright-cli run-code

Source: https://github.com/microsoft/playwright-cli/blob/main/skills/playwright-cli/references/running-code.md

Sets up a download event listener, clicks a link with the name 'Download', waits for the download to start, saves it as './downloaded-file.pdf', and returns the suggested filename. Demonstrates handling file downloads.

```bash
# Handle file download
playwright-cli run-code "async page => {
  const downloadPromise = page.waitForEvent('download');
  await page.getByRole('link', { name: 'Download' }).click();
  const download = await downloadPromise;
  await download.saveAs('./downloaded-file.pdf');
  return download.suggestedFilename();
}"
```

--------------------------------

### Attach via browser extension

Source: https://github.com/microsoft/playwright-cli/blob/main/skills/playwright-cli/references/session-management.md

Connects to a browser instance that has the Playwright extension installed.

```bash
playwright-cli attach --extension
```

--------------------------------

### Get page title, URL, content, and viewport size

Source: https://github.com/microsoft/playwright-cli/blob/main/skills/playwright-cli/references/running-code.md

Retrieves the page title, current URL, page content, and viewport size using playwright-cli run-code.

```bash
# Get page title
playwright-cli run-code "async page => {
  return await page.title();
}"

# Get current URL
playwright-cli run-code "async page => {
  return page.url();
}"

# Get page content
playwright-cli run-code "async page => {
  return await page.content();
}"

# Get viewport size
playwright-cli run-code "async page => {
  return page.viewportSize();
}"
```

--------------------------------

### playwright-cli goto snapshot output

Source: https://github.com/microsoft/playwright-cli/blob/main/README.md

Example output after running `playwright-cli goto`. The command prints the page URL, title, and a snapshot file path. The snapshot is saved to a timestamp-based file in the `.playwright-cli` directory.

```bash
> playwright-cli goto https://example.com
### Page
- Page URL: https://example.com/
- Page Title: Example Domain
### Snapshot
[Snapshot](.playwright-cli/page-2026-02-14T19-22-42-679Z.yml)
```

--------------------------------

### Check Playwright workspace

Source: https://github.com/microsoft/playwright-cli/blob/main/skills/playwright-cli/references/test-generation.md

Commands to verify Playwright is installed in the workspace. If either config file exists or the version command succeeds, the workspace is ready.

```bash
# Either of these confirms a workspace:
test -f playwright.config.ts || test -f playwright.config.js
npx --no-install playwright --version
```

--------------------------------

### Record a browser session with playwright-cli

Source: https://github.com/microsoft/playwright-cli/blob/main/skills/playwright-cli/references/video-recording.md

Records a browser session to a WebM file. Start with `video-start`, add chapter markers with `video-chapter`, perform actions, then stop with `video-stop`. The `--cursor` flag enables an animated mouse cursor that paces actions by 800ms.

```bash
# Open browser first
playwright-cli open

# Start recording, --cursor renders an animated mouse cursor that travels to each action point
# and paces actions by 800ms so that it has time to travel
playwright-cli video-start demo.webm --cursor --fps=60

# Add a chapter marker for section transitions
playwright-cli video-chapter "Getting Started" --description="Opening the homepage" --duration=2000

# Navigate and perform actions
playwright-cli goto https://example.com
playwright-cli snapshot
playwright-cli click e1

# Add another chapter
playwright-cli video-chapter "Filling Form" --description="Entering test data" --duration=2000
playwright-cli fill e2 "test input"

# Stop and save
playwright-cli video-stop
```

--------------------------------

### CLI Route Commands for Request Mocking

Source: https://github.com/microsoft/playwright-cli/blob/main/skills/playwright-cli/references/request-mocking.md

Shows the core CLI route commands for mocking, modifying, and blocking network requests. Includes examples for custom status codes, JSON bodies, custom headers, removing headers, listing active routes, and removing routes.

```bash
# Mock with custom status
playwright-cli route "**/*.jpg" --status=404

# Mock with JSON body
playwright-cli route "**/api/users" --body='[{"id":1,"name":"Alice"}]' --content-type=application/json

# Mock with custom headers
playwright-cli route "**/api/data" --body='{"ok":true}' --header="X-Custom: value"

# Remove headers from requests
playwright-cli route "**/*" --remove-header=cookie,authorization

# List active routes
playwright-cli route-list

# Remove a route or all routes
playwright-cli unroute "**/*.jpg"
playwright-cli unroute
```

--------------------------------

### Building a Playwright test file from generated code

Source: https://github.com/microsoft/playwright-cli/blob/main/skills/playwright-cli/references/test-generation.md

Shows how to collect the generated code from a playwright-cli session into a Playwright test file. Includes the test structure, the generated actions, and an example assertion using toHaveURL.

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

test('login flow', async ({ page }) => {
  // Generated code from playwright-cli session:
  await page.goto('https://example.com/login');
  await page.getByRole('textbox', { name: 'Email' }).fill('user@example.com');
  await page.getByRole('textbox', { name: 'Password' }).fill('password123');
  await page.getByRole('button', { name: 'Sign In' }).click();

  // Add assertions
  await expect(page).toHaveURL(/.*dashboard/);
});
```

--------------------------------

### Generated Playwright test file

Source: https://github.com/microsoft/playwright-cli/blob/main/skills/playwright-cli/references/test-generation.md

Example of a generated test file. It imports from './fixtures' if available, otherwise '@playwright/test'. Each numbered step is prefixed with a comment, and the describe/test names come from the spec.

```typescript
// spec: specs/basic-operations.plan.md
// seed: tests/seed.spec.ts
import { test, expect } from './fixtures';   // or '@playwright/test' if no fixtures file

test.describe('Signing in and out', () => {
  test('should sign in', async ({ page }) => {
    // 1. Navigate to the application
    // (handled by the seed fixture)

    // 2. Type 'John Doe' into the username field
    await page.getByRole('textbox', { name: 'username' }).fill('John Doe');

    // 3. Type password
    await page.getByRole('textbox', { name: 'password' }).fill('TestPassword');

    // 4. Press Enter to submit
    await page.getByRole('textbox', { name: 'password' }).press('Enter');

    await expect(page.getByRole('heading')).toContainText('Welcome, John Doe!');
  });
});
```

--------------------------------

### Record a video with screencast and overlays

Source: https://github.com/microsoft/playwright-cli/blob/main/skills/playwright-cli/references/video-recording.md

A complete Playwright script for recording a video with screencast. It starts recording, shows actions, adds chapter cards, sticky overlays, and highlights locators. Overlays are pointer-events: none, so they don't block interactions. Use with `playwright-cli run-code --filename your-script.js`.

```js
async page => {
  await page.screencast.start({ path: 'video.webm', size: { width: 1280, height: 800 }, fps: 60 });
  // Show the cursor and mark the click point, and pace actions by 800ms.
  await page.screencast.showActions({
    duration: 800,
    style: {
      point: 'width: 20px; height: 20px; border-radius: 50%; background: rgba(255, 0, 0, .7)',
      title: 'display: none',
    },
  });
  await page.goto('https://demo.playwright.dev/todomvc');

  // Show a chapter card — blurs the page and shows a dialog.
  // Blocks until duration expires, then auto-removes.
  // Use this for simple use cases, but always feel free to hand-craft your own beautiful
  // overlay via await page.screencast.showOverlay().
  await page.screencast.showChapter('Adding Todo Items', {
    description: 'We will add several items to the todo list.',
    duration: 2000,
  });

  // Perform action
  await page.getByRole('textbox', { name: 'What needs to be done?' }).pressSequentially('Walk the dog', { delay: 60 });
  await page.getByRole('textbox', { name: 'What needs to be done?' }).press('Enter');
  await page.waitForTimeout(1000);

  // Show next chapter
  await page.screencast.showChapter('Verifying Results', {
    description: 'Checking the item appeared in the list.',
    duration: 2000,
  });

  // Add a sticky annotation that stays while you perform actions.
  // Overlays are pointer-events: none, so they won't block clicks.
  const annotation = await page.screencast.showOverlay(`
    <div style="position: absolute; top: 8px; right: 8px;
      padding: 6px 12px; background: rgba(0,0,0,0.7);
      border-radius: 8px; font-size: 13px; color: white;">
      ✓ Item added successfully
    </div>
  `);

  // Perform more actions while the annotation is visible
  await page.getByRole('textbox', { name: 'What needs to be done?' }).pressSequentially('Buy groceries', { delay: 60 });
  await page.getByRole('textbox', { name: 'What needs to be done?' }).press('Enter');
  await page.waitForTimeout(1500);

  // Remove the annotation when done
  await annotation.dispose();

  // You can also highlight relevant locators and provide contextual annotations.
  const bounds = await page.getByText('Walk the dog').boundingBox();
  await page.screencast.showOverlay(`
    <div style="position: absolute;
      top: ${bounds.y}px;
      left: ${bounds.x}px;
      width: ${bounds.width}px;
      height: ${bounds.height}px;
      border: 1px solid red;">
    </div>
    <div style="position: absolute;
      top: ${bounds.y + bounds.height + 5}px;
      left: ${bounds.x + bounds.width / 2}px;
      transform: translateX(-50%);
      padding: 6px;
      background: #808080;
      border-radius: 10px;
      font-size: 14px;
      color: white;">Check it out, it is right above this text
    </div>
  `, { duration: 2000 });

  await page.screencast.stop();
}
```

--------------------------------

### Use --json for structured output

Source: https://github.com/microsoft/playwright-cli/blob/main/skills/playwright-cli/SKILL.md

Pass --json to wrap every reply as JSON. This example lists sessions with JSON output.

```bash
playwright-cli list --json
```

--------------------------------

### Work with iframe using playwright-cli run-code

Source: https://github.com/microsoft/playwright-cli/blob/main/skills/playwright-cli/references/running-code.md

Locates an iframe with id 'my-iframe', gets its content frame, and clicks a button inside it. Demonstrates how to interact with elements inside iframes.

```bash
# Work with iframe
playwright-cli run-code "async page => {
  const frame = page.locator('iframe#my-iframe').contentFrame();
  await frame.locator('button').click();
}"
```

--------------------------------

### Run Playwright CLI open command

Source: https://github.com/microsoft/playwright-cli/blob/main/CONTRIBUTING.md

Runs the Playwright CLI with the open command on example.com in headed mode. The -- --headed flag passes the headed option to the browser.

```bash
npm run playwright-cli open example.com -- --headed
```

--------------------------------

### playwright-cli cookie-get

Source: https://github.com/microsoft/playwright-cli/blob/main/README.md

Gets a cookie by name.

```APIDOC
## [CLI] playwright-cli cookie-get

### Description
Gets a cookie by name.

### Method
CLI command

### Endpoint
playwright-cli cookie-get <name>

### Parameters
#### Positional Arguments
- **name** (string) - Required - The name of the cookie to retrieve.

### Response
Prints the cookie value.
```

--------------------------------

### playwright-cli sessionstorage-get

Source: https://github.com/microsoft/playwright-cli/blob/main/README.md

Gets a sessionStorage value by key.

```APIDOC
## [CLI] playwright-cli sessionstorage-get

### Description
Gets a sessionStorage value by key.

### Method
CLI command

### Endpoint
playwright-cli sessionstorage-get <k>

### Parameters
#### Positional Arguments
- **k** (string) - Required - The key of the sessionStorage entry to retrieve.

### Response
Prints the sessionStorage value.
```

--------------------------------

### playwright-cli localstorage-get

Source: https://github.com/microsoft/playwright-cli/blob/main/README.md

Gets a localStorage value by key.

```APIDOC
## [CLI] playwright-cli localstorage-get

### Description
Gets a localStorage value by key.

### Method
CLI command

### Endpoint
playwright-cli localstorage-get <key>

### Parameters
#### Positional Arguments
- **key** (string) - Required - The key of the localStorage entry to retrieve.

### Response
Prints the localStorage value.
```

--------------------------------

### Explore before recording with playwright-cli

Source: https://github.com/microsoft/playwright-cli/blob/main/skills/playwright-cli/references/test-generation.md

Shows the workflow of opening a page, taking a snapshot to review the element structure, and then clicking an element by its reference (e5).

```bash
playwright-cli open https://example.com
playwright-cli snapshot
# Review the element structure
playwright-cli click e5
```

--------------------------------

### playwright-cli sessionstorage-get

Source: https://github.com/microsoft/playwright-cli/blob/main/skills/playwright-cli/SKILL.md

Gets a sessionStorage item by key.

```APIDOC
## playwright-cli sessionstorage-get

### Description
Gets a sessionStorage item by key.

### Usage
```bash
playwright-cli sessionstorage-get step
```

### Parameters
- **key** (string) - Required - The key of the sessionStorage item.

```

--------------------------------

### playwright-cli localstorage-get

Source: https://github.com/microsoft/playwright-cli/blob/main/skills/playwright-cli/SKILL.md

Gets a localStorage item by key.

```APIDOC
## playwright-cli localstorage-get

### Description
Gets a localStorage item by key.

### Usage
```bash
playwright-cli localstorage-get theme
```

### Parameters
- **key** (string) - Required - The key of the localStorage item.

```

--------------------------------

### playwright-cli cookie-get

Source: https://github.com/microsoft/playwright-cli/blob/main/skills/playwright-cli/SKILL.md

Gets the value of a specific cookie.

```APIDOC
## playwright-cli cookie-get

### Description
Gets the value of a specific cookie.

### Usage
```bash
playwright-cli cookie-get session_id
```

### Parameters
- **name** (string) - Required - The name of the cookie.

```

--------------------------------

### Browser Session Configuration Options

Source: https://github.com/microsoft/playwright-cli/blob/main/skills/playwright-cli/references/session-management.md

Configure browser sessions using flags like --config, --browser, --headed, and --persistent during the open command.

```bash
# Open with config file
playwright-cli open https://example.com --config=.playwright/my-cli.json

# Open with specific browser
playwright-cli open https://example.com --browser=firefox

# Open in headed mode
playwright-cli open https://example.com --headed

# Open with persistent profile
playwright-cli open https://example.com --persistent
```

--------------------------------

### playwright-cli tracing-start / tracing-stop

Source: https://github.com/microsoft/playwright-cli/blob/main/skills/playwright-cli/SKILL.md

Starts and stops tracing of browser actions for debugging.

```APIDOC
## [CLI] playwright-cli tracing-start

### Description
Starts tracing of browser actions for debugging.

### Method
CLI

### Endpoint
playwright-cli tracing-start

### Example
```bash
playwright-cli tracing-start
```

## [CLI] playwright-cli tracing-stop

### Description
Stops tracing of browser actions.

### Method
CLI

### Endpoint
playwright-cli tracing-stop

### Example
```bash
playwright-cli tracing-stop
```
```

--------------------------------

### Get Single sessionStorage Value

Source: https://github.com/microsoft/playwright-cli/blob/main/skills/playwright-cli/references/storage-state.md

Retrieves the value of the 'form_data' key from sessionStorage.

```bash
playwright-cli sessionstorage-get form_data
```

--------------------------------

### Get Single localStorage Value

Source: https://github.com/microsoft/playwright-cli/blob/main/skills/playwright-cli/references/storage-state.md

Retrieves the value of the 'token' key from localStorage.

```bash
playwright-cli localstorage-get token
```

--------------------------------

### Get a specific cookie with playwright-cli cookie-get

Source: https://github.com/microsoft/playwright-cli/blob/main/skills/playwright-cli/references/storage-state.md

Retrieves a specific cookie by name.

```bash
playwright-cli cookie-get session_id
```

--------------------------------

### A/B testing sessions

Source: https://github.com/microsoft/playwright-cli/blob/main/skills/playwright-cli/references/session-management.md

Compares different user experiences by opening separate sessions for different URL variants and capturing screenshots for each.

```bash
# Test different user experiences
playwright-cli -s=variant-a open "https://app.com?variant=a"
playwright-cli -s=variant-b open "https://app.com?variant=b"

# Compare
playwright-cli -s=variant-a screenshot
playwright-cli -s=variant-b screenshot
```

--------------------------------

### Minimal seed test

Source: https://github.com/microsoft/playwright-cli/blob/main/skills/playwright-cli/references/test-generation.md

A minimal Playwright test that navigates to the app. This is the starting point for all scenarios.

```ts
// tests/seed.spec.ts
import { test } from '@playwright/test';

test('seed', async ({ page }) => {
  await page.goto('https://example.com/');
});
```

--------------------------------

### List All localStorage Items

Source: https://github.com/microsoft/playwright-cli/blob/main/skills/playwright-cli/references/storage-state.md

Lists all items in localStorage.

```bash
playwright-cli localstorage-list
```

--------------------------------

### Multi-tab workflow with playwright-cli

Source: https://github.com/microsoft/playwright-cli/blob/main/skills/playwright-cli/SKILL.md

Opens a page, opens a new tab, lists tabs, selects the first tab, snapshots, and closes.

```bash
playwright-cli open https://example.com
playwright-cli tab-new https://example.com/other
playwright-cli tab-list
playwright-cli tab-select 0
playwright-cli snapshot
playwright-cli close
```

--------------------------------

### Tab commands: tab-list, tab-new, tab-close, tab-select

Source: https://github.com/microsoft/playwright-cli/blob/main/README.md

Tab management commands to list, create, close, and select browser tabs.

```bash
playwright-cli tab-list                 # list all tabs
playwright-cli tab-new [url]            # create a new tab
playwright-cli tab-close [index]        # close a browser tab
playwright-cli tab-select <index>       # select a browser tab
```

--------------------------------

### Get all frames with playwright-cli run-code

Source: https://github.com/microsoft/playwright-cli/blob/main/skills/playwright-cli/references/running-code.md

Retrieves all frames on the page and returns an array of their URLs. Useful for debugging or verifying frame structure.

```bash
# Get all frames
playwright-cli run-code "async page => {
  const frames = page.frames();
  return frames.map(f => f.url());
}"
```

--------------------------------

### Load code from file with --filename

Source: https://github.com/microsoft/playwright-cli/blob/main/skills/playwright-cli/references/running-code.md

Shows how to load the function from a file using the `--filename` flag. The file should contain the same single function expression.

```bash
playwright-cli run-code --filename=./my-script.js
```

--------------------------------

### playwright-cli snapshot options

Source: https://github.com/microsoft/playwright-cli/blob/main/skills/playwright-cli/SKILL.md

Demonstrates various snapshot commands: default timestamped file, custom filename, element targeting, depth limiting, bounding boxes, and searching with find.

```bash
# default - save to a file with timestamp-based name
playwright-cli snapshot

# save to file, use when snapshot is a part of the workflow result
playwright-cli snapshot --filename=after-click.yaml

# snapshot an element instead of the whole page
playwright-cli snapshot "#main"

# limit snapshot depth for efficiency, take a partial snapshot afterwards
playwright-cli snapshot --depth=4
playwright-cli snapshot e34

# include each element's bounding box as [box=x,y,width,height]
playwright-cli snapshot --boxes

# search a large snapshot instead of capturing it all — returns matching nodes
# with 3 lines of context around each match (like grep -C)
playwright-cli find "Add to cart"
playwright-cli find --regex "\\$[0-9]+\\.[0-9]{2}"
```

--------------------------------

### Clone the Playwright monorepo

Source: https://github.com/microsoft/playwright-cli/blob/main/CONTRIBUTING.md

Clones the Playwright monorepo, changes into the repository directory, and installs dependencies. Required before building or running the Playwright CLI.

```bash
git clone https://github.com/microsoft/playwright
cd playwright
npm i
```

--------------------------------

### playwright-cli goto

Source: https://github.com/microsoft/playwright-cli/blob/main/README.md

Navigates to a URL and provides a snapshot of the current browser state.

```APIDOC
## [CLI] playwright-cli goto

### Description
Navigates to a URL and provides a snapshot of the current browser state.

### Method
CLI command

### Endpoint
`playwright-cli goto <url>`

### Parameters
#### Path Parameters
- `<url>` (string) - Required - The URL to navigate to.

### Request Example
```bash
playwright-cli goto https://example.com
```

### Response
#### Success Response
Provides a snapshot of the current browser state.

#### Response Example
```
### Page
- Page URL: https://example.com/
- Page Title: Example Domain
### Snapshot
[Snapshot](.playwright-cli/page-2026-02-14T19-22-42-679Z.yml)
```

```

--------------------------------

### playwright-cli open

Source: https://github.com/microsoft/playwright-cli/blob/main/skills/playwright-cli/SKILL.md

Opens a new browser instance. Optionally navigates to a URL immediately.

```APIDOC
## playwright-cli open

### Description
Opens a new browser instance. Optionally navigates to a URL immediately.

### Usage
```bash
playwright-cli open
playwright-cli open https://example.com/
```

### Parameters
- **url** (string) - Optional - URL to navigate to after opening the browser.

```

--------------------------------

### Target elements with refs

Source: https://github.com/microsoft/playwright-cli/blob/main/README.md

Target elements using refs from the snapshot. First take a snapshot to get refs, then use a ref with `playwright-cli click` to interact with the element.

```bash
# get snapshot with refs
playwright-cli snapshot

# interact using a ref
playwright-cli click e15
```

--------------------------------

### playwright-cli recording-start

Source: https://github.com/microsoft/playwright-cli/blob/main/README.md

Records user actions in the browser.

```APIDOC
## [CLI] playwright-cli recording-start

### Description
Records user actions in the browser.

### Method
CLI command

### Endpoint
playwright-cli recording-start

### Parameters
None.

### Response
No response body. The command completes successfully or prints an error.
```

--------------------------------

### List All sessionStorage Items

Source: https://github.com/microsoft/playwright-cli/blob/main/skills/playwright-cli/references/storage-state.md

Lists all items in sessionStorage.

```bash
playwright-cli sessionstorage-list
```

--------------------------------

### playwright-cli goto

Source: https://github.com/microsoft/playwright-cli/blob/main/README.md

Navigates to a URL.

```APIDOC
## [CLI] playwright-cli goto

### Description
Navigates to a URL.

### Usage
```bash
playwright-cli goto <url>
```

### Parameters
- **url** (string) - Required - URL to navigate to.
```

--------------------------------

### page.screencast.showActions

Source: https://github.com/microsoft/playwright-cli/blob/main/skills/playwright-cli/references/video-recording.md

Programmatically enables visual annotations for actions with customizable cursor, duration, position, and styles.

```APIDOC
## page.screencast.showActions

### Description
Programmatically enables visual annotations for actions with customizable cursor, duration, position, and styles.

### Method
JavaScript API

### Endpoint
`page.screencast.showActions(options)`

### Parameters
#### Request Body
- **cursor** (string) - Optional - 'pointer' (default) animates the cursor from the previous action point, 'none' hides it.
- **duration** (integer) - Optional - How long decorations stay on screen. Actions are paced by this delay, 500ms by default.
- **position** (string) - Optional - Where the action title goes: top-left, top, top-right, bottom-left, bottom, bottom-right.
- **style** (object) - Optional - CSS style declarations for decorations.
  - **point** (string) - Optional - CSS for the click point marker. Hidden when omitted.
  - **highlight** (string) - Optional - CSS for the highlight box around the target element. Hidden when omitted.
  - **title** (string) - Optional - CSS for the action title callout. Use 'display: none' to hide the callout.

### Request Example
```js
await page.screencast.showActions({
  cursor: 'pointer',
  duration: 800,
  position: 'top-right',
  style: {
    point: 'width: 20px; height: 20px; border-radius: 50%; background: rgba(255, 0, 0, .7)',
    highlight: 'outline: 2px solid #333; background: rgba(0, 128, 255, .15)',
    title: 'font-size: 16px',
  },
});
```

### Response
No return value.

```

--------------------------------

### Debugging with DevTools: console and requests

Source: https://github.com/microsoft/playwright-cli/blob/main/skills/playwright-cli/SKILL.md

Opens a page, clicks and fills elements, then captures console logs and network requests before closing.

```bash
playwright-cli open https://example.com
playwright-cli click e4
playwright-cli fill e7 "test"
playwright-cli console
playwright-cli requests
playwright-cli close
```

--------------------------------

### Add multiple cookies with playwright-cli run-code

Source: https://github.com/microsoft/playwright-cli/blob/main/skills/playwright-cli/references/storage-state.md

Advanced example for adding multiple cookies at once using the run-code command. It passes an async function that calls page.context().addCookies() with an array of cookie objects.

```bash
playwright-cli run-code "async page => {
  await page.context().addCookies([
    { name: 'session_id', value: 'sess_abc123', domain: 'example.com', path: '/', httpOnly: true },
    { name: 'preferences', value: JSON.stringify({ theme: 'dark' }), domain: 'example.com', path: '/' }
  ]);
}"
```

--------------------------------

### Test with npm run test-playwright-cli

Source: https://github.com/microsoft/playwright-cli/blob/main/CONTRIBUTING.md

Runs the test suite for the Playwright CLI.

```bash
npm run test-playwright-cli
```

--------------------------------

### playwright-cli show

Source: https://github.com/microsoft/playwright-cli/blob/main/skills/playwright-cli/SKILL.md

Launches the dashboard for UI review/design feedback, allowing user annotation.

```APIDOC
## [CLI] playwright-cli show

### Description
Launches the dashboard for UI review / design feedback. The user annotates the page, and you receive the annotated screenshot, snapshot, and notes.

### Method
CLI

### Endpoint
playwright-cli show [--annotate]

### Parameters
#### Optional Arguments
- **--annotate** (flag) - Optional - Enables annotation mode.

### Example
```bash
playwright-cli show --annotate
```
```

--------------------------------

### Explore app with playwright-cli

Source: https://github.com/microsoft/playwright-cli/blob/main/skills/playwright-cli/references/test-generation.md

Commands to resume the seed, snapshot interactive elements, click elements, evaluate JavaScript, and show annotated view.

```bash
playwright-cli resume                   # resume so that seed test runs fully
playwright-cli snapshot                 # inventory of interactive elements
playwright-cli click e5                 # follow a flow
playwright-cli eval "location.href"     # read URL / state
playwright-cli show --annotate          # ask the user to point at something
```

--------------------------------

### Capturing Evidence for Documentation

Source: https://github.com/microsoft/playwright-cli/blob/main/skills/playwright-cli/references/tracing.md

Records a complete user flow for documentation purposes, including form filling and submission. The trace shows the exact sequence of events.

```bash
# Record a complete user flow for documentation
playwright-cli tracing-start

playwright-cli open https://app.example.com/checkout
playwright-cli fill e1 "4111111111111111"
playwright-cli fill e2 "12/25"
playwright-cli fill e3 "123"
playwright-cli click e4

playwright-cli tracing-stop
# Trace shows exact sequence of events
```

--------------------------------

### Debug a Playwright test with --debug=cli and attach with playwright-cli

Source: https://github.com/microsoft/playwright-cli/blob/main/skills/playwright-cli/references/playwright-tests.md

Run a failing Playwright test with the --debug=cli option to pause it at the start and print debugging instructions. After the instructions with a session name (e.g., tw-abcdef) are printed, use playwright-cli attach to explore the page. Keep the test running in the background while you investigate.

```bash
# Run the test
PLAYWRIGHT_HTML_OPEN=never npx playwright test --debug=cli
# ...
# ... debugging instructions for "tw-abcdef" session ...
# ...

# Attach to the test
playwright-cli attach tw-abcdef
```

--------------------------------

### Emulate media features with playwright-cli run-code

Source: https://github.com/microsoft/playwright-cli/blob/main/skills/playwright-cli/references/running-code.md

Use these commands to emulate different media features in the browser. Each command uses the page.emulateMedia method with a specific option: colorScheme for dark or light, reducedMotion for reduced motion, and media for print. These are useful for testing responsive designs and accessibility features.

```bash
# Emulate dark color scheme
playwright-cli run-code "async page => {
  await page.emulateMedia({ colorScheme: 'dark' });
}"
```

```bash
# Emulate light color scheme
playwright-cli run-code "async page => {
  await page.emulateMedia({ colorScheme: 'light' });
}"
```

```bash
# Emulate reduced motion
playwright-cli run-code "async page => {
  await page.emulateMedia({ reducedMotion: 'reduce' });
}"
```

```bash
# Emulate print media
playwright-cli run-code "async page => {
  await page.emulateMedia({ media: 'print' });
}"
```

--------------------------------

### Manage browser session lifecycle and data

Source: https://github.com/microsoft/playwright-cli/blob/main/skills/playwright-cli/references/session-management.md

Commands for listing, closing, and cleaning up browser sessions and their associated user data.

```bash
# List all browser sessions
playwright-cli list

# Stop a browser session (close the browser)
playwright-cli close                # stop the default browser
playwright-cli -s=mysession close   # stop a named browser

# Stop all browser sessions
playwright-cli close-all

# Forcefully kill all daemon processes (for stale/zombie processes)
playwright-cli kill-all

# Delete browser session user data (profile directory)
playwright-cli delete-data                # delete default browser data
playwright-cli -s=mysession delete-data   # delete named browser data
```

--------------------------------

### Show action decorations with playwright-cli video-show-actions

Source: https://github.com/microsoft/playwright-cli/blob/main/skills/playwright-cli/references/video-recording.md

Shows action decorations: cursor, highlight, point, and title callout. `video-start --cursor` only enables the cursor; the rest are opt-in via `video-show-actions`. Styles are plain CSS declarations. Use `video-hide-actions` to stop annotating.

```bash
# Cursor only, nothing else on screen
playwright-cli video-start demo.webm --cursor

# Action callout, plus a red click point and a dark frame around the target
playwright-cli video-show-actions --duration=800 --position=top-right \
  --point-style="width: 20px; height: 20px; border-radius: 50%; background: rgba(255,0,0,.7)" \
  --highlight-style="outline: 2px solid #333; background: rgba(0,128,255,.15)" \
  --title-style="font-size: 16px"

# Stop annotating actions
playwright-cli video-hide-actions
```

--------------------------------

### Navigation commands: go-back, go-forward, reload

Source: https://github.com/microsoft/playwright-cli/blob/main/README.md

Navigation commands to move backward, forward, or reload the current page.

```bash
playwright-cli go-back                  # go back to the previous page
playwright-cli go-forward               # go forward to the next page
playwright-cli reload                   # reload the current page
```

--------------------------------

### Run generated tests

Source: https://github.com/microsoft/playwright-cli/blob/main/skills/playwright-cli/references/test-generation.md

Command to run the generated test file once. Any failure goes to Section 3.

```bash
PLAYWRIGHT_HTML_OPEN=never npx playwright test tests/<group>/<scenario>.spec.ts
```

--------------------------------

### Save as commands: screenshot and pdf

Source: https://github.com/microsoft/playwright-cli/blob/main/README.md

Commands to capture screenshots (optionally of a specific element, with a custom filename, or at full device pixel ratio) and save the page as a PDF.

```bash
playwright-cli screenshot [ref]         # screenshot of the current page or element
playwright-cli screenshot --filename=f  # save screenshot with specific filename
playwright-cli screenshot --hires       # capture at full device pixel ratio
playwright-cli pdf                      # save page as pdf
playwright-cli pdf --filename=page.pdf  # save pdf with specific filename
```

--------------------------------

### Handle file download

Source: https://github.com/microsoft/playwright-cli/blob/main/skills/playwright-cli/references/running-code.md

Runs a script that handles a file download and saves it.

```APIDOC
## Handle file download

### Description
Runs a script that handles a file download and saves it.

### Command
`playwright-cli run-code "async page => { const downloadPromise = page.waitForEvent('download'); await page.getByRole('link', { name: 'Download' }).click(); const download = await downloadPromise; await download.saveAs('./downloaded-file.pdf'); return download.suggestedFilename(); }"`

### Parameters
- **page** (object) - The Playwright Page object.
- **event** (string) - The event to wait for. Value: `'download'`.
- **role** (string) - The ARIA role of the link. Value: `'link'`.
- **name** (string) - The accessible name of the link. Value: `'Download'`.
- **path** (string) - The file path to save the download to. Value: `'./downloaded-file.pdf'`.

### Returns
- **filename** (string) - The suggested filename of the download.

### Example
```bash
playwright-cli run-code "async page => {
  const downloadPromise = page.waitForEvent('download');
  await page.getByRole('link', { name: 'Download' }).click();
  const download = await downloadPromise;
  await download.saveAs('./downloaded-file.pdf');
  return download.suggestedFilename();
}"
```
```
Tokens:
Raw