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

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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: patchright-cli
-Version: 0.9.1
+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 |
@@ -246,6 +246,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
@@ -441,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
@@ -455,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
@@ -468,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
 ```
 
@@ -562,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 |
 |---------|--------|
@@ -570,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>
 
@@ -590,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.1 → 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 |
@@ -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
@@ -404,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
@@ -418,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
@@ -431,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
 ```
 
@@ -525,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 |
 |---------|--------|
@@ -533,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>
 
@@ -553,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`.
 
 ---
 

{patchright_cli-0.9.1 → patchright_cli-0.10.0}/docs/daemon-protocol.md

@@ -86,6 +86,44 @@ 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 |
+
+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.10.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "patchright-cli"
-version = "0.9.1"
+version = "0.10.0"
 description = "Anti-detect browser automation CLI using Patchright (undetected Playwright fork)"
 license = "Apache-2.0"
 requires-python = ">=3.10"
@@ -37,7 +37,7 @@ Repository = "https://github.com/AhaiMk01/patchright-cli"
 Issues = "https://github.com/AhaiMk01/patchright-cli/issues"
 
 [project.scripts]
-patchright-cli = "patchright_cli.cli:main"
+patchright-cli = "patchright_cli._entry:main"
 
 [build-system]
 requires = ["hatchling"]

patchright_cli-0.10.0/scripts/gen_skill.py

@@ -0,0 +1,79 @@
+"""Regenerate the command reference block in skills/patchright-cli/SKILL.md.
+
+The rest of SKILL.md is hand-written. Only the text between BEGIN and END is
+generated, from COMMAND_SPECS and COMMAND_CATEGORIES in cli.py, so a new or
+renamed command reaches the skill agents read.
+
+    python scripts/gen_skill.py           # rewrite the block in place
+    python scripts/gen_skill.py --check   # exit 1 when the block is stale
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+from patchright_cli.cli import COMMAND_CATEGORIES, COMMAND_SPECS
+
+SKILL_PATH = Path(__file__).resolve().parent.parent / "skills" / "patchright-cli" / "SKILL.md"
+BEGIN = "<!-- BEGIN GENERATED: commands (scripts/gen_skill.py from COMMAND_SPECS; do not edit by hand) -->"
+END = "<!-- END GENERATED -->"
+_WIDTH = 40
+
+
+def _line(name: str) -> str:
+    spec = COMMAND_SPECS[name]
+    flags = " ".join(f"[--{f}]" for f in spec.get("flags", {}))
+    usage = f"{spec['usage']} {flags}".strip()
+    return f"{usage}{' ' * max(_WIDTH - len(usage), 2)}# {spec['summary']}"
+
+
+def render_block() -> str:
+    """The generated block, markers included, every command once in manual order."""
+    listed = [name for _, names in COMMAND_CATEGORIES for name in names]
+    missing = [name for name in COMMAND_SPECS if name not in listed]
+    if missing:
+        raise SystemExit(f"commands missing from COMMAND_CATEGORIES: {', '.join(missing)}")
+    lines = [BEGIN, "```bash"]
+    for i, (category, names) in enumerate(COMMAND_CATEGORIES):
+        if i:
+            lines.append("")
+        lines.append(f"# {category}")
+        lines.extend(_line(name) for name in names)
+    lines += ["```", END]
+    return "\n".join(lines)
+
+
+def sync(text: str) -> str:
+    """`text` with its generated block replaced by the current one."""
+    start, end = text.find(BEGIN), text.find(END)
+    if start < 0 or end < start:
+        raise SystemExit(f"SKILL.md has no generated block; add the lines\n{BEGIN}\n{END}")
+    return text[:start] + render_block() + text[end + len(END) :]
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description=__doc__.splitlines()[0])
+    parser.add_argument("--check", action="store_true", help="exit 1 when the block is stale; change nothing")
+    parser.add_argument("--path", type=Path, default=SKILL_PATH, help="SKILL.md to sync (default: the bundled one)")
+    opts = parser.parse_args(argv)
+
+    raw = opts.path.read_bytes().decode("utf-8")
+    newline = "\r\n" if "\r\n" in raw else "\n"
+    text = raw.replace("\r\n", "\n")
+    synced = sync(text)
+    if synced == text:
+        print(f"{opts.path.name}: command block is current")
+        return 0
+    if opts.check:
+        print(f"error: {opts.path.name} command block is stale")
+        print("help: run `python scripts/gen_skill.py` and commit the result")
+        return 1
+    opts.path.write_bytes(synced.replace("\n", newline).encode("utf-8"))
+    print(f"{opts.path.name}: command block updated")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())