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

Tip

Just paste this into your AI coding agent — it will do the rest:

Install and set up patchright-cli by following the instructions here:
https://raw.githubusercontent.com/AhaiMk01/patchright-cli/main/docs/installation.md

Your agent handles the install, browser setup, and skill configuration automatically.

For LLM Agents

curl -s https://raw.githubusercontent.com/AhaiMk01/patchright-cli/main/docs/installation.md

Important

Requirements: Python 3.10+ and Google Chrome

# 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`)	`TreeWalker`-based DOM scan assigning `data-patchright-ref` attributes for element targeting.

📖 Commands

Core

patchright-cli open [url]              # Launch browser
patchright-cli open --persistent       # With persistent profile
patchright-cli open --headless         # Run headless
patchright-cli open --profile=<path>   # Custom profile directory
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 type <text>             # Type via keyboard
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 --filename=f   # Save to custom path
patchright-cli eval <expr>             # Run JavaScript
patchright-cli run-code <code>         # Run JS with return value
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 close                   # Close session

Navigation

patchright-cli go-back
patchright-cli go-forward
patchright-cli reload

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 / PDF

patchright-cli tracing-start
patchright-cli tracing-stop            # Saves .zip trace file
patchright-cli pdf --filename=page.pdf

DevTools

patchright-cli console                 # All console messages
patchright-cli console warning         # Filter by level
patchright-cli network                 # Network request log

Sessions

patchright-cli -s=mysession open https://example.com --persistent
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 persistent profile
patchright-cli --port=9322 open        # Custom daemon port

Snapshots

After each state-changing command, the CLI outputs page info and a YAML snapshot:

### Page
- Page URL: https://example.com/
- Page Title: Example Domain
### Snapshot
[Snapshot](.patchright-cli/page-1774376207818.yml)

The snapshot lists interactive elements with refs you can use in commands:

- ref: e1
  role: heading
  name: Example Domain
  level: 1
- ref: e2
  role: link
  name: Learn more
  url: "https://iana.org/domains/example"

Note

Use refs directly: patchright-cli click e2, patchright-cli fill e5 "text"

Anti-Detect Features

Caution

This tool is for authorized testing, security research, and legitimate automation only.

✅ Real Chrome browser (not Chromium)
✅ Patchright patches navigator.webdriver and other detection vectors
✅ Persistent profiles maintain cookies/sessions across runs
✅ No custom user-agent or headers (natural fingerprint)
✅ Headed by default (headless is more detectable)

Agent Integration

Works with any AI coding agent that supports SKILL.md skills:

Agent	Install skill
Claude Code	`mkdir -p ~/.claude/skills/patchright-cli && curl -sL https://raw.githubusercontent.com/AhaiMk01/patchright-cli/main/skills/patchright-cli/SKILL.md -o ~/.claude/skills/patchright-cli/SKILL.md`
OpenClaw	`mkdir -p ~/.openclaw/skills/patchright-cli && curl -sL https://raw.githubusercontent.com/AhaiMk01/patchright-cli/main/skills/patchright-cli/SKILL.md -o ~/.openclaw/skills/patchright-cli/SKILL.md`
Codex CLI	`mkdir -p ~/.codex/skills/patchright-cli && curl -sL https://raw.githubusercontent.com/AhaiMk01/patchright-cli/main/skills/patchright-cli/SKILL.md -o ~/.codex/skills/patchright-cli/SKILL.md`
Gemini CLI	`mkdir -p ~/.gemini/skills/patchright-cli && curl -sL https://raw.githubusercontent.com/AhaiMk01/patchright-cli/main/skills/patchright-cli/SKILL.md -o ~/.gemini/skills/patchright-cli/SKILL.md`
OpenCode	`mkdir -p ~/.opencode/skills/patchright-cli && curl -sL https://raw.githubusercontent.com/AhaiMk01/patchright-cli/main/skills/patchright-cli/SKILL.md -o ~/.opencode/skills/patchright-cli/SKILL.md`
Cursor	Copy SKILL.md to `.cursor/skills/patchright-cli/` in your project
Windsurf	Copy SKILL.md to `.windsurf/skills/patchright-cli/` in your project
Aider	Copy SKILL.md to `.aider/skills/patchright-cli/` in your project

Or just tell your agent:

Install patchright-cli skill from https://raw.githubusercontent.com/AhaiMk01/patchright-cli/main/skills/patchright-cli/SKILL.md

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.
`--config=<file>`	No config file system. Options are passed as CLI flags.
`--extension`	Browser extension connection not supported. Patchright uses CDP directly.
`show` / `devtools-start`	DevTools are available natively in headed mode (default).
`install` / `install-browser`	Use `python -m patchright install chromium` instead.

All other commands and options are fully supported.

Disclaimer

Warning

This tool is provided for authorized security testing, legitimate automation, and educational purposes only. Users are solely responsible for ensuring their use complies with applicable laws and the terms of service of any websites they interact with. The authors do not endorse or encourage any unauthorized access, scraping, or circumvention of security measures. Use at your own risk.

License

Apache 2.0 — same as playwright-cli

Name		Name	Last commit message	Last commit date
Latest commit History 33 Commits
.github/workflows		.github/workflows
docs		docs
skills/patchright-cli		skills/patchright-cli
src/patchright_cli		src/patchright_cli
.gitignore		.gitignore
.pre-commit-config.yaml		.pre-commit-config.yaml
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
patchright-cli		patchright-cli
patchright-cli.cmd		patchright-cli.cmd
pyproject.toml		pyproject.toml
uv.lock		uv.lock

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

patchright-cli

Highlights

Install

Quick Start

Architecture

📖 Commands

Core

Navigation

Keyboard / Mouse

Dialog

Upload / Resize

Tabs

State Persistence

Storage

Request Mocking

Tracing / PDF

DevTools

Sessions

Snapshots

Anti-Detect Features

Agent Integration

Star History

Differences from playwright-cli

Disclaimer

License

About

Uh oh!

Releases 2

Packages

Uh oh!

Contributors 2

Languages

Folders and files

Latest commit

History

Repository files navigation

patchright-cli

Highlights

Install

Quick Start

Architecture

📖 Commands

Core

Navigation

Keyboard / Mouse

Dialog

Upload / Resize

Tabs

State Persistence

Storage

Request Mocking

Tracing / PDF

DevTools

Sessions

Snapshots

Anti-Detect Features

Agent Integration

Star History

Differences from playwright-cli

Disclaimer

License

About

Resources

License

Contributing

Uh oh!

Stars

Watchers

Forks

Releases 2

Packages 0

Uh oh!

Contributors 2

Languages

Packages