Brainforge Knowledge

playwright-cli-setup

4 min read

Playwright CLI setup (Microsoft)

Purpose: Use the official Playwright CLI (@playwright/cli) for token-efficient browser automation from coding agents (snapshot → click/fill by ref, named sessions, optional persistent profile). It complements Cursor’s Browser MCP, which is better for exploratory one-off flows.

Repository: microsoft/playwright-cli

Who needs this

  • Anyone automating repeatable browser flows (e.g. expert-network portal forms) with an agent.
  • Optional for teams that only need occasional IDE browser automation; skip if you never use CLI.

Requirements

  • Node.js 18+ (Brainforge monorepo uses Node 22 at repo root).

Use the shared tooling in the monorepo so versions stay aligned:

cd tools/playwright-cli
npm install
npm run verify

You should see verify: OK and a short --help excerpt.

Optional: global install

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

Pin the version to match tools/playwright-cli/package.json when upgrading.

Optional: bundled skills

cd tools/playwright-cli
npm run install-skills

Useful if your agent loads skills from the CLI install (see upstream README).

First real browser session

The first time you run commands that launch a browser, Playwright may download browser binaries. That is normal and can take a few minutes on a clean machine.

Example:

cd tools/playwright-cli
npx playwright-cli open https://example.com --headed

Named sessions (in-memory)

From the upstream README:

  • Default session keeps profile in memory until the browser closes.
  • Use -s=name for named sessions; PLAYWRIGHT_CLI_SESSION=name for agents so every command targets the same browser.
  • playwright-cli list, close-all, kill-all for cleanup.

Persistent browser profile (stay logged in)

Use this for expert-network members areas (e.g. GLG Auth0 login) so you log in once and reuse cookies across CLI runs.

Recommended: --profile on disk (gitignored)

  1. Pick a directory that will hold Chromium user data. In this repo, use:

    tools/playwright-cli/.profiles/<short-name>/
    Example: tools/playwright-cli/.profiles/glg/

    That path is gitignored (see tools/playwright-cli/.gitignore). Do not move it into a tracked folder or commit it.

  2. First-time login (headed) — open the invite or members URL, sign in manually in the window:

    cd tools/playwright-cli
npx playwright-cli -s=glg open \
  "https://members.glgresearch.com/survey-accept/view/?cmrid=YOUR_ID&src=invite" \
  --headed \
  --profile ./.profiles/glg

    -s=glg ties all commands to one named session so profiles do not collide with other projects.

  3. Later runs — use the same -s and --profile on open (that reloads the saved user data). Then run snapshot, click, fill, etc. against that session without passing --profile again on those commands:

    npx playwright-cli -s=glg open "https://members.glgresearch.com/" --headed --profile ./.profiles/glg
npx playwright-cli -s=glg snapshot

  4. Headless after login works for automation-only passes:

    npx playwright-cli -s=glg open "https://members.glgresearch.com/..." --profile ./.profiles/glg

    Prefer headed if the site challenges MFA or shows unexpected interstitials.

Alternative: state-save / state-load

After a successful login in any session, you can export storage to a single file (see upstream state-save / state-load commands). Treat that file like a password: store outside the repo or in a gitignored path.

Security

  • A persistent profile directory or storage state file is effectively full account access for those sites. Protect the folder, do not sync it to untrusted backup, and do not commit it.
  • Prefer signed deep links where the portal authenticates via token in the URL when that is enough without a stored profile.

Credentials and secrets

  • Do not commit storage state files or .profiles/ contents.
  • Prefer signed deep links (e.g. expert-network email links) where the portal authenticates via token in the URL.
  • For logins that require interactive SSO, complete login once in a headed session with --profile, then reuse that profile as above.

Cursor / agent usage

  • Prefer Cursor Browser MCP for one-off “fill this form” inside the chat.
  • Prefer Playwright CLI when the same flow will run often or you want smaller context (CLI snapshots vs large MCP trees).
  • Expert-network content and safety rules live in .cursor/skills/expert-network-response/SKILL.md.

Verify from repo root

npm run tools:playwright-cli-verify
  • tools/playwright-cli/README.md — short team quickstart

Graph View