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

{patchright_cli-0.9.1 → patchright_cli-0.11.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.1"
+    "version": "0.11.0"
   },
   "plugins": [
     {

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

@@ -22,10 +22,10 @@ jobs:
     strategy:
       matrix:
         os: [ubuntu-latest, windows-latest]
-        python-version: ["3.10", "3.12"]
+        python-version: ["3.12", "3.13"]
         include:
           - os: macos-latest
-            python-version: "3.12"
+            python-version: "3.13"
     runs-on: ${{ matrix.os }}
     steps:
       - uses: actions/checkout@v7

{patchright_cli-0.9.1 → patchright_cli-0.11.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,11 +50,11 @@ 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`. A failed reply, whatever the daemon's wording, prints through `_failure_lines()`: `error: <message>`, detail lines, then `help: <next step>` lines (exit 1, or 2 when the reply carries `exit_code: 2`); `--json` adds `error`/`help` fields.
 
 - **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.
 
-- **Snapshot (`src/patchright_cli/snapshot.py`)**: Uses Playwright's native `aria_snapshot()` to get the accessibility tree. `RefRegistry` annotates each node with sequential refs (`e1`, `e2`, ...). Snapshots are saved as YAML to `.patchright-cli/` in the caller's cwd.
+- **Snapshot (`src/patchright_cli/snapshot.py`, `snapshot_text.py`)**: One full-page `page.aria_snapshot(mode="ai")` per tab (kept as `Tab.last_raw`) gives Playwright's own refs (`e5`, `f3e5` in iframes and after navigation); `page.get_by_ref` resolves them. Any other `aria_snapshot()` call replaces the page's ref map, so `snapshot.py` is the only caller (a unit test greps for it) and scoping, `--depth`, `-i` and `find` are text operations in `snapshot_text.py`. `scripts/ref_sweep/` is the before/after sweep of every ref-taking command; rerun it on a patchright bump. Snapshots are saved as YAML to `.patchright-cli/` in the caller's cwd.
 
 ## Key Design Decisions
 
@@ -59,8 +62,9 @@ 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
+- Flag and positional value shapes (numbers, choices, flags that need a value) live in `src/patchright_cli/values.py` (`FLAG_KINDS`, `ARG_KINDS`); the CLI checks them before contacting the daemon (exit 2) and the daemon checks them again for clients that skip the CLI. A new numeric or enum flag needs an entry there (`tests/test_cli_audit.py` enforces it)
 - 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)
+- Uses hatchling as build backend, ruff for linting (line-length=120, target py312)
 - Ruff rules: E, F, I, W, UP, B, SIM (ignores E501, SIM105, E402)

{patchright_cli-0.9.1 → patchright_cli-0.11.0}/CONTRIBUTING.md

@@ -31,7 +31,7 @@ pre-commit install
 
 ## Code Style
 
-- Python 3.10+
+- Python 3.12+
 - Formatted with [Ruff](https://github.com/astral-sh/ruff) (enforced via pre-commit)
 - Keep the daemon lightweight — avoid heavy dependencies
 

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: patchright-cli
-Version: 0.9.1
+Version: 0.11.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
@@ -14,16 +14,14 @@ Classifier: Environment :: Console
 Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: Apache Software License
 Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.10
-Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Topic :: Internet :: WWW/HTTP :: Browsers
 Classifier: Topic :: Software Development :: Testing
-Requires-Python: >=3.10
+Requires-Python: >=3.12
 Requires-Dist: aiohttp>=3.9
 Requires-Dist: click
-Requires-Dist: patchright
+Requires-Dist: patchright<1.65,>=1.64
 Requires-Dist: pywin32>=306; sys_platform == 'win32'
 Requires-Dist: pyyaml
 Provides-Extra: dev
@@ -46,7 +44,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 +53,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 |
@@ -85,7 +83,7 @@ curl -s https://raw.githubusercontent.com/AhaiMk01/patchright-cli/main/docs/inst
 </details>
 
 > [!IMPORTANT]
-> **Requirements:** Python 3.10+ and Google Chrome
+> **Requirements:** Python 3.12+ and Google Chrome
 
 ```bash
 # Recommended — always runs latest version, no install needed
@@ -235,7 +233,7 @@ graph LR
 |-----------|------|
 | **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`) | Playwright `aria_snapshot()` accessibility tree, annotated with sequential `[ref=eN]` handles for element targeting. |
+| **Snapshot** (`snapshot.py`) | Playwright's AI-mode `aria_snapshot()` accessibility tree, iframes included, with Playwright's own `[ref=e5]` handles, resolved with `get_by_ref`. |
 
 ### Daemon token
 
@@ -246,6 +244,10 @@ 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
@@ -291,6 +293,10 @@ patchright-cli find "text"             # Search snapshot for text
 patchright-cli find --regex "a|b"      # Search by regex
 patchright-cli find "text" --all       # Include text/paragraph nodes
 patchright-cli find "text" --limit=50  # Cap hits (default 20)
+patchright-cli find --role=button --description="Deletes"  # By role + accessible name/description
+patchright-cli html                    # Page HTML (first 8000 chars; --max-chars=0 for all)
+patchright-cli html --include-shadow --filename=page.html  # With open shadow roots, to a file
+patchright-cli html e5                 # One element's outerHTML (or --selector=CSS)
 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
@@ -396,6 +402,19 @@ patchright-cli sessionstorage-delete <key>
 patchright-cli sessionstorage-clear
 ```
 
+### Passkeys
+A virtual WebAuthn authenticator for testing passkey sign-ups and logins. The first `passkey-*` command installs it in the session, overriding `navigator.credentials.create()` / `.get()` in every page (a page can notice the override, so it stays off until asked for). **Run a `passkey-*` command (e.g. `passkey-list`) before the page calls WebAuthn**: until then the page gets Chrome's native OS passkey dialog and hangs. Passkeys live in the session only; use `passkey-export` / `passkey-import` to keep them (the export holds private keys and is written owner-only; keep it out of version control).
+```bash
+patchright-cli passkey-list                      # Installs the authenticator, lists passkeys (no keys shown)
+patchright-cli passkey-list --rp-id=example.com
+patchright-cli passkey-add example.com           # Seed a new P-256 passkey
+patchright-cli passkey-add example.com --id=<b64url> --user-handle=<b64url> --private-key=<b64url> --public-key=<b64url> --sign-count=5
+patchright-cli passkey-delete <credential-id>
+patchright-cli passkey-clear [--rp-id=example.com]
+patchright-cli passkey-export passkeys.json      # Includes private keys
+patchright-cli passkey-import passkeys.json
+```
+
 ### Request Mocking
 ```bash
 patchright-cli route "**/*.jpg" --status=404
@@ -412,7 +431,8 @@ patchright-cli unroute                 # Remove all routes
 ```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-start             # Start real-time video recording at 25 fps (CDP screencast)
+patchright-cli video-start --fps=60    # Another frame rate, 1-60
 patchright-cli video-stop              # Stop and save video (requires ffmpeg for .webm)
 patchright-cli video-stop --filename=recording.webm
 patchright-cli show --annotate          # Ask a human to mark up the page, wait for it
@@ -432,15 +452,57 @@ patchright-cli network-state-set online   # Restore connectivity
 
 ### DevTools
 ```bash
-patchright-cli console                 # All console messages
+patchright-cli console                 # Start capture / show captured console messages
 patchright-cli console warning         # Filter by level
 patchright-cli console --clear         # Clear after printing
 ```
 
+The first `console` call enables CDP Runtime capture for every page in the session,
+including tabs and popups opened later. Messages from before capture starts are
+unavailable: run `console` before reproducing an issue, then call it again to read
+the messages. Capture can make automation detectable and stays enabled until the
+session closes; `--clear` only clears the message buffer. A new session starts
+with capture disabled.
+
+Two DevTools commands leave traces a page can see. `highlight` draws inside an
+`<x-pw-glass>` element under `<html>`; `highlight --hide` removes it once no
+highlight is left. `pick-locator` runs only with `--detectable`: it installs
+Playwright's recorder, which puts `window.playwright`, `__pw_*` globals and an
+`<x-pw-glass>` element into every page of the session until the session closes.
+
 ### Output
 ```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
@@ -455,7 +517,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
@@ -468,10 +531,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
 ```
 
@@ -562,7 +651,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 |
 |---------|--------|
@@ -570,7 +659,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>
 
@@ -590,6 +679,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.1 → patchright_cli-0.11.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 |
@@ -48,7 +48,7 @@ curl -s https://raw.githubusercontent.com/AhaiMk01/patchright-cli/main/docs/inst
 </details>
 
 > [!IMPORTANT]
-> **Requirements:** Python 3.10+ and Google Chrome
+> **Requirements:** Python 3.12+ and Google Chrome
 
 ```bash
 # Recommended — always runs latest version, no install needed
@@ -198,7 +198,7 @@ graph LR
 |-----------|------|
 | **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`) | Playwright `aria_snapshot()` accessibility tree, annotated with sequential `[ref=eN]` handles for element targeting. |
+| **Snapshot** (`snapshot.py`) | Playwright's AI-mode `aria_snapshot()` accessibility tree, iframes included, with Playwright's own `[ref=e5]` handles, resolved with `get_by_ref`. |
 
 ### Daemon token
 
@@ -209,6 +209,10 @@ 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
@@ -254,6 +258,10 @@ patchright-cli find "text"             # Search snapshot for text
 patchright-cli find --regex "a|b"      # Search by regex
 patchright-cli find "text" --all       # Include text/paragraph nodes
 patchright-cli find "text" --limit=50  # Cap hits (default 20)
+patchright-cli find --role=button --description="Deletes"  # By role + accessible name/description
+patchright-cli html                    # Page HTML (first 8000 chars; --max-chars=0 for all)
+patchright-cli html --include-shadow --filename=page.html  # With open shadow roots, to a file
+patchright-cli html e5                 # One element's outerHTML (or --selector=CSS)
 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
@@ -359,6 +367,19 @@ patchright-cli sessionstorage-delete <key>
 patchright-cli sessionstorage-clear
 ```
 
+### Passkeys
+A virtual WebAuthn authenticator for testing passkey sign-ups and logins. The first `passkey-*` command installs it in the session, overriding `navigator.credentials.create()` / `.get()` in every page (a page can notice the override, so it stays off until asked for). **Run a `passkey-*` command (e.g. `passkey-list`) before the page calls WebAuthn**: until then the page gets Chrome's native OS passkey dialog and hangs. Passkeys live in the session only; use `passkey-export` / `passkey-import` to keep them (the export holds private keys and is written owner-only; keep it out of version control).
+```bash
+patchright-cli passkey-list                      # Installs the authenticator, lists passkeys (no keys shown)
+patchright-cli passkey-list --rp-id=example.com
+patchright-cli passkey-add example.com           # Seed a new P-256 passkey
+patchright-cli passkey-add example.com --id=<b64url> --user-handle=<b64url> --private-key=<b64url> --public-key=<b64url> --sign-count=5
+patchright-cli passkey-delete <credential-id>
+patchright-cli passkey-clear [--rp-id=example.com]
+patchright-cli passkey-export passkeys.json      # Includes private keys
+patchright-cli passkey-import passkeys.json
+```
+
 ### Request Mocking
 ```bash
 patchright-cli route "**/*.jpg" --status=404
@@ -375,7 +396,8 @@ patchright-cli unroute                 # Remove all routes
 ```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-start             # Start real-time video recording at 25 fps (CDP screencast)
+patchright-cli video-start --fps=60    # Another frame rate, 1-60
 patchright-cli video-stop              # Stop and save video (requires ffmpeg for .webm)
 patchright-cli video-stop --filename=recording.webm
 patchright-cli show --annotate          # Ask a human to mark up the page, wait for it
@@ -395,15 +417,57 @@ patchright-cli network-state-set online   # Restore connectivity
 
 ### DevTools
 ```bash
-patchright-cli console                 # All console messages
+patchright-cli console                 # Start capture / show captured console messages
 patchright-cli console warning         # Filter by level
 patchright-cli console --clear         # Clear after printing
 ```
 
+The first `console` call enables CDP Runtime capture for every page in the session,
+including tabs and popups opened later. Messages from before capture starts are
+unavailable: run `console` before reproducing an issue, then call it again to read
+the messages. Capture can make automation detectable and stays enabled until the
+session closes; `--clear` only clears the message buffer. A new session starts
+with capture disabled.
+
+Two DevTools commands leave traces a page can see. `highlight` draws inside an
+`<x-pw-glass>` element under `<html>`; `highlight --hide` removes it once no
+highlight is left. `pick-locator` runs only with `--detectable`: it installs
+Playwright's recorder, which puts `window.playwright`, `__pw_*` globals and an
+`<x-pw-glass>` element into every page of the session until the session closes.
+
 ### Output
 ```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
@@ -418,7 +482,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
@@ -431,10 +496,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
 ```
 
@@ -525,7 +616,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 |
 |---------|--------|
@@ -533,7 +624,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>
 
@@ -553,6 +644,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.1 → patchright_cli-0.11.0}/docs/daemon-protocol.md

@@ -86,6 +86,50 @@ this table are part of the protocol:
 | `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. |
 
+### Idempotent no-ops
+
+A mutation whose target state already holds succeeds instead of failing:
+`success` is `true` and `output` ends with ` (no-op)`. This covers `close` and
+`detach` of a session that is not open (the output still contains
+`Session '<name>' is not open`), `close` of a named tab that is not open,
+`video-stop`, `tracing-stop` and `codegen-stop` with nothing running,
+`video-start` and `tracing-start` while already running, `video-hide-actions`
+when callouts are off, `unroute` of a pattern that is not routed (or with no
+routes at all), `cookie-delete`, `localstorage-delete` and
+`sessionstorage-delete` of an absent name or key, `highlight --hide` with
+nothing highlighted, and `profile-delete` of a profile that does not exist.
+`go-back` and `go-forward` at the edge of the history still fail.
+
+### Structured data
+
+Some replies carry an optional `data` field next to `output`, holding the same
+result as JSON. `output` stays the human-readable text. When a list reply shows
+fewer items than exist, `total` holds the full count.
+
+| Command | `data` |
+| --- | --- |
+| `url` | `{"url"}` |
+| `title` | `{"title"}` |
+| `list` | `[{"name", "status", "url"}]`, where `status` is `open` or `attached` |
+| `tab-list` | `[{"index", "title", "url", "active"}]` |
+| `cookie-list` | `[{"name", "domain", "expires"}]` |
+| `localstorage-list`, `sessionstorage-list` | `[{"key", "value"}]` |
+| `route-list` | `[{"pattern", "status"}]` |
+| `console` | `[{"level", "text"}]`, plus `total` when older messages are cut off |
+| `network` (alias `requests`) | `[{"id", "method", "status", "url"}]`, plus `total` when older requests are cut off |
+| `profile-list` | `[{"name", "size", "session"}]`, where `size` is bytes and `session` is the holding session or `null` |
+| `find` | `[{"ref", "role", "name"}]`, plus `total` when `--limit` cut the hits |
+
+`console` opts the session into CDP Runtime capture on existing and future pages.
+Earlier messages are unavailable; the first response explains this and the CDP
+detection risk. Capture lasts until the session closes; `--clear` only clears the
+buffer. If capture fails on a live page, the response has `success: false` and any
+available messages; another `console` call retries pages that failed.
+
+An empty list is `[]`, and its `output` states the zero explicitly, for example
+`0 cookies in this session`. Commands not listed here send no `data`. More
+fields or commands can gain `data` later, so read only the keys you need.
+
 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

{patchright_cli-0.9.1 → patchright_cli-0.11.0}/docs/installation.md

@@ -2,7 +2,7 @@
 
 ## Prerequisites
 
-- Python 3.10+
+- Python 3.12+
 - Google Chrome installed on the system
 
 ## Install