/ README.md
README.md
1 # OpenCLI 2 3 > **Turn websites, browser sessions, Electron apps, and local tools into deterministic interfaces for humans and AI agents.** 4 > Reuse your logged-in browser, automate live workflows, and crystallize repeated actions into reusable CLI commands. 5 6 [](./README.zh-CN.md) 7 [](https://www.npmjs.com/package/@jackwener/opencli) 8 [](https://nodejs.org) 9 [](./LICENSE) 10 11 OpenCLI gives you one surface for three different kinds of automation: 12 13 - **Use built-in adapters** for sites like Bilibili, Zhihu, Xiaohongshu, Reddit, HackerNews, Twitter/X, and [many more](#built-in-commands). 14 - **Let AI Agents operate any website** — install the `opencli-adapter-author` skill in your AI agent (Claude Code, Cursor, etc.), and it can navigate, click, type, extract, and inspect any page through your logged-in browser via `opencli browser` primitives. 15 - **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 browser verify`. 16 17 It also works as a **CLI hub** for local tools such as `gh`, `docker`, and other binaries you register yourself, plus **desktop app adapters** for Electron apps like Cursor, Codex, Antigravity, ChatGPT, and Notion. 18 19 ## Highlights 20 21 - **Desktop App Control** — Drive Electron apps (Cursor, Codex, ChatGPT, Notion, etc.) directly from the terminal via CDP. 22 - **Browser Automation for AI Agents** — Install the `opencli-adapter-author` skill, and your AI agent can operate any website: navigate, click, type, extract, screenshot — all through your logged-in Chrome session. 23 - **Website → CLI** — Turn any website into a deterministic CLI: 90+ pre-built adapters, or write your own with the `opencli-adapter-author` skill + `opencli browser verify`. 24 - **Account-safe** — Reuses Chrome/Chromium logged-in state; your credentials never leave the browser. 25 - **AI Agent ready** — One skill takes you from site recon through API discovery, field decoding, adapter writing, and verification. 26 - **CLI Hub** — Discover, auto-install, and passthrough commands to any external CLI (gh, docker, obsidian, etc). 27 - **Zero LLM cost** — No tokens consumed at runtime. Run 10,000 times and pay nothing. 28 - **Deterministic** — Same command, same output schema, every time. Pipeable, scriptable, CI-friendly. 29 30 --- 31 32 ## Quick Start 33 34 ### 1. Install OpenCLI 35 36 ```bash 37 npm install -g @jackwener/opencli 38 ``` 39 40 ### 2. Install the Browser Bridge Extension 41 42 OpenCLI connects to Chrome/Chromium through a lightweight Browser Bridge extension plus a small local daemon. The daemon auto-starts when needed. 43 44 1. Download the latest `opencli-extension-v{version}.zip` from the GitHub [Releases page](https://github.com/jackwener/opencli/releases). 45 2. Unzip it, open `chrome://extensions`, and enable **Developer mode**. 46 3. Click **Load unpacked** and select the unzipped folder. 47 48 ### 3. Verify the setup 49 50 ```bash 51 opencli doctor 52 ``` 53 54 ### 4. Run your first commands 55 56 ```bash 57 opencli list 58 opencli hackernews top --limit 5 59 opencli bilibili hot --limit 5 60 ``` 61 62 ## For Humans 63 64 Use OpenCLI directly when you want a reliable command instead of a live browser session: 65 66 - `opencli list` shows every registered command. 67 - `opencli <site> <command>` runs a built-in or generated adapter. 68 - `opencli register mycli` exposes a local CLI through the same discovery surface. 69 - `opencli doctor` helps diagnose browser connectivity. 70 71 ## For AI Agents 72 73 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. 74 75 ### Install skills 76 77 ```bash 78 npx skills add jackwener/opencli 79 ``` 80 81 Or install only what you need: 82 83 ```bash 84 npx skills add jackwener/opencli --skill opencli-adapter-author 85 npx skills add jackwener/opencli --skill opencli-autofix 86 npx skills add jackwener/opencli --skill opencli-browser 87 npx skills add jackwener/opencli --skill opencli-usage 88 npx skills add jackwener/opencli --skill smart-search 89 ``` 90 91 ### Which skill to use 92 93 | Skill | When to use | Example prompt to your AI agent | 94 |-------|------------|-------------------------------| 95 | **opencli-adapter-author** | Operate a site in real time, or write a reusable adapter for a new site | "Help me check my Xiaohongshu notifications" / "Write an adapter for douyin trending" / "Make a command that grabs the top posts from this page" | 96 | **opencli-autofix** | Repair a broken adapter when a built-in command fails | "`opencli zhihu hot` is returning empty — fix it" | 97 | **opencli-browser** | Browser automation reference for AI agents | "Use browser commands to scrape this page" | 98 | **opencli-usage** | Quick reference for all OpenCLI commands and sites | "What commands does OpenCLI have for Twitter?" | 99 | **smart-search** | Search across existing OpenCLI capabilities | "Find me a Bilibili trending adapter" | 100 101 ### How it works 102 103 Once `opencli-adapter-author` is installed, your AI agent can: 104 105 1. **Navigate** to any URL using your logged-in browser 106 2. **Read** page content via structured DOM snapshots (not screenshots) 107 3. **Interact** — click buttons, fill forms, select options, press keys 108 4. **Extract** data from the page or intercept network API responses 109 5. **Wait** for elements, text, or page transitions 110 111 The agent handles all the `opencli browser` commands internally — you just describe what you want done in natural language. 112 113 **Skill references:** 114 - [`skills/opencli-adapter-author/SKILL.md`](./skills/opencli-adapter-author/SKILL.md) — browser operation + adapter authoring, end-to-end 115 - [`skills/opencli-autofix/SKILL.md`](./skills/opencli-autofix/SKILL.md) — repair broken adapters 116 - [`skills/opencli-browser/SKILL.md`](./skills/opencli-browser/SKILL.md) — browser automation reference 117 - [`skills/opencli-usage/SKILL.md`](./skills/opencli-usage/SKILL.md) — command and site reference 118 - [`skills/smart-search/SKILL.md`](./skills/smart-search/SKILL.md) — capability search 119 120 Available browser commands include `open`, `state`, `click`, `type`, `select`, `keys`, `wait`, `get`, `find`, `extract`, `frames`, `screenshot`, `scroll`, `back`, `eval`, `network`, `tab list`, `tab new`, `tab select`, `tab close`, `init`, `verify`, and `close`. 121 122 `opencli browser open <url>` and `opencli browser tab new [url]` both return a target ID. Use `opencli browser tab list` to inspect the target IDs of tabs that already exist, 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 `opencli browser ...` commands. 123 124 ## Core Concepts 125 126 ### `browser`: AI Agent browser control 127 128 `opencli browser` commands are the low-level primitives that AI Agents use to operate websites. You don't run these manually — instead, install the `opencli-adapter-author` skill into your AI agent, describe what you want in natural language, and the agent handles the browser operations. 129 130 For example, tell your agent: *"Help me check my Xiaohongshu notifications"* — the agent will use `opencli browser open`, `state`, `click`, etc. under the hood. 131 132 ### Built-in adapters: stable commands 133 134 Use site-specific commands such as `opencli hackernews top` or `opencli reddit hot` when the capability already exists. These are deterministic and work without browser — ideal for both humans and AI agents. 135 136 ### Writing a new adapter 137 138 When the site you need is not yet covered, use the `opencli-adapter-author` skill. It takes the agent end-to-end: 139 140 1. Recon the site and classify its pattern (SPA / SSR / JSONP / Token / Streaming). 141 2. Discover the right endpoint — network inspection, initial state, bundle search, token trace, or interceptor fallback. 142 3. Decide the auth strategy — `PUBLIC` / `COOKIE` / `HEADER` / `INTERCEPT`. 143 4. Decode response fields and design output columns. 144 5. `opencli browser init <site>/<name>` → write adapter → `opencli browser verify <site>/<name>`. 145 6. Persist site knowledge to `~/.opencli/sites/<site>/` so the next adapter for the same site is faster. 146 147 ### CLI Hub and desktop adapters 148 149 OpenCLI is not only for websites. It can also: 150 151 - expose local binaries like `gh`, `docker`, `obsidian`, or custom tools through `opencli <tool> ...` 152 - control Electron desktop apps through dedicated adapters and CDP-backed integrations 153 154 ## Prerequisites 155 156 - **Node.js**: >= 21.0.0 (or **Bun** >= 1.0) 157 - **Chrome or Chromium** running and logged into the target site for browser-backed commands 158 159 > **Important**: Browser-backed commands reuse your Chrome/Chromium login session. If you get empty data or permission-like failures, first confirm the site is already open and authenticated in Chrome/Chromium. 160 161 ## Configuration 162 163 | Variable | Default | Description | 164 |----------|---------|-------------| 165 | `OPENCLI_DAEMON_PORT` | `19825` | HTTP port for the daemon-extension bridge | 166 | `OPENCLI_WINDOW_FOCUSED` | `false` | Set to `1` to open automation windows in the foreground (useful for debugging). The `--focus` flag sets this. | 167 | `OPENCLI_LIVE` | `false` | Set to `1` to keep the automation window open after an adapter command finishes (useful for inspection). The `--live` flag sets this. | 168 | `OPENCLI_BROWSER_CONNECT_TIMEOUT` | `30` | Seconds to wait for browser connection | 169 | `OPENCLI_BROWSER_COMMAND_TIMEOUT` | `60` | Seconds to wait for a single browser command | 170 | `OPENCLI_CDP_ENDPOINT` | — | Chrome DevTools Protocol endpoint for remote browser or Electron apps | 171 | `OPENCLI_CDP_TARGET` | — | Filter CDP targets by URL substring (e.g. `detail.1688.com`) | 172 | `OPENCLI_VERBOSE` | `false` | Enable verbose logging (`-v` flag also works) | 173 | `OPENCLI_DIAGNOSTIC` | `false` | Set to `1` to capture structured diagnostic context on failures | 174 | `DEBUG_SNAPSHOT` | — | Set to `1` for DOM snapshot debug output | 175 176 `--focus` works for both `opencli browser *` and browser-backed adapter commands. `--live` is mainly for adapter commands: browser subcommands already keep the automation window open until you run `opencli browser close` or the idle timeout expires. 177 178 ## Update 179 180 ```bash 181 npm install -g @jackwener/opencli@latest 182 183 # If you use the packaged OpenCLI skills, refresh them too 184 npx skills add jackwener/opencli 185 ``` 186 187 Or refresh only the skills you actually use: 188 189 ```bash 190 npx skills add jackwener/opencli --skill opencli-adapter-author 191 npx skills add jackwener/opencli --skill opencli-autofix 192 npx skills add jackwener/opencli --skill opencli-browser 193 npx skills add jackwener/opencli --skill opencli-usage 194 npx skills add jackwener/opencli --skill smart-search 195 ``` 196 197 ## For Developers 198 199 Install from source: 200 201 ```bash 202 git clone git@github.com:jackwener/opencli.git 203 cd opencli 204 npm install 205 npm run build 206 npm link 207 ``` 208 209 To load the source Browser Bridge extension: 210 211 1. Open `chrome://extensions` and enable **Developer mode**. 212 2. Click **Load unpacked** and select this repository's `extension/` directory. 213 214 ## Built-in Commands 215 216 | Site | Commands | 217 |------|----------| 218 | **xiaohongshu** | `search` `note` `comments` `feed` `user` `download` `publish` `notifications` `creator-notes` `creator-notes-summary` `creator-note-detail` `creator-profile` `creator-stats` | 219 | **bilibili** | `hot` `search` `history` `feed` `ranking` `download` `comments` `dynamic` `favorite` `following` `me` `subtitle` `video` `user-videos` | 220 | **tieba** | `hot` `posts` `search` `read` | 221 | **hupu** | `hot` `search` `detail` `mentions` `reply` `like` `unlike` | 222 | **twitter** | `trending` `search` `timeline` `tweets` `lists` `list-tweets` `list-add` `list-remove` `bookmarks` `post` `download` `profile` `article` `like` `likes` `notifications` `reply` `reply-dm` `thread` `follow` `unfollow` `followers` `following` `block` `unblock` `bookmark` `unbookmark` `delete` `hide-reply` `accept` | 223 | **reddit** | `hot` `frontpage` `popular` `search` `subreddit` `read` `user` `user-posts` `user-comments` `upvote` `upvoted` `save` `saved` `comment` `subscribe` | 224 | **zhihu** | `hot` `search` `question` `download` `follow` `like` `favorite` `comment` `answer` | 225 | **amazon** | `bestsellers` `search` `product` `offer` `discussion` `movers-shakers` `new-releases` `rankings` | 226 | **1688** | `search` `item` `assets` `download` `store` | 227 | **gitee** | `trending` `search` `user` | 228 | **gemini** | `new` `ask` `image` `deep-research` `deep-research-result` | 229 | **yuanbao** | `new` `ask` | 230 | **notebooklm** | `status` `list` `open` `current` `get` `history` `summary` `note-list` `notes-get` `source-list` `source-get` `source-fulltext` `source-guide` | 231 | **spotify** | `auth` `status` `play` `pause` `next` `prev` `volume` `search` `queue` `shuffle` `repeat` | 232 | **xianyu** | `search` `item` `chat` | 233 | **xiaoe** | `courses` `detail` `catalog` `play-url` `content` | 234 | **quark** | `ls` `mkdir` `mv` `rename` `rm` `save` `share-tree` | 235 | **uiverse** | `code` `preview` | 236 | **baidu-scholar** | `search` | 237 | **google-scholar** | `search` | 238 | **gov-law** | `search` `recent` | 239 | **gov-policy** | `search` `recent` | 240 | **nowcoder** | `hot` `trending` `topics` `recommend` `creators` `companies` `jobs` `search` `suggest` `experience` `referral` `salary` `papers` `practice` `notifications` `detail` | 241 | **wanfang** | `search` | 242 | **hackernews** | `top` `new` `best` `ask` `show` `jobs` `search` `user` | 243 | **xiaoyuzhou** | `auth*` `podcast*` `podcast-episodes*` `episode*` `download*` `transcript*` | 244 245 90+ adapters in total — **[→ see all supported sites & commands](./docs/adapters/index.md)** 246 247 `*` `opencli xiaoyuzhou podcast`, `podcast-episodes`, `episode`, `download`, and `transcript` require local Xiaoyuzhou credentials in `~/.opencli/xiaoyuzhou.json`. 248 249 ## CLI Hub 250 251 OpenCLI acts as a universal hub for your existing command-line tools — unified discovery, pure passthrough execution, and auto-install (if a tool isn't installed, OpenCLI runs `brew install <tool>` automatically before re-running the command). 252 253 | External CLI | Description | Example | 254 |--------------|-------------|---------| 255 | **gh** | GitHub CLI | `opencli gh pr list --limit 5` | 256 | **obsidian** | Obsidian vault management | `opencli obsidian search query="AI"` | 257 | **docker** | Docker | `opencli docker ps` | 258 | **lark-cli** | Lark/Feishu — messages, docs, calendar, tasks, 200+ commands | `opencli lark-cli calendar +agenda` | 259 | **dws** | DingTalk — cross-platform CLI for DingTalk's full suite, designed for humans and AI agents | `opencli dws msg send --to user "hello"` | 260 | **wecom-cli** | WeCom/企业微信 — CLI for WeCom open platform, for humans and AI agents | `opencli wecom-cli msg send --to user "hello"` | 261 | **vercel** | Vercel — deploy projects, manage domains, env vars, logs | `opencli vercel deploy --prod` | 262 263 **Register your own** — add any local CLI so AI agents can discover it via `opencli list`: 264 265 ```bash 266 opencli register mycli 267 ``` 268 269 ### Desktop App Adapters 270 271 Control Electron desktop apps directly from the terminal. Each adapter has its own detailed documentation: 272 273 | App | Description | Doc | 274 |-----|-------------|-----| 275 | **Cursor** | Control Cursor IDE — Composer, chat, code extraction | [Doc](./docs/adapters/desktop/cursor.md) | 276 | **Codex** | Drive OpenAI Codex CLI agent headlessly | [Doc](./docs/adapters/desktop/codex.md) | 277 | **Antigravity** | Control Antigravity Ultra from terminal | [Doc](./docs/adapters/desktop/antigravity.md) | 278 | **ChatGPT App** | Automate ChatGPT macOS desktop app | [Doc](./docs/adapters/desktop/chatgpt-app.md) | 279 | **ChatWise** | Multi-LLM client (GPT-4, Claude, Gemini) | [Doc](./docs/adapters/desktop/chatwise.md) | 280 | **Notion** | Search, read, write Notion pages | [Doc](./docs/adapters/desktop/notion.md) | 281 | **Discord** | Discord Desktop — messages, channels, servers | [Doc](./docs/adapters/desktop/discord.md) | 282 | **Doubao** | Control Doubao AI desktop app via CDP | [Doc](./docs/adapters/desktop/doubao-app.md) | 283 284 To add a new Electron app, start with [docs/guide/electron-app-cli.md](./docs/guide/electron-app-cli.md). 285 286 ## Download Support 287 288 OpenCLI supports downloading images, videos, and articles from supported platforms. 289 290 | Platform | Content Types | Notes | 291 |----------|---------------|-------| 292 | **xiaohongshu** | Images, Videos | Downloads all media from a note | 293 | **bilibili** | Videos | Requires `yt-dlp` installed | 294 | **twitter** | Images, Videos | From user media tab or single tweet | 295 | **douban** | Images | Poster / still image lists | 296 | **pixiv** | Images | Original-quality illustrations, multi-page | 297 | **1688** | Images, Videos | Downloads page-visible product media from item pages | 298 | **xiaoyuzhou** | Audio, Transcript | Downloads episode audio and transcript JSON/text with local credentials | 299 | **zhihu** | Articles (Markdown) | Exports with optional image download | 300 | **weixin** | Articles (Markdown) | WeChat Official Account articles | 301 302 For video downloads, install `yt-dlp` first: `brew install yt-dlp` 303 304 ```bash 305 opencli xiaohongshu download "https://www.xiaohongshu.com/search_result/<id>?xsec_token=..." --output ./xhs 306 opencli xiaohongshu download "https://xhslink.com/..." --output ./xhs 307 opencli bilibili download BV1xxx --output ./bilibili 308 opencli twitter download elonmusk --limit 20 --output ./twitter 309 opencli 1688 download 841141931191 --output ./1688-downloads 310 opencli xiaoyuzhou download 69b3b675772ac2295bfc01d0 --output ./xiaoyuzhou 311 opencli xiaoyuzhou transcript 69dd0c98e2c8be31551f6a33 --output ./xiaoyuzhou-transcripts 312 ``` 313 314 `opencli xiaoyuzhou download` and `transcript` require local Xiaoyuzhou credentials in `~/.opencli/xiaoyuzhou.json`. 315 316 ## Output Formats 317 318 All built-in commands support `--format` / `-f` with `table` (default), `json`, `yaml`, `md`, and `csv`. 319 320 ```bash 321 opencli bilibili hot -f json # Pipe to jq or LLMs 322 opencli bilibili hot -f csv # Spreadsheet-friendly 323 opencli bilibili hot -v # Verbose: show pipeline debug steps 324 ``` 325 326 ## Exit Codes 327 328 opencli follows Unix `sysexits.h` conventions so it integrates naturally with shell pipelines and CI scripts: 329 330 | Code | Meaning | When | 331 |------|---------|------| 332 | `0` | Success | Command completed normally | 333 | `1` | Generic error | Unexpected / unclassified failure | 334 | `2` | Usage error | Bad arguments or unknown command | 335 | `66` | Empty result | No data returned (`EX_NOINPUT`) | 336 | `69` | Service unavailable | Browser Bridge not connected (`EX_UNAVAILABLE`) | 337 | `75` | Temporary failure | Command timed out — retry (`EX_TEMPFAIL`) | 338 | `77` | Auth required | Not logged in to target site (`EX_NOPERM`) | 339 | `78` | Config error | Missing credentials or bad config (`EX_CONFIG`) | 340 | `130` | Interrupted | Ctrl-C / SIGINT | 341 342 ```bash 343 opencli spotify status || echo "exit $?" # 69 if browser not running 344 opencli gh issue list 2>/dev/null 345 [ $? -eq 77 ] && opencli gh auth login # auto-auth if not logged in 346 ``` 347 348 ## Plugins 349 350 Extend OpenCLI with community-contributed adapters: 351 352 ```bash 353 opencli plugin install github:user/opencli-plugin-my-tool 354 opencli plugin list 355 opencli plugin update --all 356 opencli plugin uninstall my-tool 357 ``` 358 359 | Plugin | Type | Description | 360 |--------|------|-------------| 361 | [opencli-plugin-github-trending](https://github.com/ByteYue/opencli-plugin-github-trending) | JS | GitHub Trending repositories | 362 | [opencli-plugin-hot-digest](https://github.com/ByteYue/opencli-plugin-hot-digest) | JS | Multi-platform trending aggregator | 363 | [opencli-plugin-juejin](https://github.com/Astro-Han/opencli-plugin-juejin) | JS | 稀土掘金 (Juejin) hot articles | 364 | [opencli-plugin-vk](https://github.com/flobo3/opencli-plugin-vk) | JS | VK (VKontakte) wall, feed, and search | 365 366 See [Plugins Guide](./docs/guide/plugins.md) for creating your own plugin. 367 368 ## For AI Agents (Developer Guide) 369 370 Before writing any adapter code, read the [`opencli-adapter-author` skill](./skills/opencli-adapter-author/SKILL.md). It takes you end-to-end: 371 372 - Recon the site and pick a pattern (SPA / SSR / JSONP / Token / Streaming). 373 - Discover the right endpoint via `opencli browser network`, `eval`, or the interceptor fallback. 374 - Decide auth strategy (`PUBLIC` / `COOKIE` / `HEADER` / `INTERCEPT`). 375 - Decode response fields, design columns, scaffold with `opencli browser init`. 376 - Verify with `opencli browser verify <site>/<name>` before shipping. 377 378 Adapters you write outside the repo live at `~/.opencli/clis/<site>/<name>.js`. Site knowledge (endpoints, field maps, fixtures) accumulates in `~/.opencli/sites/<site>/` so the next adapter for the same site starts from context instead of zero. 379 380 ## Testing 381 382 See **[TESTING.md](./TESTING.md)** for how to run and write tests. 383 384 ## Troubleshooting 385 386 - **"Extension not connected"** — Ensure the Browser Bridge extension is installed and **enabled** in `chrome://extensions` in Chrome or Chromium. 387 - **"attach failed: Cannot access a chrome-extension:// URL"** — Another extension may be interfering. Try disabling other extensions temporarily. 388 - **Empty data or 'Unauthorized' error** — Your Chrome/Chromium login session may have expired. Navigate to the target site and log in again. 389 - **Node API errors** — Ensure Node.js >= 21. Some features require `node:util` styleText (stable in Node 21+). 390 - **Daemon issues** — Check status: `curl localhost:19825/status` · View logs: `curl localhost:19825/logs` 391 392 ## Star History 393 394 [](https://star-history.com/#jackwener/opencli&Date) 395 396 ## License 397 398 [Apache-2.0](./LICENSE)