--- name: opencli-uso-referencia description: Capa de orientación para OpenCLI, la herramienta que convierte cualquier web, app Electron o CLI externa en una superficie uniforme `opencli ` que los agentes pueden invocar sin scraping. Documenta los tres pilares (adaptadores, control de navegador, passthrough de CLIs externas), flags universales, formatos de salida y a qué skill especializada acudir según la tarea. allowed-tools: Bash(opencli:*), Read license: Apache-2.0 metadata: id: fa408828 slug: opencli-uso-referencia titulo: "OpenCLI — Guía de uso y referencia principal" servicio: Automatizaciones categoria_recurso: Web-Desarrollo tipo: referencia nivel: intermedio idioma: es idioma_original: en acceso: gratis precio_eur: 0 plataformas: [Node.js, Chrome, macOS, Linux, Windows] dependencias: [opencli (@jackwener/opencli), Node >= 21, Chrome + OpenCLI Extension (para estrategias COOKIE/INTERCEPT/UI)] licencia: { spdx: Apache-2.0, redistribuible: true, uso_comercial: true } fuente: repo: mxyhi/ok-skills url: https://github.com/mxyhi/ok-skills/tree/main/opencli/opencli-usage commit: ee29738 autor: mxyhi nombre_original: opencli-usage duplicados_en: [] seguridad: { veredicto: seguro, riesgo: bajo, escaneado: "2026-06-14", motor: "grep-estatico+auditor-llm" } ficha: que_hace: "Proporciona el mapa completo de capacidades de OpenCLI para que un agente sepa qué puede hacer la herramienta, cómo descubrir adaptadores y qué skill cargar a continuación." como_lo_hace: "Documenta los pilares de OpenCLI (adaptadores, browser driving, passthrough), flags universales, variables de entorno, estrategias de conexión por tipo de comando y comandos de descubrimiento como `opencli list -f json`." content_hash: "fa408828b36764fcacc7024003a39e0d03a87e121c4fa2410586e06d64697947" version: 1.0.0 --- # 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 | 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`. - **Current-tab binding** — `opencli browser bind` attaches the Chrome tab the user already opened/logged into to that browser session. Follow-up commands use `opencli browser ...`. See `opencli-browser` before using it; bound sessions still block tab mutation. - **External CLI passthrough** — `opencli gh`, `opencli docker`, `opencli vercel`, etc. Managed via `opencli external install ` (auto-install from `external-clis.yaml`) or `opencli external register ` (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 # same surface, no global install ``` `opencli doctor` prints a structured `DoctorReport` — daemon status, extension connection, version checks, and a live browser connectivity probe. 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` / `INTERCEPT` / `UI` adapters and the `opencli browser *` subcommands do. Flag: `-v` (verbose). ## Prerequisites by command type | Strategy tag on `opencli list` | What it needs | |--------------------------------|---------------| | `PUBLIC` | Nothing — pure HTTP, no browser. | | `COOKIE` | Chrome logged into the target site + **OpenCLI** extension installed from the [Chrome Web Store](https://chromewebstore.google.com/detail/opencli/ildkmabpimmkaediidaifkhjpohdnifk). 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, 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 --help # see that site's commands + flags opencli --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_CDP_ENDPOINT` | — | Manual CDP endpoint override (dev / remote Chrome / Electron). | | `OPENCLI_CACHE_DIR` | `~/.opencli/cache` | Network capture + browser-state cache. | | `OPENCLI_WINDOW` | command-specific | `foreground` or `background` browser window mode. | | `OPENCLI_VERBOSE` | `false` | Verbose logging (also triggered by `-v`). | ## Self-repair When an adapter command fails because the site changed (selectors drifted, API rotated, response schema shifted), re-run with `--trace retain-on-failure`. The error envelope includes a `trace` block pointing at `summary.md`; patch only the `adapterSourcePath` from that summary 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: ```bash opencli browser init / # 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 / # 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 opencli plugin create # 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 external install gh # auto-install via brew/apt/npm per external-clis.yaml opencli external register my-tool \ --binary my-tool \ --install "npm i -g my-tool" \ --desc "My internal CLI" opencli external list 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`, `longbridge`, `dws`, `wecom-cli`, `obsidian`, `ntn`, `tg(tg-cli)`, `discord(discord-cli)`, `wx(wx-cli)`. Some official CLIs use shell-script installers instead of a shell-free package-manager command. Entries without an `install` config, such as `ntn`, must be installed manually from their homepage before passthrough use. ## 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 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` — `--trace retain-on-failure` gives you the browser evidence and adapter source path. Do that first.