opencli-usage

OpenCLI turns any website, Electron desktop app, or external CLI into a uniform opencli 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 [...]. 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 (auto-install from external-clis.yaml) or opencli register (bring your own).

Install

# 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 list | What it needs |

|--------------------------------|---------------|

| PUBLIC | Nothing — pure HTTP, no browser. |

| COOKIE / HEADER | Chrome logged into the target site + opencli Browser Bridge extension loaded (see extension/). Command captures the credential from your live session — no re-login. |

| INTERCEPT | Same as COOKIE, plus opencli opens an automation window to capture a signed request. |

| UI | Same as COOKIE, full DOM interaction. |

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

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)

| flag | effect |

|------|--------|

| -f, --format | 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, --verbose | Debug logs + stack traces on failure; also sets OPENCLI_VERBOSE=1 for the process. |

Command-specific flags (--limit, --tab, --filter, …) are not universal — consult --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

| variable | default | purpose |

|----------|---------|---------|

| OPENCLI_DAEMON_PORT | 19825 | Daemon ↔ extension bridge port. |

| OPENCLI_BROWSER_CONNECT_TIMEOUT | 30 | Seconds to wait for the browser bridge. |

| OPENCLI_BROWSER_COMMAND_TIMEOUT | 60 | Per-command timeout. |

| OPENCLI_BROWSER_EXPLORE_TIMEOUT | 120 | For long-running recon (plugin/adapter scaffolding). |

| OPENCLI_CDP_ENDPOINT | — | Manual CDP endpoint override (dev / remote Chrome / Electron). |

| OPENCLI_CACHE_DIR | ~/.opencli/cache | Network capture + browser-state cache. |

| OPENCLI_WINDOW_FOCUSED | false | 1 → automation window opens in the foreground. |

| OPENCLI_VERBOSE | false | Verbose 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//.js — no build step, hot-available, not visible in the public package.
• Public / PR: clis//.js — for upstream contribution; requires build.

Scaffolding & verification:

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:

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:

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

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

|---------------------|-----------------|

| Drive a live browser ad-hoc (no adapter available, or prototyping) | opencli-browser |

| Write a new adapter, or add a command to an existing site | opencli-adapter-author |

| Fix a broken adapter after a command failure | opencli-autofix |

| Route a search / lookup / research request to the right adapter | smart-search |

Commands that used to exist

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

• opencli explore — superseded by opencli browser network + opencli browser find for live API discovery, and by the opencli-adapter-author workflow for capture.
• opencli record — 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.