ai-native-cli

opencli

Make any website your CLI.
This is the TypeScript version of the project. The repo is opencli, and the user-facing command is:

opencli

opencli connects to your existing Chrome browser through the Playwright MCP Bridge extension, reuses your real login session, and turns site capabilities into stable terminal commands.

What Exists Today

Current top-level commands:

opencli list
opencli validate
opencli verify
opencli explore
opencli synthesize
opencli generate

Current built-in sites:

• bilibili
• github
• hackernews
• twitter
• v2ex
• zhihu

opencli list may also show user-generated CLIs from ~/.opencli/clis/.

Prerequisites

Before using opencli, make sure:

• Node.js is installed
• Chrome is running
• The target sites are already logged in in that Chrome profile
• The Playwright MCP Bridge extension is installed
• PLAYWRIGHT_MCP_EXTENSION_TOKEN is available in the environment used by opencli

Install the extension:

• Playwright MCP Bridge

Export the token:

export PLAYWRIGHT_MCP_EXTENSION_TOKEN=*****

If you are using Claude Code / Codex / another MCP-aware tool, configure Playwright MCP like this:

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["@playwright/mcp@latest", "--extension"],
      "env": {
        "PLAYWRIGHT_MCP_EXTENSION_TOKEN": "*****"
      }
    }
  }
}

Install

For local development:

npm install
npm run build

Run directly from source:

npm run dev -- list

If you want a local opencli binary during development:

npm link

Quick Start

Use existing commands:

opencli list
opencli zhihu hot --limit 5
opencli bilibili me --format json
opencli github trending

Explore a new site:

opencli explore https://www.bilibili.com/v/popular/all --site bilibili
opencli synthesize bilibili
opencli validate
opencli verify bilibili/hot --smoke

One-shot generation:

opencli generate https://www.bilibili.com/v/popular/all --site bilibili --goal hot

Command Model

There are two plugin paths:

• Built-in CLIs in src/clis/<site>/
• User CLIs in ~/.opencli/clis/<site>/

Built-ins can be written as:

• YAML files for straightforward pipelines
• TypeScript adapters for complex logic

TypeScript adapters self-register on import. The built-in TS adapters are imported from:

• src/clis/index.ts

Authoring Model

Prefer this flow:

• opencli explore <url>
• Inspect .opencli/explore/<site>/
• Add or edit a CLI definition
• opencli validate
• opencli verify <target> --smoke

Use YAML when the flow is simple:

• direct fetch
• small mapping
• no custom signing
• no multi-step stateful logic

Use TypeScript when you need:

• custom auth propagation
• signing
• retries
• pagination
• cross-request normalization
• DOM-specific extraction

Built-In Site Coverage

Current built-ins in this repo:

• bilibili: hot, me, search
• github: search, trending
• hackernews: top
• twitter: trending
• v2ex: hot, latest
• zhihu: hot

Generated candidates and user CLIs can expand this list.

Always prefer:

opencli list

as the source of truth for the current command surface.

Serial Execution Rule

Playwright MCP Bridge is effectively a single shared browser extension session.

That means:

• browser-backed opencli commands must run serially
• verify --smoke must run serially
• real end-to-end tests must run serially
• agents should not fan out multiple browser-backed subprocesses in parallel

If a run leaves the bridge connect.html tab open, finish the current run before retrying.

Troubleshooting

Browser connect timed out

Usually means:

• Chrome is not running
• the extension is not installed or not active
• the token is missing or stale
• another browser-backed run is already holding the shared extension session

Check:

echo $PLAYWRIGHT_MCP_EXTENSION_TOKEN
opencli list

Then retry one command, serially.

Transport closed

This usually means the Bridge session is dirty or an MCP helper exited unexpectedly.

Try this order:

• stop other browser-backed opencli runs
• close leftover bridge tabs
• confirm the extension token is still current
• retry one minimal command

Validation fails

Use:

opencli validate
opencli verify <target>
opencli verify <target> --smoke

Project Layout

src/
├── main.ts                # Commander entrypoint
├── browser.ts             # Playwright MCP Bridge integration
├── runtime.ts             # Browser session guards + timeouts
├── engine.ts              # YAML/TS discovery + execution
├── pipeline.ts            # YAML pipeline runtime
├── validate.ts            # Static validation
├── verify.ts              # Validation + optional smoke
├── explore.ts             # Discovery artifacts
├── synthesize.ts          # Candidate generation
├── generate.ts            # One-shot flow
└── clis/
    ├── index.ts           # TS adapter imports
    └── <site>/

Agent Workflow

If an AI agent is authoring CLIs for this repo, start with:

• SKILL.md
• CLI_AUTHORING_GUIDE.md

That file describes:

• the authoring workflow
• serial-execution constraints
• YAML vs TypeScript decisions
• seed-input strategy for parameterized commands
• validation and verification expectations