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: