Skills + CLI

Use o Thunderbit a partir do terminal — destile páginas em Markdown, extraia dados estruturados, sugira campos e processe em lote até 100 URLs. A CLI funciona de forma autônoma ou como um toolkit de skills que agentes de codificação AI podem descobrir.

Destile, extraia, sugira campos e execute jobs em lote diretamente do terminal.

Instalação

A CLI é publicada no npm como @thunderbit/thunderbit-cli e expõe um binário thunderbit no seu PATH.

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

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

Uma versão Python (pip install thunderbit) com a mesma interface de comandos está no roadmap.

Autenticação

Antes de usar a CLI, você precisa autenticar com sua API key do Thunderbit. Obtenha uma key no Thunderbit Dashboard. Formato: tb_ seguido de 32 caracteres hex.

Definir via variável de ambiente

export THUNDERBIT_API_KEY=tb_YOUR_API_KEY

Passar por comando

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

Auto-hospedado / Desenvolvimento local

Para gateways Thunderbit auto-hospedados, sobrescreva a 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

Verificar versão

thunderbit --version
# or
thunderbit -V

Opções globais

Estas flags estão disponíveis para cada comando:

Opção	Descrição
`--api-key <key>`, `-k`	API key (ou definir `THUNDERBIT_API_KEY`)
`--base-url <url>`	URL base da API (ou definir `THUNDERBIT_API_BASE_URL`)
`--format <format>`, `-f`	Formato de saída: `json`, `table` ou `markdown` (padrão `json`)
`--version`, `-V`	Imprimir versão da CLI
`--help`, `-h`	Mostrar ajuda do comando

Comandos

Distill

Destile uma única URL em Markdown limpo, pronto para LLM.

# 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

Opções de 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

Opções disponíveis:

Opção	Padrão	Descrição
`--render-mode <mode>`	`none`	`none`, `basic` ou `full`
`--timeout <ms>`	`30000`	Timeout da requisição por página em ms
`--country-code <CC>`	`US`	Código ISO de 2 letras, em maiúsculas
`--sync`	`false`	Usar modo sync em vez de async submit + poll

Extract

Extraia dados estruturados de uma página. O schema é um mapa plano de fieldName → instrução em linguagem natural — cada valor é uma dica que a AI usa para encontrar o campo na página.

Nota: o exemplo da spec OpenAPI upstream mostra JSON Schema ({type:"object",properties:…}). No momento da escrita, o servidor em produção espera o mapa plano de instruções mostrado abaixo; estamos alinhando a spec.

# Schema inline — mapa plano de campo → instrução
thunderbit extract https://example.com/product \
  --schema '{"name":"product name","price":"the listed price as a number","currency":"3-letter currency code"}'

# Schema a partir de arquivo
thunderbit extract https://example.com/product --schema ./schema.json

# Salvar o JSON extraído
thunderbit extract https://example.com/product --schema ./schema.json --format json -o data.json

A resposta sempre retorna data.data como um array, um elemento por região da página que corresponda ao seu schema:

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

Modo interativo

# 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

Opções de 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

Opções disponíveis:

Opção	Padrão	Descrição
`--schema <json-or-file>`	—	JSON inline ou caminho para arquivo de schema
`--interactive`, `-i`	`false`	Sugerir → curar → extrair em uma só etapa
`--prompt <text>`	—	Dica para sugestão da AI (com `-i`)
`--render-mode <mode>`	`none`	`none`, `basic` ou `full`
`--timeout <ms>`	`60000`	Timeout da requisição por página em ms
`--sync`	`false`	Modo sync
`--save-schema <file>`	—	Persistir o schema final para reuso

Suggest Fields

Deixe a AI propor campos extraíveis antes de você escrever um schema.

# 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

O editor interativo permite alternar campos por número (1 3 5), add, rm 2, edit 4, e então done para confirmar. suggest-fields retorna [{name, type, instruction}, …]; quando você passa isso para o extract, transforme primeiro em um mapa plano:

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

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

Opções disponíveis:

Opção	Padrão	Descrição
`--prompt <text>`	—	Dica de orientação
`--country-code <CC>`	`US`	Código ISO de 2 letras

Batch Distill

Envie até 100 URLs em um único job em lote. Por padrão, faz submit + polling até 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

Opções de 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

Opções disponíveis:

Opção	Padrão	Descrição
`--file <path>`	—	Ler URLs de arquivo (uma por linha)
`--timeout <ms>`	`30000`	Timeout da requisição por página em ms
`--no-poll`	`false`	Apenas submeter, imprimir job ID, sair

Cancelar um job batch distill em execução

thunderbit batch cancel-distill <jobId>

As páginas já concluídas mantêm seus resultados. As páginas pendentes são descartadas e você deixa de ser cobrado por elas. O status muda para CANCELLED assim que o servidor confirma.

Batch Extract

Envie até 100 URLs com um schema compartilhado.

# 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

Opções disponíveis:

Opção	Padrão	Descrição
`--file <path>`	—	Ler URLs de arquivo (uma por linha)
`--schema <json-or-file>`	—	JSON inline ou arquivo de schema (obrigatório)
`--timeout <ms>`	`60000`	Timeout da requisição por página em ms
`--no-poll`	`false`	Apenas submeter, imprimir job ID, sair

Cancelar um job batch extract em execução

thunderbit batch cancel-extract <jobId>

Mesma semântica de cancel-distill — as linhas concluídas são preservadas, as pendentes são descartadas, e a cobrança é interrompida para o restante.

Tratamento da saída

A CLI escreve no stdout por padrão, facilitando pipes ou redirecionamentos.

# 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

Comportamento do formato

--format json (padrão): resposta completa da API como JSON compacto, incluindo success, data, creditsUsed, etc. Faça pipe para jq.
--format markdown: corpo Markdown bruto para distill; JSON completo para outros comandos.
--format table: tabela ASCII para resultados tabulares (extract, suggest-fields).

# Markdown body straight to disk
thunderbit distill https://example.com --format markdown

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

Exemplos

Distill rápido

# 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

Ingestão RAG em massa

# 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

Descobrir e depois extrair

# 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

Gate de CI — falhar quando a extração não retornar nada

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

Combinar com outras tools

# 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'

Códigos de saída

Código	Significado
`0`	Sucesso. O resultado fica em `stdout` no formato escolhido por `--format`.
`1`	Qualquer falha — API key ausente, erro de auth, HTTP 4xx/5xx, erro de rede, arquivo de schema ausente, argumento obrigatório ausente.

Todo o texto de erro é escrito em stderr. Em caso de falha, stdout permanece vazio (sim, mesmo com --format json). Isso significa que um pipeline jq nunca recebe um envelope pela metade — verifique o exit code (ou set -e) antes de fazer parsing.

O progresso do polling (por exemplo Processing... (3) do async submit + poll) também é escrito em stderr. Faça pipe 2>/dev/null para silenciar. Chamadas síncronas de página única (--sync) não emitem progresso.

Solução de problemas

Error: API key is required. Exporte THUNDERBIT_API_KEY ou passe --api-key.

Erros de rede atrás de um proxy corporativo. Defina HTTPS_PROXY e HTTP_PROXY — clientes Node e Python ambos respeitam essas variáveis.

Polling de batch lento. Aumente --timeout para o orçamento por página. A cadência de polling em si é fixa em alguns segundos e atualmente não é configurável pela CLI.

Open source

A Thunderbit CLI é licenciada sob MIT e open source no GitHub: GitHub repository (o mesmo repositório também disponibiliza o servidor MCP e o plugin Claude Code). Distribuída no npm como @thunderbit/thunderbit-cli.

Relacionados

Servidor MCP — mesmas operações, expostas como tools MCP
SDKs — chame a partir do seu próprio código
API Reference — HTTP puro

On this page