patchright-cli 0.5.0__tar.gz → 0.7.0__tar.gz

{patchright_cli-0.5.0 → patchright_cli-0.7.0}/.claude-plugin/marketplace.json

@@ -5,7 +5,7 @@
   },
   "metadata": {
     "description": "Anti-detect browser automation CLI & Skills for AI agents, powered by Patchright",
-    "version": "0.5.0"
+    "version": "0.7.0"
   },
   "plugins": [
     {

{patchright_cli-0.5.0 → patchright_cli-0.7.0}/.gitignore

@@ -6,4 +6,7 @@ __pycache__/
 dist/
 build/
 docs/reddit-post.md
+docs/superpowers/
 .worktrees/
+.claude/settings.local.json
+=*

{patchright_cli-0.5.0 → patchright_cli-0.7.0}/CLAUDE.md

@@ -57,10 +57,10 @@ CLI (cli.py) --TCP:9321--> Daemon (daemon.py) --Patchright--> Chrome
 
 - Always uses persistent browser context (`launch_persistent_context`) with real Chrome (`channel="chrome"`), not Chromium
 - Headed by default (headless is more detectable)
-- Default daemon port: 9321, profiles stored at `~/.patchright-cli/profiles/<session-name>`
+- Default daemon port: 9321, profiles stored at `~/.patchright-cli/profiles/<profile-name>`; a session's profile defaults to its session name (`--profile=<name>` overrides, a value with `/` or `\` is a directory). One session per profile at a time
 - CLI-daemon protocol: length-prefixed (4-byte big-endian `!I`) JSON over TCP
 - CLI parses argv manually in `main()` — click is only used for `click.echo()`, not subcommands. New commands must be added to both `COMMANDS_HELP` dict and the `handle_command()` if/elif chain in daemon.py
-- Version must be updated in both `pyproject.toml` and `src/patchright_cli/__init__.py` (then run `uv lock` to sync the lock file)
+- Version must be updated in `pyproject.toml`, `src/patchright_cli/__init__.py` and `.claude-plugin/marketplace.json` (then run `uv lock` to sync the lock file; `tests/test_packaging.py` checks they match)
 - `python -m patchright_cli` works via `__main__.py`
 - Uses hatchling as build backend, ruff for linting (line-length=120, target py310)
 - Ruff rules: E, F, I, W, UP, B, SIM (ignores E501, SIM105, E402)

patchright_cli-0.7.0/GLOSSARY.md

@@ -0,0 +1,58 @@
+# patchright-cli
+
+An anti-detect browser automation CLI: callers drive real Chrome through short commands sent to a long-running daemon.
+
+## Sessions and browsers
+
+**Session**:
+A named handle on one browser context that callers drive with commands; selected with `-s`.
+_Avoid_: Browser, instance, profile
+
+**Default Session**:
+The Session used when no `-s` is given.
+
+**Launched Session**:
+A Session whose Chrome patchright-cli started itself and therefore owns outright.
+
+**Profile**:
+A named, persistent store of browser state — cookies, storage, logins, history — that a Launched Session runs on; at most one Session uses a Profile at a time. Unless told otherwise, a Session's Profile is named after the Session.
+_Avoid_: User data dir, profile directory, persistent context
+
+**Attached Session**:
+A Session connected to a Chrome that something else started, reached over CDP.
+_Avoid_: Connected session, remote session
+
+**Host**:
+Whatever started and owns the Chrome an Attached Session connects to — a person, a script, or a product such as a workspace manager.
+_Avoid_: External browser, owner
+
+**Host Context**:
+The Host's own browser context, carrying its profile's cookies, storage and logins; at most one Session may use a given Host Context.
+_Avoid_: Default context, existing context, persistent context
+
+**Isolated Context**:
+A fresh browser context an Attached Session creates inside the Host's Chrome, sharing none of the Host's state.
+_Avoid_: Incognito context
+
+## Tabs and pages
+
+**Page**:
+One browser tab as Chrome sees it.
+_Avoid_: Tab (except in the playwright-cli-compatible `tab-*` command names, which act on Pages)
+
+**Tab**:
+A named workspace inside a Session — its own Page, element refs and navigation history — selected with `--tab`.
+_Avoid_: Lane, worker
+
+**Default Tab**:
+The Tab used when no `--tab` is given; it follows whichever Page is currently selected rather than owning one.
+
+## Ending a Session
+
+**Close**:
+Ending a Session by destroying what it owns: its Tabs' Pages and, for a context it owns, the context itself.
+_Avoid_: Quit, kill (except `kill-all`)
+
+**Detach**:
+Letting go of an Attached Session while leaving the Host's Chrome, and anything the Host owns, untouched.
+_Avoid_: Disconnect, release

{patchright_cli-0.5.0 → patchright_cli-0.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: patchright-cli
-Version: 0.5.0
+Version: 0.7.0
 Summary: Anti-detect browser automation CLI using Patchright (undetected Playwright fork)
 Project-URL: Homepage, https://github.com/AhaiMk01/patchright-cli
 Project-URL: Repository, https://github.com/AhaiMk01/patchright-cli
@@ -149,7 +149,7 @@ graph LR
 |-----------|------|
 | **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. |
+| **Snapshot** (`snapshot.py`) | Playwright `aria_snapshot()` accessibility tree, annotated with sequential `[ref=eN]` handles for element targeting. |
 
 ---
 
@@ -159,9 +159,12 @@ graph LR
 ### Core
 ```bash
 patchright-cli open [url]              # Launch browser
-patchright-cli open --persistent       # With persistent profile
+patchright-cli open --profile=work     # Named profile any session can use (logins persist)
 patchright-cli open --headless         # Run headless
-patchright-cli open --profile=<path>   # Custom profile directory
+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
@@ -180,8 +183,13 @@ 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
@@ -190,6 +198,7 @@ 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
 ```
 
@@ -198,6 +207,10 @@ patchright-cli close                   # Close session
 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
@@ -285,6 +298,9 @@ 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
 ```
 
@@ -317,13 +333,15 @@ patchright-cli install --skills        # Auto-install skills for detected AI age
 
 ### Sessions
 ```bash
-patchright-cli -s=mysession open https://example.com --persistent
+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 persistent profile
+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
 ```
 
@@ -331,74 +349,41 @@ 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:
-
-```yaml
-- 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.
-
-- :white_check_mark: Real Chrome browser (not Chromium)
-- :white_check_mark: Patchright patches `navigator.webdriver` and other detection vectors
-- :white_check_mark: Persistent profiles maintain cookies/sessions across runs
-- :white_check_mark: No custom user-agent or headers (natural fingerprint)
-- :white_check_mark: Headed by default (headless is more detectable)
-
----
-
 ## Agent Integration
 
-Works with any AI coding agent that supports SKILL.md skills:
+Works with Claude Code, Cursor, Gemini CLI, Codex, and [40+ other agents](https://github.com/vercel-labs/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 |
+```bash
+# Install skill for all detected agents (recommended)
+npx skills add AhaiMk01/patchright-cli
+```
 
-Or auto-install for all detected agents:
+<details>
+<summary><b>Other install methods</b></summary>
 
 ```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"
 ```
 
-Or just tell your agent:
+</details>
 
-> Install patchright-cli skill from https://raw.githubusercontent.com/AhaiMk01/patchright-cli/main/skills/patchright-cli/SKILL.md
+### Skill docs
+
+| File | Topic |
+|------|-------|
+| [`SKILL.md`](skills/patchright-cli/SKILL.md) | Main skill — commands, options, patterns |
+| [`snapshot-refs.md`](skills/patchright-cli/references/snapshot-refs.md) | Snapshots, element refs, `-i` flag |
+| [`session-management.md`](skills/patchright-cli/references/session-management.md) | Named sessions, profiles, CDP, dashboard |
+| [`request-mocking.md`](skills/patchright-cli/references/request-mocking.md) | Route mocking, network state |
+| [`storage-state.md`](skills/patchright-cli/references/storage-state.md) | Cookies, localStorage, sessionStorage |
+| [`running-code.md`](skills/patchright-cli/references/running-code.md) | eval, run-code, `--file`, stdin |
+| [`tracing.md`](skills/patchright-cli/references/tracing.md) | Trace recording and debugging |
+| [`video-recording.md`](skills/patchright-cli/references/video-recording.md) | Video, codegen, screenshot, PDF |
 
 ---
 

{patchright_cli-0.5.0 → patchright_cli-0.7.0}/README.md

@@ -116,7 +116,7 @@ graph LR
 |-----------|------|
 | **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. |
+| **Snapshot** (`snapshot.py`) | Playwright `aria_snapshot()` accessibility tree, annotated with sequential `[ref=eN]` handles for element targeting. |
 
 ---
 
@@ -126,9 +126,12 @@ graph LR
 ### Core
 ```bash
 patchright-cli open [url]              # Launch browser
-patchright-cli open --persistent       # With persistent profile
+patchright-cli open --profile=work     # Named profile any session can use (logins persist)
 patchright-cli open --headless         # Run headless
-patchright-cli open --profile=<path>   # Custom profile directory
+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
@@ -147,8 +150,13 @@ 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
@@ -157,6 +165,7 @@ 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
 ```
 
@@ -165,6 +174,10 @@ patchright-cli close                   # Close session
 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
@@ -252,6 +265,9 @@ 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
 ```
 
@@ -284,13 +300,15 @@ patchright-cli install --skills        # Auto-install skills for detected AI age
 
 ### Sessions
 ```bash
-patchright-cli -s=mysession open https://example.com --persistent
+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 persistent profile
+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
 ```
 
@@ -298,74 +316,41 @@ 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:
-
-```yaml
-- 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.
-
-- :white_check_mark: Real Chrome browser (not Chromium)
-- :white_check_mark: Patchright patches `navigator.webdriver` and other detection vectors
-- :white_check_mark: Persistent profiles maintain cookies/sessions across runs
-- :white_check_mark: No custom user-agent or headers (natural fingerprint)
-- :white_check_mark: Headed by default (headless is more detectable)
-
----
-
 ## Agent Integration
 
-Works with any AI coding agent that supports SKILL.md skills:
+Works with Claude Code, Cursor, Gemini CLI, Codex, and [40+ other agents](https://github.com/vercel-labs/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 |
+```bash
+# Install skill for all detected agents (recommended)
+npx skills add AhaiMk01/patchright-cli
+```
 
-Or auto-install for all detected agents:
+<details>
+<summary><b>Other install methods</b></summary>
 
 ```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"
 ```
 
-Or just tell your agent:
+</details>
 
-> Install patchright-cli skill from https://raw.githubusercontent.com/AhaiMk01/patchright-cli/main/skills/patchright-cli/SKILL.md
+### Skill docs
+
+| File | Topic |
+|------|-------|
+| [`SKILL.md`](skills/patchright-cli/SKILL.md) | Main skill — commands, options, patterns |
+| [`snapshot-refs.md`](skills/patchright-cli/references/snapshot-refs.md) | Snapshots, element refs, `-i` flag |
+| [`session-management.md`](skills/patchright-cli/references/session-management.md) | Named sessions, profiles, CDP, dashboard |
+| [`request-mocking.md`](skills/patchright-cli/references/request-mocking.md) | Route mocking, network state |
+| [`storage-state.md`](skills/patchright-cli/references/storage-state.md) | Cookies, localStorage, sessionStorage |
+| [`running-code.md`](skills/patchright-cli/references/running-code.md) | eval, run-code, `--file`, stdin |
+| [`tracing.md`](skills/patchright-cli/references/tracing.md) | Trace recording and debugging |
+| [`video-recording.md`](skills/patchright-cli/references/video-recording.md) | Video, codegen, screenshot, PDF |
 
 ---
 

patchright_cli-0.7.0/docs/installation.md

@@ -0,0 +1,146 @@
+# patchright-cli Installation Guide
+
+## Prerequisites
+
+- Python 3.10+
+- Google Chrome installed on the system
+
+## Install
+
+### Step 1: Ensure uv is installed
+
+uv is the recommended Python package manager. Check if it's installed:
+
+```bash
+uv --version
+```
+
+If not installed:
+
+```bash
+# macOS / Linux
+curl -LsSf https://astral.sh/uv/install.sh | sh
+
+# Windows (PowerShell)
+powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
+```
+
+### Step 2: Run patchright-cli
+
+With uvx (recommended — always uses the latest version, no install needed):
+
+```bash
+uvx patchright-cli open https://example.com
+uvx patchright-cli snapshot
+uvx patchright-cli close
+```
+
+> **Note:** If you have Google Chrome installed, patchright-cli will use it directly via `channel="chrome"` for maximum stealth. If Chrome is not found, install the Patchright fallback browser: `uvx patchright install chromium`
+
+### Step 3: Verify
+
+```bash
+uvx patchright-cli --version
+uvx patchright-cli open https://example.com
+uvx patchright-cli eval "document.title"
+uvx patchright-cli close
+```
+
+<details>
+<summary><b>Alternative: pip install</b></summary>
+
+```bash
+pip install patchright-cli
+patchright-cli open https://example.com
+patchright-cli close
+```
+
+</details>
+
+### Troubleshooting
+
+If you see `browser not found` errors:
+
+```bash
+# Check if Chrome is installed
+google-chrome --version    # Linux
+/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome --version  # macOS
+reg query "HKLM\SOFTWARE\Google\Chrome\BLBeacon" /v version   # Windows
+
+# If no Chrome, install the Patchright browser
+uvx patchright install chromium
+```
+
+If you see `patchright-cli: command not found`:
+
+```bash
+# Use uvx instead (no install or PATH needed)
+uvx patchright-cli --help
+```
+
+## Agent Integration
+
+Install the patchright-cli skill so your AI coding agent knows how to use it. Works with Claude Code, Cursor, Gemini CLI, Codex, and [40+ other agents](https://github.com/vercel-labs/skills).
+
+### Recommended: Skills CLI
+
+```bash
+npx skills add AhaiMk01/patchright-cli
+```
+
+This auto-detects your installed agents and installs the skill (including reference docs) to all of them.
+
+### Alternative: patchright-cli built-in
+
+```bash
+pip install patchright-cli
+patchright-cli install --skills
+```
+
+### Alternative: Tell your agent
+
+Just paste this into your agent and it will handle the rest:
+
+> Install patchright-cli skill from https://raw.githubusercontent.com/AhaiMk01/patchright-cli/main/skills/patchright-cli/SKILL.md
+
+### Manual install
+
+Copy the skill file to your agent's skills directory:
+
+```bash
+# Example for 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
+```
+
+Replace `~/.claude` with `~/.gemini`, `~/.codex`, `~/.opencode`, `.cursor`, etc. for other agents.
+
+## Usage
+
+```bash
+# Open an anti-bot-protected site
+uvx patchright-cli open https://protected-site.com
+
+# Take a snapshot to see interactive elements
+uvx patchright-cli snapshot
+
+# Interact with elements using refs from the snapshot
+uvx patchright-cli fill e3 "username"
+uvx patchright-cli fill e4 "password"
+uvx patchright-cli click e5
+
+# Save login state for reuse
+uvx patchright-cli state-save auth.json
+
+# Later, restore the session
+uvx patchright-cli open https://protected-site.com --persistent
+uvx patchright-cli state-load auth.json
+
+# Close when done
+uvx patchright-cli close
+```
+
+## All Commands
+
+Run `patchright-cli --help` for the full command reference.

{patchright_cli-0.5.0 → patchright_cli-0.7.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "patchright-cli"
-version = "0.5.0"
+version = "0.7.0"
 description = "Anti-detect browser automation CLI using Patchright (undetected Playwright fork)"
 license = "Apache-2.0"
 requires-python = ">=3.10"