OpenCLI Documentation

Technical Documentation: jackwener/OpenCLI

ℹ️ Provenance: Multi-Tier Ingestion · CodeWiki Reference

Overview (`README.md`) Copy Section

OpenCLI

Convert any website into a CLI & run Browser Use on your logged-in Chrome.
Turn websites and browser sessions into deterministic interfaces for humans and AI agents.
Or run Browser Use against any page — navigate, fill forms, click, extract, automate.

OpenCLI is a general-purpose browser automation CLI for AI agents and an agent-browser alternative. Navigate, inspect, click, fill forms, extract, and screenshot websites without a site adapter. Built-in adapters add reusable, deterministic site commands. See OpenCLI vs agent-browser and migration.

OpenCLI gives you one surface for three different kinds of automation:

• Use built-in adapters for sites like Bilibili, Zhihu, Xiaohongshu, Reddit, HackerNews, Twitter/X, and many more.
• Let AI Agents operate any website — install the opencli-browser skill in your AI agent (Claude Code, Cursor, etc.), and it can navigate, click, type/fill, extract, and inspect any page through your logged-in browser via opencli browser primitives.
• Write new adapters end-to-end with opencli browser + the opencli-adapter-author skill, which guides from first recon through field decoding, code, and opencli adapter test.

Agent command contract Copy Chapter

Commands default to JSON: { "ok": true, "data": ... }; failures return
{ "ok": false, "error": { "code": "...", "message": "...", "hint": "..." } }
on stdout with a nonzero exit code. Logs use stderr. Explicit human formats,
help, version and completion retain their own formats; browser follow modes use JSON Lines.

opencli list search --site github
opencli browser open https://example.com --session research
opencli browser network --static --session research
opencli browser chrome describe
opencli adapter check github/search

list returns compact, paginated capabilities (commands, total, nextOffset);
read arguments with <command> --help -f json. Page scope is --session, native
Chrome calls need no session. Adapter authoring is grouped under adapter init|check|test.
state --diagnostics and network --static replace analyze and discover.
This changes CLI syntax and JSON output. JS adapters keep cli({...}),
func(args) and func(page, args); adapter defaultFormat no longer changes the CLI default.

Quick Start Copy Chapter

1. Install OpenCLI Copy Section

For desktop use, start with OpenCLIApp. It bundles the OpenCLI runtime,
keeps the managed opencli command installed, and gives you a system tray UI
for setup, diagnostics, updates, browser-login keepalive, and Web → Markdown.

Option A — OpenCLIApp (recommended for macOS / Windows):
Download the latest app from https://opencli.info/download, install it, then
open the app once and use the System page to install or repair the opencli
command.

Option B — npm global install (CLI-only / CI / servers):
OpenCLI requires Node.js >= 20.18.1 when installed through npm.

node --version
npm install @jackwener/opencli

2. Install the Browser Bridge Extension Copy Section

OpenCLI connects to Chrome/Chromium through a lightweight Browser Bridge extension plus a small local daemon. The daemon auto-starts when needed.

Option A — Chrome Web Store (recommended):
Install OpenCLI from the Chrome Web Store.

Option B — Manual install:

1. Download the latest opencli-extension-v{version}.zip from the GitHub Releases page.
2. Unzip it, open chrome://extensions, and enable Developer mode.
3. Click Load unpacked and select the unzipped folder.

3. Verify the setup Copy Section

opencli doctor

4. Optional: name your Chrome profile Copy Section

Each Chrome profile runs its own OpenCLI extension instance. If you use multiple Chrome profiles, list the connected profiles and assign local aliases:

opencli profile list
opencli profile rename <contextId> work
opencli profile use work
opencli --profile work browser main state

With only one connected profile, OpenCLI uses it automatically. With multiple connected profiles and no default, OpenCLI asks you to choose instead of guessing.

5. Run your first commands Copy Section

opencli list
opencli hackernews top --limit 5
opencli bilibili hot --limit 5

For Humans Copy Chapter

Use OpenCLI directly when you want a reliable command instead of a live browser session:

• opencli list shows every registered command.
• opencli <site> <command> runs a built-in or generated adapter.
• opencli doctor helps diagnose browser connectivity.

Extending OpenCLI Copy Chapter

If you want to add your own commands, start with the Extending OpenCLI guide. README keeps this short; the guide covers the directory layout, source-control model, and install commands.

Close temporary browser tabs after use Copy Section

To remove temporary owned tabs when a workflow finishes:

export OPENCLI_CLOSE_OWNED_TAB=1
opencli web read --url https://example.com --stdout true
# Multi-step browser sessions stay open between calls; close explicitly at the end:
opencli browser close --session research

This opts into closing only the current lease's owned tab. Chrome closes its
window automatically if no tabs remain; existing user pages and other sessions
are preserved. Bound tabs are detached and kept open. The default reusable
container policy, idle expiry, --keep-tab true, and persistent site sessions
remain unchanged. Use --site-session ephemeral for one-shot reads of adapters
that otherwise keep a persistent site session.

Cleanup uses a dedicated action, so older extensions reject it without releasing
the lease, and requires an extension acknowledgement. If cleanup fails or the extension
is too old, a warning reports it separately from the site action. Retry explicit
browser cleanup, or close a remaining one-shot adapter tab manually; do not
repeat a completed site write. Explicit browser close also exits
with an error; a one-shot adapter can still return its already-completed result.

For AI Agents Copy Chapter

OpenCLI's browser commands are designed to be used by AI Agents — not run manually. Install skills into your AI agent (Claude Code, Cursor, etc.), and the agent operates websites on your behalf using your logged-in Chrome session.

Install skills (also refreshes existing installs) Copy Section

npx skills add jackwener/opencli

Or install only what you need:

npx skills add jackwener/opencli --skill opencli-adapter-author
npx skills add jackwener/opencli --skill opencli-autofix
npx skills add jackwener/opencli --skill opencli-browser
npx skills add jackwener/opencli --skill opencli-usage

Which skill to use Copy Section

How it works Copy Section

Once opencli-browser is installed, your AI agent can:

1. Navigate to any URL using your logged-in browser
2. Read page content via structured DOM snapshots (not screenshots)
3. Interact — click buttons, fill forms, select options, press keys
4. Extract data from the page or intercept network API responses
5. Wait for elements, text, or page transitions

The agent handles all the opencli browser commands internally — you just describe what you want done in natural language.

Skill references:

• skills/opencli-browser/SKILL.md — drive Chrome ad-hoc (navigate, fill forms, click, extract)
• skills/opencli-adapter-author/SKILL.md — write a new adapter end-to-end
• skills/opencli-autofix/SKILL.md — repair broken adapters
• skills/opencli-usage/SKILL.md — command and site reference

Available browser commands include open, state, click, type, fill, select, keys, wait, get, find, extract, frames, screenshot, scroll, back, eval, network, tab list, tab new, tab select, tab close, chrome describe, chrome call, and close.

opencli browser commands require a --session <name> option for page operations. opencli browser --session work open and opencli browser --session work tab new [url] both return a target ID. Use opencli browser --session work tab list to inspect target IDs, then pass --tab <targetId> to route a command to a specific tab. tab new creates a new tab without changing the default browser target; only tab select <targetId> promotes that tab to the default target for later untargeted commands in the same session.

Writing a new adapter Copy Chapter

When the site you need is not yet covered, use the opencli-adapter-author skill end-to-end:

1. Recon the site and pick a pattern (SPA / SSR / JSONP / Token / Streaming).
2. Discover the right endpoint — network inspection, initial state, bundle search, token trace, or interceptor fallback.
3. Pick auth — PUBLIC / COOKIE / INTERCEPT / UI / LOCAL.
4. Decode response fields and design output columns.
5. opencli browser recon analyze → opencli browser recon init <site>/<name> → write adapter → opencli browser recon verify <site>/<name>.
6. Site knowledge persists to ~/.opencli/sites/<site>/ so the next adapter for the same site starts from context.

Configuration Copy Chapter

opencli browser * requires an explicit --session <name> option for page operations, uses a foreground browser window by default, and keeps that session's tab lease until opencli browser --session <session> close or idle cleanup. Browser-backed adapters use a background adapter window and release one-shot tab leases by default. Interactive adapters can declare siteSession: 'persistent' to keep a stable site tab for continuity; pass --site-session ephemeral for a one-shot tab.

Built-in Commands Copy Chapter

Curated highlights — → see all 100+ supported sites & commands (douyin / weibo / spotify / 1688 / quark / nowcoder / google-scholar / hupu / xianyu / weread / weread-official / xiaoyuzhou / Chess.com / and more).

Download Support Copy Chapter

OpenCLI supports downloading images, videos, and articles from supported platforms.

For video downloads, install yt-dlp first: brew install yt-dlp

opencli xiaohongshu download "https://www.xiaohongshu.com/search_result/<id>?xsec_token=..." --output ./xhs
opencli xiaohongshu download "https://xhslink.com/..." --output ./xhs
opencli rednote download "https://www.rednote.com/search_result/<id>?xsec_token=..." --output ./rednote
opencli bilibili download BV1xxx --output ./bilibili
opencli twitter download elonmusk --limit 20 --output ./twitter
opencli 1688 download 841141931191 --output ./1688-downloads
opencli xiaoyuzhou download 69b3b675772ac2295bfc01d0 --output ./xiaoyuzhou
opencli xiaoyuzhou transcript 69dd0c98e2c8be31551f6a33 --output ./xiaoyuzhou-transcripts

opencli xiaoyuzhou download and transcript require local Xiaoyuzhou credentials in ~/.opencli/xiaoyuzhou.json.

Output Formats Copy Chapter

All built-in commands support --format / -f with json (default), table, yaml, md, and csv.

opencli bilibili hot -f json    # Pipe to jq or LLMs
opencli bilibili hot -f csv     # Spreadsheet-friendly
opencli bilibili hot -v         # Verbose: show pipeline debug steps

Exit Codes Copy Chapter

opencli follows Unix sysexits.h so CI / scripts can branch on failure mode: 0 success, 66 empty result, 69 Browser Bridge down, 75 timeout, 77 auth required, 78 config error, 130 Ctrl-C. Full reference: docs/guide/exit-codes.md.

Plugins Copy Chapter

Extend OpenCLI with community-contributed adapters:

opencli plugin install github:user/opencli-plugin-my-tool
opencli plugin list
opencli plugin update --all
opencli plugin uninstall my-tool

Albato, Goofish and Taobao use local adapter-subdirectory installation; see the installation notes.

See Plugins Guide for creating your own plugin.

Testing Copy Chapter

See TESTING.md for how to run and write tests.

Troubleshooting Copy Chapter

• "Extension not connected" — Ensure the Browser Bridge extension is installed from the Chrome Web Store and enabled in chrome://extensions.
• "attach failed: Cannot access a chrome-extension:// URL" — Another extension may be interfering. Try disabling other extensions temporarily.
• Empty data or 'Unauthorized' error — Your Chrome/Chromium login session may have expired. Navigate to the target site and log in again.
• Node API errors / missing fetch / startup crash on old Node — OpenCLI requires Node.js >= 20.18.1. Run node --version, upgrade Node if needed, then retry.
• Daemon issues — Check status: curl localhost:19825/status · View logs: curl localhost:19825/logs

Star History Copy Chapter

License Copy Chapter

Apache-2.0

Overview (`cases/README.md`) Copy Section

Use Cases

Real-world examples of how people use OpenCLI.

Contributing Copy Chapter

Want to share your use case? Submit a PR that adds a new .md file to this directory.

Each file is one use case — describe what you wanted to do, which commands you used, and the result.

Overview (`extension/README.md`) Copy Section

OpenCLI Browser Bridge Extension

The extension connects Chrome tabs to the local OpenCLI daemon. It uses Chrome
extension APIs only as a transport and browser-control layer for explicit CLI
commands.

Permission Notes Copy Chapter

• debugger: sends CDP commands to OpenCLI-controlled or bound tabs.
• tabs / tabGroups: manages the dedicated OpenCLI automation container and
  reports selected tab metadata back to the CLI.
• cookies: reads cookies for browser-backed adapters that need authenticated
  fetches.
• downloads: surfaces download lifecycle to opencli browser wait download.
  The extension observes started / in-progress / completed / failed downloads so
  the CLI can wait for a file triggered by an automation command. OpenCLI
  filters by the command's filename/URL pattern and timeout, and does not modify,
  redirect, or persist browser download history.

Suggested Chrome Web Store justification for downloads:

This extension uses chrome.downloads to surface download lifecycle
(started / in-progress / completed / failed) to the OpenCLI command-line tool,
so agents can wait for downloads triggered during an automation workflow. The
command filters by a user-provided filename or URL pattern and timeout. We do
not modify, redirect, or persist user download history.

Index (`docs/index.md`) Copy Section

layout: home
hero:
name: OpenCLI
text: Make any website your CLI
tagline: General-purpose browser automation · Reuse Chrome login · Reusable site commands
actions:
- theme: brand
text: Get Started
link: /guide/getting-started
- theme: alt
text: OpenCLI vs agent-browser
link: /guide/agent-browser-alternative
- theme: alt
text: View on GitHub
link: https://github.com/jackwener/opencli

features:

• icon: 🌐
  title: Browser Automation
  details: "General-purpose browser control for AI agents: navigate, click, fill, extract, and screenshot. No site adapter required."
• icon: 🔐
  title: Account Safe
  details: Reuses Chrome's logged-in state. Your credentials never leave the browser — no tokens, no exposed passwords.
• icon: 🤖
  title: AI Agent Ready
  details: "Browser primitives plus adapter-authoring skills give AI agents a repeatable loop for recon, extraction, verification, and adapter writing."
• icon: 💰
  title: No Built-in LLM Dependency
  details: Commands run without LLM inference. An AI agent choosing actions still has its own model costs.
• icon: 🔁
  title: Deterministic Adapters
  details: Same command, same output schema, every time. Pipeable, scriptable, CI-friendly.

Adapters Index (`docs/adapters/index.md`) Copy Section

All Adapters

Run opencli list for the live registry.

Browser Adapters Copy Chapter

Public API Adapters Copy Chapter

Guide Getting Started (`docs/guide/getting-started.md`) Copy Section

Getting Started

Make any website your CLI.
Zero risk · Reuse Chrome login · AI-powered discovery · Browser automation

OpenCLI turns any website into a command-line interface — Bilibili, Zhihu, 小红书, Twitter/X, Reddit, YouTube, and many more — powered by browser session reuse and AI-native discovery.

OpenCLI is a general-purpose browser automation CLI and an agent-browser alternative. Browse unfamiliar sites without adapters; use adapters for reusable site commands. See the migration guide.

Highlights Copy Chapter

• Browser Automation — browser gives AI agents direct browser control: click, type/fill, extract, screenshot — fully scriptable.
• Website → CLI — Turn any website into a deterministic CLI: 100+ site surfaces are already registered, or author your own with the opencli-adapter-author skill.
• Account-safe — Reuses Chrome's logged-in state; your credentials never leave the browser.
• AI Agent ready — opencli browser * primitives (open / network / state / eval) and adapter init|check|test drive the adapter-authoring loop.
• No built-in LLM dependency — Commands run without LLM inference; an AI agent orchestrating actions still has its own model costs.
• Deterministic adapters — Site commands provide structured output schemas. Pipeable, scriptable, CI-friendly.

Quick Start Copy Chapter

Install via npm Copy Section

npm install @jackwener/opencli

Browse without a site adapter Copy Section

Set up Browser Bridge, then run:

opencli doctor
opencli browser --session work open https://example.com
opencli browser --session work state
opencli browser --session work extract
opencli browser --session work close

Install the opencli-browser skill so your AI agent can use the same browser primitives:

npx skills add jackwener/opencli --skill opencli-browser

Basic Usage Copy Section

opencli list                              # See all commands
opencli hackernews top --limit 5          # Public API, no browser
opencli bilibili hot --limit 5            # Browser command
opencli zhihu hot -f json                 # JSON output

Output Formats Copy Section

All built-in commands support --format / -f:

opencli bilibili hot -f table   # Rich terminal table
opencli bilibili hot -f json    # JSON (pipe to jq or LLMs)
opencli bilibili hot -f yaml    # YAML (human-readable)
opencli bilibili hot -f md      # Markdown
opencli bilibili hot -f csv     # CSV
opencli bilibili hot -v         # Verbose: show pipeline debug

Tab Completion Copy Section

OpenCLI supports intelligent tab completion to speed up command input:

# Add shell completion to your startup config
echo 'eval "$(opencli completion zsh)"' >> ~/.zshrc              # Zsh
echo 'eval "$(opencli completion bash)"' >> ~/.bashrc            # Bash
echo 'opencli completion fish | source' >> ~/.config/fish/config.fish  # Fish

# Restart your shell, then press Tab to complete:
opencli [Tab]          # Complete site names (bilibili, zhihu, twitter...)
opencli bilibili [Tab] # Complete commands (hot, search, me, download...)

The completion includes:

• All available sites and adapters
• Built-in commands (list, validate, verify, browser, doctor, plugin...)
• Command aliases
• Real-time updates as you add new adapters

Next Steps Copy Chapter

• Installation details
• Browser Bridge setup
• Extending OpenCLI — custom commands and plugins
• Plugins — extend with community adapters
• All available adapters
• For developers / AI agents

Zh Index (`docs/zh/index.md`) Copy Section

layout: home
hero:
name: OpenCLI
text: 让任何网站成为你的 CLI
tagline: General-purpose browser automation · 复用 Chrome 登录态 · 可复用站点命令
actions:
- theme: brand
text: 快速开始
link: /zh/guide/getting-started
- theme: alt
text: 替代 agent-browser
link: /zh/guide/agent-browser-alternative
- theme: alt
text: 在 GitHub 查看
link: https://github.com/jackwener/opencli

features:

• icon: 🌐
  title: 浏览器自动化
  details: AI Agent 直接导航、点击、填表、提取和截图。操作网页无需 site adapter。
• icon: 🔐
  title: 账号安全
  details: 复用 Chrome 登录态，凭证永远不会离开浏览器 — 无 token，无密码泄露。
• icon: 🤖
  title: AI Agent 就绪
  details: Browser 原语加上适配器编写 skill，让 AI Agent 可以稳定完成侦察、提取、验证和适配器落地。
• icon: 💰
  title: 无内置 LLM 依赖
  details: 命令本身不调用 LLM。由 AI Agent 决定操作步骤时，仍有 Agent 自身的 model costs。
• icon: 🔁
  title: Adapter 确定性输出
  details: 相同命令，相同输出结构，每次一致。可管道、可脚本、CI 友好。

Zh Adapters Index (`docs/zh/adapters/index.md`) Copy Section

所有适配器

运行 opencli list 查看完整命令列表。

详细文档请参考 英文版本。

Zh Guide Getting Started (`docs/zh/guide/getting-started.md`) Copy Section

快速开始

让任何网站成为你的 CLI。
零风险 · 复用 Chrome 登录态 · AI 驱动发现 · 浏览器自动化

OpenCLI 将任何网站变成命令行界面 — Bilibili、知乎、小红书、Twitter/X、Reddit、YouTube 等 — 基于浏览器会话复用和 AI 原生发现。

OpenCLI 是 general-purpose browser automation CLI，可以作为 agent-browser 的替代工具。操作陌生网站无需 adapter；adapters 用于可复用的站点命令。参见 迁移指南。

安装 Copy Chapter

npm install @jackwener/opencli

直接操作网页（无需 adapter） Copy Chapter

先完成 Browser Bridge 设置，然后运行：

opencli doctor
opencli browser --session work open https://example.com
opencli browser --session work state
opencli browser --session work extract
opencli browser --session work close

安装 opencli-browser skill，让 AI Agent 使用同一组 browser primitives：

npx skills add jackwener/opencli --skill opencli-browser

基本使用 Copy Chapter

opencli list                              # 查看所有命令
opencli hackernews top --limit 5          # 公开 API，无需浏览器
opencli bilibili hot --limit 5            # 浏览器命令
opencli zhihu hot -f json                 # JSON 输出

输出格式 Copy Chapter

所有命令支持 --format / -f：

opencli bilibili hot -f table   # 默认：终端表格
opencli bilibili hot -f json    # JSON
opencli bilibili hot -f yaml    # YAML
opencli bilibili hot -f md      # Markdown
opencli bilibili hot -f csv     # CSV

终端自动补全 Copy Chapter

OpenCLI 支持智能的 Tab 自动补全，加快命令输入：

# 把自动补全加入 shell 启动配置
echo 'eval "$(opencli completion zsh)"' >> ~/.zshrc              # Zsh
echo 'eval "$(opencli completion bash)"' >> ~/.bashrc            # Bash
echo 'opencli completion fish | source' >> ~/.config/fish/config.fish  # Fish

# 重启 shell 后，按 Tab 键补全：
opencli [Tab]          # 补全站点名称（bilibili、zhihu、twitter...）
opencli bilibili [Tab] # 补全命令（hot、search、me、download...）

补全功能包含：

• 所有可用的站点和适配器
• 内置命令（list、validate、verify、browser、doctor、plugin、adapter...）
• 命令别名
• 新增适配器时的实时更新

下一步 Copy Chapter

• 安装详情
• Browser Bridge 设置
• 扩展 OpenCLI：自定义命令和 plugin
• 所有适配器
• 开发者指南

Comparison (`docs/comparison.md`) Copy Section

title: OpenCLI Browser Automation Comparison Copy Chapter

Comparison Guide

OpenCLI combines general-purpose browser automation with reusable site adapters. This guide evaluates where opencli excels, where it's a viable option, and where other tools are a better fit.

Looking for an agent-browser alternative? OpenCLI supports the general-purpose browser loop without site adapters. See OpenCLI vs agent-browser for a workflow comparison and command migration guide.

At a Glance Copy Chapter

Scenario Comparison Copy Chapter

1. Scheduled Batch Data Extraction Copy Section

"I want to pull trending posts from Bilibili/Reddit/HackerNews every hour into my pipeline."

Why opencli wins here: A command like opencli bilibili hot -f json returns the same structured schema every time, costs nothing to run, and finishes in seconds. For recurring data extraction from known sites, pre-built adapters beat LLM-driven approaches on cost, speed, and reliability.

2. AI Agent Site Operations Copy Section

"My AI agent needs to search Twitter, read Reddit threads, or post to Xiaohongshu."

Why opencli wins here: When your agent needs twitter search "AI news" -f json, a deterministic command that returns in seconds is strictly better than an LLM clicking through a webpage. The agent saves tokens for reasoning, not navigation.

3. Authenticated Operations (Login-Required Sites) Copy Section

"I need to access my bookmarks, post content, or interact with sites that require login."

Why opencli wins here: The Browser Bridge extension reuses your existing Chrome login state in real-time. You log in once in Chrome, and opencli commands work immediately. No OAuth setup, no API keys, no credential files.

4. General Web Browsing & Exploration Copy Section

"I need to explore an unknown website, fill forms, or navigate complex multi-step flows."

opencli supports this directly. An AI agent can use the opencli-browser skill and opencli browser primitives to explore unknown websites and carry out multi-step tasks through your logged-in browser. No pre-built adapter is required. For recurring workflows, an adapter packages those operations into a reusable, deterministic command.

Key Trade-offs Copy Chapter

opencli's Strengths Copy Section

• General-purpose browser automation — Agents can operate websites through opencli browser primitives without writing or installing a site adapter.
• No built-in LLM dependency — Adapter commands and browser primitives run without LLM inference. An AI agent driving the browser still incurs its own model costs.
• Deterministic adapter output — Adapter commands provide structured schemas. Pipeable, scriptable, CI-friendly.
• Speed — Adapter commands return in seconds, not minutes.
• Broad platform coverage — 100+ registered site surfaces spanning global platforms (Reddit, HackerNews, Twitter, YouTube) and Chinese platforms (Bilibili, Zhihu, Xiaohongshu, Douban, Weibo) with adapters that understand local anti-bot patterns.
• Easy to extend — Drop a .js adapter into the clis/ folder for auto-registration. Contributing a new site adapter is straightforward.

opencli's Limitations Copy Section

• Ready-made command coverage varies — Site-specific commands require adapters, but general browser automation does not. Use opencli browser on sites without adapters, and add an adapter when a workflow needs a reusable command.
• Adapter maintenance — When a website updates its DOM or API, the corresponding adapter may need updating. The community maintains these, but breakage is possible.
• Browser workflows need orchestration — For tasks without adapters, a script or AI agent must choose actions and handle page state using the browser primitives. General-purpose access does not make every workflow a single deterministic command.

Choosing a Workflow Copy Chapter

Use opencli's adapters for ready-made commands and its general-purpose browser primitives for exploration or tasks without adapters:

Has adapter?  ──yes──▶  opencli <site> <command> (deterministic)
     │
     no
     │
     ▼
Explore site / run task with opencli browser (script or AI agent)
     │
     ▼
Recurring?    ──yes──▶  Package the workflow as an opencli adapter

Further Reading Copy Chapter

• Architecture Overview
• Writing a TypeScript Adapter
• Testing Guide
• AI Workflow
• Contributing Guide

Advanced Android Chrome (`docs/advanced/android-chrome.md`) Copy Section

Using OpenCLI with Android Chrome

OpenCLI can control Chrome on a connected Android device via ADB port forwarding and CDPBridge — no extra tools or custom builds required. The same adapters that run on desktop Chrome work identically on Android, reusing whatever cookies are already in the mobile browser.

How It Works Copy Chapter

Android Chrome supports remote debugging via CDP. The device exposes a local Unix socket that ADB can forward to a TCP port on your machine. OpenCLI's CDPBridge then connects to that port exactly as it would to any other CDP endpoint.

OpenCLI (CDPBridge)
    │  WebSocket (CDP)
    ▼
localhost:9222                ← ADB forward
    │  adb forward
    ▼
Android device
  chrome_devtools_remote      ← Chrome's Unix debug socket

No Chrome extension, no daemon process — just a direct CDP WebSocket connection.

Prerequisites Copy Chapter

On the Android device:

1. Settings → About Phone → tap Build Number 7 times to enable Developer Options
2. Settings → Developer Options → enable USB Debugging
3. In Chrome for Android, open chrome://flags, search for DevTools remote debugging, and enable it (Chrome 119+). On older versions this is on by default when USB debugging is active.

On your machine:

• Android Debug Bridge (ADB) installed and on $PATH
• OpenCLI installed (npm install opencli)

Step-by-Step Setup Copy Chapter

1. Connect the device Copy Section

adb devices

Expected output:

List of devices attached
R5CT443TRDM    device

If the device shows as unauthorized, check for a "Allow USB Debugging?" prompt on the phone and tap Allow.

2. Forward the CDP port Copy Section

adb forward tcp:9222 localabstract:chrome_devtools_remote

3. Verify the connection Copy Section

curl http://localhost:9222/json

A successful response lists the open tabs:

[
  {
    "id": "3941",
    "title": "Hacker News",
    "type": "page",
    "url": "https://news.ycombinator.com",
    "webSocketDebuggerUrl": "ws://localhost:9222/devtools/page/3941"
  }
]

4. Run any OpenCLI command Copy Section

export OPENCLI_CDP_ENDPOINT=http://localhost:9222
opencli hackernews top --limit 5

Targeting a Specific Tab Copy Chapter

When multiple tabs are open, CDPBridge picks the best one automatically using a scoring algorithm (prefer type=page, real URLs over about:blank, etc.). To override this, set OPENCLI_CDP_TARGET to a substring of the tab's title or URL:

OPENCLI_CDP_TARGET="twitter" opencli twitter trending

You can also connect directly to a specific tab's WebSocket URL (from /json):

OPENCLI_CDP_ENDPOINT=ws://localhost:9222/devtools/page/3941 opencli ...

Using Login-Required Adapters Copy Chapter

Adapters that use the cookie strategy (most social/content sites) need you to be logged in on the Android device. The cookies are already in Android Chrome — OpenCLI reads them automatically over CDP.

To check whether an adapter requires login:

opencli zhihu hot --help
# Strategy: cookie | Browser: yes | Domain: www.zhihu.com

If you see Strategy: cookie, log into the site on the phone first, then run the command.

Teardown Copy Chapter

Remove the port forward when done:

adb forward --remove tcp:9222
# or remove all forwards:
adb forward --remove-all

Differences from Desktop Chrome Copy Chapter

Multiple Devices Copy Chapter

To connect to more than one Android device simultaneously, assign each a different local port:

# Device 1
adb -s <device1-serial> forward tcp:9222 localabstract:chrome_devtools_remote

# Device 2
adb -s <device2-serial> forward tcp:9223 localabstract:chrome_devtools_remote

# Run commands targeting each device
OPENCLI_CDP_ENDPOINT=http://localhost:9222 opencli twitter trending
OPENCLI_CDP_ENDPOINT=http://localhost:9223 opencli twitter trending

Troubleshooting Copy Chapter

adb devices shows nothing

• Check USB cable (data cable, not charge-only)
• Revoke USB debugging authorizations on the device and re-approve

curl http://localhost:9222/json returns empty array []

• Chrome for Android is not open, or has no visible tabs — open a tab and retry
• Remote debugging flag in chrome://flags may be disabled

curl http://localhost:9222/json returns connection refused

• Port forward may have dropped (happens after device screen lock on some ROMs) — re-run adb forward

Adapter returns (no data) despite a working connection

• The site's API requires authentication: log into the site in Android Chrome first
• Confirm with --verbose to see which pipeline step returns 0 items

Advanced Cdp (`docs/advanced/cdp.md`) Copy Section

Connecting OpenCLI via CDP (Remote/Headless Servers)

If you cannot use the opencli Browser Bridge extension (e.g., in a remote headless server environment without a UI), OpenCLI provides an alternative: connecting directly to Chrome via CDP (Chrome DevTools Protocol).

Because CDP binds to localhost by default for security reasons, accessing it from a remote server requires an additional networking tunnel.

This guide is broken down into three phases:

1. Preparation: Start Chrome with CDP enabled locally.
2. Network Tunnels: Expose that CDP port to your remote server using either SSH Tunnels or Reverse Proxies.
3. Execution: Run OpenCLI on your server.

Phase 1: Preparation (Local Machine) Copy Chapter

First, you need to start a Chrome browser on your local machine with remote debugging enabled.

macOS:

/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome \
  --remote-debugging-port=9222 \
  --user-data-dir="$HOME/chrome-debug-profile" \
  --remote-allow-origins="*"

Linux:

google-chrome \
  --remote-debugging-port=9222 \
  --user-data-dir="$HOME/chrome-debug-profile" \
  --remote-allow-origins="*"

Windows:

"C:\Program Files\Google\Chrome\Application\chrome.exe" ^
  --remote-debugging-port=9222 ^
  --user-data-dir="%USERPROFILE%\chrome-debug-profile" ^
  --remote-allow-origins="*"

Note: The --remote-allow-origins="*" flag is often required for modern Chrome versions to accept cross-origin CDP WebSocket connections (e.g. from reverse proxies like ngrok).

Once this browser instance opens, log into the target websites you want to use (e.g., bilibili.com, zhihu.com) so that the session contains the correct cookies.

Phase 2: Remote Access Methods Copy Chapter

Once CDP is running locally on port 9222, you must securely expose this port to your remote server. Choose one of the two methods below depending on your network conditions.

Method A: SSH Tunnel (Recommended) Copy Section

If your local machine has SSH access to the remote server, this is the most secure and straightforward method.

Run this command on your Local Machine to forward the remote server's port 9222 back to your local port 9222:

ssh -R 9222:localhost:9222 your-server-user@your-server-ip

Leave this SSH session running in the background.

Method B: Reverse Proxy (ngrok / frp / socat) Copy Section

If you cannot establish a direct SSH connection (e.g., due to NAT or firewalls), you can use an intranet penetration tool like ngrok.

Run this command on your Local Machine to expose your local port 9222 to the public internet securely via ngrok:

ngrok http 9222

This will print a forwarding URL, such as https://abcdef.ngrok.app. Copy this URL.

Phase 3: Execution (Remote Server) Copy Chapter

Now switch to your Remote Server where OpenCLI is installed.

Depending on the network tunnel method you chose in Phase 2, set the OPENCLI_CDP_ENDPOINT environment variable and run your commands.

If you used Method A (SSH Tunnel): Copy Section

export OPENCLI_CDP_ENDPOINT="http://localhost:9222"
opencli doctor                    # Verify connection
opencli bilibili hot --limit 5    # Test a command

If you used Method B (Reverse Proxy like ngrok): Copy Section

# Use the URL you copied from ngrok earlier
export OPENCLI_CDP_ENDPOINT="https://abcdef.ngrok.app"
opencli doctor                    # Verify connection
opencli bilibili hot --limit 5    # Test a command

Tip: If you provide a standard HTTP/HTTPS CDP endpoint, OpenCLI requests the /json target list and picks the most likely inspectable page target automatically. If multiple page targets exist, you can further narrow selection with OPENCLI_CDP_TARGET (for example example.com or localhost:3000).

Tip: Set OPENCLI_CDP_INIT_SCRIPT to a readable regular JavaScript file to run it on every new document of the connected page (registered after the built-in stealth script). The file is validated before connecting; directories and named pipes are rejected. Useful when the CDP peer keeps state per connection, so the page must be prepared on OpenCLI's own connection.

If you plan to use this setup frequently, you can persist the environment variable by adding the export line to your ~/.bashrc or ~/.zshrc on the server.

Advanced Download (`docs/advanced/download.md`) Copy Section

Download Support

OpenCLI supports downloading images, videos, and articles from supported platforms.

Supported Platforms Copy Chapter

Prerequisites Copy Chapter

For video downloads from streaming platforms, install yt-dlp:

# Install yt-dlp
pip install yt-dlp
# or
brew install yt-dlp

Usage Examples Copy Chapter

/* Detailed source-code truncated for AI context efficiency. */

opencli xiaoyuzhou download and transcript require local Xiaoyuzhou credentials in ~/.opencli/xiaoyuzhou.json.

Pipeline Step Copy Chapter

The download step can be used in pipeline adapters:

::: v-pre

pipeline:
  - fetch: https://api.example.com/media
  - download:
      url: ${{ item.imageUrl }}
      dir: ./downloads
      filename: ${{ item.title | sanitize }}.jpg
      concurrency: 5
      skip_existing: true

:::

Advanced Rate Limiter Plugin (`docs/advanced/rate-limiter-plugin.md`) Copy Section

Rate Limiter Plugin

An optional plugin that adds a random sleep between browser-based commands to reduce the risk of platform rate-limiting or bot detection.

Install Copy Chapter

opencli plugin install github:jackwener/opencli-plugin-rate-limiter

Or copy the example below into ~/.opencli/plugins/rate-limiter/ to use it locally without installing from GitHub.

What it does Copy Chapter

After every command targeting a browser platform (xiaohongshu, weibo, bilibili, douyin, tiktok, …), the plugin sleeps for a random duration — 5–30 seconds by default — before returning control to the caller.

Configuration Copy Chapter

# Shorter delays for light scraping
OPENCLI_RATE_MIN=3 OPENCLI_RATE_MAX=10 opencli xiaohongshu search "AI眼镜"

# Skip delays when iterating locally
OPENCLI_NO_RATE=1 opencli bilibili comments BV1WtAGzYEBm

Local installation (without GitHub) Copy Chapter

1. Create the plugin directory:

   bash Copy

   mkdir -p ~/.opencli/plugins/rate-limiter

2. Create ~/.opencli/plugins/rate-limiter/package.json:

   json Copy

   { "type": "module" }

3. Create ~/.opencli/plugins/rate-limiter/index.js:

   js Copy

   import { onAfterExecute } from '@jackwener/opencli/registry'
   
   const BROWSER_DOMAINS = [
     'xiaohongshu', 'weibo', 'bilibili', 'douyin', 'tiktok',
     'instagram', 'twitter', 'youtube', 'zhihu', 'douban',
     'jike', 'weixin', 'xiaoyuzhou',
   ]
   
   onAfterExecute(async (ctx) => {
     if (process.env.OPENCLI_NO_RATE === '1') return
   
     const site = ctx.command?.split('/')?.[0] ?? ''
     if (!BROWSER_DOMAINS.includes(site)) return
   
     const min = Number(process.env.OPENCLI_RATE_MIN ?? 5)
     const max = Number(process.env.OPENCLI_RATE_MAX ?? 30)
     const ms = Math.floor(Math.random() * (max - min + 1) + min) * 1000
   
     process.stderr.write(`[rate-limiter] ${site}: sleeping ${(ms / 1000).toFixed(0)}s\n`)
     await new Promise(r => setTimeout(r, ms))
   })

4. Verify it loaded:

   bash Copy

   OPENCLI_NO_RATE=1 opencli xiaohongshu search "test" 2>&1 | grep rate-limiter
   # → (no output — plugin loaded but rate limit skipped)
   
   opencli xiaohongshu search "test" 2>&1 | grep rate-limiter
   # → [rate-limiter] xiaohongshu: sleeping 12s

Writing your own plugin Copy Chapter

Plugins are plain JS/TS files in ~/.opencli/plugins/<name>/. A plugin file must export a hook registration call that matches the pattern onStartup(, onBeforeExecute(, or onAfterExecute( — opencli's discovery engine uses this pattern to identify hook files vs. command files.

// ~/.opencli/plugins/my-plugin/index.js
import { onAfterExecute } from '@jackwener/opencli/registry'

onAfterExecute(async (ctx) => {
  // ctx.command — e.g. "bilibili/comments"
  // ctx.args    — coerced command arguments
  // ctx.error   — set if the command threw
  console.error(`[my-plugin] finished: ${ctx.command}`)
})

See hooks.ts for the full HookContext type.

Browser command hooks Copy Chapter

Browser page actions, session bind/unbind, and native Chrome commands emit the
same before/after lifecycle hooks as site commands. Names include browser/open,
browser/bind, and browser/chrome/call. ctx.args includes named positional
arguments (for example, ctx.args.url for browser open) and inherited options
such as session and profile. The before hook is awaited before connection or
browser work begins.

The after hook receives the same context, a completion timestamp, and the last
emitted result. Reported command failures populate ctx.error, including errors
handled by the command's output layer. Streaming commands emit the after hook
when they finish, with their last result. Hook exceptions remain warnings and do
not stop commands; these hooks support observation and cooperative pacing, not
a security policy that can veto execution.

Advanced Remote Chrome (`docs/advanced/remote-chrome.md`) Copy Section

Remote Chrome

Run OpenCLI on a server or headless environment by connecting to a remote Chrome instance.

Use Cases Copy Chapter

• Running CLI commands on a remote server
• CI/CD automation with headed browser
• Shared team browser sessions

Setup Copy Chapter

1. Start Chrome on the Remote Machine Copy Section

# On the remote machine (or your Mac)
/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome \
  --remote-debugging-port=9222

2. SSH Tunnel (If Needed) Copy Section

If the remote Chrome is on a different machine, create an SSH tunnel:

# On your local machine or server
ssh -L 9222:127.0.0.1:9222 user@remote-host

::: warning
Use 127.0.0.1 instead of localhost in the SSH command to avoid IPv6 resolution issues that can cause timeouts.
:::

3. Configure OpenCLI Copy Section

export OPENCLI_CDP_ENDPOINT="http://127.0.0.1:9222"

4. Verify Copy Section

# Test the connection
curl http://127.0.0.1:9222/json/version

# Run a diagnostic
opencli doctor

CI/CD Integration Copy Chapter

For CI/CD environments, use a real Chrome instance with xvfb:

::: v-pre

steps:
  - uses: browser-actions/setup-chrome@latest
    id: setup-chrome
  - run: |
      xvfb-run --auto-servernum \
        ${{ steps.setup-chrome.outputs.chrome-path }} \
        --remote-debugging-port=9222 &

:::

Conventions Convention Audit (`docs/conventions/convention-audit.md`) Copy Section

Convention Audit

opencli convention-audit scans adapter metadata plus source files for common
agent-native convention violations.

The command is intentionally report-first. It gives agents a shared fact base
before starting a sweep PR; --strict can be used later by CI gates.

Usage Copy Chapter

opencli convention-audit
opencli convention-audit --site twitter
opencli convention-audit twitter/search
opencli convention-audit --site pixiv -f yaml
opencli convention-audit --strict

Formats:

• table prints a grouped human-readable report.
• yaml is the recommended agent-facing format.
• json is available for stricter machine consumers.

Rules Copy Chapter

The first version reports these categories:

• silent-column-drop: source rows emit top-level keys that are not present in columns.
• camelCase-in-columns: output columns should use stable snake_case keys.
• missing-access-metadata: every adapter command must declare access: 'read' | 'write'.
• silent-clamp: Math.min(...limit...) can silently change user input instead of throwing ArgumentError.
• silent-empty-fallback: return [] can hide fetch/parse failures from agents.
• silent-sentinel: ?? 'unknown' / || 'N/A' style fallbacks can turn missing data into fake data.
• write-without-delete-pair: write commands such as like, save, follow, create, or post should have an undo/delete counterpart when the site supports one.

The scanners are heuristic. Treat reports as prioritized review input by
default, then turn a specific rule into a strict CI gate only after the current
violations and exemptions are understood.

CI Gates Copy Chapter

npm run check:silent-column-drop enforces the silent-column-drop rule in
baseline mode. The baseline file is
scripts/silent-column-drop-baseline.json.

npm run check:typed-error-lint enforces the silent failure rules in baseline
mode:

• silent-clamp
• silent-empty-fallback
• silent-sentinel

The baseline file is scripts/typed-error-lint-baseline.json.

Each gate fails only on new violations beyond its baseline. This lets the repo
adopt the invariant immediately while existing findings are cleaned up in
separate sweep PRs.

When a sweep fixes existing silent-column-drop entries, update the baseline:

npm run build
node scripts/check-silent-column-drop.mjs --update-baseline

When a sweep fixes existing typed-error findings, update the baseline:

npm run build
node scripts/check-typed-error-lint.mjs --update-baseline

Conventions Listing Detail Id Pairing (`docs/conventions/listing-detail-id-pairing.md`) Copy Section

Listing↔detail ID pairing (advisory)

Status: advisory convention, not a CI gate. Use as guidance when
designing listing columns; an audit script (npm run advise:listing-id-pairing)
can surface candidate listings for human review.

When a site exposes both a listing-class command (search / hot /
recent / top / feed / ...) and a detail-class command (read /
paper / article / job / view / ...), it's usually nicer for agents
if the listing rows include an id-shaped column whose value can be passed
directly into the detail command.

Without that, the agent has to either re-search by title or scrape a URL
out of band to follow up on a listing row.

Soft convention Copy Chapter

If <site> has both a listing command and a detail command, prefer
giving each listing row a column whose value round-trips into the
detail command's positional argument.

That column is whatever the detail command expects:

Why this matters Copy Chapter

The agent never has eyes on a webpage. It sees the listing rows as a
plain table of strings. If the listing emits [rank, title, author, votes]
and the detail command needs an id, the agent has three bad options:

1. Re-search by title — fragile, may hit a different post for ambiguous
   titles, costs an extra round-trip plus quota.
2. Parse the URL — assumes URL shape stays stable and is regex-able,
   often breaks across A/B buckets or after a site redesign.
3. Hand-craft a search — pure guess; agents trained to do this leak
   the failure mode silently downstream.

Surfacing the id in the listing collapses all three into a single,
unambiguous column.

Why this is advisory, not a gate Copy Chapter

Whether a listing should pair with a detail is a case-by-case product/UX
call. Many legitimate listings genuinely don't pair:

• Topic-string listings (twitter trending, weibo hot) — rows are
  search keywords, not addressable entities.
• Profile-attribute listings (reddit user, lesswrong user,
  weibo user) — rows are [field, value] pairs of one profile.
• UI-only sessions (browser quick find surfaces)
  — page ids aren't extractable from the rendered DOM.
• Comment / reply listings — sub-resources of a parent thread; the
  detail command fetches the parent, not the comment.

A hard CI gate forced authors to either add an artificial id column or
file an exemption with a reason — both of which were higher cognitive cost
than the silent-loss bugs the rule actually catches. See PR #1311 thread
for the broader "anti-pattern vs case-by-case" filter.

What counts as an "id-shaped column" Copy Chapter

The advisory script (scripts/check-listing-id-pairing.mjs) considers any
of these column names a valid round-trip handle:

• Exact id / short_id
• Anything ending in _id or Id (e.g. offer_id, paperId)
• Domain-specific ids: jk (indeed), tid (thread id), bvid / aid
  (bilibili), sku (retail product SKU), asin (amazon), isbn, doi,
  slug
• username / handle (only when the detail command keys off the user
  rather than a post)
• url — only when the detail command's positional argument explicitly
  accepts a URL (for example read , article , or help
  text such as Post ID or full URL). URL is not a valid substitute when
  the detail command only says an id comes "from URL"; callers would still
  need to parse the URL out of band.
• uri — for sites whose canonical handle is a URI scheme (e.g.
  Bluesky's at://did:.../app.bsky.feed.post/...).

If the natural id for your site is a different shape, add the pattern to
ID_COLUMN_PATTERNS in the script.

How to add an id column to a listing Copy Chapter

1. Find the source field. Most listing endpoints already include the
   id in their raw response — they're just dropped before the row is
   shaped. Check func's mapper before adding new fetch logic.

2. Pick the column position. Convention is [rank, id, ...rest, url]
   so identifiers stay near the front and the URL stays last.

3. Update the docs. The site's docs/adapters/browser/<site>.md
   should list the new column under "Listing columns" and call out that
   it round-trips into the detail command.

4. Optional: run the advisory script to confirm the manifest reflects
   the new column.

   bash Copy

   npm run advise:listing-id-pairing

Advisory script usage Copy Chapter

# Print a report of listings that don't currently carry an id-shaped column.
# Always exits 0 — does not fail CI.
npm run advise:listing-id-pairing

The script reads cli-manifest.json, so always rebuild the manifest
(npx tsx src/build-manifest.ts) after touching adapter columns.

Related principles Copy Chapter

• docs/developer/ts-adapter.md — adapter
  authoring conventions, including the required access: 'read' | 'write'
  metadata.
• "Output design" reference inside the bundled
  opencli-adapter-author skill — column naming, ordering, and id-first
  conventions.

Design Browser Agent Runtime (`docs/design/browser-agent-runtime.md`) Copy Section

Browser Agent Runtime

OpenCLI browser should become reliable for unknown SaaS workflows without
becoming a Playwright clone. The target is an agent-native runtime:

• compact observation that gives an agent the right refs in one call,
• refs that survive common React re-render/stale-node cases,
• real browser input events for user-like interactions,
• a small command surface that reduces calls only when the abstraction is
  proven.

This design was triggered by a customer report: Mercury expense category
dropdowns worked with agent-browser + Claude Code, but OpenCLI often failed
to select the category.

Source Findings Copy Chapter

We compared OpenCLI against vercel-labs/agent-browser at source level, not
only from documentation.

What agent-browser Actually Does Copy Section

The reliable dropdown behavior is not from a full Playwright actionability
pipeline or a magic custom-select command.

• cli/src/native/interaction.rs: click resolves the target center and sends
  CDP Input.dispatchMouseEvent as mouseMoved, mousePressed,
  mouseReleased. It does not run Playwright's full visible/stable/enabled/
  receives-events pipeline.
• cli/src/native/interaction.rs: select_option only handles native
  <select> by mutating selected options and dispatching change.
• cli/src/native/snapshot.rs: snapshots come from
  Accessibility.getFullAXTree, not a DOM walk. Refs carry accessibility
  role/name and backend node id.
• cli/src/native/element.rs: ref resolution first tries the cached
  backendDOMNodeId; if stale, it re-queries the AX tree by role/name/nth.
  This is the important stale-ref recovery mechanism.
• cli/src/native/snapshot.rs and cli/src/native/actions.rs: iframe refs
  carry frame context, including dedicated sessions for cross-origin iframes
  when CDP exposes them.
• cli/src/native/actions.rs: semantic locators such as getbyrole are
  simple JS queries that mark an element with data-agent-browser-located,
  then delegate to the same action path.
• skill-data/core/SKILL.md: the intended agent loop remains
  snapshot -> click/fill/type by @ref -> snapshot again.

Implication: for Mercury-style custom dropdowns, the minimum necessary fix is
real CDP input plus better refs/observation. A one-shot choose command is a
later optimization, not the root cause fix.

Current OpenCLI Gaps Copy Section

• src/browser/base-page.ts and src/browser/target-resolver.ts: generic
  browser click currently resolves an element and calls DOM el.click()
  first. CDP native click is only a fallback when JS click fails. Radix/MUI/
  shadcn controls often open/select on pointerdown, mousedown, mouseup,
  or pointerup, so el.click() can report success while the UI did not
  change.
• src/browser/dom-snapshot.ts: OpenCLI observation is DOM-based. It emits
  useful compact refs, but refs do not have AX role/name/nth fallback semantics
  and are weaker across re-rendered portals.
• OpenCLI already has the right low-level plumbing: IPage.cdp,
  nativeClick, nativeType, nativeKeyPress, setFileInput, and extension
  CDP passthrough including Accessibility.getFullAXTree.
• Extension CDP passthrough already allows Input.dispatchMouseEvent,
  Accessibility.getFullAXTree, and DOM.getBoxModel. It does not currently
  allow DOM.describeNode; AX subtree/iframe work must add that allowlist entry
  before depending on it.
• OpenCLI exposes fewer general browser primitives than agent-browser:
  hover, focus, check, uncheck, dblclick, drag, upload, and
  wait download are not a consistent first-class CLI surface.
• browser find is currently CSS-oriented; role/name/label/text locators are
  not first-class for agents.

Product Position Copy Chapter

OpenCLI has two browser jobs:

1. deterministic adapters for known sites,
2. a reliable browser toolbelt for unknown pages and adapter authors.

Borrow from Playwright only where it improves reliability:

• real pointer/mouse/keyboard/file input events,
• selected actionability checks when they prevent silent failures,
• strict locator ambiguity for write actions,
• typed failure reasons.

Do not copy:

• Playwright's test runner, assertion DSL, trace viewer, route/HAR surface, or
  one-to-one API list.

Borrow from agent-browser:

• AX-tree observation,
• compact refs as the default agent selector,
• role/name stale-ref re-resolution,
• iframe-aware refs,
• annotated screenshots mapped to refs,
• a simple snapshot/action loop.

Do not copy blindly:

• broad command sprawl,
• natural-language act as the primary runtime,
• route/mock/HAR as near-term browser CLI surface,
• claims that a custom dropdown should be solved by magic if the source system
  itself still uses snapshot/click/snapshot/click.

Design Principles Copy Chapter

• Prefer one reliable primitive over three brittle workarounds.
• Reduce agent calls by improving observation first. A better snapshot can
  avoid many follow-up help/find calls without inventing high-level commands
  prematurely.
• Keep actions transparent. A failed action should return a branchable reason,
  not a generic "click failed".
• Add command surface only when it maps to a distinct browser task and reduces
  real agent calls.
• Keep adapter compatibility explicit. Any change to default click/type/fill
  behavior must run full adapter tests. Escape hatches are emergency plan B, not
  a reason to merge known regressions.

Architecture Copy Chapter

Native Input Backend Copy Section

Normalize native input through a small internal backend over existing IPage
capabilities:

interface NativeInputBackend {
  click(point: Point, opts?: ClickOptions): Promise<void>;
  dblclick(point: Point): Promise<void>;
  hover(point: Point): Promise<void>;
  key(key: string, modifiers?: string[]): Promise<void>;
  insertText(text: string): Promise<void>;
  setFiles(selector: string, files: string[]): Promise<void>;
}

The Browser Bridge and direct CDP implementation can both use:

• Input.dispatchMouseEvent,
• Input.dispatchKeyEvent,
• Input.insertText,
• DOM.setFileInputFiles.

This is the P0 fix for Mercury dropdowns: CDP mouse primary for click, with
DOM el.click() only as fallback.

This does not change browser select. Native <select> remains a separate
operation that sets selected options and dispatches change, matching both
OpenCLI's current behavior and agent-browser's select_option behavior.

AX Observation And Refs Copy Section

Add an AX-backed observation path alongside the current DOM snapshot.

Ref identity should include enough data for re-resolution:

type BrowserRef = {
  ref: string;
  backendNodeId?: number;
  role: string;
  name: string;
  nth?: number;
  frame?: {
    frameId?: string;
    sessionId?: string;
    url?: string;
  };
  bbox?: { x: number; y: number; width: number; height: number };
};

Resolution order:

1. cached backendNodeId,
2. AX re-query by role/name/nth in the same frame,
3. existing CSS/DOM resolver fallback when the target is not a ref.

The first rollout should be additive:

• keep current browser state output stable,
• Phase 0: add an internal or opt-in AX prototype; do not change the default
  browser state text output,
• Phase 1 decision point: either promote AX to default observation or keep it
  opt-in,
• decision criteria: fixture pass rate, stale-ref recovery rate, manual SaaS
  results, adapter compatibility, and snapshot token size versus the current DOM
  snapshot.

Frame Routing Copy Section

Refs from iframes need frame context so commands can act without manual frame
switching in common cases.

The route should mirror agent-browser's model:

• same-origin iframe: parent session plus frameId params where CDP supports
  them,
• cross-origin iframe: dedicated attached target session when available,
• if unsupported: typed frame_unreachable with the iframe ref/name/url.

Do not add a global "switch frame" burden to the normal agent path unless the
target cannot be routed automatically.

Actionability Helper Copy Section

Do not start with full Playwright actionability. Implement a small helper that
prevents known silent failures:

1. resolve target/ref,
2. scroll into view when CDP supports it,
3. measure a non-zero bounding box,
4. dispatch native input.

Boundary by phase:

• MVP: scroll into view plus non-zero bounding box only.
• Phase 1: add visible/enabled/not-editable checks if the target action needs
  them and compatibility remains clean.
• Phase 2: add stability and receives-events checks only if fixtures or manual
  SaaS cases show real failures.

Each added wait/check has compatibility and latency cost.

Typed statuses:

type ActionStatus =
  | 'ready'
  | 'not_found'
  | 'stale_ref_recovered'
  | 'stale_ref_unresolved'
  | 'zero_rect'
  | 'not_visible'
  | 'disabled'
  | 'not_editable'
  | 'frame_unreachable'
  | 'native_backend_unavailable';

Semantic Locators Copy Section

Add semantic locator support after AX refs are in place:

opencli browser --session research click --role button --name "Submit"
opencli browser --session research fill --label "Email" "[email protected]"
opencli browser --session research get text --testid invoice-total

For write operations, ambiguous locators must fail with candidates. They should
not silently choose the first match.

Command Surface Copy Section

Keep the surface smaller than agent-browser and Playwright.

Near-term primitives:

opencli browser --session research click <target>
opencli browser --session research dblclick <target>
opencli browser --session research hover <target>
opencli browser --session research focus <target>
opencli browser --session research check <target>
opencli browser --session research uncheck <target>
opencli browser --session research upload <target> <file...>
opencli browser --session research drag <source> <target>
opencli browser --session research wait download [pattern]

Keep browser select native <select> only. It should clearly return
not_a_select when used on custom controls.

Defer browser choose <target> <option> until after the MVP proves the
snapshot/ref/action loop on Mercury-like fixtures. If added later, it should be
a thin deterministic helper for common combobox/listbox/menu patterns, not a
general AI act command.

Backward Compatibility Copy Chapter

Milestones Copy Chapter

Phase 0: Mercury Reliability MVP Copy Section

Documented in docs/design/mercury-fix-mvp.md.

Scope:

• CDP mouse primary for browser click,
• Radix/shadcn/MUI-style fixture coverage,
• AX snapshot/ref-map prototype with role/name/nth re-resolution,
• native type/fill normalization where existing behavior is already close.

Out of scope for Phase 0:

• iframe/frame-aware action routing,
• full actionability,
• browser choose.

Exit:

• Mercury-like custom select can be completed with
  snapshot -> click trigger -> snapshot -> click option -> verify.
• No silent "clicked true but no UI event chain" failure remains for fixture
  dropdowns.
• Existing adapter tests do not regress.
• Quantitative gates from docs/design/mercury-fix-mvp.md pass.

Phase 1: Ref And Observation Upgrade Copy Section

Scope:

• decide AX default versus opt-in based on Phase 0 metrics,
• AX-backed browser state or browser snapshot option,
• ref cache that stores backend node id, role/name/nth, frame context,
• iframe-aware action routing,
• annotated screenshot with the same ref ids and sidecar metadata.

Status after implementation:

• same-origin iframe AX refs route through Accessibility.getFullAXTree
frameId params,
• cross-origin iframe AX routing is best-effort. Real Chrome extension smoke
  verified that chrome.debugger may not expose attachable OOPIF iframe
  targets to extensions even after Target.setDiscoverTargets,
  Target.getTargets, and Target.setAutoAttach,
• unsupported frames degrade by omission or typed action failure rather than
  requiring global manual frame switching.

Implementation note: Phase 1 also includes a DOM-ref visual slice via
browser screenshot --annotate. It refreshes current DOM refs and overlays
visible [N] labels on the captured image. AX-side visual labels and richer
sidecar metadata remain follow-up work.

Exit:

• Agent can act on iframe refs without manual frame selection in common cases.
• Stale refs from simple React re-renders recover by role/name/nth.
• Snapshot output remains compact enough for normal agent context.

Phase 2: Browser Toolbelt Copy Section

Scope:

• hover, focus, dblclick, check, uncheck, upload, drag, and
  wait download (implemented),
• semantic locator options for role/name, label, text, testid,
• structured ambiguity errors for write locators.

Implementation note: semantic locators cover browser find, browser click,
browser get text|value|attributes, input actions (type, fill, select),
and Phase 2 action primitives (hover, focus, dblclick, check,
uncheck, upload). drag uses prefixed endpoint locators (--from-role /
--to-role, etc.) so source and target cannot be confused. Placeholder is
folded into accessible-name matching for --name; a dedicated --placeholder
flag can be added only if real usage shows the distinction matters.

Exit:

• A representative form with text, checkbox/radio, file upload, custom select,
  and submit can be completed without eval.
• Agents can usually avoid inventing CSS selectors.

Phase 3: High-Level Deterministic Helpers Copy Section

Only after Phase 0/1 metrics justify it:

• browser choose for common custom select/combobox/listbox/menu controls,
• optional browser form inspect and browser form fill <json> for structured
  forms,
• failure artifact bundle: screenshot, refs, target diagnostics, console/
  network summary, and suggested next command.

Do not add a free-form natural-language act as the primary interface.

Success Metrics Copy Chapter

Track both reliability and call count.

Mercury-like custom select:

• current OpenCLI baseline: often fails because click is DOM el.click();
• Phase 0 target: reliable 4-step snapshot/action loop, with fixture pass rate
  at least N-1/N after recording baseline;
• Phase 3 target, only if warranted: deterministic 1-step choose after
  target discovery.

Stale-ref recovery:

• Phase 0 AX prototype target: at least 9/10 repeated React re-render fixture
  runs recover through role/name/nth.

Compatibility:

• Any PR changing default click/type/fill behavior must run full adapter tests.
  New failures are merge blockers unless proven unrelated to the PR.

Fixture matrix:

• Radix Select,
• shadcn Select,
• Material UI Select/Autocomplete,
• native <select>,
• checkbox/radio label retarget,
• file upload,
• same-origin iframe form,
• cross-origin iframe where CDP target attach is available.

Manual SaaS matrix:

Manual matrix is not a CI gate at first. It is the calibration set for deciding
whether OpenCLI is approaching agent-browser reliability.

Execution process:

• Phase 0 completion: @opencli-质量官 runs Mercury, Brex, and Linear when access
  is available.
• On each form page, collect opencli browser --session research state --compare-sources so the AX
  default decision has DOM-vs-AX metrics: refs, frame sections, approximate
  tokens, elapsed time, and per-source errors.
• Pass means the relevant category/field can be selected and the form state can
  be saved or committed.
• Failures do not block the already-shipped MVP unless they expose a regression,
  but they become Phase 1 backlog with exact command sequence and failure
  reason.

Test Strategy Copy Chapter

Phase 0:

• unit tests for CDP-primary click fallback behavior,
• local fixture that records pointer/mouse/click event order,
• component fixtures for Radix/shadcn/MUI-style controls,
• stale-ref fixture that re-renders an option after snapshot and verifies
  AX re-resolution,
• direct CDP and Browser Bridge paths where practical.

Regression gates:

npm run build
npm run typecheck
npm test -- --run src/browser src/cli.test.ts
npm run check:typed-error-lint
npm run check:silent-column-drop

Before changing default action behavior, also run the adapter suite on main and
on the branch and compare failures.

Documentation Copy Chapter

Update after Phase 0:

• skills/opencli-browser/SKILL.md: recommend snapshot/click/snapshot/click for
  custom dropdowns until choose exists.
• Browser command help: explain that select is native <select> only.
• Troubleshooting: explain zero_rect, not_visible, disabled,
  frame_unreachable, stale_ref_unresolved, and native_backend_unavailable.
• Comparison guide: OpenCLI's goal is not "Playwright in CLI form"; it is an
  adapter-first CLI with reliable agent browser primitives.

Open Questions Copy Chapter

• Should the CDP click escape hatch be public (--mode js) or env-only?
  Prefer env-only unless a real adapter regression needs user control.
• Should AX snapshot replace DOM snapshot by default or exist as
  --source ax first? Prefer opt-in/prototype first, then promote after
  fixture and manual SaaS validation.
• How much actionability is enough? Start with scroll/rect/visible/enabled.
  Add stability/receives-events only with measured failures.
• Does browser choose materially reduce successful Mercury workflows after
  AX refs land? If not, do not add it.

Design Mercury Fix Mvp (`docs/design/mercury-fix-mvp.md`) Copy Section

Mercury Dropdown MVP

This is the short-term implementation slice for the Mercury expense category
failure. It is intentionally smaller than the full browser-agent-runtime
roadmap.

Problem Copy Chapter

Mercury-style category controls are usually custom React dropdowns. The trigger
and option are not native <select> elements. Libraries such as Radix UI,
Material UI, and shadcn commonly open or commit selection on pointer/mouse down
or up events.

OpenCLI's generic browser click currently calls DOM el.click() first. That
only dispatches a click event, so OpenCLI can return success while the dropdown
never opened or the option never committed.

agent-browser succeeds in this class mainly because its click path sends real
CDP mouse events. It still uses the normal loop:

snapshot
click trigger
snapshot
click option
snapshot or get value

It does not have a general one-shot custom-dropdown choose command.

MVP Scope Copy Chapter

0. Extension CDP Capability Check Copy Section

The MVP depends on Chrome debugger CDP passthrough. Unlike agent-browser,
OpenCLI usually reaches Chrome through the extension, so command availability
must be explicit.

Current status:

Therefore PR 1 can ship without extension changes. PR 2 must either avoid
DOM.describeNode or include the small extension allowlist addition in the same
PR. If AX re-resolution needs DOM.resolveNode, that command must be added and
tested at the same time rather than assumed.

1. CDP Mouse Primary Copy Section

Change generic browser click to:

1. resolve target,
2. scroll into view and measure a non-zero target box,
3. send CDP Input.dispatchMouseEvent sequence:
   mouseMoved -> mousePressed -> mouseReleased,
4. fall back to DOM el.click() only when native click is unavailable or the
   target has no usable point.

Required output behavior:

• keep existing success shape,
• add diagnostics only as additive fields if needed,
• never report success from JS click before trying CDP when CDP is available.

This applies only to click-like actions: browser click and later
browser dblclick. It does not change browser select; native <select>
continues to use the existing JS option setter/change-event path.

2. Real Component Fixture Copy Section

Add a local browser fixture that records event order and selected value.

Minimum cases:

• Radix/shadcn-like select:
  • trigger opens on pointerdown,
  • option selects on pointerup or mousedown,
  • menu is rendered in a portal.
• Material UI-like autocomplete:
  • combobox input opens popup,
  • option list is outside the trigger subtree.
• Native <select> remains covered by existing browser select.

Pass condition:

• Before PR 1, run and record baseline pass rate. At least one custom fixture
  case must fail on the DOM el.click() path.
• After PR 1, custom fixture pass rate must be at least N-1/N, where N is
  the number of custom dropdown cases in the fixture.
• OpenCLI verifies the selected text/value changed.

3. AX Snapshot Prototype Copy Section

Add an AX-backed snapshot/ref-map prototype behind a non-breaking option or
internal test helper.

Required data per ref:

type BrowserRef = {
  ref: string;
  backendNodeId?: number;
  role: string;
  name: string;
  nth?: number;
  frame?: { frameId?: string; sessionId?: string; url?: string };
};

Required behavior:

• build refs from Accessibility.getFullAXTree,
• use backendDOMNodeId as the fast path for action resolution,
• if that id is stale, re-query the AX tree by role/name/nth,
• keep current DOM snapshot text output stable until the AX path is proven.

This is the part that should learn most directly from agent-browser.

Success metric:

• stale-ref recovery fixture must pass at least 9/10 repeated React re-render
  runs by resolving through AX role/name/nth.

4. Native Type/Fill Normalization Copy Section

Review existing nativeType and fillText paths and make them consistent with
the native-input backend:

• focus through CDP when possible,
• use Input.insertText for printable text,
• keep fill exact-replacement semantics,
• keep existing verification as the authority for fill success.

Do not expand this into a full actionability rewrite in the MVP.

Non-Goals Copy Chapter

• No full Playwright actionability pipeline.
• No broad Playwright API clone.
• No general natural-language act.
• No one-shot browser choose in this MVP.
• No route/HAR/mock/trace-viewer surface.

browser choose can be considered after this MVP if measurements show that the
snapshot/click/snapshot/click loop is reliable but still too expensive for
agents.

PR Breakdown Copy Chapter

PR 0: Extension Allowlist For AX Prototype Copy Section

Only needed if PR 2 uses commands that are not already allowed.

• add DOM.describeNode to CDP passthrough allowlist,
• add DOM.resolveNode only if the implementation needs it,
• add extension tests that blocked commands remain blocked and allowed AX/DOM
  commands pass.

PR 1: CDP-Primary Click Copy Section

• flip generic click to CDP-first,
• keep JS fallback,
• add event-order fixture tests,
• run browser/unit gates and full adapter tests,
• list every new adapter failure compared with main and fix them before merge.

This corresponds to the immediate Mercury reliability fix.

PR 2: AX Ref Prototype Copy Section

• add AX tree fetch through existing page.cdp,
• create internal BrowserRef map,
• implement cached backend id resolution plus role/name/nth fallback,
• add stale React re-render fixture.

Keep this additive. Do not replace browser state default in the same PR.

Frame-aware routing is not part of the MVP. It moves to Phase 1 because the
Mercury exit criteria do not require iframe support.

Status after implementation:

• PR 1 shipped CDP-primary click and component fixtures.
• PR 2 shipped opt-in browser state --source ax, backend-node ref clicks, and
  stale role/name/nth recovery.
• Phase 1 same-origin iframe refs shipped for AX snapshots; cross-origin
  session routing remains deferred.
• Phase 1 metrics shipped as browser state --compare-sources so AX default
  promotion can be decided from measured DOM-vs-AX data.
• Phase 1 visual refs shipped as browser screenshot --annotate, giving agents
  a screenshot whose visible labels map back to normal DOM [N] refs.

Phase 1 Follow-Up Copy Chapter

• carry same-origin frameId and cross-origin session id when available,

• route click/fill/type by ref frame context,

• return typed frame_unreachable when not possible,

• add iframe fixture.

• decide whether AX becomes default observation or an explicit --source ax,

• update skills/opencli-browser/SKILL.md,

• add troubleshooting docs and fixture examples,

• record manual Mercury or Mercury-equivalent validation.

Compatibility Plan Copy Chapter

Exit Criteria Copy Chapter

• A custom dropdown fixture that depends on pointer/mouse events passes through
  browser click.
• A portal-rendered option can be selected with the normal
  snapshot/click/snapshot/click loop.
• A stale React-ref fixture recovers through AX role/name/nth.
• Existing browser tests and adapter tests pass.
• Documentation tells agents the correct current recipe and does not promise
  choose until it exists.

Quantitative gates:

• Custom dropdown fixtures: record baseline before PR 1, then pass at least
  N-1/N custom cases after PR 1.
• Stale-ref recovery: pass at least 9/10 repeated re-render runs after PR 2.
• Adapter compatibility: zero unexplained new full-adapter-test failures before
  a default behavior PR merges.

Manual SaaS check:

• After Phase 0, @opencli-质量官 runs Mercury, Brex, and Linear manually when
  credentials/access are available.
• Pass means the workflow can select the relevant category/field and save or
  commit the form state.
• For each site, also run opencli browser --session research state --compare-sources on the form
  page and record sources.dom.refs, sources.ax.refs, frame_sections,
  approx_tokens, elapsed_ms, and any per-source error.
• Failure does not block MVP retroactively, but each failure must be recorded as
  a Phase 1 backlog item with observed command sequence and failure reason.

Validation Commands Copy Chapter

npm run build
npm run typecheck
npm test -- --run src/browser src/cli.test.ts
npm run check:typed-error-lint
npm run check:silent-column-drop

Before merging a default behavior change:

npm test -- --run

If full tests are too slow in the review loop, run full adapter tests at least
once before merge and report any difference from main.

Developer Ai Workflow (`docs/developer/ai-workflow.md`) Copy Section

Building adapters with an agent

OpenCLI supplies composable tools and observable results. The agent chooses its
implementation from the task, available site behavior and existing adapters.

Discover capabilities Copy Chapter

opencli list search --site example
opencli example search --help -f json

list returns compact capabilities with total and optional nextOffset.
Default command results use {ok:true,data:...}; failures use
{ok:false,error:{code,message,hint?,...}} and a nonzero exit code. Logs go to stderr.

Inspect a site Copy Chapter

opencli browser open https://example.com --session research
opencli browser state --diagnostics --session research
opencli browser network --static --session research
opencli browser network --detail RequestKey --session research

Page facts, captured requests and AST candidates inform implementation choices.
Static candidates are unexecuted evidence; the agent decides what to investigate.
browser chrome describe exposes native tab, group and window management without
a page session. Use doctor to diagnose connectivity when needed.

Implement and exercise Copy Chapter

opencli adapter init example/search
opencli adapter check example/search
opencli adapter test example/search --args '{"query":"hello"}'

Write a normal JS file. cli({...}), func(args) and func(page,args) remain the
adapter contract. Return business data; the CLI adds the JSON envelope.
check validates definitions; test executes the real command and optionally
compares a fixture. Write adapters have real effects when tested.

There is no draft store, promotion step, required strategy note or site-memory gate.
Use focused tests and real execution to cover core behavior, error paths and
business semantics. Optional traces and fixtures help investigate failures.

See opencli-adapter-author
and opencli-browser
for the tool contracts and references.

Developer Architecture (`docs/developer/architecture.md`) Copy Section

Architecture

OpenCLI is a command surface that sits on top of four major subsystems:

1. command discovery and registry
2. execution and formatting
3. browser / daemon / CDP connectivity
4. adapter and plugin integration

Runtime Shape Copy Chapter

opencli CLI
  ├─ command discovery / registry
  ├─ execution / output
  ├─ browser runtime
  │   ├─ Browser Bridge extension
  │   ├─ local daemon
  │   └─ direct CDP path
  ├─ adapter loading
  │   ├─ built-in site adapters
  │   ├─ generated adapters
  │   └─ pipeline-backed adapters
  └─ plugin loading

Core Modules Copy Chapter

CLI Surface Copy Section

• src/main.ts — process entrypoint
• src/cli.ts — top-level command tree and built-in command groups
• src/completion.ts / src/completion-fast.ts — shell completion

Discovery, Registry, Execution Copy Section

• src/discovery.ts — discovers built-in adapters, generated adapters, plugins, and manifests
• src/registry.ts — central command registry
• src/registry-api.ts — adapter-facing registration helpers
• src/execution.ts — argument validation, lazy loading, and command execution
• src/commanderAdapter.ts — bridges registry metadata into Commander subcommands
• src/output.ts — table, json, yaml, md, csv formatting
• src/serialization.ts — registry and manifest serialization helpers

Browser and Runtime Copy Section

• src/runtime.ts — shared command runtime and target resolution
• src/daemon.ts — lifecycle and bridge behavior for the local daemon
• src/doctor.ts — browser bridge diagnostics
• src/observation/ — trace artifacts, redaction, and structured runtime evidence
• src/interceptor.ts — interception helpers for browser-backed strategies
• src/browser/ — Browser Bridge connection and browser-side primitives

Pipeline Engine Copy Section

• src/pipeline/executor.ts — pipeline execution
• src/pipeline/template.ts — template expansion
• src/pipeline/transform.ts — transform helpers
• src/pipeline/steps/ — concrete steps such as:
  • fetch
  • download
  • browser
  • intercept
  • tap
  • transform

Adapter and Extension Surfaces Copy Section

• clis/ — built-in site adapters
• src/plugin.ts / src/plugin-manifest.ts / src/plugin-scaffold.ts — plugin install, metadata, scaffold

Command Sources Copy Chapter

OpenCLI merges commands from multiple places into one registry:

The user sees one unified command tree through opencli list.

Connectivity Modes Copy Chapter

Browser Bridge mode Copy Section

Primary path for browser-backed commands:

opencli process
  ↔ local daemon
  ↔ Browser Bridge extension
  ↔ logged-in Chrome / Chromium

This path is used for:

• cookie-backed websites
• browser automation primitives
• interactive browser verification

Direct CDP mode Copy Section

Used when OpenCLI talks directly to a Chrome debugging endpoint through OPENCLI_CDP_ENDPOINT.

Typical uses:

• remote Chrome
• headless Chrome

Authentication / Access Strategies Copy Chapter

OpenCLI currently uses these access strategies:

The key distinction is operational:

• public favors direct network access
• cookie, intercept, ui depend on a live browser surface

High-Risk Change Zones Copy Chapter

Changes in these files usually affect broad command behavior:

• src/cli.ts
• src/commanderAdapter.ts
• src/discovery.ts
• src/execution.ts
• src/runtime.ts
• src/daemon.ts
• src/plugin.ts
• src/pipeline/**

These areas deserve targeted tests first, then broader validation when the change crosses module boundaries.

Mental Model Copy Chapter

The simplest accurate model is:

1. OpenCLI discovers command definitions.
2. It registers them into one command registry.
3. It resolves each invocation through execution + runtime.
4. It reaches the target through one of:
   • network fetch
   • Browser Bridge
   • direct CDP
5. It formats the result into a stable output surface.

That is the architecture to preserve when refactoring.

Developer Contributing (`docs/developer/contributing.md`) Copy Section

Contributing

Thanks for your interest in contributing to OpenCLI.

Quick Start Copy Chapter

# 1. Fork & clone
git clone [email protected]:<your-username>/opencli.git
cd opencli

# 2. Install dependencies
npm install

# 3. Build
npm run build

# 4. Run a few checks
npx tsc --noEmit
npm run build

# 5. Link globally (optional, for testing `opencli` command)
npm link

Adding a New Site Adapter Copy Chapter

This is the most common type of contribution. All adapters use TypeScript with the cli() API.

Before you start:

• Prefer positional args for the command's primary subject (search <query>, topic , download ). Reserve named flags for optional modifiers such as --limit, --sort, --lang, and --output.
• Normalize expected adapter failures to CliError subclasses instead of raw Error whenever possible. Prefer AuthRequiredError, EmptyResultError, CommandExecutionError, TimeoutError, and ArgumentError so the top-level CLI can render better messages and hints.
• If you add a new adapter or make a command newly discoverable, update the matching doc page and the user-facing indexes that expose it.

Create the Adapter Copy Section

Built-in adapters are authored in JavaScript. Create a file like clis/<site>/<command>.js:

import { cli, Strategy } from '@jackwener/opencli/registry';
import { CommandExecutionError, EmptyResultError } from '@jackwener/opencli/errors';

cli({
  site: 'mysite',
  name: 'search',
  description: 'Search MySite',
  access: 'read', // 'read' | 'write'
  example: 'opencli mysite search <query> -f yaml',
  domain: 'www.mysite.com',
  strategy: Strategy.COOKIE,
  args: [
    { name: 'query', positional: true, required: true, help: 'Search query' },
    { name: 'limit', type: 'int', default: 10, help: 'Max results' },
  ],
  columns: ['title', 'url', 'date'],

  func: async (page, kwargs) => {
    const { query, limit = 10 } = kwargs;
    // ... browser automation logic
    if (!Array.isArray(data)) throw new CommandExecutionError('MySite returned an unexpected response');
    if (!data.length) throw new EmptyResultError('mysite search', 'Try a different keyword');
    return data.slice(0, Number(limit)).map((item) => ({
      title: item.title,
      url: item.url,
      date: item.created_at,
    }));
  },
});

TypeScript adapters are also supported — see TypeScript Adapter.

Validate Your Adapter Copy Section

opencli <site> <command> --limit 3 -f json   # Test your command
opencli <site> <command> -v    # Verbose mode for debugging

Code Style Copy Chapter

• TypeScript strict mode — avoid any where possible.
• ES Modules — use .js extensions in imports (TypeScript output).
• Naming: kebab-case for files, camelCase for variables/functions, PascalCase for types/classes.
• No default exports — use named exports.
• Errors — throw CliError subclasses for expected adapter failures; avoid raw Error for normal adapter control flow.

Commit Convention Copy Chapter

We use Conventional Commits:

feat(twitter): add thread command
fix(browser): handle CDP timeout gracefully
docs: update CONTRIBUTING.md
test(reddit): add e2e test for save command
chore: bump vitest to v4

Submitting a Pull Request Copy Chapter

1. Create a feature branch: git checkout -b feat/mysite-trending
2. Make your changes and add tests when relevant
3. Run the smallest check set that matches your change:
   bash Copy

   npx tsc --noEmit           # Type check
   npm run build              # Ensure dist stays healthy
   npx vitest run clis/<site>/<command>.test.js   # Your adapter's tests
   npm test                   # Broader local gate when shared runtime changes justify it

4. Commit using conventional commit format
5. Push and open a PR

If your PR adds a new adapter or changes user-facing commands, also verify:

• Adapter docs exist under docs/adapters/
• docs/adapters/index.md is updated for new adapters
• VitePress sidebar includes the new doc page
• README.md / README.zh-CN.md stay aligned when command discoverability changes

Developer Documentation Audit 2026 05 (`docs/developer/documentation-audit-2026-05.md`) Copy Section

Documentation Audit — 2026-05

This document reviews the current long-form docs, README surfaces, and developer guides in opencli. It focuses on stale facts, internal contradictions, and documentation structure that now causes drift.

Scope Copy Chapter

• README.md
• README.zh-CN.md
• docs/
• skills/ references that are linked from user-facing docs

Executive View Copy Chapter

The docs are usable, but they are drifting in four visible ways:

1. Hard-coded counts and feature claims are stale.
2. Developer docs describe an older architecture and older test layout.
3. English and Chinese docs are no longer updated with the same rigor.
4. Some pages still describe deleted concepts or old workflows.

The highest-value work is:

1. Fix the stale facts in README*, docs/index.md, docs/zh/index.md, and docs/guide/getting-started.md.
2. Rewrite docs/developer/testing.md and docs/developer/architecture.md against current main.
3. Make English and Chinese entry docs derive from the same source-of-truth checklist.
4. Stop writing command/adapters counts by hand unless they are generated.

Priority 0 — Clearly stale or incorrect Copy Chapter

1. Adapter / site counts are stale across multiple entry points Copy Section

Affected files:

• README.md
• README.zh-CN.md
• docs/guide/getting-started.md
• docs/comparison.md

Current problems:

• README.md and README.zh-CN.md still say 90+ adapters.
• docs/guide/getting-started.md still says 87+ pre-built adapters.
• docs/comparison.md still says 87+ sites.

Current reality:

• node dist/src/main.js list --format json | jq 'map(.site) | unique | length' returns 106.

Why this matters:

• These are the first pages people read.
• The mismatch is easy to notice and weakens trust in the rest of the docs.
• These values will keep drifting if we maintain them manually.

Recommended fix:

• Replace all hard-coded counts with one of:
  • 100+
  • 100+ sites
  • over 100 registered sites
• Best option: generate this number into docs at release time or avoid explicit counts entirely.

2. `docs/developer/testing.md` is materially out of date Copy Section

Affected file:

• docs/developer/testing.md

Current problems:

• It says adapter tests live in clis/**/*.test.{ts,js}.
• The file examples name adapter tests such as:
  • clis/zhihu/download.test.ts
  • clis/twitter/timeline.test.ts
  • clis/reddit/read.test.ts
  • clis/bilibili/dynamic.test.ts
• Those files do not exist.
• It says E2E coverage is 5 files.
• Current reality is 11 E2E files.
• It presents npm test as the main local gate, while current team rule is to prefer the smallest sufficient test set instead of default full-suite runs.

Current reality from the repo:

• find src -name '*.test.ts' | wc -l → 60
• find clis -iregex '.*\\.test\\.(ts|js)$' | wc -l → 0
• find tests/e2e -name '*.test.ts' | wc -l → 11
• find tests/smoke -name '*.test.ts' | wc -l → 1

Why this matters:

• This page is the main developer testing contract.
• A new contributor following it will get the wrong mental model of the test layout.
• It encourages a heavier default test habit than the team currently wants.

Recommended fix:

• Rewrite the page from current files, not from remembered structure.
• Separate:
  • fast local checks
  • targeted validation
  • full CI coverage
• Remove nonexistent adapter test examples.
• Add a short rule:
  • local default = smallest sufficient validation
  • full-suite = broader refactor, shared runtime changes, or CI

3. `docs/developer/architecture.md` describes an older system shape Copy Section

Affected file:

• docs/developer/architecture.md

Current problems:

• It refers to src/browser.ts, but that file does not exist.
• The directory structure block says src/clis/, but adapters live at top-level clis/.
• The architecture diagram is too simplified for the current system and omits important pieces such as:
  • daemon.ts
  • plugin.ts
  • update check / diagnostics / runtime detection paths
• It says “3-tier authentication strategy” but lists 5 strategies.

Why this matters:

• This is the page people read to understand the project.
• Once architecture docs are stale, all deeper docs become harder to trust.

Recommended fix:

• Rewrite this page around current modules:
  • command discovery and registry
  • execution
  • browser / daemon bridge
  • plugin system
  • direct browser CDP path
  • pipeline engine
• Replace the static tree with a curated module map that matches current filenames.
• Change “3-tier” to a neutral label like authentication strategies.

4. Home pages still mention deleted concepts Copy Section

Affected files:

• docs/index.md
• docs/zh/index.md

Current problems:

• Both home pages say:
  • explore
  • synthesize
  • cascade
• docs/developer/ai-workflow.md explicitly says those commands do not exist and that the skill drives the loop.

Why this matters:

• The home page is currently teaching a product vocabulary that the actual CLI does not have.
• This creates immediate confusion for users who go from docs to terminal.

Recommended fix:

• Replace those phrases with current concepts:
  • browser primitives
  • adapter-authoring skill
  • verify loop
• Keep the homepage aligned with docs/developer/ai-workflow.md.

5. Chinese getting-started page lists a deleted built-in command Copy Section

Affected file:

• docs/zh/guide/getting-started.md

Current problem:

• It says built-in commands include list、explore、validate...
• explore is not a current built-in command.

Why this matters:

• This is a hard user-facing error.

Recommended fix:

• Replace the example list with current built-ins such as:
  • list
  • validate
  • verify
  • browser
  • doctor
  • plugin
  • adapter

Priority 1 — Inconsistent or incomplete Copy Chapter

6. Installation pages are inconsistent about runtime support and update flow Copy Section

Affected files:

• README.md
• README.zh-CN.md
• docs/guide/installation.md
• docs/zh/guide/installation.md

Current problems:

• README.md says Node >= 21 or Bun >= 1.0.
• docs/guide/installation.md and docs/zh/guide/installation.md only mention Node.
• README.md documents skill refresh on update.
• docs/zh/guide/installation.md only documents package update and omits skills refresh.

Why this matters:

• Entry docs should agree on install prerequisites and upgrade procedure.

Recommended fix:

• Pick one official runtime support statement and reuse it everywhere.
• If Bun is supported, add it consistently to guide pages.
• Mirror the post-update skill refresh guidance in the install/update guides.

7. README and docs still use top-level tables and examples that will drift by hand Copy Section

Affected files:

• README.md
• README.zh-CN.md

Current problems:

• The “Built-in Commands” section is manually curated and already partially selective.
• The surrounding copy still frames it like a broad current snapshot.

Why this matters:

• Manual command snapshots go stale quickly in a repo with active adapter growth.

Recommended fix:

• Reframe the section as:
  • “Representative built-in commands”
  • “Sample sites”
• Keep opencli list and docs/adapters/index.md as the full registry surface.

8. `docs/comparison.md` contains stale scale claims Copy Section

Affected file:

• docs/comparison.md

Current problem:

• It still says 87+ sites.

Why this matters:

• Comparison pages shape market positioning.
• Stale numbers make the project look less maintained than it is.

Recommended fix:

• Remove exact numbers from comparison copy unless they are generated.

Priority 2 — Structural drift risks Copy Chapter

9. English and Chinese docs are drifting independently Copy Section

Most visible examples:

• docs/index.md and docs/zh/index.md both kept the deleted explore / synthesize / cascade language.
• docs/zh/guide/getting-started.md contains a stale built-in command example that should have been caught by parity review.
• README.md and README.zh-CN.md both carry the same stale adapter count.

Why this keeps happening:

• We have mirrored content with no explicit parity checklist.
• Updates land in one place and rely on memory for the rest.

Recommended fix:

• Introduce a small doc parity checklist for any change that touches:
  • README.md
  • README.zh-CN.md
  • docs/index.md
  • docs/zh/index.md
  • docs/guide/*
  • docs/zh/guide/*
• Add one PR checklist item:
  • “Did this change require an English/Chinese mirror update?”

10. Core product pages mix generated facts with narrative copy Copy Section

Examples:

• command counts
• site counts
• test counts
• lists of built-in commands

Why this matters:

• Numbers and command inventories drift faster than narrative guidance.

Recommended fix:

• For fast-changing facts:
  • generate them
  • or generalize them
• Reserve hand-written docs for:
  • mental models
  • workflows
  • constraints
  • trade-offs

Suggested rewrite order Copy Chapter

Pass 1 — Fix trust-breaking errors Copy Section

1. README.md
2. README.zh-CN.md
3. docs/index.md
4. docs/zh/index.md
5. docs/guide/getting-started.md
6. docs/zh/guide/getting-started.md
7. docs/comparison.md

Pass 2 — Rebuild the technical source-of-truth pages Copy Section

1. docs/developer/testing.md
2. docs/developer/architecture.md
3. docs/guide/installation.md
4. docs/zh/guide/installation.md

Pass 3 — Prevent the next round of drift Copy Section

1. Add a docs parity checklist to PR workflow.
2. Remove exact counts from hand-written copy unless generated.
3. Decide which pages are authoritative for:
   • install
   • browser bridge
   • testing
   • architecture
   • AI workflow

Concrete edits I would make next Copy Chapter

Small fast edits Copy Section

• Replace all 87+ / 90+ claims with 100+.
• Remove explore / synthesize / cascade from both home pages.
• Remove explore from docs/zh/guide/getting-started.md.
• Align install docs on Node/Bun support and skill refresh.

Medium rewrites Copy Section

• Rewrite docs/developer/testing.md from current filesystem state.
• Rewrite docs/developer/architecture.md from current module boundaries.

Process fix Copy Section

• Add a lightweight “doc drift” checklist to PRs that touch command surface, runtime support, testing strategy, or adapter discovery.

Bottom line Copy Chapter

The docs do not need a ground-up rewrite. They need a focused trust repair pass on entry pages, then a source-of-truth rebuild for testing and architecture, then a small process change so counts and mirrored pages stop drifting.

Developer Testing (`docs/developer/testing.md`) Copy Section

Testing Guide

测试配置以 vitest.config.ts 和 package.json 为准；不要维护容易过期的测试数量清单。

测试职责 Copy Chapter

本地验证 Copy Chapter

先跑改动对应的测试；共享逻辑或跨模块改动再扩大范围。

npm ci
npm run build

# 默认：unit + extension + adapter，不调用真实站点 E2E
npm test

# 目标文件
npx vitest run --project adapter clis/ctrip/auth.test.js

# 真实 CLI + 隔离的站点 fixture，无需登录或 Chrome
npx vitest run --project e2e tests/e2e/auth-contract.test.ts tests/e2e/management.test.ts

# 离线 CLI 与 daemon contract（固定端口测试会重启 daemon）
npm run test:e2e

# 少量严格的真实公开 API 检查
npx vitest run --project smoke

# 所有默认启用的 projects，包含公开 API smoke
npm run test:all

npm run build 已包含 TypeScript 检查。只需要类型反馈时可单独运行 npm run typecheck。
E2E 运行构建后的 CLI，修改源码后先重新 build。
e2e-fixed-port 使用固定端口，运行前确认不会与正在使用的 daemon 冲突。

如何避免重复测试 Copy Chapter

• 共享 helper 的完整边界矩阵放在 helper 所在层；各 command 保留必要 wiring 验证。
• Adapter test 覆盖站点 response shape 和解析边界；E2E 保留代表性的成功、typed error、exit code 与跨层连接验证，不复制整套解析矩阵。
• CLI 输出格式入口统一放在 tests/e2e/management.test.ts；具体格式渲染逻辑放在 src/output.test.ts。
• 不逐 command 抄录 columns、strategy、默认值做静态断言；manifest 一致性、全量 validate 与 column lint 统一负责声明检查。站点测试应调用行为；特有的 session/navigation contract 仍可保留。
• 相同 test body 如果调用不同 command，并不自动构成重复。
• 不添加“非零退出时只要有文字就通过”的 auth test：未知命令和程序崩溃也能满足这种断言。应检查具体错误类型、状态或输出内容。
• 不为了验证 auth 自动执行创建、删除、发布或付费操作；使用隔离 fixture 验证这些分支。

浏览器与真实站点 Copy Chapter

browser-public.test.ts 等真实站点测试依赖网络、站点状态和可用的 Browser Bridge。
部分测试允许站点限制导致的空数据，因此不能把这些通过结果视为完整登录流程已验证。
Auth 的确定性 CLI contract 在 auth-contract.test.ts，站点特有判断在 adapter tests。

可选测试通过环境变量启用：

# 手动运行真实站点、文章下载与 GitHub plugin 测试
OPENCLI_E2E=1 npm run test:e2e

# 真实 Chrome + extension contract
OPENCLI_AX_E2E=1 npx vitest run --project e2e tests/e2e/browser-ax-chrome.test.ts

# 站点槽位池（OPENCLI_SITE_SLOTS）：真实 daemon + extension + 隔离浏览器，本地 fixture；需先停掉占用 19825 的 daemon。
# 品牌版 Google Chrome 会忽略 --load-extension，需用 CHROME_PATH 指向 Chromium / Chrome for Testing
# 本地有界面时窗口可能被其他窗口遮挡、被系统标记为 hidden，渲染断言会不稳定，建议加 OPENCLI_E2E_HEADLESS=1
OPENCLI_E2E_HEADLESS=1 CHROME_PATH=/path/to/chrome-for-testing OPENCLI_AX_E2E=1 npx vitest run --project e2e tests/e2e/site-slots-chrome.test.ts

真实登录问题还应使用已登录浏览器，手动执行对应的只读命令验证。

CI 分工 Copy Chapter

Bun compatibility 不再作为每次 PR 的 gate；相关 runtime 改动应在本地额外运行 npm run test:bun。
CI 的精确触发条件与命令以 .github/workflows/ 为准。

跨平台 core/build 回归改由每周或手动检查，可能比每次 push 更晚发现。真实站点宽覆盖改为 opt-in；默认 CI 不证明所有网站当前可用。

Developer Ts Adapter (`docs/developer/ts-adapter.md`) Copy Section

TypeScript Adapter Guide

Use TypeScript adapters when you need browser-side logic, multi-step flows, DOM manipulation, or complex data extraction that goes beyond simple API fetching.

Basic Structure Copy Chapter

import { cli, Strategy } from '@jackwener/opencli/registry';
import { CommandExecutionError, EmptyResultError } from '@jackwener/opencli/errors';

cli({
  site: 'mysite',
  name: 'search',
  description: 'Search MySite',
  access: 'read', // 'read' | 'write'
  example: 'opencli mysite search <query> -f yaml',
  domain: 'www.mysite.com',
  strategy: Strategy.COOKIE,      // PUBLIC | COOKIE | INTERCEPT | UI
  args: [
    { name: 'query', required: true, help: 'Search query' },
    { name: 'limit', type: 'int', default: 10, help: 'Max results' },
  ],
  columns: ['title', 'url', 'date'],

  func: async (page, kwargs) => {
    const { query, limit = 10 } = kwargs;

    // Navigate and extract data
    await page.goto('https://www.mysite.com');

    const data = await page.evaluate(async (q: string) => {
      const res = await fetch(`/api/search?q=${encodeURIComponent(q)}`, {
        credentials: 'include',
      });
      return (await res.json()).results;
    }, String(query));

    if (!Array.isArray(data)) throw new CommandExecutionError('MySite returned an unexpected response');
    if (!data.length) throw new EmptyResultError('mysite search', 'Try a different keyword');

    return data.slice(0, Number(limit)).map((item: any) => ({
      title: item.title,
      url: item.url,
      date: item.created_at,
    }));
  },
});

Pipeline JSON Requests Copy Chapter

The fetch pipeline step can send JSON request bodies from Node or the browser
session. Define a body alongside an explicit HTTP method:

pipeline: [
  {
    fetch: {
      url: 'https://example.com/graphql',
      method: 'POST',
      body: {
        query: 'query Search($term: String!, $limit: Int!) { search(term: $term, limit: $limit) { id title } }',
        variables: {
          term: '${{ args.query }}',
          limit: '${{ args.limit }}',
        },
      },
    },
  },
  { select: 'data.search' },
]

Body templates support nested objects and arrays. A full expression keeps its
value type, so numbers, booleans, arrays, objects and null remain JSON values.
Use body: '${{ data }}' to send the previous step's complete result. Strings
inside values returned by expressions are treated as data, without another
template evaluation pass.

Bodies are JSON-encoded exactly once, including scalar strings. The step adds
Content-Type: application/json unless a content-type header is already present
(case-insensitive). It preserves explicit headers. GET and HEAD requests cannot
have a body; an omitted body sends no payload. A body that resolves to undefined
or cannot be JSON-serialized fails before any request is sent. Raw text, form data
and file uploads are not supported by this JSON request option.

Per-item Requests Copy Section

Set forEach: true to issue one request per element of the preceding step's
array, including when every request uses the same URL:

pipeline: [
  { fetch: 'https://example.com/catalog' },
  { select: 'entries' },
  {
    fetch: {
      url: 'https://example.com/graphql',
      method: 'POST',
      forEach: true,
      concurrency: 3,
      params: { language: '${{ args.language }}' },
      headers: { 'X-Request-Index': '${{ index }}' },
      body: {
        query: 'query Detail($id: ID!) { entry(id: $id) { id title } }',
        variables: { id: '${{ item.id }}' },
      },
    },
  },
]

URLs, query parameters, headers and bodies all receive the same per-item context:
item is the current element, index is zero-based, data is the complete input
array, and args contains command arguments. forEach: true requires an array;
an empty array produces [] without making requests. Use forEach: false to
force a single request, for example to send an entire array as one JSON body.
When omitted, existing implicit per-item URL fetching continues to apply.

Concurrency defaults to 5 and must be a positive integer. Results retain input
order even if requests finish out of order. Batch HTTP or network failures occupy
their result slot as { error: '...' }; successful requests are not repeated.
Body serialization completes before sending begins, so an undefined or
unserializable body fails the whole batch before any requests are issued.
Browser batches run in one evaluation and include the browser's credentials.

Access Metadata Copy Chapter

Every adapter must declare access: 'read' | 'write'.

• Use read when the command only retrieves data from the target product or account.
• Use write when the command changes remote product/account state, such as sending messages, publishing, liking, following, buying, deleting, creating remote assets, or starting paid/credit-consuming generation.
• download and export commands are read when they only read remote data and write local files; local filesystem writes are a separate permission dimension.

Adapters may also declare example to override the canonical invocation shown in agent-facing help. Prefer YAML examples, e.g. opencli mysite search <query> -f yaml.

Listing↔Detail ID Pairing (advisory) Copy Chapter

If your site exposes both a listing-class command (search / hot / top /
recent / ...) and a detail-class command (read / paper / article /
post / view / ...), it's usually nicer for agents if listing rows surface
an id-shaped column that round-trips into the detail command's positional
arg. Without that, an agent can't follow up on a row without re-searching by
title or scraping a URL out of band.

This is a soft convention, not a CI gate. Many legitimate listings
genuinely don't pair (topic-string trending, profile-attribute rows,
UI-only sessions). Use judgment per command, not a checklist.

Run npm run advise:listing-id-pairing to see candidate listings without an
id column. See Listing↔Detail ID Pairing
for context, the full pattern table, and how to add an id to a listing.

Strategy Types Copy Chapter

Browser Session Reuse Copy Chapter

Browser-backed commands are one-shot by default: each execution gets a fresh
tab lease and releases it when the command returns. For interactive sites where
successive commands should continue in the same page, opt into a persistent site
session:

cli({
  site: 'mysite',
  name: 'ask',
  strategy: Strategy.COOKIE,
  siteSession: 'persistent',
  // ...
});

siteSession: 'persistent' makes commands for the same site share a stable
adapter site tab and keeps that tab open until it is explicitly closed. Users
can override the adapter default with --site-session ephemeral or force
persistence with --site-session persistent.

A persistent site tab is shared, so concurrent persistent commands for one site
can navigate each other's page. Users who batch a site can instead pool it with
OPENCLI_SITE_SLOTS (for example xiaohongshu:1:1500-3000): each command run
borrows one of poolSize persistent slot sessions (site:<site>#<n>, one warm
tab each) for its whole duration, reads included, and waits in a daemon-side
queue when every slot is busy. A command's --timeout covers the queue wait and
the run together; without one, the wait alone is capped at 60s. The optional interval spaces slot grants start-to-start, so the
pace applies per command run rather than per navigation. A waiting command that
exits leaves the queue. When a holder stops sending commands for longer than the
session-lease TTL, its slot can go to the next waiting run. Commands from expired
or released runs are rejected until they acquire a slot again. Adapters need no changes to be pooled.

All adapter tabs share one automation window, and only its active tab renders.
A pooled run brings its slot tab to the front when it starts, but another
command opening a tab during the run (or a second slot of the same site) puts it
in the background, where rAF and IntersectionObserver-driven lazy loading stall.
Keep poolSize at 1 for render-dependent commands.
Slot pools require Browser Bridge; direct CDP callers can opt out with
--site-session ephemeral. Pool sizes are limited to 1–32 and intervals/wait
budgets to 2,147,483,647 ms. Concurrent callers must use the same policy while a
pool has active runs or waiters. A policy can change after the pool is idle.
Manual slot-session commands are rejected while a run holds that slot; runs
must acquire their own slot and cannot reuse a run identity in another pool.

The `page` Object Copy Chapter

The page parameter provides browser interaction methods:

• page.goto(url) — Navigate to a URL
• page.evaluate(fn, ...args) — Execute a serializable function in the page context. Pass Node-side values through JSON-serializable args; the function cannot close over local variables.
• page.evaluate(script) — Execute a raw JavaScript string in the page context. Prefer function form for new adapter code.
• page.waitForSelector(selector) — Wait for an element
• page.click(selector) — Click an element
• page.type(selector, text) — Type text into an input

The `kwargs` Object Copy Chapter

Contains parsed CLI arguments as key-value pairs. Always destructure with defaults:

const { query, limit = 10, format = 'json' } = kwargs;

For most search/read/detail commands, the main subject should be positional (opencli mysite search "rust", opencli mysite article 123) instead of a named flag such as --query or --id. Keep named flags for optional modifiers.

Error Handling Copy Chapter

Prefer throwing CliError subclasses from src/errors.ts for expected adapter failures:

• AuthRequiredError for missing login / cookies
• EmptyResultError for empty but valid responses
• CommandExecutionError for unexpected API or browser failures
• TimeoutError for site timeouts
• ArgumentError for invalid user input

Avoid raw Error for normal adapter control flow. This keeps top-level CLI output consistent and preserves hints for users.

AI-Assisted Development Copy Chapter

Use the opencli-adapter-author skill plus the opencli browser * primitives to scaffold and verify adapters end-to-end:

# Recon on the target site
opencli browser --session research open https://example.com
opencli browser --session research network
opencli browser --session research state

# Scaffold + verify
opencli adapter init mysite/trending
opencli adapter test mysite/trending

See AI Workflow for the full loop and the adapter-author skill for the step-by-step runbook.

Developer Yaml Adapter (`docs/developer/yaml-adapter.md`) Copy Section

YAML Adapter Guide (Deprecated)

YAML adapters are no longer supported. All adapters now use TypeScript with the cli() API from @jackwener/opencli/registry.

See Contributing Guide for how to write TypeScript adapters using the pipeline API or func().

Development Auth Audit 2026 10 (`docs/development/auth-audit-2026-10.md`) Copy Section

Authentication audit — October 2026

Base: 77af6bc4 (OpenCLI 1.8.8). The audit covers all 70 auth.js / whoami.js entry files, shared registration, CLI status/refresh aggregation, Browser Bridge cookie transport, direct CDP cookie scope, command discovery, and dependency advisories. The complete unit, extension and adapter suites were run before and after the changes. This is a source and regression audit; it is not a claim that every website was tested with a live account.

Confirmed defects addressed Copy Chapter

Auth result contract Copy Chapter

• A full probe must return a verified account or throw a typed error. AUTH_REQUIRED means a positive login-required signal; network failures, unexpected responses and unsupported DOM layouts are command errors.
• A quick probe is optional and may return unknown. Ctrip, ChatGPT and the three Google adapters no longer infer a valid session from cookie names. Use opencli auth status --site ctrip --full or opencli ctrip whoami for verification.
• Missing display names or redacted IDs do not invalidate an account established by the authoritative probe.
• Login polling must preserve the user's login surface and keep infrastructure errors separate from pending authentication.

Reproduction and checks Copy Chapter

npm run build
npm test
npx vitest run --project e2e tests/e2e/auth-contract.test.ts
npm run typecheck
npm run check:typed-error-lint
npm run check:silent-column-drop
npm audit --omit=dev

The CLI fixture test starts an isolated CDP server on a random port, evaluates the actual adapter JavaScript against fixture responses, and invokes the built CLI in child processes. It checks output, error codes and full/quick status behavior without requiring accounts or modifying the user's daemon.

Live Ctrip and Gemini probes used the existing browser connection with the repository's actual adapter functions. The separate v1.8.8 CLI Browser Bridge extension was disconnected, so live browser checks and CLI transport checks were performed separately. No cookies or tokens are stored in fixtures or this report.

Remaining verification limits Copy Chapter

Other adapters still have site-specific cookie/DOM assumptions. In particular, cookie-only identities (1688/JD), cookie preconditions in other API-backed adapters, and DOM absence or challenge pages interpreted as logout require individual live fixtures before changing their contracts. The audit found these as risk patterns, not confirmed current failures on those accounts. Blanket removal or guessing replacement endpoints would not establish correctness.

Several development-tool dependency advisories remain in the Vite/VitePress/Vue toolchain; the production dependency tree is clear. The existing static-lint baselines also remain (they are not evidence of a clean repository).

Entry-file inventory Copy Section

The following inventory records the reviewed entrypoints, not live-site certification.

• clis/12306/auth.js
• clis/1688/auth.js
• clis/1point3acres/auth.js
• clis/amazon/auth.js
• clis/band/auth.js
• clis/bilibili/auth.js
• clis/boss/auth.js
• clis/chaoxing/auth.js
• clis/chatgpt/auth.js
• clis/claude/auth.js
• clis/coupang/auth.js
• clis/ctrip/auth.js
• clis/deepseek/auth.js
• clis/dianping/auth.js
• clis/douban/auth.js
• clis/doubao/auth.js
• clis/douyin/auth.js
• clis/dribbble/auth.js
• clis/facebook/auth.js
• clis/flomo/auth.js
• clis/gemini/auth.js
• clis/gitee/auth.js
• clis/github/auth.js
• clis/gmail/auth.js
• clis/grok/auth.js
• clis/hf/auth.js
• clis/hupu/auth.js
• clis/instagram/auth.js
• clis/jd/auth.js
• clis/jianyu/auth.js
• clis/jike/auth.js
• clis/jimeng/auth.js
• clis/ke/auth.js
• clis/kimi/auth.js
• clis/linkedin/auth.js
• clis/linkedin-learning/auth.js
• clis/linux-do/auth.js
• clis/maimai/auth.js
• clis/manus/auth.js
• clis/midjourney/whoami.js
• clis/notebooklm/auth.js
• clis/nowcoder/auth.js
• clis/pixiv/auth.js
• clis/powerchina/auth.js
• clis/quark/auth.js
• clis/qwen/auth.js
• clis/reddit/auth.js
• clis/reddit/whoami.js
• clis/rednote/auth.js
• clis/reuters/auth.js
• clis/slock/whoami.js
• clis/suno/auth.js
• clis/taobao/auth.js
• clis/tiktok/auth.js
• clis/toutiao/auth.js
• clis/twitter/auth.js
• clis/upwork/auth.js
• clis/v2ex/auth.js
• clis/wechat-channels/auth.js
• clis/weibo/auth.js
• clis/weread/auth.js
• clis/xianyu/auth.js
• clis/xiaoe/auth.js
• clis/xiaohongshu/auth.js
• clis/xiaoyuzhou/auth.js
• clis/xueqiu/auth.js
• clis/youtube/auth.js
• clis/yuanbao/auth.js
• clis/zhihu/auth.js
• clis/zsxq/auth.js

Guide Agent Browser Alternative (`docs/guide/agent-browser-alternative.md`) Copy Section

title: OpenCLI vs agent-browser — Browser Automation and Migration Copy Chapter

OpenCLI vs agent-browser

OpenCLI is a general-purpose browser automation CLI and an alternative to agent-browser for AI agent browsing. Use opencli browser to navigate websites, inspect page state, click, fill forms, extract content, and take screenshots. A site does not need a pre-built adapter.

OpenCLI also provides reusable site commands. These extend its browser capabilities; the adapter catalog is not the boundary of what an agent can browse.

Can OpenCLI replace agent-browser? Copy Chapter

Yes, for workflows built around the observe → act → observe browser loop. An agent can operate an unfamiliar website directly through OpenCLI, including multi-step navigation and form entry. It does not have to generate an adapter first.

The CLI syntax, element references, session lifecycle, and output formats differ. Migrate the actions in your workflow and verify the result; existing agent-browser scripts are not command-line compatible. If a workflow depends on a specialized flag or runtime feature, check that requirement individually rather than assuming complete feature parity.

Two ways to operate a website Copy Chapter

Both browser primitives and adapter commands execute without built-in LLM inference. An AI agent choosing browser actions still has its own model usage. Adapter commands can reduce the number of actions the agent needs to plan.

Start browsing without an adapter Copy Chapter

Install OpenCLI and the Browser Bridge extension, then check the connection:

npm install @jackwener/opencli
opencli doctor
npx skills add jackwener/opencli --skill opencli-browser

Run the browser loop with a named session:

opencli browser --session work open https://example.com
opencli browser --session work state
opencli browser --session work extract
opencli browser --session work screenshot /tmp/opencli-example.png
opencli browser --session work close

Reuse work across commands to preserve the session. state returns interactive elements with numeric references. On a page with an interactive element, use a reference from the latest state:

opencli browser --session work click 12
opencli browser --session work state

12 is an illustrative reference, not a fixed element on example.com. Inspect state again after navigation or page changes. close releases the session's tab lease; do not assume it has the same lifecycle semantics as another tool's browser shutdown.

Command migration reference Copy Chapter

The agent-browser examples below follow its upstream README. Element references are specific to each tool's current page snapshot.

Use opencli browser --help and opencli browser work <command> --help for current options. Do not copy @e2 into OpenCLI or assume reference 2 identifies the same element in both tools.

When are adapters useful? Copy Chapter

If an agent needs a site's trending posts every day, opencli bilibili hot -f json can replace repeated browser exploration with one structured command. If the site has no adapter, the agent can still browse it immediately. Add an adapter when the workflow benefits from a reusable interface.

See Getting Started, the broader tool comparison, and Extending OpenCLI.

Guide Browser Bridge (`docs/guide/browser-bridge.md`) Copy Section

Browser Bridge Setup

⚠️ Important: Browser commands reuse your Chrome login session. You must be logged into the target website in Chrome before running commands.

OpenCLI connects to your browser through a lightweight Browser Bridge Chrome Extension + micro-daemon (zero config, auto-start).

Extension Installation Copy Chapter

Method 1: Chrome Web Store (Recommended) Copy Section

Install OpenCLI from the Chrome Web Store.

Method 2: Download Pre-built Release Copy Section

1. Go to the GitHub Releases page and download the latest opencli-extension-v{version}.zip.
2. Unzip the file and open chrome://extensions, enable Developer mode (top-right toggle).
3. Click Load unpacked and select the unzipped folder.

Method 3: Load Unpacked Source (For Developers) Copy Section

1. Open chrome://extensions and enable Developer mode.
2. Click Load unpacked and select the extension/ directory from the repository.

Verification Copy Chapter

That's it! The daemon auto-starts when you run any browser command. No tokens, no manual configuration.

opencli doctor            # Check extension + daemon connectivity

Tab Targeting Copy Chapter

Browser commands require an explicit --session <name> option. Use the same session name for a multi-step flow, and use different names to isolate parallel work.

opencli browser --session baidu open https://www.baidu.com/
opencli browser --session baidu tab list
opencli browser --session baidu tab new https://www.baidu.com/
opencli browser --session baidu eval --tab <targetId> 'document.title'
opencli browser --session baidu tab select <targetId>
opencli browser --session baidu get title
opencli browser --session baidu tab close <targetId>

Key rules:

• opencli browser --session <session> open and opencli browser --session <session> tab new [url] return a targetId.
• opencli browser --session <session> tab list prints the targetId values of tabs that already exist.
• --tab <targetId> routes a single browser command to that specific tab.
• tab new creates a new tab but does not change the default browser target.
• tab select <targetId> makes that tab the default target for later untargeted opencli browser ... commands.
• tab close <targetId> removes the tab; if it was the current default target, the stored default is cleared.

Session Lifecycle Copy Chapter

Use a stable session name when you want multiple opencli browser commands to keep operating on the same page:

opencli browser --session my-session open https://example.com
opencli browser --session my-session state
opencli browser --session my-session extract "main"

Owned browser sessions use an interactive tab lease with a 10-minute idle timeout. Release it explicitly when done:

opencli browser --session my-session close

Use opencli browser --session <session> bind when you want to attach OpenCLI to a Chrome tab you already opened manually. Bound sessions do not have the owned-session idle close timer; they stay attached until unbind, tab close, window close, or daemon restart. For owned sessions, use --window foreground to watch OpenCLI work in a visible automation window, or --window background to keep that automation window out of the way.

The OpenCLI Browser and OpenCLI Adapter tab groups are extension-managed automation containers; avoid putting your own long-lived tabs in them or renaming them.

Native Chrome management Copy Chapter

Use Chrome APIs to manage ordinary browser tabs, groups and windows:

opencli browser chrome describe
opencli browser chrome describe tabs.group
opencli browser chrome call tabs.query '[{}]'
opencli browser chrome call tabs.group '[{"tabIds":[123,456]}]'
opencli browser chrome call tabGroups.update '[789,{"title":"Research","color":"blue"}]'
opencli browser chrome call tabs.ungroup '[[123,456]]'

Replace the example IDs with numeric Chrome IDs returned by the native queries, not the targetId strings used by page commands. Arguments are a JSON array of positional arguments. The success envelope contains native Chrome values in data; methods returning nothing return null.

describe lists the supported browser-management methods. For a method it returns its signature, availability, current permissions and official reference URL. These commands use the selected --profile and do not attach a page. Native-created tabs and windows persist after the CLI exits. Mutations affecting an active OpenCLI session or its managed group return managed_resource_conflict.

API discovery Copy Chapter

opencli browser --session research open https://example.com
opencli browser --session research network --static
# Follow a returned request key to inspect its captured response:
opencli browser --session research network --detail '<key>'

network summarizes captured API requests; --static also parses loaded JavaScript with an AST scanner. Each candidate includes method, URL, parameter names and evidence (network, static, or network+static). Script locations and request keys link back to the evidence. Unresolved expressions appear as EXPR; they are not guessed into observed routes.

Static candidates are not executed. The agent decides which endpoints to investigate, writes a normal JS adapter, and runs it with the existing CLI. There is no draft store or activation workflow.

Limits are explicit: up to 20 document scripts, 2 MiB per script, a 2 MiB combined inline-script budget, and a 10-second timeout per external script. External scripts are fetched through Node without browser credentials. Imports, workers, alias/data-flow resolution and scripts not present in the current document are not crawled. The report includes parse/fetch errors, omitted scripts and analysisComplete for this bounded scan; it does not claim complete site coverage. A drained network buffer falls back to the session cache, with networkSource and networkSavedAt identifying cached evidence.

Real-browser regression test Copy Section

After building the CLI and extension, use Chrome for Testing or Chromium:

OPENCLI_P0_E2E=1 CHROME_PATH=/path/to/chrome npx vitest run tests/e2e/browser-p0-chrome.test.ts

The test uses a temporary Chrome profile and an installation copy with a separate port. It covers native group operations, discovery/cache, and the existing Node/browser JS adapter contracts.

How It Works Copy Chapter

┌─────────────┐     WebSocket      ┌──────────────┐     Chrome API     ┌─────────┐
│  opencli    │ ◄──────────────► │  micro-daemon │ ◄──────────────► │  Chrome  │
│  (Node.js)  │    localhost:19825  │  (auto-start) │    Extension       │ Browser  │
└─────────────┘                    └──────────────┘                    └─────────┘

The daemon manages the WebSocket connection between your CLI commands and the Chrome extension. The extension executes JavaScript in the context of web pages, with access to the logged-in session.

Daemon Lifecycle Copy Chapter

The daemon auto-starts on first browser command and stays alive persistently.

opencli daemon stop      # Graceful shutdown

The daemon is persistent — it stays alive until you explicitly stop it (opencli daemon stop) or uninstall the package.

Running OpenCLI from a remote machine Copy Chapter

If you need to run opencli on a remote server (CI runner, agent host) but keep the browser session on your local machine, see Remote Orchestration. It walks through the SSH reverse-tunnel pattern so the daemon never leaves localhost.

Native input and hidden pages Copy Section

Native click, key, hover, double-click and drag actions require the target page
to report document.visibilityState === 'visible'. If Chrome reports a hidden
page (for example a background tab or a minimized/occluded window), OpenCLI
returns COMMAND_EXEC before dispatching native input. Visibility-check failures
also stop the action. Select the intended tab and restore/uncover its window,
then retry. OpenCLI does not automatically focus the window or replay a blocked
native action through synthetic DOM events. Visibility is a precondition, not a
verification that the application completed the requested action.

Guide Exit Codes (`docs/guide/exit-codes.md`) Copy Section

Exit Codes

opencli follows Unix sysexits.h conventions so it integrates naturally with shell pipelines and CI scripts.

Example: branch on exit code Copy Chapter

opencli spotify status || echo "exit $?"   # 69 if browser not running

opencli twitter timeline 2>/dev/null
[ $? -eq 77 ] && opencli twitter login      # auto-auth if not logged in