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

{patchright_cli-0.9.0 → patchright_cli-0.10.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.9.0"
+    "version": "0.10.0"
   },
   "plugins": [
     {

{patchright_cli-0.9.0 → patchright_cli-0.10.0}/.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.10.0}/.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.10.0}/.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.10.0}/CLAUDE.md

@@ -4,7 +4,7 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 ## 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.).
+patchright-cli is an anti-detect browser automation CLI built on [Patchright](https://github.com/kaliiiiiiiiii/patchright-python) (undetected Playwright fork). Its commands follow Microsoft's playwright-cli, but it bypasses bot detection (Akamai, Cloudflare, etc.) and is not a drop-in replacement: playwright-cli features Patchright cannot support (other browsers, extensions) are left out, and unknown flags are rejected with exit 2 rather than ignored.
 
 ## Development Setup
 
@@ -37,6 +37,9 @@ pytest tests/test_e2e.py -v
 
 # Lint
 pre-commit run --all-files
+
+# SKILL.md command block in sync with COMMAND_SPECS (rewrite without --check)
+python scripts/gen_skill.py --check
 ```
 
 ## Architecture
@@ -47,7 +50,7 @@ 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.
+- **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 `COMMAND_SPECS` dict (usage, summary, flags, examples; `COMMANDS_HELP` and `ALL_COMMANDS` derive from it) and grouped for the manual in `COMMAND_CATEGORIES`. With no arguments it prints the home view (`_print_home`): live daemon state from an already-running daemon only, never starting one. `--toon` renders a reply's `data` field with `toon.py`.
 
 - **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 uses `@register()` decorated handlers in `COMMAND_HANDLERS` dict, dispatched by `handle_command()`. Console capture uses CDP sessions (not Playwright's `page.on('console')`) because Patchright suppresses it.
 
@@ -59,7 +62,7 @@ CLI (cli.py) --TCP:9321--> Daemon (daemon.py) --Patchright--> Chrome
 - Headed by default (headless is more detectable)
 - 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; every message carries a `token` field read from `~/.patchright-cli/daemon-<port>.token` (written 0600 by the daemon before it listens), and the daemon rejects messages without the right one
-- CLI parses argv manually in `main()` — click is only used for `click.echo()`, not subcommands. New commands need a `COMMANDS_HELP` entry and a `@register("<name>")` handler in daemon.py; only session and lifecycle commands (open, attach, close, kill-all, ...) live in `handle_command()` itself
+- CLI parses argv manually in `main()` — click is only used for `click.echo()`, not subcommands. New commands need a `COMMAND_SPECS` entry, a place in `COMMAND_CATEGORIES`, and a `@register("<name>")` handler in daemon.py, then `python scripts/gen_skill.py` to refresh the generated command block in `skills/patchright-cli/SKILL.md` (`--check` exits 1 when stale; `tests/test_skill_sync.py` enforces it); only session and lifecycle commands (open, attach, close, kill-all, ...) live in `handle_command()` itself
 - 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)

{patchright_cli-0.9.0 → patchright_cli-0.10.0}/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.10.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: patchright-cli
-Version: 0.9.0
+Version: 0.10.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
@@ -46,7 +46,7 @@ Description-Content-Type: text/markdown
 [![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.
+Anti-detect browser automation CLI. Commands follow [Microsoft's playwright-cli](https://github.com/microsoft/playwright-cli), but it uses [Patchright](https://github.com/kaliiiiiiiiii/patchright-python) (undetected Playwright fork) to bypass bot detection.
 
 [Install](#install) · [Quick Start](#quick-start) · [Commands](#-commands) · [Snapshots](#snapshots) · [Agent Integration](#agent-integration)
 
@@ -55,7 +55,7 @@ Anti-detect browser automation CLI. Same command interface as [Microsoft's playw
 | | Feature |
 |---|---|
 | :shield: | Bypasses Akamai, Cloudflare, and other anti-bot systems |
-| :rocket: | Same command interface as playwright-cli — zero learning curve |
+| :rocket: | playwright-cli's command names and arguments — little to relearn |
 | :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 |
@@ -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,16 @@ 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.
 
+### Stopping a stuck daemon
+
+The daemon runs without a window. `kill-all` asks it to close every session and exit. If it does not answer within 20 seconds, or with `--force`, the CLI ends the daemon process and the browsers it launched (`taskkill /T` on Windows, the daemon's process group elsewhere). It finds the process through `~/.patchright-cli/daemon-<port>.pid`, which the daemon writes at startup with its PID and start time, and kills only a process whose start time still matches, so a reused PID is never touched. A daemon from a version that writes no PID file has to be ended by hand: its command line contains `patchright_cli.daemon`.
+
+### 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 +342,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
@@ -409,6 +445,35 @@ patchright-cli console --clear         # Clear after printing
 ```bash
 patchright-cli --raw eval --file=s.js  # Raw output (no page/snapshot decoration)
 patchright-cli --raw snapshot > p.yml  # Pipe raw snapshot to file
+patchright-cli --json tab-list         # Whole reply as JSON ({success, output, data, ...})
+patchright-cli --toon tab-list         # Structured result as TOON
+```
+
+`--toon` prints a reply's structured `data` as [TOON](https://github.com/toon-format/spec), a compact
+format for agents: `list`, `tab-list`, `cookie-list`, `localstorage-list`, `sessionstorage-list`,
+`route-list`, `console`, `network`, `profile-list` and `find` give a table, `url` and `title` a single
+field. A cut-short list adds `total` and a `help:` line. Commands without structured data, and errors,
+print exactly as they do without the flag. `--json` and `--toon` together are a usage error.
+
+```
+tabs[2]{index,title,url,active}:
+  0,Example Domain,"https://example.com/",true
+  1,"","about:blank",false
+```
+
+Run with no arguments, `patchright-cli` prints a short home view instead of the manual (that is
+`--help`): where the binary is, whether the daemon is running on the port (`--port=N` picks another),
+the open sessions with their URL and tab count, and what to run next. It only asks a daemon that is
+already running and never starts one. Add `--toon` or `--json` for the same state as data.
+
+```
+~/.local/bin/patchright-cli v0.10.0 -- anti-detect Chrome automation CLI (playwright-cli style commands)
+daemon: running on port 9321 (1 session)
+sessions[1]{name,status,url,tabs}:
+  default,open,"https://example.com/",2
+help: patchright-cli snapshot  (element refs for the current page; -s=<name> for another session)
+help: patchright-cli list  (sessions and their tabs)
+help: patchright-cli --help  (all commands); patchright-cli <command> --help  (one command)
 ```
 
 ### Setup
@@ -423,7 +488,8 @@ 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 kill-all                # Stop the daemon; force-stops it if it does not answer
+patchright-cli kill-all --force        # Kill the daemon and its browsers without asking
 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
@@ -436,10 +502,36 @@ patchright-cli --port=9322 open        # Custom daemon port
 
 ## Agent Integration
 
-Works with Claude Code, Cursor, Gemini CLI, Codex, and [40+ other agents](https://github.com/vercel-labs/skills).
+The CLI follows the [AXI](https://github.com/kunchenguid/axi) standard for agent-facing tools: errors and hints on stdout, exit 2 for usage errors, `(no-op)` for repeated actions, and a no-argument home view with live state.
+
+There are two ways to teach your agent about patchright-cli. Both get it to the same place, so you only need one.
+
+| | Session hook | Skill |
+|---|---|---|
+| Install | `patchright-cli install --hooks` | `npx skills add AhaiMk01/patchright-cli` or `patchright-cli install --skills` |
+| What the agent gets | Live state (open sessions, the commands to drive them) at the start of every session | Full command reference, loaded when a browser task comes up |
+| Cost | A few lines of context in every session | Nothing until it is needed |
+| Agents | Claude Code, Codex, OpenCode | Claude Code, Cursor, Gemini CLI, Codex and [40+ others](https://github.com/vercel-labs/skills) |
+
+### Session hook (recommended)
+
+```bash
+patchright-cli install --hooks              # install or repair
+patchright-cli install --hooks --uninstall  # remove
+```
+
+At the start of each session the agent runs `patchright-cli` with no arguments, which prints the home view (see [Output](#output)): whether the daemon is up and which sessions are open, so the agent can pick up an open browser session without asking. The hook goes only to apps whose config directory exists, and prints one line per app (`installed`, `updated`, `(no-op)` or `skipped`):
+
+- **Claude Code**: a `SessionStart` hook in `~/.claude/settings.json`
+- **Codex**: a `SessionStart` hook in `~/.codex/hooks.json`, plus `hooks = true` under `[features]` in `~/.codex/config.toml`
+- **OpenCode**: a managed plugin at `~/.config/opencode/plugins/patchright-cli.js` that adds the dashboard to the system prompt
+
+The hook calls plain `patchright-cli` when that name on your `PATH` is the same binary you ran the install with, and its absolute path otherwise. Re-run `install --hooks` after reinstalling or moving patchright-cli and it rewrites the path. Your other hooks and settings are left as they are, and `--uninstall` removes only patchright-cli's entries (the Codex `[features]` flag stays, since other hooks may need it).
+
+### Skill
 
 ```bash
-# Install skill for all detected agents (recommended)
+# Install skill for all detected agents
 npx skills add AhaiMk01/patchright-cli
 ```
 
@@ -530,7 +622,7 @@ URLs passed to `patchright_open`, `patchright_goto` and `patchright_tab_new` mus
 <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:
+patchright-cli follows the command names and arguments of [Microsoft's playwright-cli](https://github.com/microsoft/playwright-cli) where Patchright allows it, but it is **not a drop-in replacement**. Some playwright-cli features cannot work on Patchright and are not implemented:
 
 | Feature | Reason |
 |---------|--------|
@@ -538,7 +630,7 @@ patchright-cli aims for full command parity with [Microsoft's playwright-cli](ht
 | `--extension` | Browser extension connection not supported. Patchright uses CDP directly. |
 | `install` / `install-browser` | Use `python -m patchright install chromium` instead. |
 
-All other commands and options are fully supported.
+Each command accepts only the flags it implements. A playwright-cli flag patchright-cli does not support, such as `open --browser=firefox`, is rejected with `error: unknown flag` and exit code 2 rather than silently ignored, so a script ported from playwright-cli fails loudly where it would otherwise behave differently. `patchright-cli <command> --help` lists a command's flags.
 
 </details>
 
@@ -558,6 +650,8 @@ This project builds on the work of:
 - **[Patchright](https://github.com/Kaliiiiiiiiii-Vinyzu/patchright)** by [@Kaliiiiiiiiii-Vinyzu](https://github.com/Kaliiiiiiiiii-Vinyzu) — the undetected Playwright fork that makes this possible. All anti-detect capabilities come from Patchright.
 - **[playwright-cli](https://github.com/microsoft/playwright-cli)** by Microsoft — the original CLI that patchright-cli's command interface is modeled after.
 - **[camoufox-cli](https://github.com/Bin-Huang/camoufox-cli)** by [@Bin-Huang](https://github.com/Bin-Huang) — inspiration for the CLI-first approach to anti-detect browser automation and the SKILL.md agent integration pattern.
+- **[AXI (Agent eXperience Interface)](https://github.com/kunchenguid/axi)** by [@kunchenguid](https://github.com/kunchenguid) — the standard for agent-facing CLIs that shaped the home view, strict per-command flags, `error:`/`help:` output, `(no-op)` replies, explicit empty states and the session-start hook.
+- **[TOON](https://github.com/toon-format/spec)** — the token-oriented output format behind `--toon`.
 
 ---
 

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

@@ -9,7 +9,7 @@
 [![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.
+Anti-detect browser automation CLI. Commands follow [Microsoft's playwright-cli](https://github.com/microsoft/playwright-cli), but it uses [Patchright](https://github.com/kaliiiiiiiiii/patchright-python) (undetected Playwright fork) to bypass bot detection.
 
 [Install](#install) · [Quick Start](#quick-start) · [Commands](#-commands) · [Snapshots](#snapshots) · [Agent Integration](#agent-integration)
 
@@ -18,7 +18,7 @@ Anti-detect browser automation CLI. Same command interface as [Microsoft's playw
 | | Feature |
 |---|---|
 | :shield: | Bypasses Akamai, Cloudflare, and other anti-bot systems |
-| :rocket: | Same command interface as playwright-cli — zero learning curve |
+| :rocket: | playwright-cli's command names and arguments — little to relearn |
 | :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 |
@@ -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,16 @@ 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.
 
+### Stopping a stuck daemon
+
+The daemon runs without a window. `kill-all` asks it to close every session and exit. If it does not answer within 20 seconds, or with `--force`, the CLI ends the daemon process and the browsers it launched (`taskkill /T` on Windows, the daemon's process group elsewhere). It finds the process through `~/.patchright-cli/daemon-<port>.pid`, which the daemon writes at startup with its PID and start time, and kills only a process whose start time still matches, so a reused PID is never touched. A daemon from a version that writes no PID file has to be ended by hand: its command line contains `patchright_cli.daemon`.
+
+### 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 +305,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
@@ -372,6 +408,35 @@ patchright-cli console --clear         # Clear after printing
 ```bash
 patchright-cli --raw eval --file=s.js  # Raw output (no page/snapshot decoration)
 patchright-cli --raw snapshot > p.yml  # Pipe raw snapshot to file
+patchright-cli --json tab-list         # Whole reply as JSON ({success, output, data, ...})
+patchright-cli --toon tab-list         # Structured result as TOON
+```
+
+`--toon` prints a reply's structured `data` as [TOON](https://github.com/toon-format/spec), a compact
+format for agents: `list`, `tab-list`, `cookie-list`, `localstorage-list`, `sessionstorage-list`,
+`route-list`, `console`, `network`, `profile-list` and `find` give a table, `url` and `title` a single
+field. A cut-short list adds `total` and a `help:` line. Commands without structured data, and errors,
+print exactly as they do without the flag. `--json` and `--toon` together are a usage error.
+
+```
+tabs[2]{index,title,url,active}:
+  0,Example Domain,"https://example.com/",true
+  1,"","about:blank",false
+```
+
+Run with no arguments, `patchright-cli` prints a short home view instead of the manual (that is
+`--help`): where the binary is, whether the daemon is running on the port (`--port=N` picks another),
+the open sessions with their URL and tab count, and what to run next. It only asks a daemon that is
+already running and never starts one. Add `--toon` or `--json` for the same state as data.
+
+```
+~/.local/bin/patchright-cli v0.10.0 -- anti-detect Chrome automation CLI (playwright-cli style commands)
+daemon: running on port 9321 (1 session)
+sessions[1]{name,status,url,tabs}:
+  default,open,"https://example.com/",2
+help: patchright-cli snapshot  (element refs for the current page; -s=<name> for another session)
+help: patchright-cli list  (sessions and their tabs)
+help: patchright-cli --help  (all commands); patchright-cli <command> --help  (one command)
 ```
 
 ### Setup
@@ -386,7 +451,8 @@ 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 kill-all                # Stop the daemon; force-stops it if it does not answer
+patchright-cli kill-all --force        # Kill the daemon and its browsers without asking
 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
@@ -399,10 +465,36 @@ patchright-cli --port=9322 open        # Custom daemon port
 
 ## Agent Integration
 
-Works with Claude Code, Cursor, Gemini CLI, Codex, and [40+ other agents](https://github.com/vercel-labs/skills).
+The CLI follows the [AXI](https://github.com/kunchenguid/axi) standard for agent-facing tools: errors and hints on stdout, exit 2 for usage errors, `(no-op)` for repeated actions, and a no-argument home view with live state.
+
+There are two ways to teach your agent about patchright-cli. Both get it to the same place, so you only need one.
+
+| | Session hook | Skill |
+|---|---|---|
+| Install | `patchright-cli install --hooks` | `npx skills add AhaiMk01/patchright-cli` or `patchright-cli install --skills` |
+| What the agent gets | Live state (open sessions, the commands to drive them) at the start of every session | Full command reference, loaded when a browser task comes up |
+| Cost | A few lines of context in every session | Nothing until it is needed |
+| Agents | Claude Code, Codex, OpenCode | Claude Code, Cursor, Gemini CLI, Codex and [40+ others](https://github.com/vercel-labs/skills) |
+
+### Session hook (recommended)
+
+```bash
+patchright-cli install --hooks              # install or repair
+patchright-cli install --hooks --uninstall  # remove
+```
+
+At the start of each session the agent runs `patchright-cli` with no arguments, which prints the home view (see [Output](#output)): whether the daemon is up and which sessions are open, so the agent can pick up an open browser session without asking. The hook goes only to apps whose config directory exists, and prints one line per app (`installed`, `updated`, `(no-op)` or `skipped`):
+
+- **Claude Code**: a `SessionStart` hook in `~/.claude/settings.json`
+- **Codex**: a `SessionStart` hook in `~/.codex/hooks.json`, plus `hooks = true` under `[features]` in `~/.codex/config.toml`
+- **OpenCode**: a managed plugin at `~/.config/opencode/plugins/patchright-cli.js` that adds the dashboard to the system prompt
+
+The hook calls plain `patchright-cli` when that name on your `PATH` is the same binary you ran the install with, and its absolute path otherwise. Re-run `install --hooks` after reinstalling or moving patchright-cli and it rewrites the path. Your other hooks and settings are left as they are, and `--uninstall` removes only patchright-cli's entries (the Codex `[features]` flag stays, since other hooks may need it).
+
+### Skill
 
 ```bash
-# Install skill for all detected agents (recommended)
+# Install skill for all detected agents
 npx skills add AhaiMk01/patchright-cli
 ```
 
@@ -493,7 +585,7 @@ URLs passed to `patchright_open`, `patchright_goto` and `patchright_tab_new` mus
 <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:
+patchright-cli follows the command names and arguments of [Microsoft's playwright-cli](https://github.com/microsoft/playwright-cli) where Patchright allows it, but it is **not a drop-in replacement**. Some playwright-cli features cannot work on Patchright and are not implemented:
 
 | Feature | Reason |
 |---------|--------|
@@ -501,7 +593,7 @@ patchright-cli aims for full command parity with [Microsoft's playwright-cli](ht
 | `--extension` | Browser extension connection not supported. Patchright uses CDP directly. |
 | `install` / `install-browser` | Use `python -m patchright install chromium` instead. |
 
-All other commands and options are fully supported.
+Each command accepts only the flags it implements. A playwright-cli flag patchright-cli does not support, such as `open --browser=firefox`, is rejected with `error: unknown flag` and exit code 2 rather than silently ignored, so a script ported from playwright-cli fails loudly where it would otherwise behave differently. `patchright-cli <command> --help` lists a command's flags.
 
 </details>
 
@@ -521,6 +613,8 @@ This project builds on the work of:
 - **[Patchright](https://github.com/Kaliiiiiiiiii-Vinyzu/patchright)** by [@Kaliiiiiiiiii-Vinyzu](https://github.com/Kaliiiiiiiiii-Vinyzu) — the undetected Playwright fork that makes this possible. All anti-detect capabilities come from Patchright.
 - **[playwright-cli](https://github.com/microsoft/playwright-cli)** by Microsoft — the original CLI that patchright-cli's command interface is modeled after.
 - **[camoufox-cli](https://github.com/Bin-Huang/camoufox-cli)** by [@Bin-Huang](https://github.com/Bin-Huang) — inspiration for the CLI-first approach to anti-detect browser automation and the SKILL.md agent integration pattern.
+- **[AXI (Agent eXperience Interface)](https://github.com/kunchenguid/axi)** by [@kunchenguid](https://github.com/kunchenguid) — the standard for agent-facing CLIs that shaped the home view, strict per-command flags, `error:`/`help:` output, `(no-op)` replies, explicit empty states and the session-start hook.
+- **[TOON](https://github.com/toon-format/spec)** — the token-oriented output format behind `--toon`.
 
 ---