CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/pypi-ddgs

A metasearch library that aggregates results from diverse web search services

—

Pending
Overview
Eval results
Files

cli.mddocs/

Command Line Interface

Complete CLI interface for performing searches from the command line with support for all search types, output formats, and configuration options. The CLI provides access to all DDGS functionality through a simple command-line interface.

Installation and Access

After installing the ddgs package, the CLI is available as the ddgs command:

pip install ddgs
ddgs --help

Capabilities

Global Commands

Version Information

Display the current version of the ddgs package.

ddgs version

Help Information

Display help information for the CLI or specific commands.

ddgs --help
ddgs COMMAND --help

Text Search Command

Perform text search across multiple search engines with comprehensive filtering and output options.

ddgs text [OPTIONS]

Options:
  -q, --query TEXT              Search query (required)
  -r, --region TEXT             Search region [default: us-en]
  -s, --safesearch [on|moderate|off]  Safety filter level [default: moderate]
  -t, --timelimit [d|w|m|y]     Time limit filter
  -m, --max_results INTEGER     Maximum results to return [default: 10]
  -p, --page INTEGER            Page number [default: 1]  
  -b, --backend [auto|all|bing|brave|duckduckgo|google|mojeek|mullvad_brave|mullvad_google|yandex|yahoo|wikipedia]
                                Search backend selection [default: auto]
  -o, --output TEXT             Output format: csv, json, or filename
  -d, --download                Download results flag
  -dd, --download-directory TEXT Download directory path
  -th, --threads INTEGER        Download threads [default: 10]
  -pr, --proxy TEXT             Proxy URL (supports 'tb' for Tor Browser)
  -v, --verify / --no-verify    SSL verification [default: verify]
  --help                        Show help message

Usage Examples:

# Basic text search
ddgs text -q "python programming"

# Advanced text search with filters
ddgs text -q "machine learning" -r "us-en" -s "moderate" -t "w" -m 20

# Search with specific backends
ddgs text -q "artificial intelligence" -b "google,bing" -m 50

# Output to JSON file
ddgs text -q "data science" -o results.json

# Search with proxy
ddgs text -q "research topic" -pr "socks5://127.0.0.1:9050"

# Search without SSL verification
ddgs text -q "query" --no-verify

Image Search Command

Perform image search with size, color, type, layout, and license filtering options.

ddgs images [OPTIONS]

Options:
  -q, --query TEXT              Search query (required)
  -r, --region TEXT             Search region [default: us-en]
  -s, --safesearch [on|moderate|off]  Safety filter level [default: moderate]
  -t, --timelimit [d|w|m|y]     Time limit filter
  -m, --max_results INTEGER     Maximum results to return [default: 10]
  -p, --page INTEGER            Page number [default: 1]
  -b, --backend [auto|all|duckduckgo]  Search backend [default: auto]
  -size [Small|Medium|Large|Wallpaper]  Image size filter
  -c, --color [color|Monochrome|Red|Orange|Yellow|Green|Blue|Purple|Pink|Brown|Black|Gray|Teal|White]
                                Color filter
  -type, --type_image [photo|clipart|gif|transparent|line]
                                Image type filter
  -l, --layout [Square|Tall|Wide]  Image layout filter
  -lic, --license_image [any|Public|Share|ShareCommercially|Modify|ModifyCommercially]
                                License filter
  -o, --output TEXT             Output format: csv, json, or filename
  -d, --download                Download images flag
  -dd, --download-directory TEXT Download directory path
  -th, --threads INTEGER        Download threads [default: 10]
  -pr, --proxy TEXT             Proxy URL
  -v, --verify / --no-verify    SSL verification [default: verify]
  --help                        Show help message

Usage Examples:

# Basic image search
ddgs images -q "sunset landscape"

# Filtered image search
ddgs images -q "logo design" -size "Large" -c "Blue" -type "transparent"

# Download images
ddgs images -q "nature photos" -d -dd "./downloads" -th 5

# High-resolution wallpapers
ddgs images -q "mountain wallpaper" -size "Wallpaper" -l "Wide"

News Search Command

Perform news search across news sources with date filtering.

ddgs news [OPTIONS]

Options:
  -q, --query TEXT              Search query (required)
  -r, --region TEXT             Search region [default: us-en]
  -s, --safesearch [on|moderate|off]  Safety filter level [default: moderate]
  -t, --timelimit [d|w|m|y]     Time limit filter
  -m, --max_results INTEGER     Maximum results to return [default: 10]
  -p, --page INTEGER            Page number [default: 1]
  -b, --backend [auto|all|duckduckgo|yahoo]  Search backend [default: auto]
  -o, --output TEXT             Output format: csv, json, or filename
  -pr, --proxy TEXT             Proxy URL
  -v, --verify / --no-verify    SSL verification [default: verify]
  --help                        Show help message

Usage Examples:

# Recent news search
ddgs news -q "climate change" -t "d" -m 20

# Business news from specific source
ddgs news -q "stock market" -b "yahoo" -m 15

# Export news to CSV
ddgs news -q "technology trends" -o "tech_news.csv"

Video Search Command

Perform video search with resolution, duration, and license filtering.

ddgs videos [OPTIONS]

Options:
  -q, --query TEXT              Search query (required)
  -r, --region TEXT             Search region [default: us-en]
  -s, --safesearch [on|moderate|off]  Safety filter level [default: moderate]
  -t, --timelimit [d|w|m]       Time limit filter (videos support d/w/m only)
  -m, --max_results INTEGER     Maximum results to return [default: 10]
  -p, --page INTEGER            Page number [default: 1]
  -b, --backend [auto|all|duckduckgo]  Search backend [default: auto]
  -res, --resolution [high|standard]  Video resolution filter
  -dur, --duration [short|medium|long]  Video duration filter
  -lic, --license_videos [creativeCommon|youtube]  Video license filter
  -o, --output TEXT             Output format: csv, json, or filename
  -pr, --proxy TEXT             Proxy URL
  -v, --verify / --no-verify    SSL verification [default: verify]
  --help                        Show help message

Usage Examples:

# Basic video search
ddgs videos -q "python tutorial"

# High-quality, short videos
ddgs videos -q "quick recipes" -res "high" -dur "short" -m 10

# Creative Commons videos
ddgs videos -q "educational content" -lic "creativeCommon"

Book Search Command

Perform book search across book databases and archives.

ddgs books [OPTIONS]

Options:
  -q, --query TEXT              Search query (required)
  -m, --max_results INTEGER     Maximum results to return [default: 10]
  -p, --page INTEGER            Page number [default: 1]
  -b, --backend [auto|all|annasarchive]  Search backend [default: auto]
  -o, --output TEXT             Output format: csv, json, or filename
  -pr, --proxy TEXT             Proxy URL
  -v, --verify / --no-verify    SSL verification [default: verify]
  --help                        Show help message

Usage Examples:

# Book search
ddgs books -q "machine learning textbook"

# Programming books with results export
ddgs books -q "python programming" -m 30 -o "programming_books.json"

Output Formats

Console Output (Default)

Results are displayed in the console with formatted output showing titles, URLs, and descriptions.

JSON Output

# Output to console as JSON
ddgs text -q "query" -o json

# Save to JSON file
ddgs text -q "query" -o results.json

CSV Output

# Output to console as CSV
ddgs text -q "query" -o csv

# Save to CSV file  
ddgs text -q "query" -o results.csv

Configuration Options

Proxy Configuration

# Use system proxy
ddgs text -q "query" -pr "http://proxy.example.com:8080"

# Use SOCKS proxy
ddgs text -q "query" -pr "socks5://127.0.0.1:9050"

# Use Tor Browser (shortcut)
ddgs text -q "query" -pr "tb"

SSL Verification

# Disable SSL verification (not recommended)
ddgs text -q "query" --no-verify

# Enable SSL verification (default)
ddgs text -q "query" --verify

Region and Language Settings

# US English (default)
ddgs text -q "query" -r "us-en"

# German Germany
ddgs text -q "query" -r "de-de"

# UK English
ddgs text -q "query" -r "uk-en"

# Russian Russia
ddgs text -q "query" -r "ru-ru"

Safety Filters

# Strict filtering
ddgs text -q "query" -s "on"

# Moderate filtering (default)
ddgs text -q "query" -s "moderate"

# No filtering
ddgs text -q "query" -s "off"

Time Filters

# Last day
ddgs text -q "query" -t "d"

# Last week
ddgs text -q "query" -t "w"

# Last month
ddgs text -q "query" -t "m"

# Last year
ddgs text -q "query" -t "y"

Advanced Usage

Batch Processing

#!/bin/bash
# Batch search script

queries=("machine learning" "artificial intelligence" "data science")
for query in "${queries[@]}"; do
    echo "Searching for: $query"
    ddgs text -q "$query" -m 20 -o "${query// /_}_results.json"
    sleep 2  # Rate limiting
done

Pipeline Integration

# Use with other command-line tools
ddgs text -q "python libraries" -o json | jq '.[] | .title'

# Extract URLs only
ddgs text -q "research papers" -o json | jq -r '.[] | .href'

# Count results
ddgs text -q "statistics" -o json | jq '. | length'

Download Automation

# Download images automatically
ddgs images -q "stock photos" -d -dd "./stock_images" -th 8 -m 50

# Download with specific naming
ddgs images -q "logos" -d -dd "./company_logos" -th 4

Error Handling

The CLI returns appropriate exit codes:

  • 0: Success
  • 1: General error (invalid arguments, network issues)
  • 2: Rate limit exceeded
  • 3: Timeout error
# Check exit status
ddgs text -q "query"
if [ $? -eq 0 ]; then
    echo "Search successful"
else
    echo "Search failed with code $?"
fi

Environment Variables

Set environment variables for default configuration:

export DDGS_PROXY="socks5://127.0.0.1:9050"
export DDGS_TIMEOUT="15"
ddgs text -q "query"  # Uses environment proxy and timeout

Install with Tessl CLI

npx tessl i tessl/pypi-ddgs

docs

cli.md

config-utils.md

core-search.md

exceptions.md

index.md

tile.json