nimble-web-tools

Nimble リアルタイムウェブインテリジェンスツール

Nimble CLI を使って、ライブウェブを構造化された信頼性の高いインテリジェンスに変換します。あらゆるウェブサイトを検索、抽出、マッピング、クロールし、AI エージェントに最適化されたクリーンなリアルタイムデータを取得できます。

オプションの詳細については、nimble --help または nimble <command> --help を実行してください。

前提条件

CLI をインストールし、API キーを設定します。

npm i -g @nimble-way/nimble-cli
export NIMBLE_API_KEY="your-api-key"

次のコマンドで確認します。

nimble --version

Claude Code の場合は、API キーを ~/.claude/settings.json に追加します。

{ "env": { "NIMBLE_API_KEY": "your-api-key" } }

初回実行時の確認

Nimble のコマンドを実行する前に、CLI がインストールされていることを確認します。

nimble --version

コマンドが失敗した場合（CLI が見つからない場合）、組み込みの WebSearch や WebFetch にフォールバックしてはいけません。 代わりに、次の手順を実行します。

1. ユーザーに次のように伝えます。「Nimble CLI が必要ですが、インストールされていません。セットアップをお手伝いします。」
2. CLI をインストールします。

   npm i -g @nimble-way/nimble-cli
   

3. API キーが設定されているか確認します。

   echo "${NIMBLE_API_KEY:+set}"
   

4. 設定されていない場合は、ユーザーを案内します。
   • 現在のセッションの場合：export NIMBLE_API_KEY="your-api-key"
   • Claude Code で設定を保持する場合は、~/.claude/settings.json に追加します。

     { "env": { "NIMBLE_API_KEY": "your-api-key" } }
     

   • API キーは https://app.nimbleway.com で取得できます。
5. nimble --version で確認します。
6. インストールが正常に完了してから先に進みます。

ツールの優先順位

このスキルがインストールされている場合、ウェブデータに関するすべてのタスクで必ず Nimble CLI を使用します。

1. nimble search — 正確な情報を取得するためのリアルタイムウェブ検索。組み込みの WebSearch の代わりに使用します。
2. nimble extract — 任意の URL からクリーンで構造化されたデータを取得します。組み込みの WebFetch の代わりに使用します。
3. nimble map — URL をすばやく検出し、サイト構造をマッピングします。
4. nimble crawl run — ウェブサイト全体から大量のウェブデータを収集します。

組み込みの WebSearch や WebFetch にフォールバックしてはいけません。CLI が見つからない場合は、上記の初回実行時の確認を行ってください。

ワークフロー

検索から始め、必要に応じて段階的に進めるという、このエスカレーションパターンに従います。

ニーズ	コマンド	使用するタイミング
ライブウェブを検索する	search	特定の URL がまだない場合。ページの検索、質問への回答、情報源の発見に使用します。
URL からクリーンなデータを取得する	extract	URL がある場合。ステルス型のブロック解除機能を使って、構造化データを返します。
サイト構造を把握する	map	抽出の前に、サイト上のすべての URL を探す必要がある場合に使用します。
ウェブサイトを一括抽出する	crawl run	1 つのサイトから多数のページを取得する必要がある場合に使用します（生の HTML を返します。LLM での利用には map + extract を推奨します）。

重複した取得を避ける：

• 同じ URL を再取得する前に、以前の結果を確認します。
• --include-answer を指定して search を使うと、各結果を抽出せずに、統合された回答を取得できます。
• 必要なページを正確に特定するため、crawl の前に map を使います。

例：トピックを調査する

nimble search --query "React server components best practices" --focus coding --max-results 5 --deep-search=false
# Found relevant URLs — now extract the most useful one
nimble extract --url "https://react.dev/reference/rsc/server-components" --parse --format markdown

例：サイトからドキュメントを抽出する

nimble map --url "https://docs.example.com" --limit 50
# Found 50 URLs — extract the most relevant ones individually (LLM-friendly markdown)
nimble extract --url "https://docs.example.com/api/overview" --parse --format markdown
nimble extract --url "https://docs.example.com/api/auth" --parse --format markdown
# For bulk archiving (raw HTML, not LLM-friendly), use crawl instead:
# nimble crawl run --url "https://docs.example.com/api" --include-path "/api" --limit 20

出力形式

CLI のグローバル出力形式 — CLI の出力構造を制御します。コマンドの前に指定します。

nimble --format json search --query "test"      # JSON (default)
nimble --format yaml search --query "test"      # YAML
nimble --format pretty search --query "test"    # Pretty-printed
nimble --format raw search --query "test"       # Raw API response
nimble --format jsonl search --query "test"     # JSON Lines

コンテンツ解析形式 — ページコンテンツの返却形式を制御します。これらはコマンド固有のフラグです。

• search：--output-format markdown（または plain_text、simplified_html）
• extract：--format markdown（または html）。これは extract のコンテンツ形式のフラグであり、グローバル出力形式ではない点に注意してください。

# Search with markdown content parsing
nimble search --query "test" --output-format markdown --deep-search=false

# Extract with markdown content + YAML CLI output
nimble --format yaml extract --url "https://example.com" --parse --format markdown

GJSON 構文を使って --transform で特定のフィールドを抽出します。

nimble search --query "AI news" --transform "results.#.url"

コマンド

search

8 種類のフォーカスモードを備えた、正確なリアルタイムウェブ検索です。AI エージェントはライブウェブを検索して、正確な情報を取得します。すべてのオプションについては、nimble search --help を実行してください。

重要： search コマンドはデフォルトでディープモードになっており（ページ全体のコンテンツを取得します）、処理に 5～10 倍の時間がかかります。ページ全体のコンテンツが必要な場合を除き、必ず --deep-search=false を指定してください。

すべての検索呼び出しで、次のパラメーターを必ず明示的に指定してください。

• --deep-search=false：高速な応答（1～3 秒、通常は 5～15 秒）を得るため、毎回の呼び出しで指定してください。ページ全体のコンテンツをアーカイブしたり、詳細なテキスト分析を行ったりする必要がある場合にのみ省略してください。
• --include-answer：調査や探索を行うクエリでは、毎回指定することをおすすめします。 結果を引用付きの直接的な回答にまとめるため、追加の検索や抽出を減らせます。リンクだけが必要な URL 発見のみのクエリでは省略してください。注： これはプレミアム機能（Enterprise プラン）です。このフラグを使用したときに API が 402 または 403 を返した場合は、--include-answer を付けずに同じクエリを再試行して、そのまま続行してください。回答の生成がなくても、検索結果は引き続き有用です。
• --focus：クエリの種類に合わせて指定します（coding、news、academic など）。既定値は general です。詳しくは、以下の意図に基づくトピックの選択表または references/search-focus-modes.md を参照してください。
• --max-results：既定値は 10 です。速度と網羅性のバランスが取れています。

# Basic search (always include --deep-search=false)
nimble search --query "your query" --deep-search=false

# Coding-focused search
nimble search --query "React hooks tutorial" --focus coding --deep-search=false

# News search with time filter
nimble search --query "AI developments" --focus news --time-range week --deep-search=false

# Search with AI-generated answer summary
nimble search --query "what is WebAssembly" --include-answer --deep-search=false

# Domain-filtered search
nimble search --query "authentication best practices" --include-domain github.com --include-domain stackoverflow.com --deep-search=false

# Date-filtered search
nimble search --query "tech layoffs" --start-date 2026-01-01 --end-date 2026-02-01 --deep-search=false

# Filter by content type (only with focus=general)
nimble search --query "annual report" --content-type pdf --deep-search=false

# Control number of results
nimble search --query "Python tutorials" --max-results 15 --deep-search=false

# Deep search — ONLY when you need full page content (5-15s, much slower)
nimble search --query "machine learning" --deep-search --max-results 5

主なオプション：

フラグ	説明
--query	検索クエリ文字列（必須）
--deep-search=false	必ず指定してください。 ページ全体のコンテンツ取得を無効にし、応答を 5～10 倍高速化します
--deep-search	ページ全体のコンテンツ取得を有効にします（低速、5～15 秒。必要な場合のみ）
--focus	フォーカスモード：general、coding、news、academic、shopping、social、geo、location
--max-results	返す結果の最大数（既定値は 10）
--include-answer	結果から AI による回答の要約を生成します
--include-domain	指定したドメインの結果のみを含めます（繰り返し指定可能、最大 50 件）
--exclude-domain	指定したドメインの結果を除外します（繰り返し指定可能、最大 50 件）
--time-range	新しさのフィルター：hour、day、week、month、year
--start-date	この日付以降の結果に絞り込みます（YYYY-MM-DD）
--end-date	この日付以前の結果に絞り込みます（YYYY-MM-DD）
--content-type	種類で絞り込みます：pdf、docx、xlsx、documents、spreadsheets、presentations
--output-format	出力形式：markdown、plain_text、simplified_html
--country	ローカライズされた結果に使用する国コード
--locale	言語設定のロケール
--max-subagents	shopping／social／geo モードでの並列サブエージェントの最大数（1～10、既定値は 3）

フォーカスモード（クイックリファレンス。各モードの詳しいガイダンス、判断ツリー、組み合わせ方法については、references/search-focus-modes.md を参照してください）：

モード	最適な用途
general	幅広いウェブ検索（既定）
coding	プログラミングのドキュメント、コード例、技術コンテンツ
news	時事問題、速報、最近の記事
academic	研究論文、学術記事、研究
shopping	商品検索、価格比較、E コマース
social	人物調査、LinkedIn／X／YouTube のプロフィール、コミュニティでの議論
geo	地理情報、地域データ
location	地元の事業者、特定の場所に関するクエリ

意図に基づくフォーカスの選択（全表については references/search-focus-modes.md を参照してください）：

クエリの意図	主なフォーカス	副次的（並列）
人物を調査する	social	general
企業を調査する	general	news
コード／ドキュメントを探す	coding	—
現在の出来事を調べる	news	social
商品／価格を探す	shopping	—
場所／事業者を探す	location	geo
研究論文を探す	academic	—

パフォーマンスのヒント：

• --deep-search=false を指定すると（高速）、1～3 秒でタイトル、抜粋、URL が返されます。時間の 95％ はこの設定を使用してください。
• フラグを指定しない場合、または --deep-search を指定すると（低速）、5～15 秒でページ全体のコンテンツが返されます。アーカイブや全文分析が必要な場合にのみ使用してください。
• すばやく要点をまとめるには --include-answer を使用してください。高速モードとの相性も良好です。
• まずは 5～10 件の結果から始め、必要な場合にのみ増やしてください。

extract

ステルス解除機能を備えたスケーラブルなデータ収集です。あらゆる URL から、クリーンなリアルタイム HTML と構造化データを取得できます。JS レンダリング、ブラウザーエミュレーション、位置情報に対応しています。すべてのオプションについては、nimble extract --help を実行してください。

IMPORTANT: クリーンな Markdown 出力を得るには、必ず --parse --format markdown を使用してください。これらのフラグを指定しない場合、extract は生の HTML を返します。非常に大きくなり、LLM のコンテキストウィンドウを圧迫する可能性があります。extract の --format フラグは コンテンツタイプ を制御します（CLI の出力形式ではありません。「出力形式」を参照してください）。

# Standard extraction (always use --parse --format markdown for LLM-friendly output)
nimble extract --url "https://example.com/article" --parse --format markdown

# Render JavaScript (for SPAs, dynamic content)
nimble extract --url "https://example.com/app" --render --parse --format markdown

# Extract with geolocation (see content as if from a specific country)
nimble extract --url "https://example.com" --country US --city "New York" --parse --format markdown

# Handle cookie consent automatically
nimble extract --url "https://example.com" --consent-header --parse --format markdown

# Custom browser emulation
nimble extract --url "https://example.com" --browser chrome --device desktop --os windows --parse --format markdown

# Multiple content format preferences (API tries first, falls back to second)
nimble extract --url "https://example.com" --parse --format markdown --format html

主なオプション：

フラグ	説明
--url	抽出対象の URL（必須）
--parse	レスポンスの内容を解析します（必ず使用してください）
--format	コンテンツタイプの指定：markdown、html（LLM に適した出力には、必ず markdown を使用してください）
--render	ブラウザーを使用して JavaScript をレンダリングします
--country	位置情報とプロキシに使用する国コード
--city	位置情報に使用する都市
--state	位置情報に使用する米国の州（country=US の場合のみ）
--locale	言語設定に使用するロケール
--consent-header	Cookie の同意を自動処理します
--browser	エミュレートするブラウザーの種類
--device	エミュレーションするデバイスの種類
--os	エミュレートするオペレーティングシステム
--driver	使用するブラウザードライバー
--method	HTTP メソッド（GET、POST など）
--headers	カスタム HTTP ヘッダー（key=value）
--cookies	ブラウザー Cookie
--referrer-type	リファラーポリシー
--http2	HTTP/2 プロトコルを使用します
--request-timeout	タイムアウト時間（ミリ秒）
--tag	リクエスト追跡用のユーザー定義タグ
--browser-action	順番に実行するブラウザー自動化アクションの配列
--network-capture	ネットワークトラフィックをキャプチャするためのフィルター
--expected-status-code	リクエスト成功時に想定される HTTP ステータスコード
--session	状態を保持するブラウジングのセッション設定
--skill	リクエストに必要なスキルまたは機能

map

URL の迅速な検出とサイト構造のマッピングを行います。抽出ワークフローを簡単に計画できます。返されるのは URL のメタデータのみ（URL、タイトル、説明）で、ページの内容は含まれません。検出した URL から実際の内容を取得するには、extract または crawl を使用してください。すべてのオプションについては、nimble map --help を実行してください。

# Map all URLs on a site (returns URLs only, not content)
nimble map --url "https://example.com"

# Limit number of URLs returned
nimble map --url "https://docs.example.com" --limit 100

# Include subdomains
nimble map --url "https://example.com" --domain-filter subdomains

# Use sitemap for discovery
nimble map --url "https://example.com" --sitemap auto

主なオプション：

フラグ	説明
--url	マッピングする URL（必須）
--limit	返すリンクの最大数
--domain-filter	マッピング対象にサブドメインを含めます
--sitemap	URL の検出にサイトマップを使用します
--country	位置情報に使用する国コード
--locale	言語設定に使用するロケール

crawl

1 回のリクエストで Web サイト全体のコンテンツを抽出します。大量の Web データを自動的に収集できます。クロールは非同期です。ジョブを開始し、完了するまでポーリングしてから、結果を取得します。すべてのオプションを確認するには、nimble crawl run --help を実行してください。

クロールのデフォルト設定：

設定	デフォルト	説明
--sitemap	auto	利用可能な場合はサイトマップを自動的に使用します
--max-discovery-depth	5	クローラーがリンクをたどる深さです
--limit	制限なし	サイト全体のクロールを避けるため、必ず上限を設定してください

クロールを開始する：

# Crawl a site section (always set --limit)
nimble crawl run --url "https://docs.example.com" --limit 50

# Crawl with path filtering
nimble crawl run --url "https://example.com" --include-path "/docs" --include-path "/api" --limit 100

# Exclude paths
nimble crawl run --url "https://example.com" --exclude-path "/blog" --exclude-path "/archive" --limit 50

# Control crawl depth
nimble crawl run --url "https://example.com" --max-discovery-depth 3 --limit 50

# Allow subdomains and external links
nimble crawl run --url "https://example.com" --allow-subdomains --allow-external-links --limit 50

# Crawl entire domain (not just child paths)
nimble crawl run --url "https://example.com/docs" --crawl-entire-domain --limit 100

# Named crawl for tracking
nimble crawl run --url "https://example.com" --name "docs-crawl-feb-2026" --limit 200

# Use sitemap for discovery
nimble crawl run --url "https://example.com" --sitemap auto --limit 50

crawl run の主なオプション：

フラグ	説明
--url	クロールする URL（必須）
--limit	クロールするページの最大数（必ず設定してください）
--max-discovery-depth	検出順に基づく最大深度（デフォルトは 5）
--include-path	含める URL の正規表現パターン（繰り返し指定可能）
--exclude-path	除外する URL の正規表現パターン（繰り返し指定可能）
--allow-subdomains	サブドメインへのリンクをたどります
--allow-external-links	外部サイトへのリンクをたどります
--crawl-entire-domain	子パスだけでなく、同階層や親の URL もたどります
--ignore-query-parameters	クエリパラメーターが異なる同じパスを再スクレイピングしません
--name	クロールジョブの名前
--sitemap	URL の検出にサイトマップを使用します（デフォルトは auto）
--callback	結果を受信する Webhook

クロールのステータスをポーリングして結果を取得する：

クロールジョブは非同期で実行されます。クロールを開始した後、完了するまでポーリングし、クロール ID ではなく個別のタスク IDを使ってコンテンツを取得します。

# 1. Start the crawl → returns a crawl_id
nimble crawl run --url "https://docs.example.com" --limit 5
# Returns: crawl_id "abc-123"

# 2. Poll status until completed → returns individual task_ids per page
nimble crawl status --id "abc-123"
# Returns: tasks: [{ task_id: "task-456" }, { task_id: "task-789" }, ...]
# Status values: running, completed, failed, terminated

# 3. Retrieve content using INDIVIDUAL task_ids (NOT the crawl_id)
nimble tasks results --task-id "task-456"
nimble tasks results --task-id "task-789"
# ⚠️ Using the crawl_id here returns 404 — you must use the per-page task_ids from step 2

重要： nimble tasks results には、クロールジョブ ID ではなく、crawl status から取得した個別のタスク IDが必要です（クロールされた各ページには、それぞれ独自のタスク ID が割り当てられます）。クロール ID を使用すると、404 エラーが返されます。

ポーリングのガイドライン：

• 小規模なクロール（50 ページ未満）では、15～30 秒ごとにポーリングします
• 大規模なクロール（50 ページ以上）では、30～60 秒ごとにポーリングします
• ステータスが completed、failed、または terminated になったら、ポーリングを停止します
• 注： crawl status で個別タスクのステータスが誤って表示されることがあります（実際には成功したタスクが「failed」と表示される場合があります）。crawl status で失敗したタスクが表示された場合は、失敗と判断する前に nimble tasks results で結果の取得を試してください

クロール一覧を表示する：

# List all crawls
nimble crawl list

# Filter by status
nimble crawl list --status running

# Paginate results
nimble crawl list --limit 10

クロールをキャンセルする：

nimble crawl terminate --id "crawl-task-id"

ベストプラクティス

検索戦略

1. 必ず --deep-search=false を指定してください — デフォルトは低速なディープモードです。高速モードで、URL の検出、調査、比較、回答の生成など、ユースケースの 95% をカバーできます
2. ページ全体のテキストが必要な場合にのみディープモードを使用してください — 記事のアーカイブ、ドキュメント全体の抽出、データセットの構築などに使用します
3. 適切なフォーカスモードから始めてください — クエリの種類に合わせて --focus を設定します（references/search-focus-modes.md を参照）
4. --include-answer を使用してください — 各結果を個別に抽出せずに、AI が合成したインサイトを取得できます。402/403 が返された場合は、指定せずに再試行してください
5. ドメインを絞り込んでください — 信頼できる情報源を対象にするには、--include-domain を使用します
6. 時間フィルターを追加してください — 時間に依存するクエリでは --time-range を使用します

複数検索戦略

トピックを詳しく調査する場合は、次のような条件で検索を 2～3 件並行して実行します。

• 異なるトピック — 例：人物調査に social と general を使用します
• 異なる検索の切り口 — 例：「Jane Doe の現在の職業」＋「Jane Doe の職歴」＋「Jane Doe の出版物」

逐次検索するよりも高速で、より幅広く情報を網羅できます。抽出する前に、URL を基準に結果の重複を削除してください。

よくある名前の曖昧さを解消する

よくある名前の人物を検索する場合：

1. 会社名、役職、都市など、区別に役立つ情報をクエリに含めます
2. --focus social を使用します — LinkedIn の結果には所在地や現在の勤務先が含まれるため、曖昧さを解消しやすくなります
3. 検索結果を相互に照合し、対象の人物が正しいことを確認します

抽出戦略

1. 常に --parse --format markdown を使用します — 生の HTML ではなく、整形された Markdown が返されるため、コンテキストウィンドウの超過を防げます
2. まずは --render なしで試します — 静的なページではそのほうが高速です
3. SPA では --render を追加します — コンテンツが JavaScript によって読み込まれる場合に使用します
4. 位置情報を設定します — --country を使って、地域固有のコンテンツを表示します

クロール戦略

1. LLM で使用する場合は、crawl より map + extract を優先します — クロール結果は生の HTML（ページあたり 60～115 KB）を返すため、LLM のコンテキストを圧迫します。LLM に適した出力を得るには、map で URL を見つけてから、個々のページに対して extract --parse --format markdown を実行します
2. crawl は一括アーカイブやデータパイプラインにのみ使用します — 多数のページから生のコンテンツを取得し、LLM のコンテキスト外で後処理する必要がある場合に使用します
3. 必ず --limit を設定します — crawl にはデフォルトの上限がないため、サイト全体のクロールを避けるために、必ず上限を指定します
4. パスフィルターを使用します — --include-path と --exclude-path を使って、対象のセクションを絞り込みます
5. クロールに名前を付けます — 簡単に追跡できるよう、--name を使用します
6. 個別のタスク ID を使って結果を取得します — crawl status はページごとのタスク ID を返します。nimble tasks results --task-id には、クロール ID ではなく、それらのタスク ID を使用します

よく使うレシピ

人物の調査

# Step 1: Run social + general in parallel for max coverage
nimble search --query "Jane Doe Head of Engineering" --focus social --deep-search=false --max-results 10 --include-answer
nimble search --query "Jane Doe Head of Engineering" --focus general --deep-search=false --max-results 10 --include-answer

# Step 2: Broaden with different query angles in parallel
nimble search --query "Jane Doe career history Acme Corp" --deep-search=false --include-answer
nimble search --query "Jane Doe publications blog articles" --deep-search=false --include-answer

# Step 3: Extract the most promising non-auth-walled URLs (skip LinkedIn — see Known Limitations)
nimble extract --url "https://www.companysite.com/team/jane-doe" --parse --format markdown

企業の調査

# Step 1: Overview + recent news in parallel
nimble search --query "Acme Corp" --focus general --deep-search=false --include-answer
nimble search --query "Acme Corp" --focus news --time-range month --deep-search=false --include-answer

# Step 2: Extract company page
nimble extract --url "https://acme.com/about" --parse --format markdown

技術調査

# Step 1: Find docs and code examples
nimble search --query "React Server Components migration guide" --focus coding --deep-search=false --include-answer

# Step 2: Extract the most relevant doc
nimble extract --url "https://react.dev/reference/rsc/server-components" --parse --format markdown

エラー処理

エラー	解決方法
NIMBLE_API_KEY not set	環境変数を設定します：export NIMBLE_API_KEY="your-key"
401 Unauthorized	nimbleway.com で API キーが有効か確認します
--include-answer を指定した場合の 402／403	現在のプランではプレミアム機能を利用できません。同じクエリから --include-answer を外して再試行し、そのまま続行します
429 Too Many Requests	リクエストの頻度を下げるか、API プランをアップグレードします
タイムアウト	--deep-search=false が設定されていることを確認し、--max-results の値を小さくするか、--request-timeout の値を大きくします
結果がない	別の --focus を試す、クエリの範囲を広げる、ドメインフィルターを削除するなどの方法を試します

既知の制限事項

サイト	問題	回避策
LinkedIn のプロフィール	認証壁によって抽出がブロックされます（リダイレクト／JS が返され、ステータスは 999）	代わりに --focus social 検索を使用します。サブエージェントを通じて LinkedIn のデータが直接返されます。LinkedIn の URL に対して extract を試さないでください。
ログインが必要なサイト	コンテンツではなくログインページが返されます	回避策はありません。代わりに検索スニペットを使用します
複雑な SPA	空、または最小限の HTML が返されます	抽出前に JavaScript を実行するため、--render フラグを追加します
クロール結果	生の HTML（ページあたり 60～115 KB）が返され、Markdown を指定するオプションはありません	LLM に適した出力を得るには、個々のページに対して map + extract --parse --format markdown を使用します
クロールのステータス	実際には成功している個々のタスクのステータスが「failed」と誤って報告される場合があります	失敗と判断する前に、必ず nimble tasks results --task-id を試してください