opencli-usage#

OpenCLI turns any website, Electron desktop app, or external CLI into a uniform opencli <site> <command> surface that agents can drive without screen-scraping. This skill is the orientation layer — once you know what you want to do, load one of the specialized skills below.

The three pillars#

• Adapter commands — opencli <site> <command> [...]. Built-in adapters live in clis/, user adapters in ~/.opencli/clis/. Each is backed by a strategy ( PUBLIC | COOKIE | HEADER | INTERCEPT | UI | LOCAL) that tells you whether a Chrome session is needed.
• Browser driving — opencli browser * subcommands ( open, state, click, type, select, find, extract, network, …) for ad-hoc interaction and scraping when no adapter covers the task. See opencli-browser.
• External CLI passthrough — opencli gh, opencli docker, opencli vercel, etc. Registered via opencli install <name> (auto-install from external-clis.yaml) or opencli register <name> (bring your own).

Install#

bash

# npm global
npm install -g @jackwener/opencli          # binary: opencli, requires Node >= 21
opencli doctor                              # run before browser-dependent work (see below)

# From source
git clone git@github.com:jackwener/OpenCLI.git
cd OpenCLI && npm install
npx tsx src/main.ts <command>               # same surface, no global install

opencli doctor prints a structured DoctorReport — daemon status, extension connection, version checks. Scope is narrow: it diagnoses the browser bridge (daemon + extension + Chrome wiring). PUBLIC / LOCAL adapters, opencli list, validate, verify, plugin commands, and external-CLI passthrough don't need it to be green — only COOKIE / HEADER / INTERCEPT / UI adapters and the opencli browser * subcommands do. Flags: --no-live (skip live browser test), --sessions (list active automation sessions), -v (verbose).

Prerequisites by command type#

Strategy tag on opencli listWhat it needsPUBLICNothing — pure HTTP, no browser.COOKIE / HEADERChrome logged into the target site + opencli Browser Bridge extension loaded (see extension/). Command captures the credential from your live session — no re-login.INTERCEPTSame as COOKIE, plus opencli opens an automation window to capture a signed request.UISame as COOKIE, full DOM interaction.LOCALNo browser; talks to a local/dev endpoint.

Electron desktop apps (cursor, codex, chatwise, notion, discord-app, doubao-app, antigravity, chatgpt-app) route through CDP against the running app — same cookie-less flow as a logged-in browser. Make sure the app is running before invoking.

Discover what's installed — don't read this file, run a command#

bash

opencli list                    # table, grouped by site
opencli list -f json            # machine-readable; pipe to jq or your agent
opencli list | grep -i twitter  # find commands for a specific site
opencli <site> --help           # see that site's commands + flags
opencli <site> <command> --help # see positional args and command-specific flags

Do not hard-code adapter lists — there are 100+ sites and the count moves every week. opencli list -f json is the source of truth; it emits one entry per command with {site, name, aliases, description, strategy, browser, args, columns, ...}. For an agent, that is always better than grepping a doc.

Universal flags (work on every adapter command)#

flageffect-f, --format <fmt>``table (default in TTY) · yaml (default in non-TTY) · json · plain · md · csv. Pass explicitly when you want a specific shape; agents almost always want -f json.-v, --verboseDebug logs + stack traces on failure; also sets OPENCLI_VERBOSE=1 for the process.

Command-specific flags ( --limit, --tab, --filter, …) are not universal — consult <site> <command> --help.

Output formats#

• json — pretty-printed, 2-space indent. Default choice for agents.
• plain — prints a single primary field for chat-style commands ( response/ content/ text/ value). Useful for piping to another tool.
• yaml — fallback when output is not a TTY and -f is not explicit.
• table — color-coded, site-grouped; meant for humans.
• md, csv — straightforward tabular dumps.

A few commands override the default via cmd.defaultFormat (e.g. chat commands default to plain), so don't assume without reading --help.

Environment variables#

variabledefaultpurposeOPENCLI_DAEMON_PORT``19825Daemon ↔ extension bridge port.OPENCLI_BROWSER_CONNECT_TIMEOUT``30Seconds to wait for the browser bridge.OPENCLI_BROWSER_COMMAND_TIMEOUT``60Per-command timeout.OPENCLI_BROWSER_EXPLORE_TIMEOUT``120For long-running recon (plugin/adapter scaffolding).OPENCLI_CDP_ENDPOINT—Manual CDP endpoint override (dev / remote Chrome / Electron).OPENCLI_CACHE_DIR``~/.opencli/cacheNetwork capture + browser-state cache.OPENCLI_WINDOW_FOCUSED``false``1 → automation window opens in the foreground.OPENCLI_VERBOSE``falseVerbose logging (also triggered by -v).OPENCLI_DIAGNOSTIC``false``1 → emit structured RepairContext JSON on adapter failure. Required for opencli-autofix.

Self-repair#

When an adapter command fails because the site changed (selectors drifted, API rotated, response schema shifted), the CLI emits a hint: # AutoFix: re-run with OPENCLI_DIAGNOSTIC=1 .... Do that, read the RepairContext, patch the adapter at RepairContext.adapter.sourcePath, and retry. Max 3 repair rounds. The full flow is in opencli-autofix.

Writing your own adapter#

Two-path storage:

• Private: ~/.opencli/clis/<site>/<command>.js — no build step, hot-available, not visible in the public package.
• Public / PR: clis/<site>/<command>.js — for upstream contribution; requires build.

Scaffolding & verification:

bash

opencli browser init <site>/<command>   # generates a skeleton
opencli validate [target]               # semantic checks on the loaded registry (description, domain, pipeline step names, func|pipeline|_lazy presence, arg duplicates) — no network, no browser
opencli verify [target] [--smoke]       # run the command with synthetic args
opencli browser verify <site>/<command> # end-to-end smoke inside the bridge

Adapters import only @jackwener/opencli/registry and @jackwener/opencli/errors. columns must align 1:1 (in name and order) with keys of the object returned by func. For the full workflow see opencli-adapter-author.

Plugins#

Plugins are third-party extensions pulled from git, separate from the main adapter registry:

bash

opencli plugin install github:user/repo    # install
opencli plugin list [-f json]              # see installed
opencli plugin update [name] | --all       # keep current
opencli plugin uninstall <name>
opencli plugin create <name>               # scaffold a new plugin

External CLI passthrough#

Wraps external command-line tools so you can discover + invoke them through the same opencli … entrypoint:

bash

opencli install gh             # auto-install via brew/apt/npm per external-clis.yaml
opencli register my-tool \
    --binary my-tool \
    --install "npm i -g my-tool" \
    --desc "My internal CLI"
opencli gh pr list --limit 5   # passthrough; stdio is inherited, exit code propagated
opencli docker ps

Built-in entries live in src/external-clis.yaml; user overrides and additions in ~/.opencli/external-clis.yaml. Commonly shipped: gh, docker, vercel, lark-cli, dws, wecom-cli, obsidian.

Shell completion#

bash

opencli completion bash   # also: zsh, fish
# -> script on stdout; source or save per your shell's convention

Where to go next#

If you're about to…Load this skillDrive a live browser ad-hoc (no adapter available, or prototyping)opencli-browserWrite a new adapter, or add a command to an existing siteopencli-adapter-authorFix a broken adapter after a command failureopencli-autofixRoute a search / lookup / research request to the right adaptersmart-search

Commands that used to exist#

The following were removed in the PR #1094 consolidation — don't try to invoke them:

• opencli explore <url> — superseded by opencli browser network + opencli browser find for live API discovery, and by the opencli-adapter-author workflow for capture.
• opencli record <url> — removed; manual capture now lives in opencli browser network --detail.
• opencli web read / opencli desktop * as top-level groups — folded into their respective adapters ( opencli web read still exists as the web adapter's read command, but there is no standalone web / desktop top-level group command).

Don't#

• Don't paste this skill's command list into your plan; it will rot. Call opencli list -f json at the start of a task instead.
• Don't assume every adapter needs a browser — strategy PUBLIC and LOCAL don't. Check the strategy field.
• Don't silently fall back from a failing adapter to a hand-rolled fetch — OPENCLI_DIAGNOSTIC=1 almost always tells you exactly what to change in the adapter. Do that first.