Thunderbit Open API home page
SupportAPI Console
Get Started

Skills + CLI

Run Thunderbit from the terminal — distill pages into Markdown, extract structured data, suggest fields, and batch-process URLs in bulk (max 100 distill / 50 extract). The CLI works standalone or as a skills toolkit AI coding agents can discover.

Distill, extract, suggest fields, and run batch jobs directly from the terminal.

Installation

The CLI publishes to npm as @thunderbit/thunderbit-cli and exposes a thunderbit binary on your PATH.

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

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

A Python (pip install thunderbit) flavour with the same command surface is on the roadmap.

Authentication

Before using the CLI, you need to authenticate with your Thunderbit API key. Get a key at Thunderbit Dashboard. Format: tb_ followed by 32 hex chars.

Set via environment variable

export THUNDERBIT_API_KEY=tb_YOUR_API_KEY

Pass per command

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

Self-Hosted / Local Development

For self-hosted Thunderbit gateways, override the 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

Check version

thunderbit --version
# or
thunderbit -V

Global Options

These flags are available for every command:

OptionDescription
--api-key <key>, -kAPI key (or set THUNDERBIT_API_KEY)
--base-url <url>API base URL (or set THUNDERBIT_API_BASE_URL)
--format <format>, -fOutput format: json, table, or markdown (default json)
--version, -VPrint CLI version
--help, -hShow command help

Commands

Distill

Distill a single URL into clean, LLM-ready 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 Options

# 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

Available Options:

OptionDefaultDescription
--render-mode <mode>nonenone, basic, or full
--timeout <ms>30000Per-page request timeout in ms
--country-code <CC>USISO 2-letter code, uppercase
--syncfalseUse sync mode instead of async submit + poll

Extract

Extract structured data from a page. The schema is a flat map of fieldName → natural-language instruction — each value is a hint the AI uses to find the field on the page.

Note: the upstream OpenAPI spec example shows JSON Schema ({type:"object",properties:…}). At time of writing the live server expects the flat instruction map shown below; we're aligning the spec.

# Inline schema — flat map of field → instruction
thunderbit extract https://example.com/product \
  --schema '{"name":"product name","price":"the listed price as a number","currency":"3-letter currency code"}'

# Schema from file
thunderbit extract https://example.com/product --schema ./schema.json

# Save the extracted JSON
thunderbit extract https://example.com/product --schema ./schema.json --format json -o data.json

The response always returns data.data as an array, one element per page region matching your schema:

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