A feature-rich command-line interface for DuckDuckGo search that brings the power of privacy-focused searching directly to your terminal. Whether you're a developer looking for quick documentation, a researcher gathering information, or someone who prefers the efficiency of command-line tools, this CLI has you covered.
Note: This tool works entirely in your terminal - no browser required! Perfect for server environments, automated scripts, or when you just want fast, private search results.
- Privacy First: Built on DuckDuckGo's privacy-focused search engine
- Lightning Fast: Get search results without opening a browser
- Developer Friendly: Export results in multiple formats for further processing
- Highly Configurable: Filter, bookmark, and organize your searches
- Terminal Native: Fits perfectly into any command-line workflow
- Zero Tracking: No personal data collection or search history stored externally
# Install the package
pip install .
# Search for something
ddg-cli search "python web scraping"
# Get more results
ddg-cli search "machine learning tutorials" --results 20
# Export to JSON for processing
ddg-cli search "api documentation" --format json --output results.json- Python 3.8 or higher
- pip package manager
-
Clone the repository
git clone https://github.com/GrecAndrei/duckduckgo-cli.git cd duckduckgo-cli -
Install the package
pip install . -
Start using the CLI
ddg-cli search "your search query"
-
Build the Docker image
docker build -t ddg-cli . -
Run searches in Docker
docker run ddg-cli search "hello world"
Search DuckDuckGo with customizable result counts and instant terminal output.
# Basic search
ddg-cli search "kubernetes deployment strategies"
# Limit results
ddg-cli search "react hooks examples" --results 5
# Quick search (backward compatibility)
ddg-cli "neural networks" 10Export your search results in the format that works best for your workflow.
# JSON for data processing
ddg-cli search "python libraries 2024" --format json --output libraries.json
# CSV for spreadsheet analysis
ddg-cli search "startup funding rounds" --format csv --output funding.csv
# Markdown for documentation
ddg-cli search "git best practices" --format markdown --output git-guide.md
# XML for structured data
ddg-cli search "weather api services" --format xml --output weather-apis.xmlFine-tune your search results with powerful filtering options.
# Include only GitHub repositories
ddg-cli search "javascript frameworks" --filter "github.com"
# Exclude tutorial content
ddg-cli search "machine learning" --exclude "tutorial"
# Combine for precise results
ddg-cli search "docker" --filter "documentation" --exclude "tutorial"Keep track of your searches and never lose that perfect query again.
# View your search history
ddg-cli history list
# Clear old searches
ddg-cli history clearSave your most useful search queries for quick access.
# Bookmark a search
ddg-cli bookmarks add "python performance optimization"
# View all bookmarks
ddg-cli bookmarks list
# Clean up bookmarks
ddg-cli bookmarks clearSeamlessly move from terminal to browser when needed.
# Open all results in browser
ddg-cli search "new web technologies 2024" --open
# Download content for offline reading
ddg-cli search "programming cheatsheets" --download# Find API documentation
ddg-cli search "stripe api documentation" --filter "stripe.com" --format json
# Research new libraries
ddg-cli search "python async libraries" --results 15 --exclude "tutorial"
# Quick reference lookup
ddg-cli search "sql join syntax examples" --results 5# Academic research with export
ddg-cli search "climate change 2024 research" --format csv --output climate-research.csv
# News gathering
ddg-cli search "renewable energy news" --filter "2024" --results 25
# Fact-checking sources
ddg-cli search "vaccination statistics WHO" --filter "who.int"# Topic research
ddg-cli search "content marketing trends 2024" --format markdown --output trends.md
# Competitor analysis
ddg-cli search "blog monetization strategies" --exclude "course"
# Social media research
ddg-cli search "instagram algorithm updates" --results 10 --openddg-cli search <query> [options]
Options:
-r, --results NUM Number of results (default: 10)
-f, --format FORMAT Output format: text, json, csv, xml, markdown
-o, --output FILE Save results to file
--filter TERM Include only results containing term
--exclude TERM Exclude results containing term
--open Open URLs in browser
--download Download content from URLs
ddg-cli history list # Show search history
ddg-cli history clear # Clear search history
ddg-cli bookmarks add <query> # Add bookmark
ddg-cli bookmarks list # Show bookmarks
ddg-cli bookmarks clear # Clear bookmarks
The CLI automatically creates a configuration file at ~/.ddgs_config.ini with sensible defaults. You can customize:
- Default number of results
- Default output format
- Network timeout settings
- Display preferences
This project is well-organized for easy maintenance and extension:
duckduckgo-cli/
├── duckduckgo_cli/ # Main package
│ ├── main.py # Main CLI entry point
│ ├── search.py # DuckDuckGo search integration
│ ├── display.py # Result formatting
│ ├── history.py # Search history management
│ ├── bookmarks.py # Bookmark system
│ ├── config.py # Configuration management
│ ├── export.py # Multi-format export
│ ├── filter.py # Result filtering
│ └── utils.py # Browser and download utilities
├── tests/ # Test suite
├── pyproject.toml # Modern Python packaging
├── Dockerfile # Container configuration
└── .github/workflows/ # CI/CD configuration
Run the comprehensive test suite to ensure everything works correctly:
# Run all tests with pytest
pytest
# Or run tests with verbose output
pytest -v"Module not found" errors
# Make sure the package is installed
pip install .Network connectivity issues
- Check your internet connection
- Some networks may block DuckDuckGo search API
- Try using a VPN if searches consistently fail
Permission denied on installation
# Install in user mode if needed
pip install --user .If you encounter issues:
- Check the existing issues on GitHub
- Review the troubleshooting section above
- Create a new issue with details about your environment and the problem
- Optimize result counts: Use
--resultsto limit output for faster searches - Use filters early: Apply
--filterand--excludeto reduce processing time - Export large datasets: Use
--format jsonfor further processing with tools likejq - Bookmark frequent searches: Save common queries to avoid retyping
# Process results with jq
ddg-cli search "api tutorials" --format json | jq '.[] | .title'
# Count results
ddg-cli search "python" --format json | jq '. | length'
# Extract URLs only
ddg-cli search "documentation" --format json | jq -r '.[].href'
# Filter and pipe to other commands
ddg-cli search "github repositories" --filter "python" --format csv | head -10#!/bin/bash
# Daily tech news aggregator
ddg-cli search "tech news $(date +'%Y')" --results 20 --format json > daily_tech.json
# Research automation
for topic in "kubernetes" "docker" "terraform"; do
ddg-cli search "$topic best practices" --format markdown --output "${topic}_practices.md"
doneWhile primarily a CLI tool, the modular architecture makes it easy to import individual components:
from duckduckgo_cli.search import search_duckduckgo
from duckduckgo_cli.filter import filter_results
results = search_duckduckgo("python programming", 10)
filtered = filter_results(results, include="github.com")We welcome contributions! Whether it's bug fixes, new features, or documentation improvements, your help makes this tool better for everyone.
See CONTRIBUTING.md for detailed guidelines on:
- Setting up the development environment
- Code style and standards
- Testing requirements
- Submitting pull requests
This project is licensed under the MIT License - see the LICENSE file for details.
- Built with the excellent ddgs library
- Inspired by the need for privacy-focused search tools
- Thanks to the DuckDuckGo team for providing a great search API
Happy searching! 🦆