CLI

The superscraper CLI lets you run scrapes, extractions, and lead pulls from the terminal, useful for shell scripts, CI pipelines, and one-off jobs without writing any code.

curl -sX POST https://api.superscraper.dev/v1/scrape \
  -H "x-api-key: $SUPERSCRAPER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com"}'

Running it from source

Clone the repository, install workspace dependencies, and build packages/cli. The package declares two equivalent binaries, superscraper and leadsnap, both pointing at the same entry point. Examples below use superscraper.

You need a SuperScraper API key, get one free at app.superscraper.dev (opens in a new tab) or mint one with POST /v1/keys/provision.

Authentication

Auth is resolved in this order:

1. SUPERSCRAPER_API_KEY environment variable
2. ~/.leadsnap/config.json written by superscraper init (the config path is still the legacy name in source)

Set the environment variable directly:

export SUPERSCRAPER_API_KEY=ss_live_xxxxxxxxxxxxxxxxxxxx

Or run superscraper init to save credentials to the config file (recommended for interactive use).

Set SUPERSCRAPER_API_URL to point at a self-hosted instance (defaults to https://api.superscraper.dev).

Commands

init

Save your API key and base URL to ~/.leadsnap/config.json. Runs interactively by default; pass flags to skip the prompts.

superscraper init [options]

Examples:

# Interactive, prompts for key and URL
superscraper init
 
# Non-interactive, write key directly
superscraper init --api-key ss_live_xxxxxxxxxxxxxxxxxxxx

The config file is written with mode 0600 (owner-read-only). An existing key is never echoed back; leave the prompt blank to keep it.

scrape

Scrape a single URL and return its content.

superscraper scrape <url> [options]

Examples:

# Print markdown (default)
superscraper scrape https://acmeplumbing.com
 
# Return structured listing JSON
superscraper scrape https://acmeplumbing.com --format json
 
# Force headless browser with extra wait, raw API response
superscraper scrape https://react-app.com --force-playwright --wait-for 2000 --json

extract

Extract structured data from a URL. Without --schema, uses the free JSON-LD cascade. With --schema, calls the LLM-powered extraction endpoint.

superscraper extract <url> [options]

Examples:

# Free JSON-LD cascade (no schema required)
superscraper extract https://acmeplumbing.com
 
# LLM-powered extraction with a schema file
superscraper extract https://acmeplumbing.com --schema ./contact-schema.json

pull

Execute a full data pull via a connector ID or URL. Use superscraper connectors to browse available connector IDs. Pass --job to redeem a previewed job returned by superscraper chat.

superscraper pull <connectorId|url> [options]
superscraper pull --job <jobId>

Examples:

# Pull by connector ID with query params
superscraper pull google-maps --params '{"query":"HVAC Austin TX"}'
 
# Save results to CSV
superscraper pull google-maps --params '{"query":"pizza Miami"}' --out results.csv
 
# Redeem a job previewed via superscraper chat
superscraper pull --job job_8f3a2c1d

connectors

List all registered data source connectors.

superscraper connectors [options]

Examples:

# Human-readable table
superscraper connectors
 
# Machine-readable JSON
superscraper connectors --json

chat

Pull data using a plain-English prompt. The API selects the best connector (or falls back to ad-hoc extraction), returns a preview with sample rows and cost estimate, and provides a jobId to redeem the full pull via superscraper pull --job.

superscraper chat "<prompt>" [options]

Examples:

# Basic prompt
superscraper chat "HVAC companies in Austin TX"
 
# With region hint, raw JSON response
superscraper chat "restaurants near Miami" --region US --json
 
# Continue a conversation (refine / add filters)
superscraper chat "more results" --conversation-id <id>

The response includes sample rows, a cost preview, and a jobId. Redeem it:

superscraper pull --job <jobId>

Global options

These flags work on every command:

Environment variables

Exit codes

Further reading

• API Reference, underlying REST endpoints
• MCP Server guide, use SuperScraper from Claude Desktop / Claude Code