opencli-usage

OpenCLI は、任意のウェブサイト、Electron デスクトップアプリ、または外部 CLI を、エージェントが画面スクレイピングなしで駆動できる統一された opencli <site> <command> インターフェースに変えます。このスキルはオリエンテーション層です — やりたいことが決まったら、以下の専門的なスキルの1つを読み込んでください。

3つの柱

• Adapter コマンド — opencli <site> <command> [...]。組み込みアダプターは clis/ に、ユーザーアダプターは ~/.opencli/clis/ に存在します。各アダプターは戦略 (PUBLIC | COOKIE | INTERCEPT | UI | LOCAL) に支えられており、Chrome セッションが必要かどうかを示しています。
• ブラウザー駆動 — opencli browser * サブコマンド (open, state, click, type, select, find, extract, network, …) は、アダプターがタスクをカバーしない場合のアドホック操作とスクレイピング用です。opencli-browser を参照してください。
• 現在のタブバインディング — opencli browser <session> bind は、ユーザーが既に開く/ログインしているChrome タブをそのブラウザーセッションに接続します。その後のコマンドは opencli browser <session> ... を使用します。使用する前に opencli-browser を参照してください；バインドされたセッションはタブ変更をブロックします。
• 外部 CLI パススルー — opencli gh、opencli docker、opencli vercel など。opencli external install <name> (external-clis.yaml から自動インストール) または opencli external register <name> (独自のツール) で管理します。

インストール

# npm グローバル
npm install -g @jackwener/opencli          # バイナリ: opencli, Node >= 21 が必須
opencli doctor                              # ブラウザー依存作業前に実行 (下記参照)

# ソースから
git clone git@github.com:jackwener/OpenCLI.git
cd OpenCLI && npm install
npx tsx src/main.ts <command>               # 同じインターフェース、グローバルインストール不要

opencli doctor は構造化された DoctorReport を出力します — デーモンの状態、拡張機能の接続、バージョンチェック、および実時間のブラウザー接続プローブです。スコープは限定的です: ブラウザーブリッジ (デーモン + 拡張機能 + Chrome 配線) を診断します。PUBLIC / LOCAL アダプター、opencli list、validate、verify、プラグインコマンド、外部 CLI パススルーは緑色である必要はありません — COOKIE / INTERCEPT / UI アダプターと opencli browser * サブコマンドのみ必要です。フラグ: -v (詳細)。

コマンドタイプ別の前提条件

opencli list の戦略タグ	必要なもの
PUBLIC	なし — 純粋な HTTP、ブラウザーなし。
COOKIE	ターゲットサイトにログインした Chrome + Chrome ウェブストア からインストールした OpenCLI 拡張機能。コマンドはあなたの実時間セッションから認証情報をキャプチャします — 再ログインなし。
INTERCEPT	COOKIE と同じ、さらに opencli は署名済みリクエストをキャプチャするためのオートメーションウィンドウを開きます。
UI	COOKIE と同じ、完全な DOM 操作。
LOCAL	ブラウザーなし；ローカル/dev エンドポイントと通信します。

Electron デスクトップアプリ (cursor, codex, chatwise, discord-app, doubao-app, antigravity, chatgpt-app) は実行中のアプリに対する CDP を経由してルーティングされます — ログイン済みのブラウザーと同じ認証不要のフローです。呼び出す前にアプリが実行中であることを確認してください。

インストール済みのものを発見する — このファイルを読まずにコマンドを実行してください

opencli list                    # テーブル、サイトごとにグループ化
opencli list -f json            # マシン読み取り可能；jq またはエージェントにパイプ
opencli list | grep -i twitter  # 特定のサイトのコマンドを検索
opencli <site> --help           # そのサイトのコマンド + フラグを表示
opencli <site> <command> --help # 位置引数とコマンド固有フラグを表示

アダプターリストをハードコーディングしないでください — 100 以上のサイトがあり、数は毎週変わります。opencli list -f json が真実の源です；{site, name, aliases, description, strategy, browser, args, columns, ...} を持つコマンドごとに1つのエントリを出力します。エージェントにとって、それはドキュメントをグリップするよりも常に優れています。

ユニバーサルフラグ (すべてのアダプターコマンドで機能)

フラグ	効果
-f, --format <fmt>	table (TTY ではデフォルト) · yaml (非 TTY ではデフォルト) · json · plain · md · csv。特定の形式が必要な場合は明示的に渡してください；エージェントはほぼ常に -f json を望みます。
-v, --verbose	デバッグログ + 失敗時のスタックトレース；また OPENCLI_VERBOSE=1 をプロセスに設定します。

コマンド固有のフラグ (--limit, --tab, --filter など) はユニバーサルではありません — <site> <command> --help で確認してください。

出力フォーマット

• json — きれいに出力、2スペースインデント。エージェント向けのデフォルト選択。
• plain — チャットスタイルコマンド用の単一の主フィールド (response/content/text/value) を出力します。別のツールへのパイプに便利です。
• yaml — 出力が TTY でなく、-f が明示的でない場合のフォールバック。
• table — カラーコード化、サイトごとにグループ化；人間向け。
• md, csv — 直接的な表形式ダンプ。

いくつかのコマンドは cmd.defaultFormat 経由でデフォルトをオーバーライドします (例: チャットコマンドはデフォルトで plain)、--help を読まずに想定しないでください。

環境変数

変数	デフォルト	用途
OPENCLI_DAEMON_PORT	19825	デーモン ↔ 拡張機能ブリッジポート。
OPENCLI_BROWSER_CONNECT_TIMEOUT	30	ブラウザーブリッジ待機秒数。
OPENCLI_BROWSER_COMMAND_TIMEOUT	60	コマンドごとのタイムアウト。
OPENCLI_CDP_ENDPOINT	—	手動 CDP エンドポイントオーバーライド (dev / リモート Chrome / Electron)。
OPENCLI_CACHE_DIR	~/.opencli/cache	ネットワークキャプチャ + ブラウザー状態キャッシュ。
OPENCLI_WINDOW	コマンド固有	foreground または background ブラウザーウィンドウモード。
OPENCLI_VERBOSE	false	詳細ログ (-v でもトリガーされます)。

自己修復

アダプターコマンドがサイト変更 (セレクタドリフト、API ローテーション、レスポンススキーマシフト) により失敗した場合、--trace retain-on-failure で再実行してください。エラーエンベロープには summary.md を指すトレースブロックが含まれます；そのサマリーから adapterSourcePath のみをパッチして再試行してください。最大 3 修復ラウンド。完全なフローは opencli-autofix にあります。

独自のアダプターを書く

2つのパス保存:

• プライベート: ~/.opencli/clis/<site>/<command>.js — ビルドステップなし、ホット利用可能、パブリックパッケージに見えない。
• パブリック / PR: clis/<site>/<command>.js — アップストリームコントリビューション用；ビルドが必須。

スキャフォールディングと検証:

opencli browser init <site>/<command>   # スケルトンを生成
opencli validate [target]               # 読み込まれたレジストリの意味チェック (description, domain, pipeline step names, func|pipeline|_lazy presence, arg duplicates) — ネットワーク、ブラウザーなし
opencli verify [target] [--smoke]       # 合成引数でコマンドを実行
opencli browser verify <site>/<command> # ブリッジ内のエンドツーエンドスモーク

アダプターは @jackwener/opencli/registry と @jackwener/opencli/errors のみをインポートします。columns は func が返すオブジェクトのキーと 1:1 で名前と順序を一致させる必要があります。完全なワークフローについては opencli-adapter-author を参照してください。

プラグイン

プラグインは git から取得されたサードパーティ拡張機能で、メインアダプターレジストリから独立しています:

opencli plugin install github:user/repo    # インストール
opencli plugin list [-f json]              # インストール済みを表示
opencli plugin update [name] | --all       # 最新版に保つ
opencli plugin uninstall <name>
opencli plugin create <name>               # 新しいプラグインをスキャフォールド

外部 CLI パススルー

外部コマンドラインツールをラップして、同じ opencli … エンドポイントで発見し、呼び出すことができます:

opencli external install gh    # external-clis.yaml 経由で brew/apt/npm で自動インストール
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   # パススルー；stdio は継承、終了コードは伝播
opencli docker ps

組み込みエントリは src/external-clis.yaml に、ユーザーオーバーライドと追加は ~/.opencli/external-clis.yaml にあります。一般的に付属: gh、docker、vercel、lark-cli、longbridge、dws、wecom-cli、obsidian、ntn、tg(tg-cli)、discord(discord-cli)、wx(wx-cli)。

いくつかの公式 CLI はシェルフリーパッケージマネージャーコマンドの代わりにシェルスクリプトインストーラーを使用します。ntn などの install 設定なしエントリは、パススルー使用前にホームページから手動でインストールする必要があります。

シェル補完

opencli completion bash   # also: zsh, fish
# -> stdout 上のスクリプト；シェルの規約に従ってソースまたは保存

次に行くべき場所

やろうとしている場合…	このスキルを読み込んでください
ライブブラウザーをアドホック駆動 (利用可能なアダプターなし、またはプロトタイピング)	opencli-browser
新しいアダプターを書く、または既存サイトにコマンドを追加	opencli-adapter-author
コマンド失敗後に破損したアダプターを修復	opencli-autofix
検索 / ルックアップ / リサーチリクエストを正しいアダプターにルーティング	smart-search

かつて存在していたコマンド

以下は PR #1094 統合で削除されました — それらを呼び出そうとしないでください:

• opencli explore <url> — opencli browser network + opencli browser find (ライブ API 発見用) および opencli-adapter-author ワークフロー (キャプチャ用) に置き換えられました。
• opencli record <url> — 削除されました；手動キャプチャは現在 opencli browser network --detail にあります。
• opencli web read / opencli desktop * トップレベルグループとして — 各アダプターにまとめられました (opencli web read は依然として web アダプターの read コマンドとして存在しますが、スタンドアロンの web / desktop トップレベルグループコマンドはありません)。

するな

• このスキルのコマンドリストを計画に貼り付けないでください；劣化します。代わりにタスクの開始時に opencli list -f json を呼び出してください。
• すべてのアダプターがブラウザーを必要とすると想定しないでください — 戦略 PUBLIC と LOCAL はそうではありません。strategy フィールドを確認してください。
• 失敗したアダプターからハンドロールされた fetch に静かにフォールバックしないでください — --trace retain-on-failure はあなたにブラウザー証拠とアダプターソースパスを与えます。先にそれをしてください。