patchright-cli 0.9.0__tar.gz → 0.9.1__tar.gz

{patchright_cli-0.9.0 → patchright_cli-0.9.1}/.claude-plugin/marketplace.json

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

{patchright_cli-0.9.0 → patchright_cli-0.9.1}/.github/workflows/ci.yml

@@ -10,8 +10,8 @@ jobs:
   lint:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
-      - uses: astral-sh/setup-uv@v6
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v7
         with:
           version: ">=0.7,<0.8"
           python-version: "3.12"
@@ -28,8 +28,8 @@ jobs:
             python-version: "3.12"
     runs-on: ${{ matrix.os }}
     steps:
-      - uses: actions/checkout@v4
-      - uses: astral-sh/setup-uv@v6
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v7
         with:
           version: ">=0.7,<0.8"
           python-version: ${{ matrix.python-version }}
@@ -39,7 +39,7 @@ jobs:
   docker:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v7
       - run: docker build -t patchright-cli:ci .
       - run: docker run --rm patchright-cli:ci --help
       - name: Browser session inside the container
@@ -78,6 +78,16 @@ jobs:
           grep -q "refusing to start \`mcp --http\`" unprotected.log
       - name: compose.yml works without a token
         run: docker compose config -q
+      - uses: astral-sh/setup-uv@v7
+        with:
+          version: ">=0.7,<0.8"
+          python-version: "3.12"
+      - name: Image test suite
+        run: |
+          uv venv && uv pip install -e ".[dev]"
+          uv run pytest tests/test_docker.py -v
+        env:
+          PATCHRIGHT_CLI_DOCKER_IMAGE: patchright-cli:ci
       - if: failure()
         run: |
           docker logs cli || true

{patchright_cli-0.9.0 → patchright_cli-0.9.1}/.github/workflows/publish-docker.yml

@@ -24,7 +24,7 @@ jobs:
 
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v6
+        uses: actions/checkout@v7
 
       - name: Set up Docker Buildx
         uses: docker/setup-buildx-action@v4

{patchright_cli-0.9.0 → patchright_cli-0.9.1}/.github/workflows/publish.yml

@@ -15,10 +15,10 @@ jobs:
   build:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v7
 
       - name: Install uv
-        uses: astral-sh/setup-uv@v5
+        uses: astral-sh/setup-uv@v7
 
       - name: Set up Python
         run: uv python install 3.12
@@ -27,7 +27,7 @@ jobs:
         run: uv build
 
       - name: Upload artifacts
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@v7
         with:
           name: dist
           path: dist/
@@ -40,13 +40,13 @@ jobs:
       id-token: write
     steps:
       - name: Download artifacts
-        uses: actions/download-artifact@v4
+        uses: actions/download-artifact@v8
         with:
           name: dist
           path: dist/
 
       - name: Install uv
-        uses: astral-sh/setup-uv@v5
+        uses: astral-sh/setup-uv@v7
 
       - name: Publish to PyPI
         run: uv publish
@@ -59,16 +59,16 @@ jobs:
     permissions:
       contents: write
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v7
 
       - name: Download artifacts
-        uses: actions/download-artifact@v4
+        uses: actions/download-artifact@v8
         with:
           name: dist
           path: dist/
 
       - name: Create GitHub Release
-        uses: softprops/action-gh-release@v2
+        uses: softprops/action-gh-release@v3
         with:
           files: dist/*
           generate_release_notes: true

{patchright_cli-0.9.0 → patchright_cli-0.9.1}/Dockerfile

@@ -1,6 +1,6 @@
 # Base images are pinned by multi-arch index digest; Dependabot (.github/dependabot.yml) bumps them.
 # uv is a named stage because Dependabot only reads image references on FROM lines.
-FROM ghcr.io/astral-sh/uv:latest@sha256:32a7bb39b496babbd997b0a39a4d66c126bdaf5661b302bf6f06abda8deca6ff AS uv
+FROM ghcr.io/astral-sh/uv:latest@sha256:af22a52f5eafef3d78e551599d405c02df61919d18028f0cea8eda93bc9986d0 AS uv
 
 FROM python:3.12-slim@sha256:5b8b1421ccb6a525860a77863c049eab5847076cda34e030c75a80c58faf3f3c
 

{patchright_cli-0.9.0 → patchright_cli-0.9.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: patchright-cli
-Version: 0.9.0
+Version: 0.9.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
@@ -211,6 +211,16 @@ patchright-cli screenshot
 patchright-cli close
 ```
 
+Quote URLs that contain `&`; unquoted, bash, PowerShell and cmd.exe all split the command there. On Windows two cases need more than quotes: in cmd.exe without quotes, escape it as `^&` (inside quotes the `^` stays in the URL, so use one or the other), and when PowerShell runs a `.cmd`/`.bat` wrapper such as the repo's `patchright-cli.cmd`, PowerShell drops the quotes and cmd.exe splits at `&`, so pass the rest verbatim with `--%`:
+
+```
+patchright-cli goto "https://example.com/?a=1&b=2"           # any shell, patchright-cli.exe
+patchright-cli goto https://example.com/?a=1^&b=2            # cmd.exe, unquoted
+.\patchright-cli.cmd --% goto "https://example.com/?a=1&b=2" # PowerShell, .cmd wrapper
+```
+
+Don't use `--%` with the installed `patchright-cli.exe`: in PowerShell 7 the quotes after it reach the CLI and end up in the URL.
+
 ---
 
 ## Architecture
@@ -236,6 +246,12 @@ The daemon only listens on `127.0.0.1`, but any local process can reach that por
 - Run the CLI as the same user, with the same home directory, as the daemon. In Docker the MCP server and daemon share a user and `HOME`, so this holds.
 - An older CLI talking to a newer daemon gets an error saying the daemon requires an auth token: upgrade, or stop the daemon (`patchright-cli kill-all` from the newer install, or end the process). A newer CLI talking to an older daemon finds no token file and sends none, which the older daemon accepts.
 
+### Daemon client protocol
+
+Third-party clients can use the daemon TCP interface directly. The
+[client protocol reference](docs/daemon-protocol.md) defines discovery,
+authentication, message framing, replies, and compatibility rules.
+
 ---
 
 <details>
@@ -322,6 +338,22 @@ patchright-cli upload ./file.pdf e5    # Upload to specific input
 patchright-cli resize 1920 1080        # Resize viewport
 ```
 
+### Emulation
+```bash
+patchright-cli set-color-scheme dark   # dark | light | no-preference
+patchright-cli clear-color-scheme
+patchright-cli set-reduced-motion reduce  # reduce | no-preference
+patchright-cli clear-reduced-motion
+patchright-cli set-forced-colors active   # active | none
+patchright-cli clear-forced-colors
+patchright-cli set-contrast more       # more | no-preference
+patchright-cli clear-contrast
+patchright-cli set-media print         # screen | print
+patchright-cli clear-media
+```
+
+Each setting holds for the whole session, including tabs and popups opened later; `clear-*` drops just that one, back to the browser default. A popup gets the setting just after it opens, so a script that reads media queries the instant the popup is created may still see the default.
+
 ### Tabs
 ```bash
 patchright-cli tab-list

{patchright_cli-0.9.0 → patchright_cli-0.9.1}/README.md

@@ -174,6 +174,16 @@ patchright-cli screenshot
 patchright-cli close
 ```
 
+Quote URLs that contain `&`; unquoted, bash, PowerShell and cmd.exe all split the command there. On Windows two cases need more than quotes: in cmd.exe without quotes, escape it as `^&` (inside quotes the `^` stays in the URL, so use one or the other), and when PowerShell runs a `.cmd`/`.bat` wrapper such as the repo's `patchright-cli.cmd`, PowerShell drops the quotes and cmd.exe splits at `&`, so pass the rest verbatim with `--%`:
+
+```
+patchright-cli goto "https://example.com/?a=1&b=2"           # any shell, patchright-cli.exe
+patchright-cli goto https://example.com/?a=1^&b=2            # cmd.exe, unquoted
+.\patchright-cli.cmd --% goto "https://example.com/?a=1&b=2" # PowerShell, .cmd wrapper
+```
+
+Don't use `--%` with the installed `patchright-cli.exe`: in PowerShell 7 the quotes after it reach the CLI and end up in the URL.
+
 ---
 
 ## Architecture
@@ -199,6 +209,12 @@ The daemon only listens on `127.0.0.1`, but any local process can reach that por
 - Run the CLI as the same user, with the same home directory, as the daemon. In Docker the MCP server and daemon share a user and `HOME`, so this holds.
 - An older CLI talking to a newer daemon gets an error saying the daemon requires an auth token: upgrade, or stop the daemon (`patchright-cli kill-all` from the newer install, or end the process). A newer CLI talking to an older daemon finds no token file and sends none, which the older daemon accepts.
 
+### Daemon client protocol
+
+Third-party clients can use the daemon TCP interface directly. The
+[client protocol reference](docs/daemon-protocol.md) defines discovery,
+authentication, message framing, replies, and compatibility rules.
+
 ---
 
 <details>
@@ -285,6 +301,22 @@ patchright-cli upload ./file.pdf e5    # Upload to specific input
 patchright-cli resize 1920 1080        # Resize viewport
 ```
 
+### Emulation
+```bash
+patchright-cli set-color-scheme dark   # dark | light | no-preference
+patchright-cli clear-color-scheme
+patchright-cli set-reduced-motion reduce  # reduce | no-preference
+patchright-cli clear-reduced-motion
+patchright-cli set-forced-colors active   # active | none
+patchright-cli clear-forced-colors
+patchright-cli set-contrast more       # more | no-preference
+patchright-cli clear-contrast
+patchright-cli set-media print         # screen | print
+patchright-cli clear-media
+```
+
+Each setting holds for the whole session, including tabs and popups opened later; `clear-*` drops just that one, back to the browser default. A popup gets the setting just after it opens, so a script that reads media queries the instant the popup is created may still see the default.
+
 ### Tabs
 ```bash
 patchright-cli tab-list

patchright_cli-0.9.1/docs/daemon-protocol.md

@@ -0,0 +1,102 @@
+# Daemon client protocol
+
+The TCP interface is a public interface for third-party clients. The current
+protocol version is **1**, defined by `PROTOCOL_VERSION` in `daemon.py`.
+
+## Discovery
+
+`patchright-cli daemon-info --json` prints one JSON object and exits without
+starting a daemon or browser, connecting to the daemon, or reading the token.
+For example, on a Unix installation with home directory `/home/alice`:
+
+```json
+{"version": "0.9.0", "protocol": 1, "port": 9321, "token_path": "/home/alice/.patchright-cli/daemon-9321.token"}
+```
+
+`version` is the installed package version. `protocol` describes that installed
+version's wire contract, not a handshake with a running daemon. After upgrading,
+restart any older daemon before using the new contract.
+
+`--port=N` and `--port N`, before or after the command, select the port and its
+token path. The default port is 9321. There is currently no port or token-path
+environment override. `token_path` is absolute and follows the current user's
+home directory. The file need not exist for discovery to succeed. Discovery
+reports configuration, not daemon readiness, and never prints the token value.
+Older installations without this command do not advertise a protocol version.
+
+## Transport and authentication
+
+Connect to `127.0.0.1` on the discovered port. Each connection carries one
+request and one reply, after which the daemon closes the connection. Both
+messages use the same framing:
+
+1. Four bytes containing the unsigned payload byte length in big-endian order
+   (`struct.pack("!I", length)`).
+2. That many bytes of UTF-8 encoded JSON, with an object as the top-level value.
+
+Reads must loop until the entire header and payload arrive. There is no newline
+or other delimiter. An incomplete request can close without a reply.
+
+The daemon reads a request before checking its token, so it bounds that read:
+
+- The whole request must arrive within 30 seconds of connecting, or the daemon
+  closes the connection without a reply. Commands themselves and replies have
+  no time limit.
+- A request whose header announces more than 64 MiB (67,108,864 bytes) gets a
+  `success: false` reply whose `output` starts with `Daemon error: request of`,
+  sent without reading the body, and the connection closes.
+
+The daemon writes a new secret to `~/.patchright-cli/daemon-<port>.token` when
+it starts and removes its token on clean shutdown. Read the discovered
+`token_path` as UTF-8 text and strip surrounding whitespace before each request.
+The token may change when the daemon restarts. Send it in the request's `token`
+field. Keep the value private. The client must run as a user who can read this
+file. A missing file can indicate that the daemon has not started or has stopped.
+
+## Request fields
+
+| Field | JSON type | Meaning |
+| --- | --- | --- |
+| `command` | string | Command name, such as `list`, `open`, or `snapshot`. |
+| `args` | array of strings | Positional command arguments. Defaults to `[]` if omitted. |
+| `options` | object | Command options using CLI option names without leading `--`. Defaults to `{}`. Values are the JSON the CLI sends: a string for `--name=value`, `true` for a bare flag, and an object for a few structured options (for example `viewport` is `{"width": 1280, "height": 720}`). |
+| `cwd` | string or null | Absolute caller working directory for relative paths and output files. Omitted or null uses the daemon's working directory. |
+| `token` | string | Current authentication token read from `token_path`. Required. |
+
+`options.session` and `options.tab` select a session and named tab; both default
+to `default`. Command-specific arguments and options follow CLI help.
+
+## Reply fields
+
+Every reply carries an explicit boolean `success` and a string `output`, on
+both success and failure. `success: false` indicates authentication, command,
+or daemon errors. `output` contains the result or a human-readable error.
+Additional fields, such as `snapshot_path`, are command-specific. Clients must
+ignore unknown fields. No structured error codes are currently provided.
+
+Clients can detect these states in failed replies by matching these output
+fragments. Surrounding context and recovery advice can vary. The fragments in
+this table are part of the protocol:
+
+| Output fragment | State |
+| --- | --- |
+| `Session '<name>' is not open` | The requested session is absent. |
+| `Tab '<name>' is not open` | The requested named tab is absent from the session. |
+| `requires an auth token` | The request omitted `token`. |
+| `rejected the auth token` | The supplied token is invalid or stale. Read the token file fresh before retrying. |
+| `Daemon error: request of` | The request exceeded the 64 MiB limit. |
+
+Best effort, not covered by the compatibility rules below: a command on a page,
+context or browser that has closed usually fails with Playwright's own message
+containing `has been closed`. That text comes from Playwright and can change
+with its version without a protocol increment.
+
+## Compatibility
+
+`protocol` is independent of the package version. Any incompatible change to
+framing, request limits, request fields (`command`, `args`, `options`, `cwd`,
+`token`), reply fields (`success`, `output`), authentication, or the
+state-detection fragments in the table above requires a protocol increment.
+Raising a request limit is not incompatible. Optional additive fields and new
+commands do not require an increment. Clients can reject unsupported protocol
+versions before sending requests.

{patchright_cli-0.9.0 → patchright_cli-0.9.1}/pyproject.toml

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

{patchright_cli-0.9.0 → patchright_cli-0.9.1}/skills/patchright-cli/SKILL.md

@@ -59,8 +59,21 @@ patchright-cli goto "https://example.com/search?q=cats&page=2"
 ```
 
 The same applies to `#` (a bash comment), spaces, and `%` (expanded by
-cmd.exe), and to any argument holding shell metacharacters. Quoting always
-works; leave it on.
+cmd.exe), and to any argument holding shell metacharacters. Quoting works for
+the installed `patchright-cli.exe` in bash, PowerShell and cmd.exe; leave it on.
+
+On Windows, two cases need more than quotes:
+
+```
+# cmd.exe without quotes: escape the & as ^&. Inside quotes ^ is kept
+# literally, so use one or the other, never both.
+patchright-cli goto https://example.com/search?q=cats^&page=2
+
+# PowerShell calling a .cmd/.bat wrapper (such as the repo's patchright-cli.cmd):
+# PowerShell drops the quotes and cmd.exe splits at &. Pass the rest verbatim
+# with --%. Don't use --% with patchright-cli.exe: in PowerShell 7 the quotes end up in the URL.
+.\patchright-cli.cmd --% goto "https://example.com/search?q=cats&page=2"
+```
 
 ## Global options
 
@@ -320,6 +333,25 @@ show                          # Live dashboard
 show --annotate               # Ask a human to mark up the page and wait for it
 ```
 
+### Emulation
+
+Each setting holds for the whole session: every open tab, and tabs and popups
+opened later (a popup gets it just after it opens). `clear-*` drops just that
+one, back to the browser default.
+
+```bash
+set-color-scheme dark         # dark | light | no-preference
+clear-color-scheme
+set-reduced-motion reduce     # reduce | no-preference
+clear-reduced-motion
+set-forced-colors active      # active | none
+clear-forced-colors
+set-contrast more             # more | no-preference
+clear-contrast
+set-media print               # screen | print
+clear-media
+```
+
 ### Storage
 
 ```bash

{patchright_cli-0.9.0 → patchright_cli-0.9.1}/src/patchright_cli/__init__.py

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

{patchright_cli-0.9.0 → patchright_cli-0.9.1}/src/patchright_cli/cli.py

@@ -17,7 +17,7 @@ from pathlib import Path
 import click
 
 from patchright_cli import __version__
-from patchright_cli.daemon import DEFAULT_PORT, ensure_daemon_running, read_daemon_token
+from patchright_cli.daemon import DEFAULT_PORT, PROTOCOL_VERSION, ensure_daemon_running, read_daemon_token, token_path
 
 
 def _soften_output_encoding(*streams) -> None:
@@ -497,6 +497,17 @@ COMMANDS_HELP = {
     # Upload / Resize
     "upload": "upload <file> [ref]   Upload file to input",
     "resize": "resize <w> <h>        Resize viewport",
+    # Emulation
+    "set-color-scheme": "set-color-scheme <dark|light|no-preference>  Emulate prefers-color-scheme",
+    "clear-color-scheme": "clear-color-scheme   Stop emulating prefers-color-scheme",
+    "set-reduced-motion": "set-reduced-motion <reduce|no-preference>  Emulate prefers-reduced-motion",
+    "clear-reduced-motion": "clear-reduced-motion Stop emulating prefers-reduced-motion",
+    "set-forced-colors": "set-forced-colors <active|none>  Emulate forced-colors",
+    "clear-forced-colors": "clear-forced-colors  Stop emulating forced-colors",
+    "set-contrast": "set-contrast <more|no-preference>  Emulate prefers-contrast",
+    "clear-contrast": "clear-contrast       Stop emulating prefers-contrast",
+    "set-media": "set-media <screen|print>  Emulate CSS media type",
+    "clear-media": "clear-media          Stop emulating the CSS media type",
     # State
     "state-save": "state-save [file]    Save cookies+storage to JSON",
     "state-load": "state-load <file>    Load saved state",
@@ -547,6 +558,7 @@ COMMANDS_HELP = {
     # Setup
     "install": "install --skills      Install skill files for AI agents",
     "mcp": "mcp [--http] [--host=HOST] [--port=N]  Start MCP server (stdio by default)",
+    "daemon-info": "daemon-info --json                 Show daemon client protocol and token path without starting it",
 }
 
 ALL_COMMANDS = list(COMMANDS_HELP.keys())
@@ -619,6 +631,21 @@ def _print_help():
         ("Tabs", ["tab-list", "tab-new", "tab-close", "tab-select"]),
         ("Dialog", ["dialog-accept", "dialog-dismiss"]),
         ("Upload/Resize", ["upload", "resize"]),
+        (
+            "Emulation",
+            [
+                "set-color-scheme",
+                "clear-color-scheme",
+                "set-reduced-motion",
+                "clear-reduced-motion",
+                "set-forced-colors",
+                "clear-forced-colors",
+                "set-contrast",
+                "clear-contrast",
+                "set-media",
+                "clear-media",
+            ],
+        ),
         ("State", ["state-save", "state-load"]),
         (
             "Storage",
@@ -653,7 +680,7 @@ def _print_help():
         ("Profiles", ["profile-list", "profile-delete"]),
         ("Dashboard", ["show"]),
         ("Codegen", ["codegen", "codegen-stop"]),
-        ("Setup", ["install", "mcp"]),
+        ("Setup", ["install", "mcp", "daemon-info"]),
     ]
     for cat_name, cmds in categories:
         click.echo(f"\n  {cat_name}:")
@@ -823,6 +850,22 @@ def main():
         _print_help()
         sys.exit(1)
 
+    if command == "daemon-info":
+        if not as_json or args or extra_opts:
+            click.echo("Usage: patchright-cli daemon-info --json [--port=N]", err=True)
+            sys.exit(1)
+        click.echo(
+            json.dumps(
+                {
+                    "version": __version__,
+                    "protocol": PROTOCOL_VERSION,
+                    "port": port,
+                    "token_path": str(token_path(port).resolve()),
+                }
+            )
+        )
+        return
+
     if command == "install":
         _handle_install(args + [k if v is True else f"{k}={v}" for k, v in extra_opts.items()])
         sys.exit(0)