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

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

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

patchright_cli-0.3.0/CLAUDE.md

@@ -0,0 +1,55 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+patchright-cli is an anti-detect browser automation CLI built on [Patchright](https://github.com/kaliiiiiiiiii/patchright-python) (undetected Playwright fork). It provides the same command interface as Microsoft's playwright-cli but bypasses bot detection (Akamai, Cloudflare, etc.).
+
+## Development Setup
+
+```bash
+uv venv && uv pip install -e .
+python -m patchright install chromium
+pre-commit install
+```
+
+## Commands
+
+```bash
+# Lint (pre-commit runs ruff --fix + ruff-format)
+pre-commit run --all-files
+
+# Run the CLI directly
+python -m patchright_cli <command> [args...]
+# or after install:
+patchright-cli <command> [args...]
+```
+
+There are no automated tests yet — changes are tested manually via the CLI.
+
+## Architecture
+
+Three-component client-daemon-browser design:
+
+```
+CLI (cli.py) --TCP:9321--> Daemon (daemon.py) --Patchright--> Chrome
+```
+
+- **CLI (`src/patchright_cli/cli.py`)**: Stateless thin client. Parses argv manually (not click subcommands), builds a JSON `{command, args, options, cwd}` message, sends it over a length-prefixed TCP socket to the daemon, prints the response, and exits. All commands are defined in the `COMMANDS_HELP` dict and `ALL_COMMANDS` list.
+
+- **Daemon (`src/patchright_cli/daemon.py`)**: Long-running async process managing browser sessions. Auto-spawned on `open` via `ensure_daemon_running()` which launches a subprocess. Uses `DaemonState` → multiple `Session` objects, each owning a Patchright persistent browser context. Command dispatch is a large `handle_command()` function with if/elif branches. Console capture uses CDP sessions (not Playwright's `page.on('console')`) because Patchright suppresses it.
+
+- **Snapshot (`src/patchright_cli/snapshot.py`)**: Two-pass DOM scanner injected as JavaScript: Pass 1 uses TreeWalker to assign `data-patchright-ref` attributes (`e1`, `e2`, ...) in document order; Pass 2 builds a nested tree. Python side converts to flat YAML. Snapshots are saved to `.patchright-cli/` in the caller's cwd.
+
+## Key Design Decisions
+
+- 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>`
+- 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)
+- `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.3.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.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: patchright-cli
-Version: 0.1.0
+Version: 0.3.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,87 @@ 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
-
-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.
+[Install](#install) · [Quick Start](#quick-start) · [Commands](#-commands) · [Snapshots](#snapshots) · [Agent Integration](#agent-integration)
 
-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.
+### Highlights
 
-## Install
+| | 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 |
 
-### 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
 
 ```bash
-# With pip
-pip install patchright-cli
+# Recommended — always runs latest version, no install needed
+uvx patchright-cli open https://example.com
+```
 
-# With uv (recommended)
-uv tool install patchright-cli
+<details>
+<summary><b>Other install methods</b></summary>
 
-# Run without installing (like npx)
-uvx patchright-cli open https://example.com
+```bash
+# Via pip
+pip install patchright-cli
+patchright-cli open https://example.com
+patchright-cli close
+
+# Update
+pip install --upgrade patchright-cli
 ```
 
-### 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,38 +130,57 @@ 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 fill <ref> <value> --submit  # Fill and press Enter
 patchright-cli type <text>             # Type via keyboard
+patchright-cli type <text> --submit    # Type and press Enter
 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 <ref>          # Snapshot element subtree
 patchright-cli snapshot --filename=f   # Save to custom path
 patchright-cli eval <expr>             # Run JavaScript
-patchright-cli screenshot              # Full page screenshot
+patchright-cli eval --file=script.js   # Run JS from file
+patchright-cli run-code <code>         # Run JS with return value
+patchright-cli run-code --file=f.js    # Run JS from file
+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 +236,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,23 +263,38 @@ 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
 ```
 
-### Tracing / PDF
+### Tracing / Video / PDF
 ```bash
 patchright-cli tracing-start
 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 pdf --filename=page.pdf
 ```
 
+### Network
+```bash
+patchright-cli network                 # Network request log
+patchright-cli network --static        # Include static resources
+patchright-cli network --clear         # Clear log after printing
+patchright-cli network-state-set offline  # Simulate offline mode
+patchright-cli network-state-set online   # Restore connectivity
+```
+
 ### DevTools
 ```bash
 patchright-cli console                 # All console messages
 patchright-cli console warning         # Filter by level
-patchright-cli network                 # Network request log
+patchright-cli console --clear         # Clear after printing
 ```
 
 ### Sessions
@@ -242,8 +306,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 +325,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 +338,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 +387,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)