PlaywrightXtrasCli 0.0.1-preflight.3
dotnet tool install --global PlaywrightXtrasCli --version 0.0.1-preflight.3
dotnet new tool-manifest
dotnet tool install --local PlaywrightXtrasCli --version 0.0.1-preflight.3
#tool dotnet:?package=PlaywrightXtrasCli&version=0.0.1-preflight.3&prerelease
nuke :add-package PlaywrightXtrasCli --version 0.0.1-preflight.3
playwright-xtras-cli
A .NET-only equivalent of the Playwright Agent CLI — a
session-based, snapshot/ref browser-automation CLI for coding agents, built on Microsoft.Playwright.
Ships/runs as a dotnet global tool (playwright-xtras-cli); no Node project, no npx.
(Microsoft.Playwright still spawns its bundled Node driver internally — same as src/playwright-xtras-mcp.)
Status: Phase 1 complete and verified end-to-end against BankingApp (login → dashboard, headed + headless).
Architecture — daemon + thin client
Every playwright-xtras-cli <cmd> is a short-lived client process, but the browser must persist
across commands. So:
- Client (
Program.cs): parses args, resolves the session, routes the command. Spawns the host on the first session command, then talks to it over a local socket. Subsequent commands just connect — "no per-command browser startup". - Host (hidden
__hostverb,Host/SessionHost.cs): a detached daemon that owns the live browser/page (Host/HostBrowserSession.cs, lifted from the MCP'sBrowserSession). Runs one command per connection, serialized; idle-exits after 30 min; cleans its registry entry on exit. - IPC (
Ipc/): AF_UNIX socket on all platforms (Win 10+/Unix), 4-byte length-prefixed JSON. Socket path lives in OS temp (pwnc-<hash>-<pid>.sock, kept short for the ~108-byte AF_UNIX limit). - Registry (
Sessions/SessionRegistry.cs):./.playwright-xtras-cli/sessions/<name>.json(cwd-scoped).listprunes dead entries;kill-all/delete-datareap hosts + files. - Refs (
Refs/RefResolver.cs):snapshotwrites the AI ARIA tree (AriaSnapshotMode.Ai, with[ref=eN]) to./.playwright-xtras-cli/page-<ts>.ymland returns only the path. Resolve a ref via thearia-ref=eNselector engine; CSS selectors andgetByRole/getByText/getByTestId(...)also work. Refs invalidate on navigation — re-snapshotafterwards. Frame refs (f0e2) best-effort. - Output (
Output/OutputFormatter.cs): result + a- Page: <url>footer (URL is local, no round-trip).--rawstrips the footer.
Source map: Program.cs (client), ArgParser.cs, Ipc/{Protocol,IpcTransport,CliClient}.cs,
Host/{SessionHost,HostBrowserSession}.cs, Sessions/SessionRegistry.cs, Refs/RefResolver.cs,
Snapshots/SnapshotWriter.cs, Output/OutputFormatter.cs, Commands/*.
Build / install / run
dotnet build src/playwright-xtras-cli/playwright-xtras-cli.csproj # compile
dotnet pack src/playwright-xtras-cli/playwright-xtras-cli.csproj -c Release
dotnet tool install --global --add-source artifacts/package/release PlaywrightXtrasCli
playwright-xtras-cli install # one-time browser download
Installs an .exe shim at ~/.dotnet/tools/ (git-bash auto-resolves .exe; ensure that dir is on PATH).
For dev without installing: dotnet artifacts/bin/playwright-xtras-cli/debug/playwright-xtras-cli.dll <cmd>.
Verified smoke test (BankingApp on :5000)
playwright-xtras-cli open http://localhost:5000 --headed
playwright-xtras-cli goto http://localhost:5000/Auth/Login
playwright-xtras-cli snapshot # -> .yml with refs (e45 email, e50 pwd, e54 button)
playwright-xtras-cli fill e45 alice@example.com
playwright-xtras-cli fill e50 'Password1!'
playwright-xtras-cli click e54 # -> Dashboard
playwright-xtras-cli screenshot --full-page
playwright-xtras-cli kill-all # teardown
Commands (Phase 1 — implemented)
- Navigation:
open [url],goto <url>,go-back,go-forward,reload,close - Interaction:
click <ref> [button],dblclick,fill <ref> <text> [--submit],type <text>,select <ref> <value>,check/uncheck,hover,drag <from> <to>,upload [ref] <file> - Capture:
snapshot [ref|css] [--filename] [--depth],screenshot [ref] [--full-page] [--filename],pdf [--filename] - Input:
press,keydown/keyup,mousemove/down/up,mousewheel,resize <w> <h>,dialog-accept [text]/dialog-dismiss(arm the next dialog — call before the action),eval <js> - Sessions:
list,close-all,kill-all,delete-data,config-print,install [browser] - Global flags:
-s/--session,--headed,--browser=(chromium|firefox|webkit|chrome|edge),--persistent,--raw,--filename,--depth,--submit,--full-page,--allow-unrestricted-file-access. Session also viaPLAYWRIGHT_CLI_SESSION.
File access sandbox (default-deny)
Modeled on the official Playwright MCP/CLI, the CLI is safe by default:
file://navigation is blocked (goto/open), so a hostile page can't steer the agent into reading local files through the browser.- File I/O is confined to the working directory —
upload(read) andscreenshot/snapshot/pdf(write) reject paths that resolve outside the cwd, blocking local-file exfiltration and arbitrary file overwrites.
Lift both with --allow-unrestricted-file-access (set at session creation) or by exporting
PLAYWRIGHT_XTRAS_ALLOW_UNRESTRICTED_FILE_ACCESS=1. As in the official tool this is a guardrail,
not a hard security boundary: it resolves .. but does not follow symlinks or affect redirects.
Network origins (optional allow/block lists)
To curb SSRF — an agent being steered into reaching internal services or cloud-metadata endpoints —
restrict which origins the browser may request (mirrors Playwright MCP's --allowed-origins/
--blocked-origins):
# Block internal/metadata endpoints
playwright-xtras-cli --blocked-origins='169.254.169.254;localhost;*.internal' open https://example.com
# Or allowlist only what you trust (everything else is aborted)
playwright-xtras-cli --allowed-origins='https://example.com;*.trusted.com' open https://example.com
Lists are ;-separated globs matched against each request's origin (scheme://host[:port]),
authority, and host; the blocklist is evaluated before the allowlist, and an empty allowlist
means "allow all". Set at session creation (or via PLAYWRIGHT_XTRAS_ALLOWED_ORIGINS /
PLAYWRIGHT_XTRAS_BLOCKED_ORIGINS). Like the official tool, this governs network schemes only
(http/https/ws/wss/ftp) and is a guardrail, not a hard boundary.
Redaction — keep secrets out of the model
The CLI is the single boundary between the browser and the LLM that drives it, so it's the right
place to strip sensitive values before they reach the agent. Drop a config file at
./.playwright-xtras-cli/redact.json and it's on automatically for that working directory (no
file ⇒ no-op, zero overhead):
{
"literals": ["CHK-1234", "alice@example.com"],
"patterns": ["\\b\\d{4}-\\d{4}-\\d{4}-\\d{4}\\b"],
"placeholder": "[REDACTED]",
"maskColor": "#000000"
}
All fields optional. literals are exact strings/numbers; patterns are regexes (card numbers,
IBANs, …). placeholder defaults to [REDACTED], maskColor to #000000. The loader tolerates
// comments and trailing commas. Copy redact.example.json (annotated,
with ready-made patterns for emails / JWTs / cards / SSNs / bearer tokens) as a starting point.
Prefer
patternsoverliteralsfor anything random or that you'd rather not store on disk (tokens, cookies) — a regex matches the shape so the actual secret never appears in the config.
What it covers (everything the agent can see):
- Text — snapshot YAML,
evalresults, the- Page:footer, and error messages are scrubbed (literals + regex → placeholder) before leaving the host. - Screenshots — matching elements are painted over using Playwright's native masking at capture time. No DOM mutation, so the app behaves identically.
Guarantee: redaction is output-only. Values you send to the page (fill, type, select,
eval args, press) pass through untouched — login, transfers, etc. work exactly as before. Only
what the agent sees is masked.
Limitations (by design):
- Screenshot masking is element-granular — a redacted value inside a longer text node masks the whole element's box. It over-redacts, never under.
- Text baked into a
<canvas>or an image can't be located via the DOM, so it can't be masked visually. The text channels are unaffected. - PDF output is binary and not scrubbed.
redact.jsonlives in the (git-ignored).playwright-xtras-cli/scratch dir and holds the secrets in plaintext — it's user-owned config, outside the automatic page→model leak path this targets.
When console/network capture lands (Phase 2), route those text channels through the same
Redactor.
Performance (measured 2026-05-29, Win11, warm session)
| Path | Latency | Note |
|---|---|---|
Client startup (version) |
~165 ms | mostly OS/runtime launch (real ≫ user+sys) |
Warm round-trip (eval) |
~406 ms | startup + Playwright driver hop |
Cold start (open) |
~6.8 s | one-time/session: Node driver init + headless Chromium launch |
Two hard floors: ~135 ms .NET process launch (only Native AOT beats it) and ~240 ms Playwright Node-driver round-trip (inherent to Playwright; unbeatable without a different backend).
Optimizations applied (≈30% faster than first build): InvariantGlobalization,
TieredCompilationQuickJit, URL-only footer (dropped a per-command TitleAsync round-trip),
and a client hot path that uses connect as the liveness check (no per-command Process lookup).
Decisions & gotchas (from initial build thread)
Microsoft.Playwrightpinned to1.59.0(both it and.NUnit, lockstep). The AI ref-snapshot (AriaSnapshotMode.Ai+Depth) was added in 1.59 — 1.58 lacks it; 1.60 only addsBoxes. 1.59 (~Apr 9) clears the 7-day install cooldown. Bumped inDirectory.Packages.props.- Portable tool, no R2R. ReadyToRun needs a RID-specific package, which degrades the launcher
from
.exeto a.cmdshim that git-bash can't resolve. Kept portable on purpose. NU5111suppressed in the csproj — the bundled driver ships.ps1helpers undertools/; warnings-as-errors would fail pack. This also confirmed the Node driver is packed into the nupkg, so the installed global tool finds it (the original packaging risk — resolved).installdelegates toMicrosoft.Playwright.Program.Main(["install"]).- Demo creds: the offline login fixture (
tests/pages/login.html) acceptsalice@example.com/Password1!— fictional data for exercising fill/click/redaction flows, no real backend. run-code(Node-side Playwright code) is unsupported — useevalfor in-page JS.uploadsignature deviates from the agent CLI:upload [ref] <file>(one operand → page file input).- The nupkg has no embedded README (informational warning only).
Next steps / pending
Phase 2 — command coverage
- Tabs:
tab-list,tab-new,tab-select,tab-close(multi-page tracking exists onHostBrowserSession). - Storage:
state-save/state-load,cookie-*,localstorage-*,sessionstorage-*. - Network:
console [level],requests,request <n>,route/route-list/unroute(console/network queues already buffered inHostBrowserSession).
Phase 3
tracing-start/stop,video-start/stop(RecordVideoDir needs context relaunch),run-code.
Performance (if "near-instant" is wanted)
- Native AOT thin-client split — biggest win: client startup ~165 ms → ~10–20 ms. Requires splitting client (AOT, no Playwright ref) from host (JIT, Playwright) into 2 assemblies, the MSVC/C++ build tools installed, and makes the client RID-specific (win-x64).
- Batch mode — run many commands from stdin/a file in one process to amortize startup (scripted flows).
- Hand-rolled IPC framing (drop
System.Text.Jsonfrom the client) to shave ~20–40 ms off round-trip.
Polish / open
- Confine host scratch (socket + profiles) to in-project
.playwright-xtras-cli/to minimize the outside-cwd footprint (cleaner; reduces what a sandbox must permit). .playwright/cli.config.json-style config support; embed a nupkg README; validate on Linux/macOS.- Cross-check frame-ref (
f0e2) resolution;dialog-*only arms the next dialog (document in help).
Full design rationale is in the approved plan (plan file
peppy-forging-curry.md).
| Product | Versions Compatible and additional computed target framework versions. |
|---|---|
| .NET | net10.0 is compatible. net10.0-android was computed. net10.0-browser was computed. net10.0-ios was computed. net10.0-maccatalyst was computed. net10.0-macos was computed. net10.0-tvos was computed. net10.0-windows was computed. |
This package has no dependencies.
| Version | Downloads | Last Updated |
|---|