opencli-usage

Use at the start of any OpenCLI session — this is the top-level map of what `opencli` can do, how to discover adapters, what flags and output formats are uni...

Security Scan

The skill is an instruction-only orientation doc for OpenCLI and is internally consistent with that purpose; it documents browser-driven behavior that can access live browser sessions (cookies/headers) but otherwise makes no unexpected requests or installs.

Purpose & Capability

The skill's name/description match the content: it's an orientation layer for opencli. Minor inconsistency: the registry metadata lists no required binaries, but the SKILL.md repeatedly assumes the presence of the `opencli` binary (and shows how to install it). The omission of `opencli` from required-binaries is a documentation mismatch but does not change the skill's purpose.

Instruction Scope

SKILL.md confines runtime actions to running `opencli` commands (e.g., `opencli list -f json`, `opencli doctor`) and reading documentation; allowed-tools reflect this. It does describe adapters that will capture credentials from a logged-in Chrome session, which is within the documented scope (browser-bridge adapters). The instructions do not ask the agent to read unrelated system files or exfiltrate data to unexpected endpoints.

Install Mechanism

This is an instruction-only skill with no install spec. The doc shows standard install options (npm package, GitHub repo). Those instructions reference common sources (npm, GitHub via SSH) and do not include arbitrary downloads or obscure URLs.

Credentials

The skill itself declares no required environment variables, but the documentation lists several OPENCLI_* env vars used to configure the browser bridge and timeouts. More importantly, several adapter strategies (COOKIE, HEADER, INTERCEPT, UI) require a logged-in Chrome session and will capture session cookies/headers; this is sensitive but coherent with the documented functionality. There are no unexpected credential requests in the metadata.

Persistence & Privilege

The skill does not request permanent presence (always:false), does not include install hooks, and does not attempt to modify other skills or system-wide agent settings. It's a read-and-run documentation layer with normal agent invocation allowed.

Assessment

This skill is an orientation/documentation layer for OpenCLI and appears to do what it claims. Before using it: (1) ensure you have the opencli binary installed (the SKILL.md assumes it, but the metadata didn't list it); (2) understand that some adapters require a logged-in Chrome/Electron session and will capture cookies/headers from that session — only use those adapters if you trust the site and the OpenCLI browser extension/daemon; (3) if you plan to install from the repo or npm, verify the package/source (npm @jackwener/opencli and the GitHub repo) and prefer HTTPS/git read-only URLs if you don't want to use your SSH keys; (4) the skill is instruction-only and does not request secrets itself, but running the described commands can access sensitive browser state, so review adapter behavior and the OpenCLI extension/daemon before granting it access.

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

# 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 [e-mail]: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 <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, --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 <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

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/<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:

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