patchright-cli 0.1.0__tar.gz → 0.2.0__tar.gz

{patchright_cli-0.1.0 → patchright_cli-0.2.0}/.gitignore

@@ -5,3 +5,4 @@ __pycache__/
 *.egg-info/
 dist/
 build/
+docs/reddit-post.md

patchright_cli-0.2.0/CONTRIBUTING.md

@@ -0,0 +1,44 @@
+# Contributing to patchright-cli
+
+Thanks for your interest in contributing! Here's how to get started.
+
+## Getting Started
+
+```bash
+git clone https://github.com/AhaiMk01/patchright-cli.git
+cd patchright-cli
+uv venv && uv pip install -e .
+python -m patchright install chromium
+pre-commit install
+```
+
+## Making Changes
+
+1. Fork the repo and create a branch from `main`
+2. Make your changes
+3. Run `pre-commit run --all-files` to check linting
+4. Test your changes manually with `patchright-cli`
+5. Commit and open a PR
+
+## What to Contribute
+
+- Bug fixes
+- New commands (check playwright-cli for parity gaps)
+- Snapshot accuracy improvements
+- Platform compatibility fixes (Windows/macOS/Linux)
+- Documentation improvements
+- Tests
+
+## Code Style
+
+- Python 3.10+
+- Formatted with [Ruff](https://github.com/astral-sh/ruff) (enforced via pre-commit)
+- Keep the daemon lightweight — avoid heavy dependencies
+
+## Reporting Issues
+
+Open an issue with:
+- What you expected
+- What happened
+- Steps to reproduce
+- OS and Python version

{patchright_cli-0.1.0 → patchright_cli-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: patchright-cli
-Version: 0.1.0
+Version: 0.2.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
@@ -28,59 +28,90 @@ Description-Content-Type: text/markdown
 
 # patchright-cli
 
-<!-- badges (hidden until PyPI publish)
 [![PyPI version](https://img.shields.io/pypi/v/patchright-cli?color=blue&label=PyPI)](https://pypi.org/project/patchright-cli/)
 [![Python](https://img.shields.io/pypi/pyversions/patchright-cli?label=Python)](https://pypi.org/project/patchright-cli/)
-[![License](https://img.shields.io/github/license/AhaiMk01/patchright-cli?color=green)](LICENSE)
 [![Downloads](https://img.shields.io/pypi/dm/patchright-cli?color=orange&label=Downloads)](https://pypi.org/project/patchright-cli/)
--->
+[![License](https://img.shields.io/github/license/AhaiMk01/patchright-cli?color=green)](LICENSE)
+[![CI](https://img.shields.io/github/actions/workflow/status/AhaiMk01/patchright-cli/publish.yml?label=CI)](https://github.com/AhaiMk01/patchright-cli/actions)
+[![GitHub stars](https://img.shields.io/github/stars/AhaiMk01/patchright-cli?style=flat&label=Stars)](https://github.com/AhaiMk01/patchright-cli)
+[![GitHub issues](https://img.shields.io/github/issues/AhaiMk01/patchright-cli?label=Issues)](https://github.com/AhaiMk01/patchright-cli/issues)
+[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
 
 Anti-detect browser automation CLI. Same command interface as [Microsoft's playwright-cli](https://github.com/microsoft/playwright-cli) but using [Patchright](https://github.com/kaliiiiiiiiii/patchright-python) (undetected Playwright fork) to bypass bot detection.
 
-## Why
+[Install](#install) · [Quick Start](#quick-start) · [Commands](#-commands) · [Snapshots](#snapshots) · [Agent Integration](#agent-integration)
 
-Regular Playwright and Chrome DevTools get blocked by Akamai, Cloudflare, and other anti-bot systems. Patchright patches Chromium's detection vectors (`navigator.webdriver`, WebGL fingerprints, etc.) so automated browsers look like real users.
+### Highlights
 
-This CLI wraps Patchright in the same command interface as playwright-cli, so AI agents (Claude Code, etc.) can automate anti-bot-protected sites with the same workflow they'd use for regular Playwright.
+| | Feature |
+|---|---|
+| :shield: | Bypasses Akamai, Cloudflare, and other anti-bot systems |
+| :rocket: | Same command interface as playwright-cli — zero learning curve |
+| :robot: | Built for AI agents (Claude Code, Codex, etc.) with YAML snapshots |
+| :zap: | Daemon architecture — browser stays open between commands |
+| :package: | `pip install` / `uvx` — no Docker, no config files |
+| :lock: | Persistent profiles for maintaining login sessions |
 
-## Install
+---
 
-### For Humans
-
-Just tell your AI agent:
+## 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.
 
-Seriously — let the agent do it. It handles configs better than you.
-
-### For LLM Agents
+<details>
+<summary><b>For LLM Agents</b></summary>
 
 ```bash
 curl -s https://raw.githubusercontent.com/AhaiMk01/patchright-cli/main/docs/installation.md
 ```
 
-### Manual Install
+</details>
+
+> [!IMPORTANT]
+> **Requirements:** Python 3.10+ and Google Chrome
+
+<details>
+<summary><b>Manual Install</b></summary>
 
 ```bash
-# With pip
-pip install patchright-cli
+# 1. Install the package
+pip install patchright-cli        # or: uv tool install patchright-cli
+
+# 2. Install the Patchright browser (fallback if Chrome is not found)
+python -m patchright install chromium
+
+# 3. Verify
+patchright-cli open https://example.com
+patchright-cli close
+```
 
-# With uv (recommended)
-uv tool install patchright-cli
+Or run without installing (like npx):
 
-# Run without installing (like npx)
+```bash
 uvx patchright-cli open https://example.com
 ```
 
-### From Source
+**From source:**
 
 ```bash
 git clone https://github.com/AhaiMk01/patchright-cli.git
 cd patchright-cli
 uv venv && uv pip install -e .
+python -m patchright install chromium
 ```
 
+</details>
+
+---
+
 ## Quick Start
 
 ```bash
@@ -102,27 +133,39 @@ patchright-cli screenshot
 patchright-cli close
 ```
 
+---
+
 ## Architecture
 
 ```mermaid
 graph LR
-    A[CLI Client<br/>cli.py] -->|TCP/JSON<br/>localhost:9321| B[Daemon<br/>daemon.py]
-    B -->|Patchright<br/>CDP| C[Chrome<br/>stealth]
+    A[CLI] -->|TCP:9321| B[Daemon]
+    B -->|Patchright| C[Chrome]
 ```
 
-- **Daemon** (`daemon.py`): Long-running Python process managing browser sessions via Patchright. Listens on `localhost:9321`. Auto-starts on first `open` command.
-- **CLI** (`cli.py`): Thin client. Parses args, sends JSON to daemon, prints result. Each invocation connects and disconnects — the browser stays open between commands.
-- **Snapshot** (`snapshot.py`): Walks the DOM with `TreeWalker` in document order, assigns `data-patchright-ref` attributes, outputs a flat YAML list of interactive elements.
+| 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
+<details>
+<summary><h2>📖 Commands</h2></summary>
 
 ### Core
 ```bash
 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
@@ -133,7 +176,9 @@ 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 screenshot              # Full page screenshot
+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
@@ -189,9 +234,11 @@ patchright-cli state-load <file>       # Restore saved state
 # 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
 
@@ -214,6 +261,9 @@ patchright-cli sessionstorage-clear
 ```bash
 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
@@ -242,8 +292,13 @@ 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
 ```
 
+</details>
+
+---
+
 ## Snapshots
 
 After each state-changing command, the CLI outputs page info and a YAML snapshot:
@@ -256,7 +311,7 @@ After each state-changing command, the CLI outputs page info and a YAML snapshot
 [Snapshot](.patchright-cli/page-1774376207818.yml)
 ```
 
-The snapshot lists interactive elements with refs:
+The snapshot lists interactive elements with refs you can use in commands:
 
 ```yaml
 - ref: e1
@@ -269,32 +324,44 @@ The snapshot lists interactive elements with refs:
   url: "https://iana.org/domains/example"
 ```
 
-Use refs in commands: `patchright-cli click e2`, `patchright-cli fill e5 "text"`.
+> [!NOTE]
+> Use refs directly: `patchright-cli click e2`, `patchright-cli fill e5 "text"`
+
+---
 
 ## Anti-Detect Features
 
-- 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)
+> [!CAUTION]
+> This tool is for **authorized testing, security research, and legitimate automation** only.
 
-## Claude Code Integration
+- :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)
 
-Add the skill to your project:
+---
 
-```bash
-cp -r skills/patchright-cli ~/.claude/skills/
-```
+## Agent Integration
 
-Then use in Claude Code:
-```
-patchright-cli open https://protected-site.com
-patchright-cli snapshot
-patchright-cli fill e3 "username"
-patchright-cli fill e4 "password"
-patchright-cli click e5
-```
+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
 
@@ -306,6 +373,34 @@ patchright-cli click e5
  </picture>
 </a>
 
+---
+
+<details>
+<summary><h2>Differences from playwright-cli</h2></summary>
+
+patchright-cli aims for full command parity with [Microsoft's playwright-cli](https://github.com/microsoft/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.
+
+</details>
+
+---
+
+## 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](https://github.com/microsoft/playwright-cli)