OpenCLI

Agent command contract

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 --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

1. Install OpenCLI

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 , 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 -g @jackwener/opencli

2. Install the Browser Bridge Extension

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

opencli doctor

4. Optional: name your Chrome profile

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

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

For Humans

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

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

Extending OpenCLI

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

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

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)

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

How it works

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 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 to route a command to a specific tab. tab new creates a new tab without changing the default browser target; only tab select promotes that tab to the default target for later untargeted commands in the same session.

Writing a new adapter

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 / → write adapter → opencli browser recon verify /.
6. Site knowledge persists to ~/.opencli/sites// so the next adapter for the same site starts from context.

Configuration

opencli browser * requires an explicit --session option for page operations, uses a foreground browser window by default, and keeps that session's tab lease until opencli browser --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

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

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

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

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

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

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

Troubleshooting

• "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

License

Apache-2.0

内容由编辑整理，部分信息来自 GitHub 与项目官网，版权归原作者所有。发现错误？报告问题