web-search-cli (ws)

Multi-provider web search from your terminal

Search Google, Serper, Bing, and DuckDuckGo with a unified CLI interface.

Why web-search-cli?

• Multi-Provider Support - Google Custom Search, Serper.dev, Bing, DuckDuckGo (more coming)
• Unified Interface - Consistent commands across all providers
• Rich Output - JSON, Text, or Markdown formatting
• Cost Efficient - Compare pricing across providers (Serper: $0.30/1k vs Google: $5/1k)
• Extensible - Plugin architecture makes adding new providers easy
• Lightning Fast - Built with Bun for optimal performance

Quick Start

Installation

# Using Bun (recommended)
bun install -g web-search-cli

# Or use without installing
bunx web-search-cli

Setup API Keys

# For Google Custom Search
export GOOGLE_SEARCH_API_KEY=your_api_key
export GOOGLE_SEARCH_ENGINE_ID=your_engine_id

# For Serper.dev
export SERPER_API_KEY=your_api_key

# Set default provider (optional)
export DEFAULT_SEARCH_PROVIDER=serper

Your First Search

# Search with Serper
ws serper "artificial intelligence trends 2025"

# Search with Google
ws google "best typescript frameworks"

# Use default provider
ws search "web development tutorials"

Commands

Google Custom Search

# Basic search
ws google "query"

# With options
ws google "machine learning" \
  --num-results 20 \
  --format json \
  --type web \
  --safe \
  --output ./results

# Search images
ws google "mountains landscape" --type images

# Search news
ws google "technology news" --type news

# Filter by domain
ws google "react tutorials" --filter reactjs.org

# Date range filter
ws google "latest AI news" --date-range w  # last week

Options:

• -n, --num-results <number> - Number of results (default: 10)
• -o, --output <dir> - Save results to directory
• -f, --format <format> - Output format: json, text, markdown (default: text)
• -t, --type <type> - Search type: web, images, news, videos (default: web)
• --safe - Enable safe search
• --date-range <range> - Filter by date (d=day, w=week, m=month, y=year)
• --filter <domain> - Filter by specific domain

Serper.dev Search

# Basic search
ws serper "query"

# With options
ws serper "climate change" \
  --num-results 15 \
  --format markdown \
  --type web \
  --location "United States" \
  --output ./results

# Search images
ws serper "nature photography" --type images

# Search news
ws serper "breaking news" --type news

# Search videos
ws serper "tutorial videos" --type videos

Options:

• -n, --num-results <number> - Number of results (default: 10)
• -o, --output <dir> - Save results to directory
• -f, --format <format> - Output format: json, text, markdown (default: text)
• -t, --type <type> - Search type: web, images, news, videos (default: web)
• -l, --location <location> - Search location (e.g., "United States", "London, UK")
• --auto-correct - Enable auto-correction (default: true)

Serper Features:

• Knowledge Graph results
• People Also Ask sections
• Related searches
• Rich metadata (source, published date, thumbnails)

Default Search

Use your configured default provider:

ws search "your query" --num-results 10 --format json

List Providers

Check which providers are configured:

ws providers

API Provider Comparison

| Provider | Cost (per 1k queries) | Free Tier | Daily Limit | Features | |----------|----------------------|-----------|-------------|----------| | Serper.dev | $0.30 | 2,500 queries | Unlimited | Knowledge Graph, PAA, Related | | Google Custom Search | $5.00 | 100/day | 10,000/day | Images, Safe Search | | Bing Search | Varies | 1,000/month | Varies | Coming soon | | DuckDuckGo | Free | Unlimited | None | Coming soon |

Recommendation: Start with Serper.dev for cost-effective, feature-rich searches.

Output Formats

Text (Default)

Colored, human-readable output in terminal:

ws serper "typescript" --format text

JSON

Machine-readable structured data:

ws google "nodejs" --format json > results.json

Markdown

Documentation-friendly format:

ws serper "react hooks" --format markdown --output ./docs

Use Cases

Research & Analysis

# Compare search results across providers
ws google "quantum computing" --format json > google.json
ws serper "quantum computing" --format json > serper.json

Content Creation

# Find trending topics
ws serper "2025 web development trends" --type news

SEO & Competitor Analysis

# Check domain rankings
ws google "best vpn services" --filter nordvpn.com

Data Collection

# Batch image search
ws serper "product photography" --type images --num-results 50 --output ./images

Configuration

Environment Variables

Create a .env file:

# Google Custom Search
GOOGLE_SEARCH_API_KEY=your_google_api_key
GOOGLE_SEARCH_ENGINE_ID=your_search_engine_id

# Serper.dev
SERPER_API_KEY=your_serper_api_key

# Bing Search (Coming soon)
BING_SEARCH_API_KEY=your_bing_api_key

# DuckDuckGo (Coming soon)
DDG_API_KEY=your_ddg_api_key

# Default provider
DEFAULT_SEARCH_PROVIDER=serper

# Debug mode
DEBUG=true

Getting API Keys

Google Custom Search:

1. Visit Google Cloud Console
2. Enable Custom Search JSON API
3. Create API key
4. Create a Custom Search Engine at Programmable Search Engine

Serper.dev:

1. Visit Serper.dev
2. Sign up for free account (2,500 free queries)
3. Get API key from dashboard

Development

Local Setup

# Clone repository
git clone https://github.com/yourusername/web-search-cli.git
cd web-search-cli

# Install dependencies
bun install

# Set up environment variables
cp .env.example .env
# Edit .env with your API keys

# Run in development mode
bun run dev serper "test query"

Build

# Type check
bun run typecheck

# Build for production
bun run build

# Run production build
bun run start serper "test query"

Project Structure

web-search-cli/
├── src/
│   ├── index.ts              # CLI entry point
│   ├── commands/             # Provider command implementations
│   │   ├── google.ts
│   │   └── serper.ts
│   ├── lib/
│   │   ├── search-client.ts  # Abstract search client
│   │   ├── providers/        # Provider-specific clients
│   │   │   ├── google-client.ts
│   │   │   └── serper-client.ts
│   │   └── result-formatter.ts
│   ├── utils/
│   │   ├── config.ts         # Configuration management
│   │   ├── logger.ts         # Colored logging
│   │   └── validators.ts     # Input validation
│   └── types/
│       └── index.ts          # TypeScript types
├── package.json
├── tsconfig.json
└── README.md

Contributing

Contributions are welcome! To add a new search provider:

1. Create provider client in src/lib/providers/{provider}-client.ts
2. Extend SearchClient abstract class
3. Add command in src/commands/{provider}.ts
4. Register command in src/index.ts
5. Update config in src/utils/config.ts

Roadmap

• [x] Google Custom Search integration
• [x] Serper.dev integration
• [x] JSON/Markdown output formats
• [x] Multi-search type support (web, images, news, videos)
• [ ] Bing Search integration
• [ ] DuckDuckGo integration
• [ ] Rate limiting & caching
• [ ] Interactive TUI mode
• [ ] Search history
• [ ] Bulk search operations

License

MIT © Dipendra Sharma

Acknowledgements

Built with:

• Bun - Fast TypeScript runtime
• Commander.js - CLI framework
• Chalk - Terminal styling
• Ora - Elegant spinners

Made for developers, researchers, and CLI enthusiasts

Report Bug · Request Feature