mirror of https://github.com/jackwener/OpenCLI.git synced 2026-09-14 18:25:42 +08:00

Files

T

jackwener b1e0bf1e28 fix(cli-argv): hide --session flag, fail-fast on retired form, rename to <session>

Three blockers in #1505 review:

1. `--session` flag was still visible in `opencli browser --help` and could
   be used as a public entrance, contradicting "positional only" UX.
   Fix: switch from `.requiredOption()` to `.addOption(new Option(...).hideHelp())`.
   The flag is preserved as an internal API for the daemon protocol and direct
   `program.parseAsync` callers (tests), but is no longer documented or
   surfaced in structured help.

2. `opencli browser --session foo state` still succeeded. Now the argv
   preprocessor throws `BrowserSessionArgvError` when root `browser` is
   followed by `--session`, and main.ts catches it and exits with a
   user-facing usage error pointing to the positional form.

3. Missing-session error message exposed the internal flag:
   `required option '--session <name>' not specified`. Now `getBrowserSession()`
   in the action body throws `<session> is a required positional argument:
   opencli browser <session> <command>`, and commander no longer guards the
   hidden option.

Also (per @WAWQAQ) rename placeholder `<sessionname>` -> `<session>` everywhere
user-facing — shorter, matches CLI convention. The help text "<session> is a
required positional: pass the name of the browser session..." carries the
"name" semantics in description, not in the placeholder itself.

Sync surfaces:
  - src/cli.ts — usage line, addOption with hideHelp, descriptions
  - src/cli-argv-preprocess.ts — throw on --session form
  - src/cli-argv-preprocess.test.ts — refusal test for old form
  - src/cli.test.ts — assertions updated for hidden option + new error path
  - src/help.ts — read `_usage` private field to respect `.usage()` override
    (commander's `.usage()` getter returns auto-generated form if not set,
    which would otherwise pollute every namespace's usage string)
  - src/main.ts — catch BrowserSessionArgvError, stderr + exit
  - README.md / README.zh-CN.md
  - docs/guide/browser-bridge.md / docs/zh/guide/browser-bridge.md
  - skills/opencli-browser/SKILL.md / skills/opencli-usage/SKILL.md
  - CHANGELOG.md

Manual smoke tests (against built dist):
  - `opencli browser --help` shows `Usage: opencli browser <session> <command> [options]`
  - `opencli browser --help` Options block does NOT show `--session`
  - `opencli browser --session foo state` → friendly error, no commander stacktrace
  - `opencli browser state` → `<session> is a required positional argument: opencli browser <session> <command>`
  - `opencli browser foo state` → parses correctly

2026-05-12 20:23:01 +08:00

3.5 KiB

Raw Permalink Blame History

Browser Bridge Setup

⚠️ Important: Browser commands reuse your Chrome login session. You must be logged into the target website in Chrome before running commands.

OpenCLI connects to your browser through a lightweight Browser Bridge Chrome Extension + micro-daemon (zero config, auto-start).

Extension Installation

Method 1: Download Pre-built Release (Recommended)

Go to the GitHub Releases page and download the latest opencli-extension-v{version}.zip.
Unzip the file and open chrome://extensions, enable Developer mode (top-right toggle).
Click Load unpacked and select the unzipped folder.

Method 2: Load Unpacked Source (For Developers)

Open chrome://extensions and enable Developer mode.
Click Load unpacked and select the extension/ directory from the repository.

Verification

That's it! The daemon auto-starts when you run any browser command. No tokens, no manual configuration.

opencli doctor            # Check extension + daemon connectivity

Tab Targeting

Browser commands require an explicit <session> positional immediately after browser. Use the same session name for a multi-step flow, and use different names to isolate parallel work.

opencli browser baidu open https://www.baidu.com/
opencli browser baidu tab list
opencli browser baidu tab new https://www.baidu.com/
opencli browser baidu eval --tab <targetId> 'document.title'
opencli browser baidu tab select <targetId>
opencli browser baidu get title
opencli browser baidu tab close <targetId>

Key rules:

opencli browser <session> open <url> and opencli browser <session> tab new [url] return a targetId.
opencli browser <session> tab list prints the targetId values of tabs that already exist.
--tab <targetId> routes a single browser command to that specific tab.
tab new creates a new tab but does not change the default browser target.
tab select <targetId> makes that tab the default target for later untargeted opencli browser ... commands.
tab close <targetId> removes the tab; if it was the current default target, the stored default is cleared.

How It Works

┌─────────────┐     WebSocket      ┌──────────────┐     Chrome API     ┌─────────┐
│  opencli    │ ◄──────────────► │  micro-daemon │ ◄──────────────► │  Chrome  │
│  (Node.js)  │    localhost:19825  │  (auto-start) │    Extension       │ Browser  │
└─────────────┘                    └──────────────┘                    └─────────┘

The daemon manages the WebSocket connection between your CLI commands and the Chrome extension. The extension executes JavaScript in the context of web pages, with access to the logged-in session.

Daemon Lifecycle

The daemon auto-starts on first browser command and stays alive persistently.

opencli daemon stop      # Graceful shutdown

The daemon is persistent — it stays alive until you explicitly stop it (opencli daemon stop) or uninstall the package.

Running OpenCLI from a remote machine

If you need to run opencli on a remote server (CI runner, agent host) but keep the browser session on your local machine, see Remote Orchestration. It walks through the SSH reverse-tunnel pattern so the daemon never leaves localhost.

3.5 KiB Raw Permalink Blame History