patchright-cli

Anti-Detect Browser Automation with patchright-cli

patchright-cli drives a real Chrome browser that passes bot detection (Cloudflare, Akamai, etc.). It works as a CLI: you issue commands, get back page state. This is the tool to reach for whenever regular Playwright or Chrome DevTools gets blocked.

Quick start

patchright-cli open https://example.com     # launch browser + navigate
patchright-cli snapshot                      # get element refs
# read the snapshot YAML to find the right ref, then:
patchright-cli click e5                      # interact by ref
patchright-cli fill e3 "search query"        # type into an input
patchright-cli press Enter                   # press a key
patchright-cli screenshot                    # capture the page
patchright-cli close                         # done

Every interaction follows: open -> snapshot -> read refs -> interact -> snapshot again -> repeat. Refs are ephemeral -- they change on every page update. If a ref fails, re-snapshot.

Command chaining

Commands can be chained with &&. The browser persists via a background daemon, so chaining is safe.

# Chain when you don't need intermediate output
patchright-cli open https://example.com && patchright-cli screenshot

# Run separately when you need to read refs first
patchright-cli snapshot          # read refs from output
patchright-cli click e5          # use discovered ref

Global options

These go before the command:

--headless              # Run headless (default: headed -- headed is less detectable)
--persistent            # Use persistent profile (keeps cookies/storage across sessions)
--profile=/path         # Custom profile directory
--proxy=<url>           # Proxy server (http, https, socks5) -- supports user:pass@host auth
-s=mysession            # Named session (default: "default", or PATCHRIGHT_CLI_SESSION env var)
--port=9322             # Custom daemon port (default: 9321)
--config=<path>         # Load options from JSON config file
--cdp=<url>             # Attach to Chrome via CDP endpoint (use with `attach` command)
--device="iPhone 15"    # Emulate a device
--viewport-size=1280x720 # Set viewport size
--locale=en-US          # Browser locale
--timezone=America/New_York # Timezone ID
--geolocation=40.7,-74.0   # Geolocation override (lat,lon)
--user-agent=<ua>       # Custom user agent string
--grant-permissions=geolocation,camera  # Grant permissions at launch
--timeout-action=10000  # Default action timeout (ms)
--timeout-navigation=30000 # Default navigation timeout (ms)
--show-port=9322        # Dashboard port (default: 9322)
--raw                   # Strip page/snapshot decorations from output
--json                  # Wrap full response as JSON ({success, output, ...})

---

Core commands

Browser lifecycle

open [url]                    # Launch browser (optionally navigate)
open --persistent             # Keep cookies/storage between runs
open --headless               # Headless mode
attach --cdp=<url>            # Attach to existing Chrome via CDP
close                         # Close session (closes the browser)
detach                        # Detach an attached session (keeps external browser running)

Navigation

goto <url>                    # Navigate to URL
go-back / go-forward          # History navigation
reload                        # Reload page
url                           # Print current URL
title                         # Print page title

Snapshots

snapshot                      # Full page snapshot
snapshot <ref>                # Subtree of a specific element
snapshot --depth=N            # Limit depth
snapshot -i                   # Interactive elements only
snapshot --boxes              # Append [box=x,y,w,h] to each [ref=eN] line

Interaction

click <ref>                   # Left-click (smart: navigates links directly)
click <ref> right             # Right-click
click <ref> --modifiers=Alt   # Click with modifier keys
dblclick <ref>                # Double-click
hover <ref>                   # Hover
drag <ref> <target-ref>       # Drag element to target
drop <ref> --path=./file.png  # Drop file onto element (HTML5 drop from outside)
drop <ref> --data="text/plain=hello"  # Drop arbitrary MIME data

Form input

fill <ref> "value"            # Clear field and type value
fill <ref> "value" --submit   # Fill and press Enter
type "text"                   # Type via keyboard (no target)
type "text" --submit          # Type and press Enter
select <ref> "option"         # Select dropdown option
check <ref> / uncheck <ref>   # Checkbox/radio

Text and screenshots

text <ref>                    # Get text content by ref
text "css-selector"           # Get text by CSS selector
screenshot                    # Page screenshot
screenshot <ref>              # Element screenshot
screenshot --full-page        # Full scrollable page
screenshot --filename=F       # Custom filename

Scroll, wait, and keyboard

scroll <dx> <dy>              # Scroll by pixels
scroll-to <ref>               # Scroll element into view
wait <ms>                     # Wait N milliseconds
wait-for <ref>                # Wait until element visible
wait-for <ref> --state=hidden # Wait until hidden
press <key>                   # Keypress (Enter, ArrowDown, etc.)
keydown <key> / keyup <key>   # Hold/release key

Mouse

mousemove <x> <y>             # Move to coordinates
mousedown / mouseup           # Button down/up
mousewheel <dx> <dy>          # Scroll wheel

Tabs

tab-list                      # List open tabs
tab-new <url>                 # Open new tab
tab-select <index>            # Switch to tab
tab-close [index]             # Close tab

Dialogs

Dialogs must be pre-armed before the action that triggers them:

dialog-accept                 # Accept next dialog
dialog-accept "OK"            # Accept with text input
dialog-dismiss                # Dismiss next dialog

DevTools

console                       # Show console messages
console warning               # Filter by level
network                       # Show network requests (each line is `#<id> METHOD STATUS URL`)
requests                      # Alias for `network`
network --static              # Include static assets
request <id>                  # Full detail for one request (headers + body)
request <id> --body           # Also fetch response body
generate-locator <ref>        # Emit Playwright locator string for a ref
highlight <ref>               # Persistent overlay on element [--style=CSS]
highlight <ref> --hide        # Remove overlay; `highlight --hide` clears all

Recording and capture

screenshot / pdf              # Static capture
video-start / video-stop      # Video recording
tracing-start / tracing-stop  # Playwright trace
codegen / codegen-stop        # Record interactions as script
resize <w> <h>                # Viewport resize
upload <file> [ref]           # File upload
show                          # Live dashboard

Storage

cookie-list / cookie-get / cookie-set / cookie-delete / cookie-clear
cookie-export / cookie-import
localstorage-list / localstorage-get / localstorage-set / localstorage-delete / localstorage-clear
sessionstorage-list / sessionstorage-get / sessionstorage-set / sessionstorage-delete / sessionstorage-clear
state-save <file> / state-load <file>

Network

route "<pattern>" [options]   # Mock requests (--status, --body, --content-type, --header)
route-list / unroute          # Manage routes
network-state-set offline     # Simulate offline
network-state-set online      # Restore connectivity

Sessions

list                          # List active sessions
close-all                     # Close all sessions
kill-all                      # Force-kill all + stop daemon
delete-data                   # Delete session profile data
grant-permissions <perms>     # Grant browser permissions

---

Common patterns

Login flow

patchright-cli open https://example.com/login --persistent
patchright-cli snapshot
patchright-cli fill e3 "user@example.com"
patchright-cli fill e5 "password123"
patchright-cli click e8
patchright-cli snapshot
# With --persistent, cookies survive across sessions

Extracting data

patchright-cli open https://example.com/data
patchright-cli snapshot
cat > /tmp/extract.js << 'JSEOF'
JSON.stringify(
  [...document.querySelectorAll('table tr')].map(row =>
    [...row.cells].map(cell => cell.textContent.trim())
  )
)
JSEOF
patchright-cli eval --file=/tmp/extract.js

Using a proxy

patchright-cli --proxy=http://host:port open https://example.com
patchright-cli --proxy=socks5://host:port open https://example.com
patchright-cli --proxy=http://user:pass@host:port open https://example.com

Handling dialogs

patchright-cli dialog-accept              # Arm before triggering action
patchright-cli click e5                   # This click triggers the dialog

Waiting for dynamic content

patchright-cli wait-for e12               # Wait for element
patchright-cli wait 1000                  # Fixed wait
# For custom conditions, use run-code (see references/running-code.md)

---

Anti-detect notes

• Uses real Chrome (not Chromium) -- this is what makes it undetectable
• Patchright patches navigator.webdriver and other detection vectors automatically
• Headed by default -- headless mode is more detectable, use only when necessary
• No custom user-agent or headers by default -- preserves Chrome's natural fingerprint
• Persistent profiles maintain realistic browser history and cookies
• The daemon architecture means Chrome stays running between commands, behaving like a real user's browser
• attach --cdp lets you connect to an existing Chrome instance

Config files

Create .patchright-cli/config.json in your project directory (auto-discovered) or pass --config=<path>:

{
  "headless": false,
  "persistent": true,
  "proxy": "http://proxy:8080",
  "device": "iPhone 15",
  "locale": "en-US",
  "timezone": "America/New_York"
}

CLI flags always override config file values.

Installation

CLI tool

# Recommended -- always runs latest version
uvx patchright-cli <command>

# Or install globally
pip install patchright-cli

Skill (for AI coding agents)

# Install for all detected agents (Claude Code, Cursor, Gemini, Codex, 40+ more)
npx skills add AhaiMk01/patchright-cli

Other 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"

Specific tasks

• Snapshots and element refs references/snapshot-refs.md
• Browser session management references/session-management.md
• Request mocking references/request-mocking.md
• Storage state (cookies, localStorage) references/storage-state.md
• Running JavaScript references/running-code.md
• Tracing references/tracing.md
• Video recording & capture references/video-recording.md