patchright-cli
Anti-detect browser automation CLI. Same command interface as Microsoft's playwright-cli but using Patchright (undetected Playwright fork) to bypass bot detection.
Install · Quick Start · Commands · Snapshots · Agent Integration
Highlights
| Feature | |
|---|---|
| 🛡️ | Bypasses Akamai, Cloudflare, and other anti-bot systems |
| 🚀 | Same command interface as playwright-cli — zero learning curve |
| 🤖 | Built for AI agents (Claude Code, Codex, etc.) with YAML snapshots |
| ⚡ | Daemon architecture — browser stays open between commands |
| 📦 | pip install / uvx — no Docker, no config files |
| 🔒 | Persistent profiles for maintaining login sessions |
Install
For LLM Agents
curl -s https://raw.githubusercontent.com/AhaiMk01/patchright-cli/main/docs/installation.md
# Recommended — always runs latest version, no install needed
uvx patchright-cli open https://example.com
Other install methods
# Via pip
pip install patchright-cli
patchright-cli open https://example.com
patchright-cli close
# Update
pip install --upgrade patchright-cli
From source:
git clone https://github.com/AhaiMk01/patchright-cli.git
cd patchright-cli
uv venv && uv pip install -e .
python -m patchright install chromium
Quick Start
# Launch undetected Chrome and navigate
patchright-cli open https://example.com
# Take a snapshot to see interactive elements with refs
patchright-cli snapshot
# Interact using refs from the snapshot
patchright-cli click e2
patchright-cli fill e5 "search query"
patchright-cli press Enter
# Take a screenshot
patchright-cli screenshot
# Close the browser
patchright-cli close
Architecture
graph LR
A[CLI] -->|TCP:9321| B[Daemon]
B -->|Patchright| C[Chrome]
| Component | Role |
|---|---|
Daemon (daemon.py) |
Long-running process managing browser sessions via Patchright. Auto-starts on first open. |
CLI (cli.py) |
Thin client — connects, sends command, prints result, disconnects. Browser stays open. |
Snapshot (snapshot.py) |
Playwright aria_snapshot() accessibility tree, annotated with sequential [ref=eN] handles for element targeting. |
📖 Commands
Core
patchright-cli open [url] # Launch browser
patchright-cli open --profile=work # Named profile any session can use (logins persist)
patchright-cli open --headless # Run headless
patchright-cli open --profile=./dir # A value with / or \ is a profile directory
patchright-cli --tab <name> open <url> # Named tab: shared browser, own page/refs
patchright-cli open --mobile # Emulate a generic mobile device (Pixel 7)
patchright-cli open --device="Pixel 5" # Emulate a specific Playwright device
patchright-cli goto <url> # Navigate
patchright-cli click <ref> # Click element
patchright-cli click <ref> right # Right-click
patchright-cli click <ref> --modifiers=Alt,Shift
patchright-cli dblclick <ref> # Double-click
patchright-cli dblclick <ref> --modifiers=Shift
patchright-cli fill <ref> <value> # Fill text input
patchright-cli fill <ref> <value> --submit # Fill and press Enter
patchright-cli type <text> # Type via keyboard
patchright-cli type <text> --submit # Type and press Enter
patchright-cli hover <ref> # Hover over element
patchright-cli select <ref> <value> # Select dropdown option
patchright-cli check <ref> # Check checkbox
patchright-cli uncheck <ref> # Uncheck checkbox
patchright-cli drag <from> <to> # Drag and drop
patchright-cli snapshot # Accessibility snapshot
patchright-cli snapshot -i # Interactive elements only (recommended)
patchright-cli snapshot --depth=3 # Limit depth
patchright-cli snapshot --selector=CSS # Snapshot a CSS-scoped subtree
patchright-cli snapshot <ref> # Snapshot element subtree
patchright-cli snapshot --filename=f # Save to custom path
patchright-cli find "text" # Search snapshot for text
patchright-cli find --regex "a|b" # Search by regex
patchright-cli find "text" --all # Include text/paragraph nodes
patchright-cli find "text" --limit=50 # Cap hits (default 20)
patchright-cli eval <expr> # Run JavaScript
patchright-cli eval --file=script.js # Run JS from file
patchright-cli run-code <code> # Run JS with return value
patchright-cli run-code --file=f.js # Run JS from file
patchright-cli screenshot # Page screenshot
patchright-cli screenshot --full-page # Full scrollable page
patchright-cli screenshot <ref> # Element screenshot
patchright-cli screenshot --filename=f # Save to custom path
patchright-cli screenshot --hires # Capture at device pixel ratio
patchright-cli close # Close session
Navigation
patchright-cli go-back
patchright-cli go-forward
patchright-cli reload
patchright-cli wait 500 # Wait a fixed number of milliseconds
patchright-cli wait --url="**/dashboard" # Wait for the URL to match (`*` never crosses a `/`)
patchright-cli wait-for <ref> # Wait until an element is visible
patchright-cli wait-for <ref> --state=hidden
Keyboard / Mouse
patchright-cli press Enter
patchright-cli keydown Shift
patchright-cli keyup Shift
patchright-cli mousemove 150 300
patchright-cli mousedown [button]
patchright-cli mouseup [button]
patchright-cli mousewheel 0 100
Dialog
patchright-cli dialog-accept [text] # Accept next alert/confirm/prompt
patchright-cli dialog-dismiss # Dismiss next dialog
Upload / Resize
patchright-cli upload ./file.pdf # Upload to first file input
patchright-cli upload ./file.pdf e5 # Upload to specific input
patchright-cli resize 1920 1080 # Resize viewport
Tabs
patchright-cli tab-list
patchright-cli tab-new [url]
patchright-cli tab-select <index>
patchright-cli tab-close [index]
State Persistence
patchright-cli state-save [file] # Save cookies + localStorage
patchright-cli state-load <file> # Restore saved state
Storage
# Cookies
patchright-cli cookie-list
patchright-cli cookie-list --domain=example.com
patchright-cli cookie-list --path=/api
patchright-cli cookie-get <name>
patchright-cli cookie-set <name> <value>
patchright-cli cookie-set <name> <value> --domain=example.com --httpOnly --secure
patchright-cli cookie-set <name> <value> --path=/ --sameSite=Lax --expires=1735689600
patchright-cli cookie-delete <name>
patchright-cli cookie-clear
# localStorage
patchright-cli localstorage-list
patchright-cli localstorage-get <key>
patchright-cli localstorage-set <key> <value>
patchright-cli localstorage-delete <key>
patchright-cli localstorage-clear
# sessionStorage
patchright-cli sessionstorage-list
patchright-cli sessionstorage-get <key>
patchright-cli sessionstorage-set <key> <value>
patchright-cli sessionstorage-delete <key>
patchright-cli sessionstorage-clear
Request Mocking
patchright-cli route "**/*.jpg" --status=404
patchright-cli route "https://api.example.com/**" --body='{"mock":true}'
patchright-cli route "**/*" --content-type=application/json --body='{"ok":true}'
patchright-cli route "**/*" --header=X-Custom:value
patchright-cli route "**/*" --remove-header=Content-Type
patchright-cli route-list
patchright-cli unroute "**/*.jpg"
patchright-cli unroute # Remove all routes
Tracing / Video / PDF
patchright-cli tracing-start
patchright-cli tracing-stop # Saves .zip trace file
patchright-cli video-start # Start video recording (CDP screencast)
patchright-cli video-stop # Stop and save video (requires ffmpeg for .webm)
patchright-cli video-stop --filename=recording.webm
patchright-cli show --annotate # Ask a human to mark up the page, wait for it
patchright-cli video-show-actions # Annotate each action in the recording
patchright-cli video-hide-actions # Stop annotating actions
patchright-cli pdf --filename=page.pdf
Network
patchright-cli network # Network request log
patchright-cli network --static # Include static resources
patchright-cli network --clear # Clear log after printing
patchright-cli network-state-set offline # Simulate offline mode
patchright-cli network-state-set online # Restore connectivity
DevTools
patchright-cli console # All console messages
patchright-cli console warning # Filter by level
patchright-cli console --clear # Clear after printing
Output
patchright-cli --raw eval --file=s.js # Raw output (no page/snapshot decoration)
patchright-cli --raw snapshot > p.yml # Pipe raw snapshot to file
Setup
patchright-cli install --skills # Auto-install skills for detected AI agents
Sessions
patchright-cli -s=mysession open https://example.com
patchright-cli -s=mysession click e6
patchright-cli -s=mysession close
patchright-cli list # List all sessions
patchright-cli close-all
patchright-cli kill-all
patchright-cli delete-data # Delete the profile named after the session
patchright-cli profile-list # Profiles, size, and which session uses each
patchright-cli profile-delete <name> # Delete an idle named profile
patchright-cli --port=9322 open # Custom daemon port
Agent Integration
Works with Claude Code, Cursor, Gemini CLI, Codex, and 40+ other agents.
# Install skill for all detected agents (recommended)
npx skills add AhaiMk01/patchright-cli
Other install methods
# Via patchright-cli itself
pip install patchright-cli
patchright-cli install --skills
# Or just tell your agent:
# "Install patchright-cli skill from https://raw.githubusercontent.com/AhaiMk01/patchright-cli/main/skills/patchright-cli/SKILL.md"
MCP server
MCP support is optional so the base CLI install stays small:
pip install 'patchright-cli[mcp]'
# stdio (default)
patchright-cli mcp
# Streamable HTTP
patchright-cli mcp --http --host=127.0.0.1 --port=8000
The HTTP endpoint is /mcp. Set PATCHRIGHT_CLI_MCP_TOKEN to require Authorization: Bearer <token> on every request, and always set it before binding to 0.0.0.0.
File paths passed to MCP tools (uploads, state and cookie files, screenshot/PDF/snapshot output, profile directories) must be absolute and beneath the MCP root, so a client cannot reach arbitrary host files. Outputs without a path land in <root>/output/, which browser_delete_output can clean up. patchright_eval and patchright_run_code still run arbitrary JavaScript in the page, so protect HTTP deployments regardless.
| Variable | Default | Effect |
|---|---|---|
PATCHRIGHT_CLI_MCP_TOKEN |
unset (no auth) | Bearer token required by the HTTP transport |
PATCHRIGHT_CLI_MCP_ROOT |
working directory | Root that tool file paths must sit beneath |
PATCHRIGHT_CLI_MCP_UNRESTRICTED_FILESYSTEM |
unset | 1 drops the path check and enables patchright_install_skills |
PATCHRIGHT_CLI_MCP_HEADLESS |
unset (headed) | 1 makes patchright_open default to headless, for hosts without a display |
PATCHRIGHT_CLI_MCP_DAEMON_PORT |
9321 |
Daemon port the tools talk to |
Skill docs
| File | Topic |
|---|---|
SKILL.md |
Main skill — commands, options, patterns |
snapshot-refs.md |
Snapshots, element refs, -i flag |
session-management.md |
Named sessions, profiles, CDP, dashboard |
request-mocking.md |
Route mocking, network state |
storage-state.md |
Cookies, localStorage, sessionStorage |
running-code.md |
eval, run-code, --file, stdin |
tracing.md |
Trace recording and debugging |
video-recording.md |
Video, codegen, screenshot, PDF |
Star History
Differences from playwright-cli
patchright-cli aims for full command parity with Microsoft's playwright-cli. The following playwright-cli features are intentionally not implemented due to Patchright's architecture:
| Feature | Reason |
|---|---|
--browser=firefox/webkit/msedge |
Patchright only supports Chromium/Chrome. Anti-detect patches are Chrome-specific. |
--extension |
Browser extension connection not supported. Patchright uses CDP directly. |
install / install-browser |
Use python -m patchright install chromium instead. |
All other commands and options are fully supported.
Disclaimer
Credits
This project builds on the work of:
- Patchright by @Kaliiiiiiiiii-Vinyzu — the undetected Playwright fork that makes this possible. All anti-detect capabilities come from Patchright.
- playwright-cli by Microsoft — the original CLI that patchright-cli's command interface is modeled after.
- camoufox-cli by @Bin-Huang — inspiration for the CLI-first approach to anti-detect browser automation and the SKILL.md agent integration pattern.
License
Apache 2.0 — same as playwright-cli
Metadata
Release files for patchright-cli 0.8.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| patchright_cli-0.8.0.tar.gz | 307.9 kB | Without provenance | Details for patchright_cli-0.8.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| patchright_cli-0.8.0-py3-none-any.whl | Python 3 | none | any | Details for patchright_cli-0.8.0-py3-none-any.whl |
Total release size: 403.8 kB
Release files / patchright_cli-0.8.0.tar.gz
| Download URL | patchright_cli-0.8.0.tar.gz |
|---|---|
| Size | 307.9 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
ee580f7ef6e8b5c680fee0bd391e95f4026cc5ba92b7d36a1cd3a79f93c33c99
|
|
BLAKE2b-256 checksum How to use checksums |
3bd7e70db9bc0cf473f5366b91cb0206c78625fa7f2e9583a11134f31d0e9dd3
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.13.1 {"installer":{"name":"uv","version":"0.13.1","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Release files / patchright_cli-0.8.0-py3-none-any.whl
| Download URL | patchright_cli-0.8.0-py3-none-any.whl |
|---|---|
| Size | 95.8 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
f62e7579f82b60bf43c48887742c0ebefa9adb8bef3827ea253a53de0bf0e355
|
|
BLAKE2b-256 checksum How to use checksums |
432130e391b18cbc83ddff34dd2591b99a834b47412ec782afe030c69c9d3a36
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.13.1 {"installer":{"name":"uv","version":"0.13.1","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Security for patchright-cli 0.8.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.