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

{patchright_cli-0.2.0 → patchright_cli-0.3.1}/.github/workflows/publish.yml

@@ -8,6 +8,9 @@ on:
 permissions:
   contents: write
 
+env:
+  FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true
+
 jobs:
   build:
     runs-on: ubuntu-latest
@@ -15,7 +18,7 @@ jobs:
       - uses: actions/checkout@v4
 
       - name: Install uv
-        uses: astral-sh/setup-uv@v4
+        uses: astral-sh/setup-uv@v5
 
       - name: Set up Python
         run: uv python install 3.12
@@ -43,7 +46,7 @@ jobs:
           path: dist/
 
       - name: Install uv
-        uses: astral-sh/setup-uv@v4
+        uses: astral-sh/setup-uv@v5
 
       - name: Publish to PyPI
         run: uv publish

patchright_cli-0.3.1/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.2.0 → patchright_cli-0.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: patchright-cli
-Version: 0.2.0
+Version: 0.3.1
 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
@@ -78,25 +78,22 @@ curl -s https://raw.githubusercontent.com/AhaiMk01/patchright-cli/main/docs/inst
 > [!IMPORTANT]
 > **Requirements:** Python 3.10+ and Google Chrome
 
-<details>
-<summary><b>Manual Install</b></summary>
-
 ```bash
-# 1. Install the package
-pip install patchright-cli        # or: uv tool install patchright-cli
+# Recommended — always runs latest version, no install needed
+uvx patchright-cli open https://example.com
+```
 
-# 2. Install the Patchright browser (fallback if Chrome is not found)
-python -m patchright install chromium
+<details>
+<summary><b>Other install methods</b></summary>
 
-# 3. Verify
+```bash
+# Via pip
+pip install patchright-cli
 patchright-cli open https://example.com
 patchright-cli close
-```
 
-Or run without installing (like npx):
-
-```bash
-uvx patchright-cli open https://example.com
+# Update
+pip install --upgrade patchright-cli
 ```
 
 **From source:**
@@ -167,16 +164,21 @@ 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 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
@@ -269,18 +271,30 @@ 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

{patchright_cli-0.2.0 → patchright_cli-0.3.1}/README.md

@@ -50,25 +50,22 @@ curl -s https://raw.githubusercontent.com/AhaiMk01/patchright-cli/main/docs/inst
 > [!IMPORTANT]
 > **Requirements:** Python 3.10+ and Google Chrome
 
-<details>
-<summary><b>Manual Install</b></summary>
-
 ```bash
-# 1. Install the package
-pip install patchright-cli        # or: uv tool install patchright-cli
+# Recommended — always runs latest version, no install needed
+uvx patchright-cli open https://example.com
+```
 
-# 2. Install the Patchright browser (fallback if Chrome is not found)
-python -m patchright install chromium
+<details>
+<summary><b>Other install methods</b></summary>
 
-# 3. Verify
+```bash
+# Via pip
+pip install patchright-cli
 patchright-cli open https://example.com
 patchright-cli close
-```
 
-Or run without installing (like npx):
-
-```bash
-uvx patchright-cli open https://example.com
+# Update
+pip install --upgrade patchright-cli
 ```
 
 **From source:**
@@ -139,16 +136,21 @@ 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 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
@@ -241,18 +243,30 @@ 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

{patchright_cli-0.2.0 → patchright_cli-0.3.1}/docs/installation.md

@@ -7,50 +7,56 @@
 
 ## Install
 
-### Step 1: Install the package
+### Step 1: Ensure uv is installed
 
-```bash
-pip install patchright-cli
-```
-
-Or with uv (recommended):
+uv is the recommended Python package manager. Check if it's installed:
 
 ```bash
-uv tool install patchright-cli
+uv --version
 ```
 
-### Step 2: Install the Patchright browser
-
-Patchright needs to download its patched Chromium binary on first use:
+If not installed:
 
 ```bash
 # macOS / Linux
-python -m patchright install chromium
+curl -LsSf https://astral.sh/uv/install.sh | sh
 
 # Windows (PowerShell)
-python -m patchright install chromium
+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):
 
-# Or if using uv
-uv run python -m patchright install chromium
+```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. The Chromium install above is a fallback.
+> **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
-patchright-cli --version
-patchright-cli open https://example.com
-patchright-cli eval "document.title"
-patchright-cli close
+uvx patchright-cli --version
+uvx patchright-cli open https://example.com
+uvx patchright-cli eval "document.title"
+uvx patchright-cli close
 ```
 
-### Quick one-liner (no install)
+<details>
+<summary><b>Alternative: pip install</b></summary>
 
 ```bash
-uvx patchright-cli open https://example.com
+pip install patchright-cli
+patchright-cli open https://example.com
+patchright-cli close
 ```
 
+</details>
+
 ### Troubleshooting
 
 If you see `browser not found` errors:
@@ -62,16 +68,13 @@ google-chrome --version    # Linux
 reg query "HKLM\SOFTWARE\Google\Chrome\BLBeacon" /v version   # Windows
 
 # If no Chrome, install the Patchright browser
-python -m patchright install chromium
+uvx patchright install chromium
 ```
 
 If you see `patchright-cli: command not found`:
 
 ```bash
-# Ensure pip scripts directory is in PATH
-python -m patchright_cli --help
-
-# Or use uvx (no PATH needed)
+# Use uvx instead (no install or PATH needed)
 uvx patchright-cli --help
 ```
 
@@ -148,25 +151,25 @@ curl -sL https://raw.githubusercontent.com/AhaiMk01/patchright-cli/main/skills/p
 
 ```bash
 # Open an anti-bot-protected site
-patchright-cli open https://protected-site.com
+uvx patchright-cli open https://protected-site.com
 
 # Take a snapshot to see interactive elements
-patchright-cli snapshot
+uvx patchright-cli snapshot
 
 # Interact with elements using refs from the snapshot
-patchright-cli fill e3 "username"
-patchright-cli fill e4 "password"
-patchright-cli click e5
+uvx patchright-cli fill e3 "username"
+uvx patchright-cli fill e4 "password"
+uvx patchright-cli click e5
 
 # Save login state for reuse
-patchright-cli state-save auth.json
+uvx patchright-cli state-save auth.json
 
 # Later, restore the session
-patchright-cli open https://protected-site.com --persistent
-patchright-cli state-load auth.json
+uvx patchright-cli open https://protected-site.com --persistent
+uvx patchright-cli state-load auth.json
 
 # Close when done
-patchright-cli close
+uvx patchright-cli close
 ```
 
 ## All Commands

{patchright_cli-0.2.0 → patchright_cli-0.3.1}/pyproject.toml

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