web-search-cli

# web-search-cli (ws) > **Multi-provider web search from your terminal** > > Search Google, Serper, Bing, and DuckDuckGo with a unified CLI interface. [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) --- ## 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 ```bash # Using Bun (recommended) bun install -g web-search-cli # Or use without installing bunx web-search-cli ``` ### Setup API Keys ```bash # 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 ```bash # 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 ```bash # 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 ```bash # 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: ```bash ws search "your query" --num-results 10 --format json ``` ### List Providers Check which providers are configured: ```bash 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: ```bash ws serper "typescript" --format text ``` ### JSON Machine-readable structured data: ```bash ws google "nodejs" --format json > results.json ``` ### Markdown Documentation-friendly format: ```bash ws serper "react hooks" --format markdown --output ./docs ``` --- ## Use Cases ### Research & Analysis ```bash # Compare search results across providers ws google "quantum computing" --format json > google.json ws serper "quantum computing" --format json > serper.json ``` ### Content Creation ```bash # Find trending topics ws serper "2025 web development trends" --type news ``` ### SEO & Competitor Analysis ```bash # Check domain rankings ws google "best vpn services" --filter nordvpn.com ``` ### Data Collection ```bash # Batch image search ws serper "product photography" --type images --num-results 50 --output ./images ``` --- ## Configuration ### Environment Variables Create a `.env` file: ```bash # 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](https://console.cloud.google.com/) 2. Enable Custom Search JSON API 3. Create API key 4. Create a Custom Search Engine at [Programmable Search Engine](https://programmablesearchengine.google.com/) **Serper.dev:** 1. Visit [Serper.dev](https://serper.dev/) 2. Sign up for free account (2,500 free queries) 3. Get API key from dashboard --- ## Development ### Local Setup ```bash # 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 ```bash # 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](https://bun.sh) - Fast TypeScript runtime - [Commander.js](https://github.com/tj/commander.js) - CLI framework - [Chalk](https://github.com/chalk/chalk) - Terminal styling - [Ora](https://github.com/sindresorhus/ora) - Elegant spinners --- **Made for developers, researchers, and CLI enthusiasts** [Report Bug](https://github.com/yourusername/web-search-cli/issues) · [Request Feature](https://github.com/yourusername/web-search-cli/issues)