mirror of
https://github.com/jackwener/OpenCLI.git
synced 2026-09-14 18:25:42 +08:00
jackwener
0bf8794f84
These commands were removed in the persistent daemon refactor. Only `daemon stop` remains as a user-facing command.
348 lines
16 KiB
Markdown
348 lines
16 KiB
Markdown
# OpenCLI
|
|
|
|
> **Turn websites, browser sessions, Electron apps, and local tools into deterministic interfaces for humans and AI agents.**
|
|
> Reuse your logged-in browser, automate live workflows, and crystallize repeated actions into reusable CLI commands.
|
|
|
|
[](./README.zh-CN.md)
|
|
[](https://www.npmjs.com/package/@jackwener/opencli)
|
|
[](https://nodejs.org)
|
|
[](./LICENSE)
|
|
|
|
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](#built-in-commands).
|
|
- **Drive a live browser directly** with `opencli browser` when an AI agent needs to click, type, extract, or inspect a page in real time.
|
|
- **Generate new adapters** from real browser behavior with `explore`, `synthesize`, `generate`, and `cascade`.
|
|
|
|
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.
|
|
|
|
## Why OpenCLI
|
|
|
|
---
|
|
|
|
## Highlights
|
|
|
|
- **CLI All Electron** — CLI-ify apps like Antigravity Ultra! Now AI can control itself natively.
|
|
- **Browser Automation** — `browser` gives AI agents direct browser control: click, type, extract, screenshot — any interaction, fully scriptable.
|
|
- **Website → CLI** — Turn any website into a deterministic CLI: 70+ pre-built adapters, or crystallize your own with `opencli record`.
|
|
- **Account-safe** — Reuses Chrome/Chromium logged-in state; your credentials never leave the browser.
|
|
- **Anti-detection built-in** — Patches `navigator.webdriver`, stubs `window.chrome`, fakes plugin lists, cleans ChromeDriver/Playwright globals, and strips CDP frames from Error stack traces. Extensive anti-fingerprinting and risk-control evasion measures baked in at every layer.
|
|
- **AI Agent ready** — `explore` discovers APIs, `synthesize` generates adapters, `cascade` finds auth strategies, `browser` controls the browser directly.
|
|
- **External CLI Hub** — Discover, auto-install, and passthrough commands to any external CLI (gh, obsidian, docker, etc). Zero setup.
|
|
- **Self-healing setup** — `opencli doctor` diagnoses and auto-starts the daemon, extension, and live browser connectivity.
|
|
- **Dynamic Loader** — Simply drop `.ts` adapters into the `clis/` folder for auto-registration.
|
|
- **Zero LLM cost** — No tokens consumed at runtime. Run 10,000 times and pay nothing.
|
|
- **Deterministic** — Same command, same output schema, every time. Pipeable, scriptable, CI-friendly.
|
|
- **Broad coverage** — 79+ sites across global and Chinese platforms (Bilibili, Zhihu, Xiaohongshu, Reddit, HackerNews, and more), plus desktop Electron apps via CDP.
|
|
|
|
---
|
|
|
|
## Quick Start
|
|
|
|
### 1. Install OpenCLI
|
|
|
|
```bash
|
|
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.
|
|
|
|
1. Download the latest `opencli-extension.zip` from the GitHub [Releases page](https://github.com/jackwener/opencli/releases).
|
|
2. Unzip it, open `chrome://extensions`, and enable **Developer mode**.
|
|
3. Click **Load unpacked** and select the unzipped folder.
|
|
|
|
### 3. Verify the setup
|
|
|
|
```bash
|
|
opencli doctor
|
|
```
|
|
|
|
### 4. Run your first commands
|
|
|
|
```bash
|
|
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 <site> <command>` runs a built-in or generated adapter.
|
|
- `opencli register mycli` exposes a local CLI through the same discovery surface.
|
|
- `opencli doctor` helps diagnose browser connectivity.
|
|
|
|
## For AI Agents
|
|
|
|
Use two different entry points depending on the task:
|
|
|
|
- [`skills/opencli-explorer/SKILL.md`](./skills/opencli-explorer/SKILL.md): the entry point for creating new adapters — supports both fully automated generation (`opencli generate <url>`) and manual exploration workflows.
|
|
- [`skills/opencli-browser/SKILL.md`](./skills/opencli-browser/SKILL.md): the low-level control surface for live browsing, debugging, and manual intervention.
|
|
|
|
Install the packaged skills with:
|
|
|
|
```bash
|
|
npx skills add jackwener/opencli
|
|
```
|
|
|
|
Or install only what you need:
|
|
|
|
```bash
|
|
npx skills add jackwener/opencli --skill opencli-usage
|
|
npx skills add jackwener/opencli --skill opencli-browser
|
|
npx skills add jackwener/opencli --skill opencli-explorer
|
|
npx skills add jackwener/opencli --skill opencli-oneshot
|
|
```
|
|
|
|
In practice:
|
|
|
|
- start with `opencli-explorer` when the agent needs a reusable command for a site (it covers both automated and manual flows)
|
|
- use `opencli-browser` when the agent needs to inspect or steer the page directly
|
|
|
|
Available browser commands include `open`, `state`, `click`, `type`, `select`, `keys`, `wait`, `get`, `screenshot`, `scroll`, `back`, `eval`, `network`, `init`, `verify`, and `close`.
|
|
|
|
## Core Concepts
|
|
|
|
### `browser`: live control
|
|
|
|
Use `opencli browser` when the task is inherently interactive and the agent needs to operate the page directly.
|
|
|
|
### Built-in adapters: stable commands
|
|
|
|
Use site-specific commands such as `opencli hackernews top` or `opencli reddit hot` when the capability already exists and you want deterministic output.
|
|
|
|
### `explore` / `synthesize` / `generate`: create new CLIs
|
|
|
|
Use these commands when the site you need is not covered yet:
|
|
|
|
- `explore` inspects the page, network activity, and capability surface.
|
|
- `synthesize` turns exploration artifacts into evaluate-based YAML adapters.
|
|
- `generate` runs the verified generation path and returns either a usable command or a structured explanation of why completion was blocked or needs human review.
|
|
|
|
### `cascade`: auth strategy discovery
|
|
|
|
Use `cascade` to probe fallback auth paths such as public endpoints, cookies, and custom headers before you commit to an adapter design.
|
|
|
|
### CLI Hub and desktop adapters
|
|
|
|
OpenCLI is not only for websites. It can also:
|
|
|
|
- expose local binaries like `gh`, `docker`, `obsidian`, or custom tools through `opencli <tool> ...`
|
|
- control Electron desktop apps through dedicated adapters and CDP-backed integrations
|
|
|
|
## Prerequisites
|
|
|
|
- **Node.js**: >= 20.0.0 (or **Bun** >= 1.0)
|
|
- **Chrome or Chromium** running and logged into the target site for browser-backed commands
|
|
|
|
> **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.
|
|
|
|
## Update
|
|
|
|
```bash
|
|
npm install -g @jackwener/opencli@latest
|
|
|
|
# If you use the packaged OpenCLI skills, refresh them too
|
|
npx skills add jackwener/opencli
|
|
```
|
|
|
|
Or refresh only the skills you actually use:
|
|
|
|
```bash
|
|
npx skills add jackwener/opencli --skill opencli-usage
|
|
npx skills add jackwener/opencli --skill opencli-browser
|
|
npx skills add jackwener/opencli --skill opencli-explorer
|
|
npx skills add jackwener/opencli --skill opencli-oneshot
|
|
```
|
|
|
|
## For Developers
|
|
|
|
Install from source:
|
|
|
|
```bash
|
|
git clone git@github.com:jackwener/opencli.git
|
|
cd opencli
|
|
npm install
|
|
npm run build
|
|
npm link
|
|
```
|
|
|
|
To load the source Browser Bridge extension:
|
|
|
|
1. Open `chrome://extensions` and enable **Developer mode**.
|
|
2. Click **Load unpacked** and select this repository's `extension/` directory.
|
|
|
|
## Built-in Commands
|
|
|
|
| Site | Commands |
|
|
|------|----------|
|
|
| **xiaohongshu** | `search` `note` `comments` `feed` `user` `download` `publish` `notifications` `creator-notes` `creator-notes-summary` `creator-note-detail` `creator-profile` `creator-stats` |
|
|
| **bilibili** | `hot` `search` `history` `feed` `ranking` `download` `comments` `dynamic` `favorite` `following` `me` `subtitle` `user-videos` |
|
|
| **tieba** | `hot` `posts` `search` `read` |
|
|
| **hupu** | `hot` `search` `detail` `mentions` `reply` `like` `unlike` |
|
|
| **twitter** | `trending` `search` `timeline` `bookmarks` `post` `download` `profile` `article` `like` `likes` `notifications` `reply` `reply-dm` `thread` `follow` `unfollow` `followers` `following` `block` `unblock` `bookmark` `unbookmark` `delete` `hide-reply` `accept` |
|
|
| **reddit** | `hot` `frontpage` `popular` `search` `subreddit` `read` `user` `user-posts` `user-comments` `upvote` `upvoted` `save` `saved` `comment` `subscribe` |
|
|
| **zhihu** | `hot` `search` `question` `download` `follow` `like` `favorite` `comment` `answer` |
|
|
| **amazon** | `bestsellers` `search` `product` `offer` `discussion` `movers-shakers` `new-releases` |
|
|
| **1688** | `search` `item` `assets` `download` `store` |
|
|
| **gitee** | `trending` `search` `user` |
|
|
| **gemini** | `new` `ask` `image` `deep-research` `deep-research-result` |
|
|
| **yuanbao** | `new` `ask` |
|
|
| **notebooklm** | `status` `list` `open` `current` `get` `history` `summary` `note-list` `notes-get` `source-list` `source-get` `source-fulltext` `source-guide` |
|
|
| **spotify** | `auth` `status` `play` `pause` `next` `prev` `volume` `search` `queue` `shuffle` `repeat` |
|
|
| **xianyu** | `search` `item` `chat` |
|
|
| **xiaoe** | `courses` `detail` `catalog` `play-url` `content` |
|
|
| **quark** | `ls` `mkdir` `mv` `rename` `rm` `save` `share-tree` |
|
|
|
|
79+ adapters in total — **[→ see all supported sites & commands](./docs/adapters/index.md)**
|
|
|
|
## CLI Hub
|
|
|
|
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).
|
|
|
|
| External CLI | Description | Example |
|
|
|--------------|-------------|---------|
|
|
| **gh** | GitHub CLI | `opencli gh pr list --limit 5` |
|
|
| **obsidian** | Obsidian vault management | `opencli obsidian search query="AI"` |
|
|
| **docker** | Docker | `opencli docker ps` |
|
|
| **lark-cli** | Lark/Feishu — messages, docs, calendar, tasks, 200+ commands | `opencli lark-cli calendar +agenda` |
|
|
| **dingtalk** | DingTalk — cross-platform CLI for DingTalk's full suite, designed for humans and AI agents | `opencli dingtalk msg send --to user "hello"` |
|
|
| **wecom** | WeCom/企业微信 — CLI for WeCom open platform, for humans and AI agents | `opencli wecom msg send --to user "hello"` |
|
|
| **vercel** | Vercel — deploy projects, manage domains, env vars, logs | `opencli vercel deploy --prod` |
|
|
|
|
**Register your own** — add any local CLI so AI agents can discover it via `opencli list`:
|
|
|
|
```bash
|
|
opencli register mycli
|
|
```
|
|
|
|
### Desktop App Adapters
|
|
|
|
Control Electron desktop apps directly from the terminal. Each adapter has its own detailed documentation:
|
|
|
|
| App | Description | Doc |
|
|
|-----|-------------|-----|
|
|
| **Cursor** | Control Cursor IDE — Composer, chat, code extraction | [Doc](./docs/adapters/desktop/cursor.md) |
|
|
| **Codex** | Drive OpenAI Codex CLI agent headlessly | [Doc](./docs/adapters/desktop/codex.md) |
|
|
| **Antigravity** | Control Antigravity Ultra from terminal | [Doc](./docs/adapters/desktop/antigravity.md) |
|
|
| **ChatGPT** | Automate ChatGPT macOS desktop app | [Doc](./docs/adapters/desktop/chatgpt.md) |
|
|
| **ChatWise** | Multi-LLM client (GPT-4, Claude, Gemini) | [Doc](./docs/adapters/desktop/chatwise.md) |
|
|
| **Notion** | Search, read, write Notion pages | [Doc](./docs/adapters/desktop/notion.md) |
|
|
| **Discord** | Discord Desktop — messages, channels, servers | [Doc](./docs/adapters/desktop/discord.md) |
|
|
| **Doubao** | Control Doubao AI desktop app via CDP | [Doc](./docs/adapters/desktop/doubao-app.md) |
|
|
|
|
To add a new Electron app, start with [docs/guide/electron-app-cli.md](./docs/guide/electron-app-cli.md).
|
|
|
|
## Download Support
|
|
|
|
OpenCLI supports downloading images, videos, and articles from supported platforms.
|
|
|
|
| Platform | Content Types | Notes |
|
|
|----------|---------------|-------|
|
|
| **xiaohongshu** | Images, Videos | Downloads all media from a note |
|
|
| **bilibili** | Videos | Requires `yt-dlp` installed |
|
|
| **twitter** | Images, Videos | From user media tab or single tweet |
|
|
| **douban** | Images | Poster / still image lists |
|
|
| **pixiv** | Images | Original-quality illustrations, multi-page |
|
|
| **1688** | Images, Videos | Downloads page-visible product media from item pages |
|
|
| **zhihu** | Articles (Markdown) | Exports with optional image download |
|
|
| **weixin** | Articles (Markdown) | WeChat Official Account articles |
|
|
|
|
For video downloads, install `yt-dlp` first: `brew install yt-dlp`
|
|
|
|
```bash
|
|
opencli xiaohongshu download abc123 --output ./xhs
|
|
opencli bilibili download BV1xxx --output ./bilibili
|
|
opencli twitter download elonmusk --limit 20 --output ./twitter
|
|
opencli 1688 download 841141931191 --output ./1688-downloads
|
|
```
|
|
|
|
## Output Formats
|
|
|
|
All built-in commands support `--format` / `-f` with `table` (default), `json`, `yaml`, `md`, and `csv`.
|
|
|
|
```bash
|
|
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` conventions so it integrates naturally with shell pipelines and CI scripts:
|
|
|
|
| Code | Meaning | When |
|
|
|------|---------|------|
|
|
| `0` | Success | Command completed normally |
|
|
| `1` | Generic error | Unexpected / unclassified failure |
|
|
| `2` | Usage error | Bad arguments or unknown command |
|
|
| `66` | Empty result | No data returned (`EX_NOINPUT`) |
|
|
| `69` | Service unavailable | Browser Bridge not connected (`EX_UNAVAILABLE`) |
|
|
| `75` | Temporary failure | Command timed out — retry (`EX_TEMPFAIL`) |
|
|
| `77` | Auth required | Not logged in to target site (`EX_NOPERM`) |
|
|
| `78` | Config error | Missing credentials or bad config (`EX_CONFIG`) |
|
|
| `130` | Interrupted | Ctrl-C / SIGINT |
|
|
|
|
```bash
|
|
opencli spotify status || echo "exit $?" # 69 if browser not running
|
|
opencli github issues 2>/dev/null
|
|
[ $? -eq 77 ] && opencli github auth # auto-auth if not logged in
|
|
```
|
|
|
|
## Plugins
|
|
|
|
Extend OpenCLI with community-contributed adapters:
|
|
|
|
```bash
|
|
opencli plugin install github:user/opencli-plugin-my-tool
|
|
opencli plugin list
|
|
opencli plugin update --all
|
|
opencli plugin uninstall my-tool
|
|
```
|
|
|
|
| Plugin | Type | Description |
|
|
|--------|------|-------------|
|
|
| [opencli-plugin-github-trending](https://github.com/ByteYue/opencli-plugin-github-trending) | TS | GitHub Trending repositories |
|
|
| [opencli-plugin-hot-digest](https://github.com/ByteYue/opencli-plugin-hot-digest) | TS | Multi-platform trending aggregator |
|
|
| [opencli-plugin-juejin](https://github.com/Astro-Han/opencli-plugin-juejin) | TS | 稀土掘金 (Juejin) hot articles |
|
|
| [opencli-plugin-vk](https://github.com/flobo3/opencli-plugin-vk) | TS | VK (VKontakte) wall, feed, and search |
|
|
|
|
See [Plugins Guide](./docs/guide/plugins.md) for creating your own plugin.
|
|
|
|
## For AI Agents (Developer Guide)
|
|
|
|
> **Quick mode**: To generate a single command for a specific page URL, see [opencli-oneshot skill](./skills/opencli-oneshot/SKILL.md) — just a URL + one-line goal, 4 steps done.
|
|
|
|
> **Full mode**: Before writing any adapter code, read [opencli-explorer skill](./skills/opencli-explorer/SKILL.md). It contains the complete browser exploration workflow, the 5-tier authentication strategy decision tree, and debugging guide.
|
|
|
|
```bash
|
|
opencli explore https://example.com --site mysite # Discover APIs + capabilities
|
|
opencli synthesize mysite # Generate TS adapters
|
|
opencli generate https://example.com --goal "hot" # One-shot: explore → synthesize → register
|
|
opencli cascade https://api.example.com/data # Auto-probe: PUBLIC → COOKIE → HEADER
|
|
```
|
|
|
|
## Testing
|
|
|
|
See **[TESTING.md](./TESTING.md)** for how to run and write tests.
|
|
|
|
## Troubleshooting
|
|
|
|
- **"Extension not connected"** — Ensure the Browser Bridge extension is installed and **enabled** in `chrome://extensions` in Chrome or Chromium.
|
|
- **"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** — Ensure Node.js >= 20. Some dependencies require modern Node APIs.
|
|
- **Daemon issues** — Check status: `curl localhost:19825/status` · View logs: `curl localhost:19825/logs`
|
|
|
|
## Star History
|
|
|
|
[](https://star-history.com/#jackwener/opencli&Date)
|
|
|
|
## License
|
|
|
|
[Apache-2.0](./LICENSE)
|