Qiaomu Opencli

OpenCLI — Complete Guide

Make any website or Electron App your CLI. Reuse Chrome login, zero risk, AI-powered discovery.

---

Install & Run

npm install -g @jackwener/opencli
opencli <command>

npm update -g @jackwener/opencli   # Update
opencli --version                  # Check version

Prerequisites

Browser commands require: 1. Chrome running (logged into target sites) 2. opencli Browser Bridge Chrome extension installed 3. Daemon auto-starts on first browser command

opencli doctor    # Diagnose extension + daemon connectivity

Public API commands (hackernews, arxiv, npm, pubmed…) need no browser.

---

Command Quick Reference

Usage: opencli <site> <command> [args] [--limit N] [-f json|yaml|md|csv|table]

Type legend: 🌐 = Browser (needs Chrome login) · ✅ = Public API · 🖥️ = Desktop (Electron/CDP) · 🔧 = External CLI

Website Adapters (136 sites)

Desktop Apps (CDP/Electron)

External CLI (passthrough)

opencli external install discord    # Install external CLI
opencli external list               # Show all external CLIs
opencli gh pr list --limit 5       # Passthrough to gh
opencli wx messages                 # Passthrough to wx-cli

Management Commands

opencli list [-f json|yaml]         # All available commands
opencli doctor                      # Diagnose extension + daemon
opencli daemon status|restart|stop  # Daemon control
opencli adapter eject [site]        # Eject adapter to ~/.opencli/clis/ for local editing
opencli adapter reset [site]        # Reset ejected adapter to upstream
opencli profile list|use|rename     # Chrome profile management
opencli plugin list|install|update  # Plugin management

---

Browser Automation

Control Chrome step-by-step. Reuses existing login sessions.

Critical Rules

1. Always `state` first — never guess element indices. state returns structured DOM with [N] indices, is instant and costs zero tokens. 2. Never use `eval` to click or type — use click <N> and type <N> "text" instead. 3. Verify inputs with `get value` — after type, run get value <index> to confirm. 4. Run `state` after every page change — after open, click (on links), scroll. 5. Chain commands aggressively — open + state, type + type + click in one && chain. Target 3-5 tool calls total. 6. `eval` is read-only — use ONLY for data extraction (JSON.stringify(...)), never for clicking/typing/navigating. 7. Prefer `network` to discover APIs — JSON APIs are more reliable than DOM scraping.

Command Cost Guide

Commands

# Navigation
opencli browser open <url>
opencli browser back
opencli browser scroll down|up [--amount N]

# Inspect (free)
opencli browser state                    # Primary — structured DOM with [N] indices
opencli browser screenshot [path.png]    # Only for user deliverables

# Get (free)
opencli browser get title|url|html
opencli browser get text|value|attributes <index>

# Interact
opencli browser click <index>
opencli browser type <index> "text"
opencli browser select <index> "option"
opencli browser keys "Enter"             # Enter, Escape, Tab, Control+a

# Wait
opencli browser wait time 3
opencli browser wait selector ".loaded" [--timeout 5000]
opencli browser wait text "Success"

# Extract (read-only)
opencli browser eval "JSON.stringify([...document.querySelectorAll('h2')].map(e => e.textContent))"

# Network (API discovery)
opencli browser network
opencli browser network --detail 3      # Full response body of request #3

# Save as CLI
opencli browser init hn/top             # Scaffold adapter at ~/.opencli/clis/hn/top.ts
opencli browser verify hn/top           # Test the adapter

opencli browser close

Chaining Examples

# GOOD: open + inspect in one call
opencli browser open https://example.com && opencli browser state

# GOOD: fill form in one call
opencli browser type 3 "hello" && opencli browser type 4 "world" && opencli browser click 7

# GOOD: click + wait + state (for page-changing clicks)
opencli browser click 12 && opencli browser wait time 1 && opencli browser state

Troubleshooting

---

Auto-Fix Broken Adapters

When an opencli command fails because a website changed its DOM/API, automatically diagnose, fix, and retry — don't just report the error.

Safety Boundaries

• `AUTH_REQUIRED` (exit 77) — STOP. Tell user to log in. Do not modify code.
• `BROWSER_CONNECT` (exit 69) — STOP. Tell user to run opencli doctor.
• CAPTCHA / rate limiting — STOP. Not an adapter issue.
• Only modify the file at RepairContext.adapter.sourcePath. Never touch src/, extension/, tests/, package.json.
• Max 3 repair rounds per failure.

Before Repairing: "Empty" ≠ "Broken"

EMPTY_RESULT is often NOT a bug — platforms degrade results under anti-scrape heuristics. Before patching:

• Retry with an alternative query (e.g., "AI 攻略" vs "AI")
• Spot-check in a normal Chrome tab — if visible there but empty via adapter, it's auth/rate-limit
• 0 results from a search is a valid answer, not a bug

Repair Workflow

Step 1: Collect diagnostics

OPENCLI_DIAGNOSTIC=1 opencli <site> <command> [args...] 2>diagnostic.json
cat diagnostic.json | sed -n '/___OPENCLI_DIAGNOSTIC___/{n;p;}'

Output is a RepairContext JSON with: error.code, adapter.sourcePath, adapter.source, page.snapshot, page.networkRequests.

Step 2: Classify the failure

Step 3: Explore live site

# DOM changed
opencli browser open https://example.com/target-page && opencli browser state

# API changed
opencli browser open https://example.com && opencli browser network
opencli browser network --detail <index>

Step 4: Patch the adapter

Read RepairContext.adapter.sourcePath and make minimal targeted fixes:

• Selector update: replace .old-class with .new-class
• API endpoint: update URL in fetch()
• Response schema: fix data path (data.results → data.data.items)

Step 5: Verify

opencli <site> <command> [args...]    # Run without diagnostic mode

If still failing, go back to Step 1. After 3 rounds, stop and report what was tried.

---

Create New Adapters

Quick Method (4 steps — for a single URL + goal)

1. Open page + capture API

   # Navigate and wait 3-5s for page to load
   # Check network for JSON APIs
   opencli browser open <url> && opencli browser wait time 3 && opencli browser network

2. Lock down the target API — find the one returning application/json with the data you need

3. Verify the API is reusable

   # Test in browser context
   fetch('/api/endpoint', { credentials: 'include' }).then(r => r.json())

4. Write adapter from template (see templates below)

Auth decision tree:

fetch(url) works?                          → Tier 1: PUBLIC (browser: false)
fetch(url, {credentials:'include'}) works? → Tier 2: COOKIE (most common)
Needs Bearer/CSRF header?                  → Tier 3: HEADER
Page requests it but fetch can't?          → Tier 4: INTERCEPT (installInterceptor)

Adapter Templates

Tier 1 — Public API (fastest)

// ~/.opencli/clis/<site>/<name>.ts
import { cli, Strategy } from '@jackwener/opencli/registry';

cli({
  site: 'mysite', name: 'hot', description: '一句话描述',
  domain: 'www.example.com',
  strategy: Strategy.PUBLIC, browser: false,
  args: [{ name: 'limit', type: 'int', default: 20 }],
  columns: ['rank', 'title', 'score'],
  func: async (_page, kwargs) => {
    const res = await fetch('https://api.example.com/hot');
    const data = await res.json();
    return data.items.slice(0, kwargs.limit).map((item: any, i: number) => ({
      rank: i + 1, title: item.title, score: item.score,
    }));
  },
});

Tier 2 — Cookie auth (most common)

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

cli({
  site: 'mysite', name: 'feed', description: '一句话描述',
  domain: 'www.example.com',
  strategy: Strategy.COOKIE, browser: true,
  args: [{ name: 'limit', type: 'int', default: 20 }],
  columns: ['rank', 'title', 'value'],
  func: async (page, kwargs) => {
    await page.goto('https://www.example.com');
    const data = await page.evaluate(`(async () => {
      const res = await fetch('/api/feed', { credentials: 'include' });
      const d = await res.json();
      return (d.data?.items || []).map(item => ({ title: item.title, value: item.value }));
    })()`);
    return (data as any[]).slice(0, kwargs.limit).map((item, i) => ({
      rank: i + 1, title: item.title || '', value: item.value || '',
    }));
  },
});

Tier 4 — Intercept (for sites with signing/anti-scrape)

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

cli({
  site: 'mysite', name: 'feed', description: '一句话描述',
  domain: 'www.example.com',
  strategy: Strategy.INTERCEPT, browser: true,
  args: [{ name: 'limit', type: 'int', default: 20 }],
  columns: ['rank', 'title', 'value'],
  func: async (page, kwargs) => {
    await page.goto('https://www.example.com/target');
    await page.wait(3);
    await page.installInterceptor('api-keyword');       // URL substring match
    await page.autoScroll({ times: 2, delayMs: 2000 }); // Trigger lazy load
    const requests = await page.getInterceptedRequests();
    if (!requests?.length) return [];
    const results: any[] = [];
    for (const req of requests) {
      results.push(...(req.data?.data?.items || []));
    }
    return results.slice(0, kwargs.limit).map((item, i) => ({
      rank: i + 1, title: item.title || '', value: item.value || '',
    }));
  },
});

Test After Writing

npm run build                              # Syntax check
opencli list | grep mysite                 # Confirm registered
opencli mysite mycommand --limit 3 -v      # Verify actual output

Full Exploration Guide (for new sites)

When you need to explore a site from scratch rather than a single URL:

Step 1: API Discovery

opencli explore https://www.example.com --site mysite

Outputs to .opencli/explore/mysite/: endpoints.json, capabilities.json, auth.json

Or auto-generate everything:

opencli generate https://www.example.com --goal "hot"

Key discovery tactics:

• `.json` suffix trick — Reddit-style sites: just append .json to URL for clean REST data
• `__INITIAL_STATE__` — SSR sites (Bilibili, Xiaohongshu) embed data in window.__INITIAL_STATE__
• Active interaction — Lazy-load APIs (comments, subtitles) only appear after clicking a button
• Pinia/Vuex intercept — Vue sites: call store actions to trigger signed requests without reverse-engineering signatures

Step 2: Pick auth tier — run opencli cascade <api-url> to auto-detect

Step 3: Find existing adapter to copy — ls clis/<site>/, copy the closest one, change 3 fields: name, API URL, field mapping

Step 4: Test

opencli mysite hot --limit 3 -v      # verbose: see pipeline data flow
opencli mysite hot -f json | jq '.[0]'  # confirm JSON structure

Common pitfalls:

qiaomu-opencli

Use when running OpenCLI commands to interact with websites (Bilibili, Twitter, Reddit, Xiaohongshu, etc.), desktop apps (Cursor, Notion, Claude), or public APIs (HackerNews, arXiv, npm, pubmed).

✨ 核心特性

<!-- TODO: 用 3-5 个要点说明这个 skill 的核心价值 -->

• 🚀 特性 1：描述第一个核心能力
• 🎯 特性 2：描述第二个核心能力
• 💡 特性 3：描述第三个核心能力

📦 安装

npx skills add joeseesun/qiaomu-opencli

📋 前置要求

<!-- TODO: 填写该 Skill 所需的前置条件（工具、账号、配置等） -->

• [ ] Claude Code 已安装
• [ ] （在此补充其他依赖，如 Python 3.9+、特定 CLI 工具等）

🚀 快速开始

安装后，在 Claude Code 中用自然语言描述你的需求即可。

💡 使用场景

<!-- TODO: 填写 2-3 个真实的使用场景，展示"我想做什么" → "AI 怎么做" -->

场景 1：[场景名称]

你说："[用户的自然语言输入]"
AI 做：[AI 的具体操作步骤]

场景 2：[场景名称]

你说："[用户的自然语言输入]"
AI 做：[AI 的具体操作步骤]

OpenCLI — Complete Guide

Make any website or Electron App your CLI. Reuse Chrome login, zero risk, AI-powered discovery.

---

Install & Run

npm install -g @jackwener/opencli
opencli <command>

npm update -g @jackwener/opencli   # Update
opencli --version                  # Check version

Prerequisites

Browser commands require: 1. Chrome running (logged into target sites) 2. opencli Browser Bridge Chrome extension installed 3. Daemon auto-starts on first browser command

opencli doctor    # Diagnose extension + daemon connectivity

Public API commands (hackernews, arxiv, npm, pubmed…) need no browser.

---

Command Quick Reference

Usage: opencli <site> <command> [args] [--limit N] [-f json|yaml|md|csv|table]

Type legend: 🌐 = Browser (needs Chrome login) · ✅ = Public API · 🖥️ = Desktop (Electron/CDP) · 🔧 = External CLI

Website Adapters (136 sites)

Desktop Apps (CDP/Electron)

External CLI (passthrough)

opencli external install discord    # Install external CLI
opencli external list               # Show all external CLIs
opencli gh pr list --limit 5       # Passthrough to gh
opencli wx messages                 # Passthrough to wx-cli

Management Commands

opencli list [-f json|yaml]         # All available commands
opencli doctor                      # Diagnose extension + daemon
opencli daemon status|restart|stop  # Daemon control
opencli adapter eject [site]        # Eject adapter to ~/.opencli/clis/ for local editing
opencli adapter reset [site]        # Reset ejected adapter to upstream
opencli profile list|use|rename     # Chrome profile management
opencli plugin list|install|update  # Plugin management

---

Browser Automation

Control Chrome step-by-step. Reuses existing login sessions.

Critical Rules

1. Always `state` first — never guess element indices. state returns structured DOM with [N] indices, is instant and costs zero tokens. 2. Never use `eval` to click or type — use click <N> and type <N> "text" instead. 3. Verify inputs with `get value` — after type, run get value <index> to confirm. 4. Run `state` after every page change — after open, click (on links), scroll. 5. Chain commands aggressively — open + state, type + type + click in one && chain. Target 3-5 tool calls total. 6. `eval` is read-only — use ONLY for data extraction (JSON.stringify(...)), never for clicking/typing/navigating. 7. Prefer `network` to discover APIs — JSON APIs are more reliable than DOM scraping.

Command Cost Guide

Commands

# Navigation
opencli browser open <url>
opencli browser back
opencli browser scroll down|up [--amount N]

# Inspect (free)
opencli browser state                    # Primary — structured DOM with [N] indices
opencli browser screenshot [path.png]    # Only for user deliverables

# Get (free)
opencli browser get title|url|html
opencli browser get text|value|attributes <index>

# Interact
opencli browser click <index>
opencli browser type <index> "text"
opencli browser select <index> "option"
opencli browser keys "Enter"             # Enter, Escape, Tab, Control+a

# Wait
opencli browser wait time 3
opencli browser wait selector ".loaded" [--timeout 5000]
opencli browser wait text "Success"

# Extract (read-only)
opencli browser eval "JSON.stringify([...document.querySelectorAll('h2')].map(e => e.textContent))"

# Network (API discovery)
opencli browser network
opencli browser network --detail 3      # Full response body of request #3

# Save as CLI
opencli browser init hn/top             # Scaffold adapter at ~/.opencli/clis/hn/top.ts
opencli browser verify hn/top           # Test the adapter

opencli browser close

Chaining Examples

# GOOD: open + inspect in one call
opencli browser open https://example.com && opencli browser state

# GOOD: fill form in one call
opencli browser type 3 "hello" && opencli browser type 4 "world" && opencli browser click 7

# GOOD: click + wait + state (for page-changing clicks)
opencli browser click 12 && opencli browser wait time 1 && opencli browser state

Troubleshooting

---

Auto-Fix Broken Adapters

When an opencli command fails because a website changed its DOM/API, automatically diagnose, fix, and retry — don't just report the error.

Safety Boundaries

• `AUTH_REQUIRED` (exit 77) — STOP. Tell user to log in. Do not modify code.
• `BROWSER_CONNECT` (exit 69) — STOP. Tell user to run opencli doctor.
• CAPTCHA / rate limiting — STOP. Not an adapter issue.
• Only modify the file at RepairContext.adapter.sourcePath. Never touch src/, extension/, tests/, package.json.
• Max 3 repair rounds per failure.

Before Repairing: "Empty" ≠ "Broken"

EMPTY_RESULT is often NOT a bug — platforms degrade results under anti-scrape heuristics. Before patching:

• Retry with an alternative query (e.g., "AI 攻略" vs "AI")
• Spot-check in a normal Chrome tab — if visible there but empty via adapter, it's auth/rate-limit
• 0 results from a search is a valid answer, not a bug

Repair Workflow

Step 1: Collect diagnostics

OPENCLI_DIAGNOSTIC=1 opencli <site> <command> [args...] 2>diagnostic.json
cat diagnostic.json | sed -n '/___OPENCLI_DIAGNOSTIC___/{n;p;}'

Output is a RepairContext JSON with: error.code, adapter.sourcePath, adapter.source, page.snapshot, page.networkRequests.

Step 2: Classify the failure

Step 3: Explore live site

# DOM changed
opencli browser open https://example.com/target-page && opencli browser state

# API changed
opencli browser open https://example.com && opencli browser network
opencli browser network --detail <index>

Step 4: Patch the adapter

Read RepairContext.adapter.sourcePath and make minimal targeted fixes:

• Selector update: replace .old-class with .new-class
• API endpoint: update URL in fetch()
• Response schema: fix data path (data.results → data.data.items)

Step 5: Verify

opencli <site> <command> [args...]    # Run without diagnostic mode

If still failing, go back to Step 1. After 3 rounds, stop and report what was tried.

---

Create New Adapters

Quick Method (4 steps — for a single URL + goal)

1. Open page + capture API

   # Navigate and wait 3-5s for page to load
   # Check network for JSON APIs
   opencli browser open <url> && opencli browser wait time 3 && opencli browser network

2. Lock down the target API — find the one returning application/json with the data you need

3. Verify the API is reusable

   # Test in browser context
   fetch('/api/endpoint', { credentials: 'include' }).then(r => r.json())

4. Write adapter from template (see templates below)

Auth decision tree:

fetch(url) works?                          → Tier 1: PUBLIC (browser: false)
fetch(url, {credentials:'include'}) works? → Tier 2: COOKIE (most common)
Needs Bearer/CSRF header?                  → Tier 3: HEADER
Page requests it but fetch can't?          → Tier 4: INTERCEPT (installInterceptor)

Adapter Templates

Tier 1 — Public API (fastest)

// ~/.opencli/clis/<site>/<name>.ts
import { cli, Strategy } from '@jackwener/opencli/registry';

cli({
  site: 'mysite', name: 'hot', description: '一句话描述',
  domain: 'www.example.com',
  strategy: Strategy.PUBLIC, browser: false,
  args: [{ name: 'limit', type: 'int', default: 20 }],
  columns: ['rank', 'title', 'score'],
  func: async (_page, kwargs) => {
    const res = await fetch('https://api.example.com/hot');
    const data = await res.json();
    return data.items.slice(0, kwargs.limit).map((item: any, i: number) => ({
      rank: i + 1, title: item.title, score: item.score,
    }));
  },
});

Tier 2 — Cookie auth (most common)

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

cli({
  site: 'mysite', name: 'feed', description: '一句话描述',
  domain: 'www.example.com',
  strategy: Strategy.COOKIE, browser: true,
  args: [{ name: 'limit', type: 'int', default: 20 }],
  columns: ['rank', 'title', 'value'],
  func: async (page, kwargs) => {
    await page.goto('https://www.example.com');
    const data = await page.evaluate(`(async () => {
      const res = await fetch('/api/feed', { credentials: 'include' });
      const d = await res.json();
      return (d.data?.items || []).map(item => ({ title: item.title, value: item.value }));
    })()`);
    return (data as any[]).slice(0, kwargs.limit).map((item, i) => ({
      rank: i + 1, title: item.title || '', value: item.value || '',
    }));
  },
});

Tier 4 — Intercept (for sites with signing/anti-scrape)

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

cli({
  site: 'mysite', name: 'feed', description: '一句话描述',
  domain: 'www.example.com',
  strategy: Strategy.INTERCEPT, browser: true,
  args: [{ name: 'limit', type: 'int', default: 20 }],
  columns: ['rank', 'title', 'value'],
  func: async (page, kwargs) => {
    await page.goto('https://www.example.com/target');
    await page.wait(3);
    await page.installInterceptor('api-keyword');       // URL substring match
    await page.autoScroll({ times: 2, delayMs: 2000 }); // Trigger lazy load
    const requests = await page.getInterceptedRequests();
    if (!requests?.length) return [];
    const results: any[] = [];
    for (const req of requests) {
      results.push(...(req.data?.data?.items || []));
    }
    return results.slice(0, kwargs.limit).map((item, i) => ({
      rank: i + 1, title: item.title || '', value: item.value || '',
    }));
  },
});

Test After Writing

npm run build                              # Syntax check
opencli list | grep mysite                 # Confirm registered
opencli mysite mycommand --limit 3 -v      # Verify actual output

Full Exploration Guide (for new sites)

When you need to explore a site from scratch rather than a single URL:

Step 1: API Discovery

opencli explore https://www.example.com --site mysite

Outputs to .opencli/explore/mysite/: endpoints.json, capabilities.json, auth.json

Or auto-generate everything:

opencli generate https://www.example.com --goal "hot"

Key discovery tactics:

• `.json` suffix trick — Reddit-style sites: just append .json to URL for clean REST data
• `__INITIAL_STATE__` — SSR sites (Bilibili, Xiaohongshu) embed data in window.__INITIAL_STATE__
• Active interaction — Lazy-load APIs (comments, subtitles) only appear after clicking a button
• Pinia/Vuex intercept — Vue sites: call store actions to trigger signed requests without reverse-engineering signatures

Step 2: Pick auth tier — run opencli cascade <api-url> to auto-detect

Step 3: Find existing adapter to copy — ls clis/<site>/, copy the closest one, change 3 fields: name, API URL, field mapping

Step 4: Test

opencli mysite hot --limit 3 -v      # verbose: see pipeline data flow
opencli mysite hot -f json | jq '.[0]'  # confirm JSON structure

Common pitfalls:

🏗️ 工作原理

<!-- TODO: 如果 skill 逻辑复杂，可以添加 Mermaid 架构图 -->

graph LR
    A[用户输入] --> B[Skill 解析]
    B --> C[调用工具/API]
    C --> D[处理结果]
    D --> E[返回用户]

❓ 常见问题

<!-- TODO: 填写 3-5 个用户可能遇到的问题和解决方案 -->

Q: [问题 1]

A: [解决方案]

Q: [问题 2]

A: [解决方案]

Q: [问题 3]

A: [解决方案]

🔒 隐私说明

<!-- TODO: 如果涉及数据上传、API 调用，说明数据处理方式 -->

• 本地处理：[哪些操作在本地完成]
• 外部调用：[哪些数据会发送到外部服务]

📝 License

MIT

📱 关注作者

如果这个项目对你有帮助，欢迎关注我获取更多 AI 工具分享：

• X (Twitter): @vista8
• 微信公众号「向阳乔木推荐看」:

<p align="center"> <img src="https://github.com/joeseesun/terminal-boost/raw/main/assets/wechat-qr.jpg?raw=true" alt="向阳乔木推荐看公众号二维码" width="300"> </p>