Thunderbit Open API home page
支援API 主控台
開始使用

Skills + CLI

在終端機中執行 Thunderbit —— 把網頁蒸餾成 Markdown、擷取結構化資料、推薦欄位，以及批次處理最多 100 個 URL。CLI 可獨立使用，也可作為 AI 編碼 Agent 能發現的 skills 工具集。

直接在終端機中進行蒸餾、擷取、欄位推薦與批次任務。

安裝

CLI 在 npm 上發行為 @thunderbit/thunderbit-cli，並在你的 PATH 中暴露 thunderbit 執行檔。

# Install globally
npm install -g @thunderbit/thunderbit-cli

# Or run one-shot via npx
npx -y @thunderbit/thunderbit-cli --help

同款指令面的 Python 版本（pip install thunderbit）已列入路線圖。

認證

使用 CLI 前，需要用 Thunderbit API key 完成認證。請至 app.thunderbit.com/console 取得 key。格式：tb_ 後接 32 位十六進位字元。

透過環境變數設定

export THUNDERBIT_API_KEY=tb_YOUR_API_KEY

單次指令傳入

thunderbit --api-key tb_YOUR_API_KEY distill https://example.com

自架 / 本地開發

對自架的 Thunderbit 閘道，請覆寫 base URL：

# Per call
thunderbit --base-url https://api.your-domain.com distill https://example.com

# Or set via environment variable
export THUNDERBIT_API_BASE_URL=https://api.your-domain.com
thunderbit distill https://example.com

查看版本

thunderbit --version
# or
thunderbit -V

全域選項

下列 flag 對所有指令通用：

選項說明
--api-key <key>, -kAPI key（或設定 THUNDERBIT_API_KEY）
--base-url <url>API base URL（或設定 THUNDERBIT_API_BASE_URL）
--format <format>, -f輸出格式：json、table 或 markdown（預設 json）
--version, -V印出 CLI 版本
--help, -h顯示指令說明

指令

Distill

把單一 URL 蒸餾成乾淨、適合 LLM 的 Markdown。

# Basic usage
thunderbit distill https://example.com/article

# Stream Markdown to stdout
thunderbit distill https://example.com --format markdown

# Save to file
thunderbit distill https://example.com --format markdown > article.md

Distill 選項

# Use the basic JS renderer (covers most modern sites)
thunderbit distill https://example.com --render-mode basic

# Use the full headless browser (slowest, highest fidelity)
thunderbit distill https://example.com --render-mode full

# Geo-target for region-aware sites
thunderbit distill https://example.com --country-code DE

# Bump per-page timeout
thunderbit distill https://example.com --timeout 60000

# Use sync /distill instead of the default async submit + poll
thunderbit distill https://example.com --sync

可用選項：

選項預設值說明
--render-mode <mode>nonenone、basic 或 full
--timeout <ms>30000每頁請求逾時（毫秒）
--country-code <CC>USISO 兩位國碼，大寫
--syncfalse使用同步模式而非預設的非同步送出 + 輪詢

Extract

從網頁擷取結構化資料。schema 是 欄位名 → 自然語言指令 的扁平映射 —— 每個值都是 AI 在頁面上定位該欄位的提示。

註：上游 OpenAPI 規範範例展示的是 JSON Schema ({type:"object",properties:…})。撰寫本文時線上伺服器期望下方所示的扁平指令映射，我們正在對齊規範。

# 內嵌 schema —— 欄位 → 指令的扁平映射
thunderbit extract https://example.com/product \
  --schema '{"name":"product name","price":"the listed price as a number","currency":"3-letter currency code"}'

# 從檔案讀取 schema
thunderbit extract https://example.com/product --schema ./schema.json

# 儲存擷取出來的 JSON
thunderbit extract https://example.com/product --schema ./schema.json --format json -o data.json

回應一律把 data.data 以陣列回傳，與 schema 相符的每個頁面區塊各對應一個元素：

{
  "success": true,
  "data": {
    "url": "https://example.com/product",
    "data": [
      { "name": "iPhone 15 Pro", "price": 999, "currency": "USD" }
    ]
  }
}

互動模式

# AI proposes fields, you toggle/edit, then extraction runs with the curated schema
thunderbit extract https://example.com/product --interactive

# Steer the suggestion with a prompt
thunderbit extract https://example.com/product -i --prompt "focus on pricing and availability"

# Persist the schema for reuse
thunderbit extract https://example.com/product -i --save-schema ./product-schema.json

Extract 選項

# Bump page-render time for SPAs
thunderbit extract https://example.com --schema ./schema.json --render-mode full

# Sync mode
thunderbit extract https://example.com --schema ./schema.json --sync

# Longer timeout for complex pages
thunderbit extract https://example.com --schema ./schema.json --timeout 120000

可用選項：

選項預設值說明
--schema <json-or-file>—內嵌 JSON 或 schema 檔案路徑
--interactive, -ifalse一次完成 推薦 → 整理 → 擷取
--prompt <text>—AI 推薦的引導提示（搭配 -i）
--render-mode <mode>nonenone、basic 或 full
--timeout <ms>60000每頁請求逾時（毫秒）
--syncfalse同步模式
--save-schema <file>—儲存最終 schema 以便重用

Suggest Fields

在你寫 schema 前，先讓 AI 推薦可擷取的欄位。

# Basic
thunderbit suggest-fields https://example.com/product

# Steer with a prompt
thunderbit suggest-fields https://example.com/listings --prompt "extract job postings only"

# Region-aware
thunderbit suggest-fields https://example.com --country-code DE

互動式編輯器允許你按編號切換欄位（1 3 5）、add、rm 2、edit 4，最後輸入 done 確認。suggest-fields 會回傳 [{name, type, instruction}, …]；當你把它餵給 extract 時，請先轉成扁平映射：

thunderbit suggest-fields "$URL" --format json \
  | jq 'map({(.name): .instruction}) | add' > schema.json

thunderbit extract "$URL" --schema ./schema.json

可用選項：

選項預設值說明
--prompt <text>—引導提示
--country-code <CC>USISO 兩位國碼

Batch Distill

在一次批次任務中送出最多 100 個 URL。預設會送出並輪詢，直到 COMPLETED / FAILED / CANCELLED。

# URLs as positional args
thunderbit batch distill https://a.com https://b.com https://c.com

# Or read URLs from a file (one per line)
thunderbit batch distill --file urls.txt

# Submit only — print the job ID and exit (use webhook or poll later)
thunderbit batch distill --file urls.txt --no-poll

Batch Distill 選項

# Bump per-page timeout
thunderbit batch distill --file urls.txt --timeout 60000

# Pipe results into another tool
thunderbit batch distill --file urls.txt --format json \
  | jq -r '.data.results[] | select(.success == true) | .markdown' \
  > distilled.md

可用選項：

選項預設值說明
--file <path>—從檔案讀取 URL（每行一個）
--timeout <ms>30000每頁請求逾時（毫秒）
--no-pollfalse只送出，印出 job ID 並結束

取消執行中的批次 distill 任務

thunderbit batch cancel-distill <jobId>

已完成的頁面會保留結果。待處理的頁面會被丟棄，剩餘部分不再計費。伺服器確認後，狀態會切換為 CANCELLED。

Batch Extract

提交最多 100 個 URL，並使用一份共享 schema。

# URLs as positional args + inline schema
thunderbit batch extract https://a.com https://b.com \
  --schema ./schema.json

# Read URLs from a file
thunderbit batch extract --file urls.txt --schema ./schema.json

# Submit only
thunderbit batch extract --file urls.txt --schema ./schema.json --no-poll

可用選項：

選項預設值說明
--file <path>—從檔案讀取 URL（每行一個）
--schema <json-or-file>—內嵌 JSON 或 schema 檔案（必填）
--timeout <ms>60000每頁請求逾時（毫秒）
--no-pollfalse只送出，印出 job ID 並結束

取消執行中的批次 extract 任務

thunderbit batch cancel-extract <jobId>

語意與 cancel-distill 相同——已完成的列會保留，待處理的列會被丟棄，剩餘部分不再計費。

輸出處理

CLI 預設輸出到 stdout，方便管線或重新導向。

# Pipe Markdown into another tool
thunderbit distill https://example.com --format markdown | head -50

# Redirect to a file
thunderbit distill https://example.com --format markdown > output.md

# Save extraction JSON
thunderbit extract https://example.com --schema ./schema.json --format json > data.json

格式行為

  • --format json（預設）：完整 API 回應作為精簡 JSON 輸出，包含 success、data、creditsUsed 等。可接 jq。
  • --format markdown：distill 輸出原始 Markdown 內文；其他指令輸出完整 JSON。
  • --format table：表格化結果（extract、suggest-fields）以 ASCII 表格輸出。
# Markdown body straight to disk
thunderbit distill https://example.com --format markdown

# Full structured response
thunderbit distill https://example.com --format json

範例

快速 Distill

# Distill an article
thunderbit distill https://docs.thunderbit.com/introduction --format markdown

# Save HTML-converted Markdown to disk
thunderbit distill https://example.com --format markdown -o page.md

批次 RAG 資料匯入

# Distill a docs site listed in urls.txt and write each page to disk
thunderbit batch distill --file urls.txt --format json \
  | jq -r '.data.results[] | select(.success == true) | "\(.url)\t\(.markdown)"' \
  > corpus.tsv

先發現再擷取

# Step 1: AI proposes fields, you curate, schema saved to disk
thunderbit extract https://example.com/product -i --save-schema ./schema.json

# Step 2: re-use across the catalog
thunderbit batch extract --file urls.txt --schema ./schema.json --format json > products.json

CI 檢查門 —— 擷取結果為空就失敗

thunderbit extract "$URL" --schema ./schema.json --format json \
  | jq -e '.data | length > 0'

與其他工具搭配

# Extract URLs from a search-result JSON
thunderbit distill https://example.com --format json \
  | jq -r '.data.metadata.canonicalUrl'

# Pipe distilled content into a model for summarisation
thunderbit distill "$URL" --format markdown \
  | claude -p "summarise the article in 5 bullets"

# Count successful pages in a batch
thunderbit batch distill --file urls.txt --format json \
  | jq '[.data.results[] | select(.success == true)] | length'

結束碼

Code含義
0成功。結果以 --format 選擇的格式輸出到 stdout。
1任何失敗 —— 缺少 API key、認證錯誤、HTTP 4xx/5xx、網路錯誤、缺少 schema 檔案、缺少必要參數。

所有錯誤文字都寫到 stderr。失敗時 stdout 維持為空（即使搭配 --format json 也是如此）。意思是 jq 管線永遠不會收到半成品 envelope —— 解析前請先檢查結束碼（或使用 set -e）。

輪詢進度（例如 async submit + poll 的 Processing... (3)）也會寫到 stderr。可用 2>/dev/null 靜音。單頁同步呼叫（--sync）不會輸出進度。

故障排查

Error: API key is required。 請 export THUNDERBIT_API_KEY 或傳入 --api-key。

企業代理後的網路錯誤。 設定 HTTPS_PROXY 與 HTTP_PROXY —— Node 與 Python 客戶端皆會讀取。

批次輪詢很慢。 把 --timeout 調高，控制每頁預算。輪詢節奏本身固定為數秒一次，目前 CLI 無法調整。

開源

Thunderbit CLI 採用 MIT 授權開源，儲存庫在 GitHub：thunderbit-open/thunderbit-mcp-server（同一個儲存庫也包含 MCP 伺服器與 Claude Code 外掛）。npm 套件：@thunderbit/thunderbit-cli。

相關連結

  • MCP Server —— 同樣的能力，以 MCP 工具形式暴露
  • SDKs —— 在你自己的程式碼中呼叫
  • API Reference —— 原生 HTTP

目錄

安裝認證透過環境變數設定單次指令傳入自架 / 本地開發查看版本全域選項指令DistillDistill 選項Extract互動模式Extract 選項Suggest FieldsBatch DistillBatch Distill 選項取消執行中的批次 distill 任務Batch Extract取消執行中的批次 extract 任務輸出處理格式行為範例快速 Distill批次 RAG 資料匯入先發現再擷取CI 檢查門 —— 擷取結果為空就失敗與其他工具搭配結束碼故障排查開源相關連結