BatchPrompt ⚡️

BatchPrompt is a CLI tool for building AI pipelines. It automates the process of chaining LLMs, web search, browser scrapers, validation, deduping, and Gmail actions to process data in bulk.

Unlike a chatbot, BatchPrompt is data-driven: it reads CSV/JSON rows from stdin or config data, and for every row it executes a pipeline of steps to generate files, structured data, audio, or side effects like sending email.

---

🚀 Quick Start

1. Install

npm install -g batchprompt

2. Configure Keys

(Recommended: Use OpenRouter for access to OpenAI, Anthropic, and Google models via one key).

Mac/Linux:

export BATCHPROMPT_OPENAI_BASE_URL="https://openrouter.ai/api/v1"
export BATCHPROMPT_OPENAI_API_KEY="sk-or-..."
export BATCHPROMPT_SERPER_API_KEY="your-serper-key" # Required for Serper webSearch and imageSearch
export BATCHPROMPT_DATAFORSEO_LOGIN="your-api-login"
export BATCHPROMPT_DATAFORSEO_PASSWORD="your-api-password" # Required for DataForSEO webSearch

Windows (PowerShell):

$env:BATCHPROMPT_OPENAI_BASE_URL="https://openrouter.ai/api/v1"
$env:BATCHPROMPT_OPENAI_API_KEY="sk-or-..."
$env:BATCHPROMPT_SERPER_API_KEY="your-serper-key"
$env:BATCHPROMPT_DATAFORSEO_LOGIN="your-api-login"
$env:BATCHPROMPT_DATAFORSEO_PASSWORD="your-api-password"

---

📚 Tutorials

The best way to learn BatchPrompt is by doing. We have prepared step-by-step tutorials for common use cases.

Tutorial	Difficulty	What you'll learn
1. RAG Image Generation	🟢 Easy	How to use Search to find reference images and guide Image Generation.
2. B2B Lead Generation	🔴 Advanced	How to build a Multi-Stage Pipeline (Find -> Enrich) with JSON config.
3. SEO Rank Tracker	🟡 Medium	How to use Web Search and AI Selectors to analyze search results.
4. Website Style Analyzer	🟡 Medium	How to use the Style Scraper (Vision + CSS) to reverse-engineer design systems.
5. Logo Downloader	🟡 Medium	How to use the Logo Scraper to extract brand assets (logos, favicons, colors).

---

🧠 How It Works

Think of BatchPrompt as an assembly line for your data.

1. Input: You pipe CSV/JSON rows into batchprompt generate, or provide data in config. Each row is a "raw material".
2. The Pipeline: You define a series of Steps.
   • Fetch: Plugins (Web Search, Image Search, Website Agent, Style Scraper, Logo Scraper, Load Data) go out and get data.
   • Context: The LLM receives the Row Data + Plugin Data.
   • Generate: The LLM creates content (Text, Code, JSON, Images, Audio).
3. Output: The result is saved to a file OR merged back into the row for the next step.

The Data Flow

graph TD
    Input[📂 Input CSV Row] -->|Load| Workspace[📦 Workspace]
    
    subgraph Step 1 [Step 1: Research]
        Workspace -->|Query| Plugin1[🔌 Web Search Plugin]
        Plugin1 -->|Results| Workspace
        Workspace -->|Context| LLM1[🧠 LLM (Text)]
        LLM1 -->|Summary| Workspace
    end
    
    subgraph Step 2 [Step 2: Creation]
        Workspace -->|Ref Image| LLM2[🎨 LLM (Image Gen)]
        LLM2 -->|New Image| Output[💾 File Output]
    end

Loading

---

🔌 Plugins

BatchPrompt comes with powerful built-in plugins to give your LLM access to the real world.

• Web Search (webSearch): Google Search via Serper, DataForSEO, or Puppeteer, with optional content fetching and AI selection. DataForSEO and Puppeteer can include sponsored Google Ads.
• Image Search (imageSearch): Find and download images for RAG or analysis. Supports Serper/Google Images tbs filters such as sur:cl for Creative Commons results; always verify source license terms.
• Website Agent (websiteAgent): Browser-based extraction of structured data from websites.
• Style Scraper (styleScraper): Captures screenshots and computed CSS for design analysis.
• Logo Scraper (logoScraper): Extracts logos, favicons, and brand colors from websites.
• Validation / Dedupe / Load Data (validation, dedupe, loadData): Clean, validate, merge, and expand rows.
• Gmail Sender / Replier (gmailSender, gmailReplier): Send or reply to Gmail threads from pipeline rows.

To include Google Ads, select DataForSEO (recommended for reliable automation) or Puppeteer:

{
  "type": "webSearch",
  "provider": "dataforseo",
  "includeAds": true,
  "query": "{{keyword}}"
}

provider defaults to "serper" for backwards compatibility. Serper does not expose ads through this integration and throws an UnsupportedWebSearchOptionError when called with includeAds: true. DataForSEO requires BATCHPROMPT_DATAFORSEO_LOGIN plus BATCHPROMPT_DATAFORSEO_PASSWORD, or a BATCHPROMPT_DATAFORSEO_AUTH_TOKEN.

---

⚙️ Configuration

You can run BatchPrompt using simple CLI flags or robust YAML/JSON configuration files.

CLI Mode (Simple):

cat data.csv | batchprompt generate "Write a summary of {{topic}}" --model ~google/gemini-flash-latest

Config Mode (Advanced):

cat data.csv | batchprompt generate --config config.json

See the Tutorials for examples of both methods.

Browser-backed plugins and Gmail reuse the Chrome session stored in puppeteer_user_data by default. Set BATCHPROMPT_PUPPETEER_USER_DATA_DIR=puppeteer_user_data/profiles/account-name in each account-specific environment file to keep Gmail logins separate.

Audio Output

Models can request audio output by adding modalities and audio to their model config. Streaming audio models, such as openai/gpt-audio-mini through OpenRouter, use audioTransport: "chat-stream" and pcm16 output.

model:
  model: openai/gpt-audio-mini
  modalities: [text, audio]
  audio:
    voice: alloy
    format: pcm16
  audioTransport: chat-stream