patchright-cli 0.4.1__py3-none-any.whl → 0.6.0__py3-none-any.whl

patchright_cli/__init__.py

@@ -1,3 +1,3 @@
 """patchright-cli — Undetected browser automation CLI using Patchright."""
 
-__version__ = "0.4.1"
+__version__ = "0.6.0"

patchright_cli/_skills/patchright-cli/SKILL.md

@@ -0,0 +1,350 @@
+---
+name: patchright-cli
+description: Anti-detect browser automation using Patchright (undetected Playwright fork). Use when you need to interact with websites that block regular Playwright/Chrome DevTools, such as Akamai/Cloudflare-protected sites. Provides the same command interface as playwright-cli but bypasses bot detection. Use this skill whenever the user asks to automate a browser, scrape a website, fill forms, log into sites, take screenshots, or do anything involving Chrome automation — especially if the target site has bot protection like Cloudflare or Akamai.
+---
+
+# 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
+
+```bash
+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.
+
+```bash
+# 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:
+
+```bash
+--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
+
+```bash
+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
+
+```bash
+goto <url>                    # Navigate to URL
+go-back / go-forward          # History navigation
+reload                        # Reload page
+url                           # Print current URL
+title                         # Print page title
+```
+
+### Snapshots
+
+```bash
+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
+
+```bash
+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
+
+```bash
+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
+
+```bash
+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
+
+```bash
+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
+
+```bash
+mousemove <x> <y>             # Move to coordinates
+mousedown / mouseup           # Button down/up
+mousewheel <dx> <dy>          # Scroll wheel
+```
+
+### Tabs
+
+```bash
+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:
+
+```bash
+dialog-accept                 # Accept next dialog
+dialog-accept "OK"            # Accept with text input
+dialog-dismiss                # Dismiss next dialog
+```
+
+### DevTools
+
+```bash
+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
+
+```bash
+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
+
+```bash
+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
+
+```bash
+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
+
+```bash
+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
+
+```bash
+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
+
+```bash
+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
+
+```bash
+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
+
+```bash
+patchright-cli dialog-accept              # Arm before triggering action
+patchright-cli click e5                   # This click triggers the dialog
+```
+
+### Waiting for dynamic content
+
+```bash
+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>`:
+
+```json
+{
+  "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
+
+```bash
+# Recommended -- always runs latest version
+uvx patchright-cli <command>
+
+# Or install globally
+pip install patchright-cli
+```
+
+### Skill (for AI coding agents)
+
+```bash
+# Install for all detected agents (Claude Code, Cursor, Gemini, Codex, 40+ more)
+npx skills add AhaiMk01/patchright-cli
+```
+
+Other methods:
+
+```bash
+# 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](references/snapshot-refs.md)
+* **Browser session management** [references/session-management.md](references/session-management.md)
+* **Request mocking** [references/request-mocking.md](references/request-mocking.md)
+* **Storage state (cookies, localStorage)** [references/storage-state.md](references/storage-state.md)
+* **Running JavaScript** [references/running-code.md](references/running-code.md)
+* **Tracing** [references/tracing.md](references/tracing.md)
+* **Video recording & capture** [references/video-recording.md](references/video-recording.md)

patchright_cli/_skills/patchright-cli/references/request-mocking.md

@@ -0,0 +1,103 @@
+# Request Mocking
+
+## Route command
+
+Intercept and modify network requests matching a URL pattern:
+
+```bash
+patchright-cli route "<pattern>" [options]
+```
+
+The pattern uses glob syntax (e.g., `**/*.jpg`, `https://api.example.com/**`).
+
+### Options
+
+| Flag | Effect |
+|------|--------|
+| `--status=N` | Respond with HTTP status code N |
+| `--body=<string>` | Respond with this body content |
+| `--content-type=<mime>` | Set the Content-Type header |
+| `--header=Name:Value` | Add or override a response header |
+| `--remove-header=Name` | Remove a response header |
+
+### Examples
+
+```bash
+# Block all images (respond with 404)
+patchright-cli route "**/*.jpg" --status=404
+
+# Mock an API endpoint
+patchright-cli route "https://api.example.com/**" --body='{"mock": true}' --content-type=application/json
+
+# Add a custom header to all responses
+patchright-cli route "**/*" --header=X-Custom:value
+
+# Remove a header from responses
+patchright-cli route "**/*" --remove-header=Content-Type
+
+# Block all CSS (speeds up testing)
+patchright-cli route "**/*.css" --status=404
+
+# Mock a specific API response
+patchright-cli route "https://api.example.com/users" --body='[{"id":1,"name":"Test"}]' --content-type=application/json --status=200
+```
+
+## Managing routes
+
+```bash
+patchright-cli route-list                  # List all active routes
+patchright-cli unroute "**/*.jpg"           # Remove a specific route
+patchright-cli unroute                     # Remove all routes
+```
+
+## Network state
+
+Simulate offline/online conditions:
+
+```bash
+patchright-cli network-state-set offline   # Simulate offline
+patchright-cli network-state-set online    # Restore connectivity
+```
+
+## Common patterns
+
+### Block tracking and analytics
+
+```bash
+patchright-cli route "**/analytics/**" --status=204
+patchright-cli route "**/tracking/**" --status=204
+patchright-cli route "**/*.gif?*" --status=204    # Tracking pixels
+```
+
+### Mock authentication API
+
+```bash
+patchright-cli route "https://api.example.com/auth/login" \
+  --body='{"token":"fake-jwt","user":{"id":1}}' \
+  --content-type=application/json \
+  --status=200
+```
+
+### Test error handling
+
+```bash
+# Simulate server error on API calls
+patchright-cli route "https://api.example.com/**" --status=500 --body='{"error":"Internal Server Error"}'
+
+# Simulate network timeout (offline mode)
+patchright-cli network-state-set offline
+```
+
+## DevTools inspection
+
+Monitor network activity and console output:
+
+```bash
+patchright-cli console                     # Show console messages (last 50)
+patchright-cli console warning             # Filter by level
+patchright-cli console --clear             # Clear buffer after printing
+
+patchright-cli network                     # Show requests (excludes static assets)
+patchright-cli network --static            # Include images, fonts, scripts, etc.
+patchright-cli network --clear             # Clear log after printing
+```

patchright_cli/_skills/patchright-cli/references/running-code.md

@@ -0,0 +1,129 @@
+# Running JavaScript
+
+## eval
+
+Evaluate a JavaScript expression and return the result.
+
+```bash
+patchright-cli eval --file=/tmp/expr.js
+```
+
+### Why use --file (not inline JS)
+
+**Always use `--file` or stdin for `eval` and `run-code`.** Inline JS breaks because quotes get mangled through shell layers (bash -> uvx -> python).
+
+```bash
+# WRONG -- nested quotes break
+patchright-cli eval "document.querySelector('a').href"
+
+# RIGHT -- write to a temp file
+cat > /tmp/check.js << 'JSEOF'
+JSON.stringify({title: document.title, links: document.querySelectorAll('a').length})
+JSEOF
+patchright-cli eval --file=/tmp/check.js
+
+# RIGHT -- pipe via stdin (simple expressions only)
+echo 'document.title' | patchright-cli eval
+```
+
+### eval with element ref
+
+Target a specific element by passing a ref as the second argument. The element is received as the first parameter of the expression:
+
+```bash
+echo 'el => el.textContent' | patchright-cli eval - e5
+echo 'el => el.href' | patchright-cli eval - e3
+```
+
+### eval options
+
+| Usage | Effect |
+|-------|--------|
+| `eval --file=<path>` | Read expression from file |
+| `eval` (no args) | Read expression from stdin |
+| `eval <expr> <ref>` | Evaluate on a specific element (element passed as first arg) |
+
+## run-code
+
+Run a JavaScript code block wrapped in `async () => { ... }`, so you can use `return` and `await`:
+
+```bash
+cat > /tmp/scroll.js << 'JSEOF'
+window.scrollTo(0, document.body.scrollHeight);
+return document.body.scrollHeight;
+JSEOF
+patchright-cli run-code --file=/tmp/scroll.js
+```
+
+### run-code options
+
+| Usage | Effect |
+|-------|--------|
+| `run-code --file=<path>` | Read code from file |
+| `run-code` (no args) | Read code from stdin |
+
+## Temp file heredoc pattern
+
+The recommended pattern for running JS from a shell:
+
+```bash
+cat > /tmp/myscript.js << 'JSEOF'
+// Your JavaScript here
+const data = document.querySelectorAll('.item');
+return JSON.stringify([...data].map(el => el.textContent));
+JSEOF
+patchright-cli run-code --file=/tmp/myscript.js
+```
+
+Use `'JSEOF'` (quoted) to prevent shell variable expansion inside the heredoc.
+
+## Common patterns
+
+### Extract structured data
+
+```bash
+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
+```
+
+### Wait for a custom condition
+
+```bash
+cat > /tmp/wait.js << 'JSEOF'
+for (let i = 0; i < 30; i++) {
+  if (document.querySelector('.results-loaded')) return true;
+  await new Promise(r => setTimeout(r, 500));
+}
+return false;
+JSEOF
+patchright-cli run-code --file=/tmp/wait.js
+```
+
+### Scroll to bottom of infinite scroll
+
+```bash
+cat > /tmp/infinite.js << 'JSEOF'
+let prev = 0;
+for (let i = 0; i < 20; i++) {
+  window.scrollTo(0, document.body.scrollHeight);
+  await new Promise(r => setTimeout(r, 1000));
+  if (document.body.scrollHeight === prev) break;
+  prev = document.body.scrollHeight;
+}
+return document.body.scrollHeight;
+JSEOF
+patchright-cli run-code --file=/tmp/infinite.js
+```
+
+### Get element attribute or style
+
+```bash
+echo 'el => el.getAttribute("href")' | patchright-cli eval - e5
+echo 'el => getComputedStyle(el).color' | patchright-cli eval - e3
+```

patchright_cli/_skills/patchright-cli/references/session-management.md

@@ -0,0 +1,106 @@
+# Browser Session Management
+
+## Named sessions
+
+By default, patchright-cli uses a session named `"default"`. Use `-s=name` to create or switch to a named session:
+
+```bash
+patchright-cli -s=session1 open https://site-a.com
+patchright-cli -s=session2 open https://site-b.com
+```
+
+Each named session has its own independent browser context -- separate tabs, cookies, storage, and history.
+
+### Default session via environment variable
+
+Set `PATCHRIGHT_CLI_SESSION` to avoid passing `-s` on every command:
+
+```bash
+export PATCHRIGHT_CLI_SESSION=myproject
+patchright-cli open https://example.com    # Uses "myproject" session
+patchright-cli snapshot                    # Same session
+```
+
+## Persistent profiles
+
+Use `--persistent` to keep cookies, localStorage, and browser data across sessions:
+
+```bash
+patchright-cli open https://example.com --persistent
+# ... log in, do work ...
+patchright-cli close
+# Later:
+patchright-cli open https://example.com --persistent
+# Cookies and storage are restored
+```
+
+Profiles are stored at `~/.patchright-cli/profiles/<session-name>`. Use `--profile=/path` to specify a custom profile directory:
+
+```bash
+patchright-cli open --persistent --profile=/path/to/my/profile https://example.com
+```
+
+## CDP attach
+
+Connect to an already-running Chrome instance via Chrome DevTools Protocol instead of launching a new one:
+
+```bash
+patchright-cli attach --cdp=http://localhost:9222
+```
+
+This is useful for debugging or controlling a browser you launched manually with `--remote-debugging-port`.
+
+## Session commands
+
+```bash
+patchright-cli list                        # List all active sessions
+patchright-cli close                       # Close current session gracefully
+patchright-cli close-all                   # Close all sessions gracefully
+patchright-cli kill-all                    # Force-kill all sessions + stop daemon
+patchright-cli delete-data                 # Delete default session's profile data
+patchright-cli -s=mysession delete-data    # Delete named session's profile data
+```
+
+## Concurrent sessions
+
+You can run multiple sessions simultaneously for parallel workflows:
+
+```bash
+patchright-cli -s=scrape1 open https://site1.com --persistent
+patchright-cli -s=scrape2 open https://site2.com --persistent
+# Work with both independently
+patchright-cli -s=scrape1 snapshot
+patchright-cli -s=scrape2 snapshot
+```
+
+## Dashboard
+
+The `show` command starts a local web dashboard that streams live screenshots of all active sessions:
+
+```bash
+patchright-cli show                        # Open at http://127.0.0.1:9322
+patchright-cli show --show-port=9400       # Custom port
+```
+
+## Granting permissions
+
+Grant browser permissions (geolocation, camera, etc.) to a running session:
+
+```bash
+patchright-cli grant-permissions geolocation,camera
+patchright-cli grant-permissions notifications --origin=https://example.com
+```
+
+You can also grant permissions at launch with `--grant-permissions=geolocation,camera`.
+
+## Daemon behavior
+
+The daemon auto-starts on the first command and auto-shuts down after 5 minutes of inactivity. If it ever crashes, the next command will respawn it automatically.
+
+## Cleanup best practices
+
+- Use `close` when done with a session to free resources
+- Use `close-all` at the end of a multi-session workflow
+- Use `delete-data` to remove persistent profile data you no longer need
+- Use `kill-all` as a last resort if sessions are stuck
+- Persistent profiles accumulate data over time -- periodically clean up unused ones