use-tinyfish

TinyFish CLI

TinyFish CLI（tinyfish）を利用できます。これは、ターミナルから呼び出せる一連のウェブツールです。

未インストールの場合：npm install -g @tiny-fish/cli 未認証の場合：tinyfish auth login --source openclaw を実行するか、TINYFISH_API_KEY 環境変数を設定してください。

---

このスキルを使用するタイミング

リクエストに最新のウェブ情報やページのコンテンツが必要な場合は、TinyFish を使用してください。ユーザーが「TinyFish」や「スクレイピング」と言うのを待つ必要はありません。

主な使用例：

• 検索や情報の発見：検索、検索して見つける、調べる、比較する、最新情報、現在の情報、ニュース、ドキュメント、料金、製品の詳細、最適な選択肢。
• URL／ページの閲覧：取得する、読む、要約する、このページから抽出する、この URL を確認する、コンテンツを取得する、リンクやメタデータを取得する。
• 出典に基づく回答：ウェブ上の出典を使って回答する、事実を検証する、何かが変更されたか確認する、ウェブから情報を収集する。
• ウェブサイトの操作：サイトを操作する、ページを移動する、フォームに入力する、ログインする、構造化データを収集する、ボット対策されたページに対応する。

回答できる最も軽量なツールを既定で使用してください。

• URL がなく、ユーザーがウェブ情報を必要としている場合：search を使い、さらに詳細が必要なら最適な結果を fetch します。
• URL が指定されていて、必要なのがコンテンツのみの場合：fetch を使います。
• ページの操作や動的なデータ抽出が必要な場合：agent を使います。
• 生の CDP／Playwright 形式の制御が必要な場合：browser を使います。

---

適切なツールの選択

TinyFish には 4 つのツールがあります。目的を達成できる最も軽量なものから始め、必要な場合にのみ上位のツールに切り替えてください。

search  →  fetch  →  agent  →  browser
lightest                        heaviest

ツール	使用する場面	速度	コスト
search	URL、最新情報、ドキュメント、料金、製品の詳細を探す場合や、出典に基づく簡潔な回答が必要な場合	最速	最低
fetch	URL があり、ページのコンテンツ、要約、記事本文、ドキュメント、製品ページ、リンク、メタデータが必要な場合	高速	低
agent	ページを操作する必要がある場合 — クリック、フォーム入力、ページ移動、動的なサイトからの構造化データの抽出	低速	高
browser	agent では不十分で、CDP 経由の生のプログラムによるブラウザー制御が必要な場合	最も低速	最高

一般的なパターン

調査：search → fetch トピックを検索し、最適な結果を fetch して全文を読みます。

# 1. Find URLs
tinyfish search query "best React state management libraries 2026"

# 2. Read the top results
tinyfish fetch content get --format markdown "https://result1.com" "https://result2.com"

詳細な抽出：search → agent 検索して適切なサイトを見つけ、agent を使って操作し、構造化データを抽出します。

# 1. Find the site
tinyfish search query "Nike running shoes official store"

# 2. Automate extraction on it
tinyfish agent run --url "https://nike.com/running" \
  "Extract all running shoes as JSON: [{\"name\": str, \"price\": str, \"colors\": [str]}]"

上位ツールへの切り替え：fetch → agent まず fetch を試します。ページが動的、または JS を多用しており、fetch で空または不完全なコンテンツが返された場合は、agent に切り替えます。

完全な制御：agent → browser agent で複雑な複数ステップのワークフローに対応できない場合は、生のブラウザーセッションを起動し、CDP 経由で自分で自動化します。

---

コマンド

tinyfish search query

ウェブ検索です。タイトル、URL、スニペットを含む、ランキング順の結果を返します。

tinyfish search query "<query>" [--location <hint>] [--language <hint>] [--pretty]

• 既定では 10 件の結果を返します
• 地域を指定した結果を得るには、--location と --language を使用します
• 既定の出力形式は JSON です。人が読みやすい形式にするには --pretty を指定します

tinyfish search query "best pho in Ho Chi Minh City" --location "Vietnam" --language "en"

---

tinyfish fetch content get

1 つ以上の URL から、抽出済みのクリーンなコンテンツを取得します。広告、ナビゲーション、定型文を取り除き、コンテンツのみを返します。

tinyfish fetch content get <urls...> [--format markdown|html|json] [--links] [--image-links] [--pretty]

• 1 回の呼び出しで複数の URLを指定できます。サーバー側で並列に取得されます
• --format markdown（既定）— 読みやすく整形されたテキスト
• --format json — 構造化されたドキュメントツリー
• --links — ページから抽出したすべてのリンクを含めます
• --image-links — 抽出した画像 URL を含めます
• レスポンスに含まれる項目：url、final_url、title、language、author、published_date、text、latency_ms

# Fetch one page as markdown
tinyfish fetch content get --format markdown "https://example.com/article"

# Fetch multiple pages with links
tinyfish fetch content get --links "https://site-a.com" "https://site-b.com" "https://site-c.com"

---

tinyfish agent run

自然言語の目標を使ってブラウザーの自動化を実行します。エージェントは実際のブラウザーを開き、ページに移動し、クリックやフォームへの入力を行い、データを抽出します。

tinyfish agent run --url <url> "<goal>" [--sync] [--async] [--pretty]

フラグ	用途
--url <url>	対象 URL（ホスト名のみを指定すると、自動的に先頭へ https:// が追加されます）
--sync	ステップをストリーミングせず、結果が完全に返るまで待機します
--async	送信後、すぐに戻ります
--pretty	人が読みやすい形式で出力します

出力： デフォルトでは data: {...} 形式の SSE 行をストリーミングします。最終結果は、type == "COMPLETE" かつ status == "COMPLETED" のイベントです。抽出したデータは resultJson フィールドに含まれます。出力をそのまま読み取ってください。スクリプト側での解析は不要です。

目標には、必要な JSON 構造を必ず指定してください：

tinyfish agent run --url "https://example.com/products" \
  "Extract all products as JSON array: [{\"name\": str, \"price\": str, \"url\": str}]"

tinyfish agent run --url "https://example.com/search" \
  "Search for 'wireless headphones', filter under $50, extract top 5 as JSON: [{\"name\": str, \"price\": str, \"rating\": str}]"

並列抽出 — 複数の独立したサイトにアクセスする場合は、個別に呼び出してください。1 つの目標にまとめないでください。

適切 — 並列呼び出し（同時に実行）：

tinyfish agent run --url "https://pizzahut.com" \
  "Extract pizza prices as JSON: [{\"name\": str, \"price\": str}]"

tinyfish agent run --url "https://dominos.com" \
  "Extract pizza prices as JSON: [{\"name\": str, \"price\": str}]"

不適切 — 1 つにまとめた呼び出し：

# Don't do this — less reliable and slower
tinyfish agent run --url "https://pizzahut.com" \
  "Extract prices from Pizza Hut and also go to Dominos..."

実行の管理：

tinyfish agent run list [--status PENDING|RUNNING|COMPLETED|FAILED|CANCELLED] [--limit N]
tinyfish agent run get <run_id>
tinyfish agent run cancel <run_id>

バッチ操作 — CSV ファイル（url,goal 列）から複数の実行を送信します：

tinyfish agent batch run --input runs.csv
tinyfish agent batch list
tinyfish agent batch get <batch_id>
tinyfish agent batch cancel <batch_id>

---

tinyfish browser session create

リモートブラウザーのインスタンスを起動します。プログラムから操作するための CDP WebSocket URL を返します。

tinyfish browser session create [--url <url>] [--proxy-country <code> | --proxy-url <url> [--proxy-username <user>] | --no-proxy] [--pretty]

• --url を指定すると、作成後にページへ移動します（任意）
• session_id、cdp_url（WebSocket）、base_url を返します
• cdp_url は、Playwright、Puppeteer、または任意の CDP クライアントで使用します
• デフォルトでは、通信は米国内の TinyFish プロキシを経由し、セッション全体で同じ IP を使用します
• --proxy-country <code> を指定すると、別の出口国を選択できます（ISO 3166-1 alpha-2。例：DE、JP）
• --proxy-url <url> を指定すると、ユーザー独自の HTTP(S) プロキシ経由で接続します。認証には --proxy-username <user> を指定し、パスワードは TINYFISH_PROXY_PASSWORD 環境変数で渡します（フラグとして指定しないでください）
• --no-proxy を指定すると、プロキシを使わずに直接接続します

tinyfish browser session create --url "https://example.com"
# Returns: { session_id, cdp_url: "wss://...", base_url: "https://..." }

tinyfish browser session create --url "https://example.de" --proxy-country DE

---

全般的な注意事項

• ユーザーの言語に合わせてください：ユーザーが使用する言語で応答します。
• すべてのコマンドで、人が読みやすい形式にする --pretty を使用できます。デフォルトは JSON です。
• ルートコマンドに --debug を指定するか、TINYFISH_DEBUG=1 を設定すると、HTTP リクエストを stderr に記録します。