### Simple URL migration for /new

Source: https://github.com/eze-is/web-access/blob/main/references/migration-2.5.3.md

Example of converting a simple URL GET request to /new to a POST request with the URL in the body.

```bash
curl ".../new?url=https://example.com"
```

```bash
curl -X POST --data-raw 'https://example.com' .../new
```

--------------------------------

### Handling GET calls after migration

Source: https://github.com/eze-is/web-access/blob/main/references/migration-2.5.3.md

Explains the response received when attempting to use the old GET method for /new or /navigate after the migration.

```markdown
Q: 我用 GET `?url=` 调用会发生什么？
A: 收到 HTTP 400 响应，body 中包含 `error`、`migration` 文档路径、`example` 示例。按提示改 POST 调用即可。
```

--------------------------------

### Start CDP Proxy Manually

Source: https://github.com/eze-is/web-access/blob/main/README.md

Manually start the CDP proxy. Note that the Agent typically manages the proxy's lifecycle automatically, so manual startup is usually not required.

```bash
node "${CLAUDE_SKILL_DIR}/scripts/cdp-proxy.mjs" &
```

--------------------------------

### URL migration for /navigate

Source: https://github.com/eze-is/web-access/blob/main/references/migration-2.5.3.md

Converts a /navigate GET request with target and URL to a POST request, keeping the target in the query and URL in the body.

```bash
curl ".../navigate?target=ID&url=URL"
```

```bash
curl -X POST --data-raw 'URL' ".../navigate?target=ID"
```

--------------------------------

### GET /targets

Source: https://github.com/eze-is/web-access/blob/main/references/cdp-api.md

Lists all currently open page tabs, providing their IDs, titles, and URLs.

```APIDOC
## GET /targets

### Description
Lists all open page tabs. Returns an array, each item containing `targetId`, `title`, and `url`.

### Method
GET

### Endpoint
/targets

### Response
#### Success Response (200)
- **targetId** (string) - The unique identifier for the tab.
- **title** (string) - The title of the web page.
- **url** (string) - The URL of the web page.

### Request Example
```bash
curl -s http://localhost:3456/targets
```
```

--------------------------------

### GET /back?target=ID

Source: https://github.com/eze-is/web-access/blob/main/references/cdp-api.md

Navigates the specified tab back one page in its history.

```APIDOC
## GET /back?target=ID

### Description
Navigates back one page in the specified tab's history.

### Method
GET

### Endpoint
/back

### Parameters
#### Query Parameters
- **target** (string) - Required - The ID of the tab to navigate back.

### Request Example
```bash
curl -s "http://localhost:3456/back?target=ID"
```
```

--------------------------------

### GET /info?target=ID

Source: https://github.com/eze-is/web-access/blob/main/references/cdp-api.md

Retrieves basic information about a specified tab, including its title, URL, and ready state.

```APIDOC
## GET /info?target=ID

### Description
Retrieves basic information for the specified tab, including its title, URL, and ready state.

### Method
GET

### Endpoint
/info

### Parameters
#### Query Parameters
- **target** (string) - Required - The ID of the tab to get information for.

### Response
#### Success Response (200)
- **title** (string) - The title of the web page.
- **url** (string) - The URL of the web page.
- **readyState** (string) - The current ready state of the page (e.g., 'loading', 'interactive', 'complete').

### Request Example
```bash
curl -s "http://localhost:3456/info?target=ID"
```
```

--------------------------------

### Migrate curl calls from GET to POST

Source: https://github.com/eze-is/web-access/blob/main/references/migration-2.5.3.md

Update curl commands to use POST method with data-raw for the URL, replacing the old GET query parameter method.

```diff
- curl -s "http://localhost:3456/new?url=https://example.com"
+ curl -s -X POST --data-raw 'https://example.com' http://localhost:3456/new

- curl -s "http://localhost:3456/navigate?target=ID&url=https://example.com"
+ curl -s -X POST --data-raw 'https://example.com' "http://localhost:3456/navigate?target=ID"
```

--------------------------------

### Navigate Tab Backwards

Source: https://github.com/eze-is/web-access/blob/main/references/cdp-api.md

Navigates the specified tab back one page in its history. This is a simple GET request with the target ID.

```bash
curl -s "http://localhost:3456/back?target=ID"
```

--------------------------------

### GET /health

Source: https://github.com/eze-is/web-access/blob/main/references/cdp-api.md

Health check endpoint to verify the connection status of the CDP proxy.

```APIDOC
## GET /health

### Description
Health check, returns connection status.

### Method
GET

### Endpoint
/health

### Request Example
```bash
curl -s http://localhost:3456/health
```
```

--------------------------------

### GET /close?target=ID

Source: https://github.com/eze-is/web-access/blob/main/references/cdp-api.md

Closes a specified tab using its target ID.

```APIDOC
## GET /close?target=ID

### Description
Closes the specified tab.

### Method
GET

### Endpoint
/close

### Parameters
#### Query Parameters
- **target** (string) - Required - The ID of the tab to close.

### Request Example
```bash
curl -s "http://localhost:3456/close?target=TARGET_ID"
```
```

--------------------------------

### Get Tab Information

Source: https://github.com/eze-is/web-access/blob/main/references/cdp-api.md

Retrieves basic information about a specific tab, including its title, URL, and ready state. Useful for checking the current status of a target.

```bash
curl -s "http://localhost:3456/info?target=ID"
```

--------------------------------

### Control Video Element using /eval

Source: https://github.com/eze-is/web-access/blob/main/SKILL.md

Interact with video elements using the /eval endpoint to get duration, seek to specific times, or control playback. This enables discrete sampling and analysis of video content.

```bash
curl -s "http://localhost:3456/eval?target=ID&expr=document.querySelector('video').duration"
```

--------------------------------

### GET /scroll?target=ID

Source: https://github.com/eze-is/web-access/blob/main/references/cdp-api.md

Scrolls the specified tab up or down by a given amount, or to the top/bottom of the page. Includes a small delay for lazy loading.

```APIDOC
## GET /scroll?target=ID

### Description
Scrolls the specified tab. `direction` can be `down` (default), `up`, `top`, or `bottom`. After scrolling, it waits 800ms to allow lazy loading to trigger.

### Method
GET

### Endpoint
/scroll

### Parameters
#### Query Parameters
- **target** (string) - Required - The ID of the tab to scroll.
- **y** (integer) - Optional - The amount to scroll in pixels. Defaults to 3000 if not specified and direction is 'down' or 'up'.
- **direction** (string) - Optional - The scroll direction. Can be `down`, `up`, `top`, `bottom`. Defaults to `down`.

### Request Example
```bash
curl -s "http://localhost:3456/scroll?target=ID&y=3000"
curl -s "http://localhost:3456/scroll?target=ID&direction=bottom"
```
```

--------------------------------

### GET /screenshot?target=ID

Source: https://github.com/eze-is/web-access/blob/main/references/cdp-api.md

Takes a screenshot of the specified tab. The screenshot can be saved to a file or returned as binary data. Supports JPEG format.

```APIDOC
## GET /screenshot?target=ID

### Description
Takes a screenshot of the specified tab. If the `file` parameter is provided, the screenshot is saved to that local file path. Otherwise, the raw image binary data is returned. The `format` parameter can be set to `jpeg`.

### Method
GET

### Endpoint
/screenshot

### Parameters
#### Query Parameters
- **target** (string) - Required - The ID of the tab to capture.
- **file** (string) - Optional - The local file path to save the screenshot to.
- **format** (string) - Optional - The image format, e.g., `jpeg`. Defaults to PNG.

### Request Example
```bash
curl -s "http://localhost:3456/screenshot?target=ID&file=/tmp/shot.png"
```
```

--------------------------------

### URL with query migration for /new

Source: https://github.com/eze-is/web-access/blob/main/references/migration-2.5.3.md

Demonstrates migrating a URL containing a query string to /new, ensuring the token is preserved by using POST body.

```bash
curl ".../new?url=https://xhs.com/explore/x?xsec_token=ABC" ⚠️ token 丢失
```

```bash
curl -X POST --data-raw 'https://xhs.com/explore/x?xsec_token=ABC' .../new ✓
```

--------------------------------

### URL with fragment migration for /new

Source: https://github.com/eze-is/web-access/blob/main/references/migration-2.5.3.md

Shows how to migrate a URL with a fragment identifier to /new, preserving the fragment by using POST body.

```bash
curl ".../new?url=https://app/page#sec" ⚠️ fragment 丢失
```

```bash
curl -X POST --data-raw 'https://app/page#sec' .../new ✓
```

--------------------------------

### Open URL in New Tab using /new

Source: https://github.com/eze-is/web-access/blob/main/SKILL.md

Use the /new endpoint with a full URL to open a link in a new tab. This is suitable for scenarios requiring simultaneous access to multiple pages. Ensure all necessary URL parameters, like session tokens, are included.

```bash
curl -s -X POST -d "http://example.com?param=value" "http://localhost:3456/new"
```

--------------------------------

### Site Experience File Format

Source: https://github.com/eze-is/web-access/blob/main/SKILL.md

Site experience files, stored under references/site-patterns/, use Markdown with frontmatter to define domain-specific knowledge, including platform features, effective patterns, and known pitfalls.

```markdown
---
domain: example.com
alias: [示例, Example]
updated: 2026-03-19
---
## 平台特征
架构、反爬行为、登录需求、内容加载方式等事实

## 有效模式
已验证的 URL 模式、操作策略、选择器

## 已知陷阱
什么会失败以及为什么
```

--------------------------------

### POST /new

Source: https://github.com/eze-is/web-access/blob/main/references/cdp-api.md

Creates a new background tab and waits for the page to load. The URL is passed directly in the POST body.

```APIDOC
## POST /new

### Description
Creates a new background tab, automatically waiting for the page to load. The URL is passed directly in the POST body, without URL-encoding. Returns `{ targetId }`.

### Method
POST

### Endpoint
/new

### Parameters
#### Request Body
- **URL** (string) - The URL to navigate to in the new tab.

### Request Example
```bash
curl -s -X POST --data-raw 'https://example.com' http://localhost:3456/new
# Example with query parameters:
curl -s -X POST --data-raw 'https://www.xiaohongshu.com/explore/xxx?xsec_source=app_share&xsec_token=ABC&type=normal' http://localhost:3456/new
```

### Response
#### Success Response (200)
- **targetId** (string) - The unique identifier for the newly created tab.

### Note
Starting from v2.5.3, this endpoint uses POST. The older `GET /new?url=...` is deprecated.
```

--------------------------------

### Navigate within Page using /click

Source: https://github.com/eze-is/web-access/blob/main/SKILL.md

The /click endpoint simulates a user click on an interactive element within the current tab. Use this for sequential operations on the same page, like expanding content or pagination.

```bash
curl -s "http://localhost:3456/click?target=ID"
```

--------------------------------

### Set Default Browser for Web Access

Source: https://github.com/eze-is/web-access/blob/main/README.md

Configure the default browser for web access by setting the WEB_ACCESS_BROWSER environment variable. Leave empty to be prompted each time. Valid values are 'chrome' or 'edge'.

```bash
WEB_ACCESS_BROWSER=edge
```

--------------------------------

### Temporarily Use a Different Browser

Source: https://github.com/eze-is/web-access/blob/main/README.md

Launch a web access script with a specific browser without modifying the config.env file. This is useful for temporary testing or specific tasks.

```bash
node "${CLAUDE_SKILL_DIR}/scripts/check-deps.mjs" --browser chrome
```

--------------------------------

### Check Dependencies

Source: https://github.com/eze-is/web-access/blob/main/SKILL.md

Before performing any network operations, check the availability of CDP mode by running this script. It requires Node.js 22+.

```APIDOC
## Check Dependencies

### Description

Before starting network operations, check the availability of CDP mode.

### Command

```bash
node "${CLAUDE_SKILL_DIR}/scripts/check-deps.mjs"
```

### Prerequisites

Node.js 22+ is required (uses native WebSocket).

### Exit Codes

- `exit 0`: Continue with operations.
- `exit 2`: Requires user preference, write to `${CLAUDE_SKILL_DIR}/config.env` under `WEB_ACCESS_BROWSER`.
- `exit 1`: Handle according to stdout error message. If the prompt includes "Agent processing order", follow its steps. If it still fails, ask the user for help.

### Optional Parameters

- `--browser <chrome|edge>`: Temporarily override the browser choice without modifying `config.env`.

### Notes on Browser Switching

When switching browsers, the proxy is a persistent process. You need to first `pkill -f cdp-proxy.mjs` and then re-run `check-deps.mjs`.
```

--------------------------------

### Migration script availability

Source: https://github.com/eze-is/web-access/blob/main/references/migration-2.5.3.md

Addresses the lack of an automated migration script and recommends manual review based on the provided checklist.

```markdown
Q: 我自己的脚本/别名/笔记里有大量旧写法，有迁移脚本吗？
A: 没有也不打算提供。站点经验和脚本是人写的文档/代码，掺着说明、注释、上下文判断，正则替换容易误伤。本指南的 Agent 自检 checklist 就是给"Agent 看着内容自己判断怎么改"的，比脚本可靠。
```

--------------------------------

### Simulate Real Mouse Click

Source: https://github.com/eze-is/web-access/blob/main/references/cdp-api.md

Simulates a browser-level mouse click using CDP's `Input.dispatchMouseEvent`. It finds element coordinates and simulates press/release events, mimicking real user interaction and potentially bypassing some anti-automation measures.

```bash
curl -s -X POST "http://localhost:3456/clickAt?target=ID" -d 'button.upload'
```

--------------------------------

### POST /navigate?target=ID

Source: https://github.com/eze-is/web-access/blob/main/references/cdp-api.md

Navigates an existing tab to a new URL. The URL is provided in the POST body, and the target ID is a query parameter.

```APIDOC
## POST /navigate?target=ID

### Description
Navigates an existing tab to a new URL, automatically waiting for the page to load. The target is specified via query parameter, and the URL is sent in the POST body.

### Method
POST

### Endpoint
/navigate

### Parameters
#### Query Parameters
- **target** (string) - Required - The ID of the tab to navigate.
#### Request Body
- **URL** (string) - Required - The URL to navigate to.

### Request Example
```bash
curl -s -X POST --data-raw 'https://example.com' "http://localhost:3456/navigate?target=ID"
```

### Note
Starting from v2.5.3, this endpoint uses POST. The older `GET /navigate?target=...&url=...` is deprecated.
```

--------------------------------

### Navigate Tab to New URL

Source: https://github.com/eze-is/web-access/blob/main/references/cdp-api.md

Navigates an existing tab to a new URL and waits for the page to load. The target ID is a query parameter, and the URL is sent in the POST body. This endpoint was updated to POST in v2.5.3.

```bash
curl -s -X POST --data-raw 'https://example.com' "http://localhost:3456/navigate?target=ID"
```

--------------------------------

### Consistency in POST body usage

Source: https://github.com/eze-is/web-access/blob/main/references/migration-2.5.3.md

Highlights the increased internal consistency by unifying all write operations that transfer arbitrary string payloads to use POST body.

```markdown
Q: 还有哪些 endpoint 用 POST body？
A: 一直都有：`/eval`、`/click`、`/clickAt`、`/setFiles` 全是 POST + body。这次 `/new` `/navigate` 加入后，**所有传输"任意字符串载荷"的写操作都统一走 POST body** —— 内部一致性提升。
```

--------------------------------

### Agent self-inspection checklist

Source: https://github.com/eze-is/web-access/blob/main/references/migration-2.5.3.md

Steps for agents to identify and correct outdated web-access calls in their environment.

```markdown
1. **判断调用是否过时**：搜索字符串 `localhost:3456/new?url=` 或 `localhost:3456/navigate?` 后跟 `&url=`。这两类模式属于 v2.5.2 旧写法。
2. **就地改写**：按上表对照修改成 POST 形式。
3. **更新源文件**：如果旧写法来自 `references/site-patterns/*.md` 中某个站点经验文件，把源文件也一并修正掉（不要只在当前调用上改）—— 这样下次复用同一站点经验时不会再踩坑。
4. **保留 URL 原样**：POST body 是不透明字节流，目标 URL 中的 `?`、`&`、`=`、`#`、`%` 等字符**无需任何转义**，从 DOM/分享链接抓到什么样就传什么样。
```

--------------------------------

### Rationale for breaking change

Source: https://github.com/eze-is/web-access/blob/main/references/migration-2.5.3.md

Explains why a compatibility layer was not implemented and a breaking change was preferred for a cleaner architecture.

```markdown
Q: 为什么不在 proxy 里做兼容（同时支持 GET 和 POST）？
A: 兼容路径会留下永久的"启发式截取 query"代码 + SKILL.md 里"也支持旧写法"的脚注。两条路径长期共存 → Agent 学得不彻底、维护者两套都要测、读代码的人要分辨主路径 vs 兼容路径。把架构债转成了认知债。一次性 breaking change 配合迁移指南，更彻底也更便宜。
```

--------------------------------

### Switch Browser by Restarting Proxy

Source: https://github.com/eze-is/web-access/blob/main/README.md

Restart the CDP proxy to switch browsers. This command first terminates any running proxy process and then restarts the dependency check script, which will re-initialize the proxy.

```bash
pkill -f cdp-proxy.mjs && node "${CLAUDE_SKILL_DIR}/scripts/check-deps.mjs"
```

--------------------------------

### Create New Background Tab

Source: https://github.com/eze-is/web-access/blob/main/references/cdp-api.md

Opens a new background tab and waits for the page to fully load. The URL is passed directly in the POST body. This endpoint was updated to POST in v2.5.3.

```bash
curl -s -X POST --data-raw 'https://example.com' http://localhost:3456/new
```

```bash
curl -s -X POST --data-raw 'https://www.xiaohongshu.com/explore/xxx?xsec_source=app_share&xsec_token=ABC&type=normal' http://localhost:3456/new
```

--------------------------------

### Take Page Screenshot

Source: https://github.com/eze-is/web-access/blob/main/references/cdp-api.md

Captures a screenshot of the specified tab. If a `file` parameter is provided, the image is saved locally; otherwise, the image binary is returned. JPEG format is optionally supported.

```bash
curl -s "http://localhost:3456/screenshot?target=ID&file=/tmp/shot.png"
```

--------------------------------

### Run Environment Check Script

Source: https://github.com/eze-is/web-access/blob/main/README.md

Execute the dependency check script. This is typically done automatically at Agent runtime, but can be run manually. Replace ${CLAUDE_SKILL_DIR} with the actual path if running manually.

```bash
node "${CLAUDE_SKILL_DIR}/scripts/check-deps.mjs"
```

--------------------------------

### POST /setFiles?target=ID

Source: https://github.com/eze-is/web-access/blob/main/references/cdp-api.md

Sets local file paths for a file input element using `DOM.setFileInputFiles`, bypassing the file selection dialog.

```APIDOC
## POST /setFiles?target=ID

### Description
Sets local file paths for a file input element using the `DOM.setFileInputFiles` CDP command, completely bypassing the file selection dialog. The request body must be a JSON object.

### Method
POST

### Endpoint
/setFiles

### Parameters
#### Query Parameters
- **target** (string) - Required - The ID of the tab containing the file input.
#### Request Body
- **selector** (string) - Required - The CSS selector for the file input element.
- **files** (array) - Required - An array of strings, where each string is a local file path to be set.

### Request Example
```bash
curl -s -X POST "http://localhost:3456/setFiles?target=ID" -d '{"selector":"input[type=file]","files":["/path/to/file1.png","/path/to/file2.png"]}'
```
```

--------------------------------

### List Open Browser Tabs

Source: https://github.com/eze-is/web-access/blob/main/references/cdp-api.md

Retrieve a list of all currently open tab targets in the browser. Each item includes the target's ID, title, and URL.

```bash
curl -s http://localhost:3456/targets
```

--------------------------------

### Find URLs from Local Browser History/Bookmarks

Source: https://github.com/eze-is/web-access/blob/main/SKILL.md

Use this command-line tool to search local browser history or bookmarks for specific URLs based on keywords and various filtering options like date, sort order, and browser type.

```bash
node "${CLAUDE_SKILL_DIR}/scripts/find-url.mjs" [关键词...] [--only bookmarks|history] [--browser chrome|edge] [--limit N] [--since 1d|7h|YYYY-MM-DD] [--sort recent|visits]
```

--------------------------------

### CDP Proxy API: Upload Files

Source: https://github.com/eze-is/web-access/blob/main/README.md

Upload files to a file input element within a browser tab. Specify the selector for the input element and the paths to the files. Replace 'ID' with the target tab's identifier.

```bash
curl -s -X POST "http://localhost:3456/setFiles?target=ID" \
  -d '{"selector":"input[type=file]","files":["/path/to/file.png"]}'
```

--------------------------------

### POST /clickAt?target=ID

Source: https://github.com/eze-is/web-access/blob/main/references/cdp-api.md

Simulates a real mouse click at the coordinates of an element identified by a CSS selector using CDP's `Input.dispatchMouseEvent`.

```APIDOC
## POST /clickAt?target=ID

### Description
Simulates a browser-level mouse click using CDP's `Input.dispatchMouseEvent`. It first finds the element by CSS selector, gets its coordinates, and then simulates mouse down and up events. This is useful for triggering file dialogs or bypassing some anti-automation measures.

### Method
POST

### Endpoint
/clickAt

### Parameters
#### Query Parameters
- **target** (string) - Required - The ID of the tab where the click should occur.
#### Request Body
- **cssSelector** (string) - Required - The CSS selector for the element to click.

### Request Example
```bash
curl -s -X POST "http://localhost:3456/clickAt?target=ID" -d 'button.upload'
```
```

--------------------------------

### Set File Input Values

Source: https://github.com/eze-is/web-access/blob/main/references/cdp-api.md

Sets local file paths to a file input element using `DOM.setFileInputFiles`. This bypasses the file selection dialog. The POST body must be a JSON object containing the selector and an array of file paths.

```bash
curl -s -X POST "http://localhost:3456/setFiles?target=ID" -d '{"selector":"input[type=file]","files":["/path/to/file1.png","/path/to/file2.png"]}'
```

--------------------------------

### Upload File to Input Element via CDP Proxy

Source: https://github.com/eze-is/web-access/blob/main/SKILL.md

Use a POST request to the CDP proxy's /setFiles endpoint with a JSON payload specifying the selector for a file input and the local file path to upload.

```bash
curl -s -X POST "http://localhost:3456/setFiles?target=ID" -d '{"selector":"input[type=file]","files":["/path/to/file.png"]}'
```

--------------------------------

### CDP Proxy API: New Tab

Source: https://github.com/eze-is/web-access/blob/main/README.md

Create a new browser tab using the CDP Proxy API. As of v2.5.3, the URL is sent in the POST body. The proxy automatically tracks tabs created this way.

```bash
curl -s -X POST --data-raw 'https://example.com' http://localhost:3456/new
```

--------------------------------

### CDP Proxy API: Click Element at Coordinates

Source: https://github.com/eze-is/web-access/blob/main/README.md

Perform a real mouse click at a specific element identified by a CSS selector. Replace 'ID' with the target tab's identifier.

```bash
curl -s -X POST "http://localhost:3456/clickAt?target=ID" -d '.upload-btn'
```

--------------------------------

### Display Web Access Disclaimer

Source: https://github.com/eze-is/web-access/blob/main/SKILL.md

Before initiating CDP operations, display this disclaimer to the user regarding potential risks of account suspension due to automated browser actions.

```text
温馨提示：部分站点对浏览器自动化操作检测严格，存在账号封禁风险。已内置防护措施但无法完全避免，Agent 继续操作即视为接受。
```

--------------------------------

### Find URL in Local Browser History/Bookmarks

Source: https://github.com/eze-is/web-access/blob/main/SKILL.md

Search local browser history or bookmarks for a given keyword. Useful for accessing previously visited pages or internal organization systems.

```APIDOC
## Find URL in Local Browser History/Bookmarks

### Description

Retrieves URLs from local browser history or bookmarks based on keywords. This is useful when users refer to pages they've previously visited or internal systems not found via public search.

### Command

```bash
node "${CLAUDE_SKILL_DIR}/scripts/find-url.mjs" [keywords...] [--only bookmarks|history] [--browser chrome|edge] [--limit N] [--since 1d|7h|YYYY-MM-DD] [--sort recent|visits]
```

### Parameters

- `[keywords...]`: Space-separated keywords to search for in page titles and URLs. If omitted, searches all entries.
- `--only bookmarks|history`: Filter results to only show bookmarks or history.
- `--browser chrome|edge`: Specify which browser to search (Chrome, Edge, or Chromium-based).
- `--limit N`: Limit the number of results to N.
- `--since 1d|7h|YYYY-MM-DD`: Filter results to entries since a specific time.
- `--sort recent|visits`: Sort results by most recent (`recent`) or by most frequent visits (`visits`). Defaults to most recent.
```

--------------------------------

### CDP Proxy API: Scroll Page

Source: https://github.com/eze-is/web-access/blob/main/README.md

Scroll the browser tab in a specified direction. Replace 'ID' with the target tab's identifier. Supported directions include 'bottom'.

```bash
curl -s "http://localhost:3456/scroll?target=ID&direction=bottom"
```

--------------------------------

### POST /click?target=ID

Source: https://github.com/eze-is/web-access/blob/main/references/cdp-api.md

Performs a JavaScript-based click on an element identified by a CSS selector. Includes automatic scrolling into view.

```APIDOC
## POST /click?target=ID

### Description
Performs a JavaScript-level click (using `el.click()`) on an element identified by a CSS selector. Automatically scrolls the element into view before clicking. Suitable for most common click actions.

### Method
POST

### Endpoint
/click

### Parameters
#### Query Parameters
- **target** (string) - Required - The ID of the tab where the click should occur.
#### Request Body
- **cssSelector** (string) - Required - The CSS selector for the element to click.

### Request Example
```bash
curl -s -X POST "http://localhost:3456/click?target=ID" -d 'button.submit'
```
```

--------------------------------

### POST /eval?target=ID

Source: https://github.com/eze-is/web-access/blob/main/references/cdp-api.md

Executes a JavaScript expression within the context of a specified tab. The JavaScript code is sent in the POST body.

```APIDOC
## POST /eval?target=ID

### Description
Executes a JavaScript expression in the specified tab. The POST body contains the JavaScript code.

### Method
POST

### Endpoint
/eval

### Parameters
#### Query Parameters
- **target** (string) - Required - The ID of the tab to execute the script in.
#### Request Body
- **jsCode** (string) - Required - The JavaScript code to execute.

### Request Example
```bash
curl -s -X POST "http://localhost:3456/eval?target=ID" -d 'document.title'
```

### Response
#### Success Response (200)
- **value** (any) - The result of the JavaScript expression, if successful.
- **error** (string) - An error message if the execution failed.

### Usage Tips
- Supports `awaitPromise` for async expressions.
- Return values must be serializable (string, number, object). DOM nodes require attribute extraction.
- For large data, use `JSON.stringify()` to ensure string return.
```

--------------------------------

### Check CDP Proxy Health

Source: https://github.com/eze-is/web-access/blob/main/references/cdp-api.md

Use this endpoint to verify if the CDP proxy is running and accessible. It returns the connection status.

```bash
curl -s http://localhost:3456/health
```

--------------------------------

### Evaluate JavaScript in Tab

Source: https://github.com/eze-is/web-access/blob/main/references/cdp-api.md

Executes a JavaScript expression within the context of a specified tab. The JS code is sent as the POST body. Supports `awaitPromise` for async expressions. Results must be serializable.

```bash
curl -s -X POST "http://localhost:3456/eval?target=ID" -d 'document.title'
```

--------------------------------

### Extract Image URL using /eval

Source: https://github.com/eze-is/web-access/blob/main/SKILL.md

When content is within an image, use the /eval endpoint to directly retrieve the image URL from the DOM. This provides more precise targeting than full-page screenshots.

```bash
curl -s "http://localhost:3456/eval?target=ID&expr=document.querySelector('img').src"
```

--------------------------------

### Simulate Element Click (JS)

Source: https://github.com/eze-is/web-access/blob/main/references/cdp-api.md

Performs a JavaScript click on an element identified by a CSS selector. It automatically scrolls the element into view before clicking. Suitable for most common click interactions.

```bash
curl -s -X POST "http://localhost:3456/click?target=ID" -d 'button.submit'
```

--------------------------------

### Browser CDP Proxy API

Source: https://github.com/eze-is/web-access/blob/main/SKILL.md

Interact with the user's browser using the CDP Proxy API. This allows for programmatic control over browser tabs, navigation, and element interaction.

```APIDOC
## Browser CDP Proxy API

### Description

Interact with the user's browser (Chrome, Edge, Chromium) via the CDP Proxy API. This mode leverages existing browser sessions, including login states, and operates in background tabs to minimize intrusion.

### Starting the Proxy

Ensure dependencies are checked and the proxy is running:

```bash
node "${CLAUDE_SKILL_DIR}/scripts/check-deps.mjs"
```

The script checks for Node.js and browser debugging ports, and starts the proxy if it's not running.

### API Endpoints

All operations are performed via `curl` requests to the local proxy API (default port 3456).

#### List Open Tabs

```bash
curl -s http://localhost:3456/targets
```

#### Create New Background Tab

Sends the URL in the POST body to avoid issues with query parameters.

```bash
curl -s -X POST --data-raw 'https://example.com' http://localhost:3456/new
```

#### Get Tab Information

```bash
curl -s "http://localhost:3456/info?target=ID"
```

#### Execute Arbitrary JavaScript

Used for DOM querying, data extraction, element manipulation, triggering state changes, form submission, and calling internal methods.

```bash
curl -s -X POST "http://localhost:3456/eval?target=ID" -d 'document.title'
```

#### Capture Page Render State (including video frames)

Saves a screenshot to a specified file path.

```bash
curl -s "http://localhost:3456/screenshot?target=ID&file=/tmp/shot.png"
```

#### Navigate

Navigates to a new URL. The URL is sent in the POST body, and the target ID is in the query parameter.

```bash
curl -s -X POST --data-raw 'https://example.com' "http://localhost:3456/navigate?target=ID"
```

#### Go Back

Navigates back in the tab's history.

```bash
curl -s "http://localhost:3456/back?target=ID"
```

#### Click Element (JS `el.click()`)

Performs a simple and fast click on an element identified by a CSS selector. Covers most scenarios.

```bash
curl -s -X POST "http://localhost:3456/click?target=ID" -d 'button.submit'
```

#### Click Element (Simulated Mouse Event)

Uses CDP `Input.dispatchMouseEvent` to simulate a user's mouse gesture. Can trigger file dialogs.

```bash
curl -s -X POST "http://localhost:3456/clickAt?target=ID" -d 'button.upload'
```

#### Set File Input Value

Uploads a local file by setting the value of a file input element. Bypasses the file selection dialog.

```bash
curl -s -X POST "http://localhost:3456/setFiles?target=ID" -d '{"selector":"input[type=file]","files":["/path/to/file.png"]}'
```
```

--------------------------------

### CDP Proxy API Endpoints

Source: https://github.com/eze-is/web-access/blob/main/README.md

The CDP Proxy provides a set of HTTP endpoints to interact with browser tabs. These operations allow for advanced browser automation tasks.

```APIDOC
## CDP Proxy API

Proxy through WebSocket directly connects to the browser (compatible with `chrome://inspect` / `edge://inspect` methods, no command-line arguments needed to start), providing an HTTP API.

### Starting the Proxy

```bash
# Agent automatically manages Proxy lifecycle, no manual start needed
node "${CLAUDE_SKILL_DIR}/scripts/cdp-proxy.mjs" &
```

### Page Operations

#### New Tab

Creates a new tab.

*   **Method**: POST
*   **Endpoint**: `/new`
*   **Request Body**: URL of the page to open (e.g., `https://example.com`)
*   **Example**: `curl -s -X POST --data-raw 'https://example.com' http://localhost:3456/new`

#### Evaluate JavaScript

Executes JavaScript code within a specified target tab.

*   **Method**: POST
*   **Endpoint**: `/eval?target=ID`
*   **Parameters**: 
    *   `target` (string) - Required - The ID of the target tab.
*   **Request Body**: JavaScript expression to evaluate (e.g., `document.title`)
*   **Example**: `curl -s -X POST "http://localhost:3456/eval?target=ID" -d 'document.title'`

#### Click (JS Selector)

Performs a click action using a JavaScript selector.

*   **Method**: POST
*   **Endpoint**: `/click?target=ID`
*   **Parameters**: 
    *   `target` (string) - Required - The ID of the target tab.
*   **Request Body**: CSS selector for the element to click (e.g., `button.submit`)
*   **Example**: `curl -s -X POST "http://localhost:3456/click?target=ID" -d 'button.submit'`

#### Click (Real Mouse)

Performs a click action simulating a real mouse click.

*   **Method**: POST
*   **Endpoint**: `/clickAt?target=ID`
*   **Parameters**: 
    *   `target` (string) - Required - The ID of the target tab.
*   **Request Body**: CSS selector for the element to click (e.g., `.upload-btn`)
*   **Example**: `curl -s -X POST "http://localhost:3456/clickAt?target=ID" -d '.upload-btn'`

#### File Upload

Uploads files to a file input element.

*   **Method**: POST
*   **Endpoint**: `/setFiles?target=ID`
*   **Parameters**: 
    *   `target` (string) - Required - The ID of the target tab.
*   **Request Body**: JSON object containing the selector and file paths.
    *   `selector` (string) - Required - The CSS selector for the file input element.
    *   `files` (array of strings) - Required - An array of absolute paths to the files to upload.
*   **Example**: `curl -s -X POST "http://localhost:3456/setFiles?target=ID" \
  -d '{"selector":"input[type=file]","files":["/path/to/file.png"]}'`

#### Screenshot

Takes a screenshot of the current tab.

*   **Method**: GET
*   **Endpoint**: `/screenshot?target=ID&file=/tmp/shot.png`
*   **Parameters**: 
    *   `target` (string) - Required - The ID of the target tab.
    *   `file` (string) - Required - The path to save the screenshot file.
*   **Example**: `curl -s "http://localhost:3456/screenshot?target=ID&file=/tmp/shot.png"`

#### Scroll

Scrolls the page within the specified tab.

*   **Method**: GET
*   **Endpoint**: `/scroll?target=ID&direction=bottom`
*   **Parameters**: 
    *   `target` (string) - Required - The ID of the target tab.
    *   `direction` (string) - Required - The direction to scroll (`top`, `bottom`, `left`, `right`).
*   **Example**: `curl -s "http://localhost:3456/scroll?target=ID&direction=bottom"`

#### Close Tab

Closes a specified tab.

*   **Method**: GET
*   **Endpoint**: `/close?target=ID`
*   **Parameters**: 
    *   `target` (string) - Required - The ID of the tab to close.
*   **Example**: `curl -s "http://localhost:3456/close?target=ID"`

#### Health Check

Checks the status of the proxy, including the number of managed tabs.

*   **Method**: GET
*   **Endpoint**: `/health`
*   **Example**: `curl -s "http://localhost:3456/health"`

### Tab Idle Timeout

Tabs created via `/new` are automatically closed after 15 minutes of inactivity to prevent orphaned tabs if the Agent exits unexpectedly. This timeout can be adjusted using the `CDP_TAB_IDLE_TIMEOUT` environment variable (in milliseconds).
```

--------------------------------

### CDP Proxy API: Health Check

Source: https://github.com/eze-is/web-access/blob/main/README.md

Check the status of the CDP Proxy, including the number of managed tabs. This is useful for monitoring the proxy's operational state.

```bash
curl -s "http://localhost:3456/health"
```

--------------------------------

### Scroll Page Vertically

Source: https://github.com/eze-is/web-access/blob/main/references/cdp-api.md

Scrolls the specified tab by a given amount or to a specific position. Supports directions like 'down', 'up', 'top', and 'bottom'. Includes a small delay after scrolling to allow lazy loading.

```bash
curl -s "http://localhost:3456/scroll?target=ID&y=3000"
```

```bash
curl -s "http://localhost:3456/scroll?target=ID&direction=bottom"
```

--------------------------------

### CDP Proxy API: Close Tab

Source: https://github.com/eze-is/web-access/blob/main/README.md

Close a specific browser tab. Replace 'ID' with the target tab's identifier.

```bash
curl -s "http://localhost:3456/close?target=ID"
```

--------------------------------

### Close a Specific Tab

Source: https://github.com/eze-is/web-access/blob/main/references/cdp-api.md

Closes the browser tab identified by the provided target ID. Ensure you have the correct `targetId` from the `/targets` endpoint.

```bash
curl -s "http://localhost:3456/close?target=TARGET_ID"
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.