Command Line Interface

Complete command-line interface for all DuckDuckGo search operations with result saving, downloading, and output formatting options. The CLI provides access to all search functionality through terminal commands.

Capabilities

CLI Entry Points

Main CLI interface functions providing command-line access to all search capabilities.

def cli() -> None:
    """Main CLI command group for duckduckgo_search operations."""

def safe_entry_point() -> None:
    """Safe CLI entry point with exception handling."""

CLI Installation and Usage

The CLI is automatically installed with the package and available through multiple entry points:

Via console script (recommended):

ddgs --help

Via Python module:

python -m duckduckgo_search --help

CLI Commands

Version Command

Display package version information.

ddgs version

Text Search Command

Perform text-based web searches with comprehensive filtering options.

ddgs text [OPTIONS]

Options:

• -k, --keywords TEXT (required): Text search keywords/query
• -r, --region TEXT: Region code (us-en, ru-ru, etc.)
• -s, --safesearch [on|moderate|off]: Safe search level (default: moderate)
• -t, --timelimit [d|w|m|y]: Time filter (day, week, month, year)
• -m, --max_results INTEGER: Maximum number of results
• -o, --output TEXT: Output format (csv, json) or filename with extension
• -d, --download: Download search results
• -dd, --download-directory TEXT: Custom download directory
• -b, --backend [auto|html|lite]: Search backend (default: auto)
• -th, --threads INTEGER: Download threads (default: 10)
• -p, --proxy TEXT: Proxy URL (e.g., socks5://127.0.0.1:9150)
• -v, --verify: SSL verification (default: True)

Image Search Command

Search for images with extensive filtering options.

ddgs images [OPTIONS]

Options:

• -k, --keywords TEXT (required): Image search keywords/query
• -r, --region TEXT: Region code (default: us-en)
• -s, --safesearch [on|moderate|off]: Safe search level (default: moderate)
• -t, --timelimit [Day|Week|Month|Year]: Time filter
• -size, --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]: Layout filter
• -lic, --license_image [any|Public|Share|ShareCommercially|Modify|ModifyCommercially]: License filter
• -m, --max_results INTEGER: Maximum number of results
• -o, --output TEXT: Output format (csv, json) or filename with extension
• -d, --download: Download image results
• -dd, --download-directory TEXT: Custom download directory
• -th, --threads INTEGER: Download threads (default: 10)
• -p, --proxy TEXT: Proxy URL
• -v, --verify: SSL verification (default: True)

Video Search Command

Search for videos with filtering options.

ddgs videos [OPTIONS]

Options:

• -k, --keywords TEXT (required): Video search keywords/query
• -r, --region TEXT: Region code (default: us-en)
• -s, --safesearch [on|moderate|off]: Safe search level (default: moderate)
• -t, --timelimit [d|w|m]: Time filter (day, week, month)
• -res, --resolution [high|standart]: Video resolution filter
• -d, --duration [short|medium|long]: Duration filter
• -lic, --license_videos [creativeCommon|youtube]: License filter
• -m, --max_results INTEGER: Maximum number of results
• -o, --output TEXT: Output format (csv, json) or filename with extension
• -p, --proxy TEXT: Proxy URL
• -v, --verify: SSL verification (default: True)

News Search Command

Search for news articles with time-based filtering.

ddgs news [OPTIONS]

Options:

• -k, --keywords TEXT (required): News search keywords/query
• -r, --region TEXT: Region code (default: us-en)
• -s, --safesearch [on|moderate|off]: Safe search level (default: moderate)
• -t, --timelimit [d|w|m|y]: Time filter (day, week, month, year)
• -m, --max_results INTEGER: Maximum number of results
• -o, --output TEXT: Output format (csv, json) or filename with extension
• -p, --proxy TEXT: Proxy URL
• -v, --verify: SSL verification (default: True)

Usage Examples

Basic Search Commands

Text search:

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

# Text search with filters
ddgs text -k "machine learning" -r us-en -t w -m 10

# Text search with output to file
ddgs text -k "data science" -o results.json

# Text search with CSV output
ddgs text -k "web development" -o myresults.csv

Image search:

# Basic image search
ddgs images -k "cats"

# Image search with filters
ddgs images -k "mountains" -size Large -c Green -type photo -m 20

# Image search with download
ddgs images -k "wallpapers" -size Wallpaper -d -m 5

# Image search with custom download directory
ddgs images -k "nature" -dd ./nature_images -d -m 10

Video search:

# Basic video search  
ddgs videos -k "cooking tutorial"

# Video search with filters
ddgs videos -k "programming" -res high -d medium -m 15

# Video search with Creative Commons filter
ddgs videos -k "educational content" -lic creativeCommon -m 10

News search:

# Basic news search
ddgs news -k "technology"

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

# Regional news search
ddgs news -k "politics" -r uk-en -t w

Advanced CLI Usage

Chain multiple searches:

# Multiple searches in sequence
ddgs text -k "python" -o python_results.json && \
ddgs images -k "python logo" -o python_images.json

Using proxy:

# Search through Tor proxy
ddgs text -k "privacy tools" -p socks5://127.0.0.1:9150

# Search through HTTP proxy
ddgs text -k "research" -p http://proxy.example.com:8080

Bulk downloading:

# Download text search results  
ddgs text -k "tutorials" -d -th 20 -m 50

# Download images with custom directory
ddgs images -k "photography" -dd ./photos -d -th 15 -m 30

Output Format Examples

JSON output format:

# Save as JSON
ddgs text -k "example" -o output.json

# JSON output contains structured data:
# [
#   {
#     "title": "Example Title",
#     "href": "https://example.com", 
#     "body": "Example description..."
#   }
# ]

CSV output format:

# Save as CSV
ddgs text -k "example" -o output.csv

# CSV output contains columns: title,href,body

CLI Configuration

Environment Variables

Set default proxy via environment variable:

export DDGS_PROXY="socks5://127.0.0.1:9150"
ddgs text -k "search query"  # Uses DDGS_PROXY automatically

Proxy Configuration

Supported proxy formats:

• HTTP: http://proxy.example.com:8080
• HTTPS: https://proxy.example.com:8080
• SOCKS5: socks5://127.0.0.1:9150
• With authentication: http://user:pass@proxy.example.com:8080
• Tor alias: tb (expands to socks5://127.0.0.1:9150)

Error Handling

The CLI includes comprehensive error handling:

# Rate limiting errors are handled gracefully
ddgs text -k "query" -m 1000  # May trigger rate limiting

# Timeout errors with retry suggestions
ddgs text -k "query" -p socks5://slow-proxy:9150

# Invalid parameters are caught and explained
ddgs text -k "query" -t invalid_time  # Shows valid options

CLI Output Formats

Interactive Display

By default, results are displayed interactively with pagination. Press Enter to view each result.

File Export

Results can be exported to JSON or CSV formats:

• JSON: Preserves full data structure
• CSV: Flattened format suitable for spreadsheet applications

Download Mode

For text and image searches, results can be downloaded to local files:

• Text searches: Download linked pages/documents
• Image searches: Download image files with metadata-based naming

Performance Options

Threading control for downloads:

# Use more threads for faster downloads (default: 10)
ddgs images -k "photos" -d -th 20

# Use fewer threads for slower connections
ddgs images -k "photos" -d -th 5

Integration Examples

Shell scripting integration:

#!/bin/bash
# Search and process results
ddgs news -k "breaking news" -o news.json
python -c "
import json
with open('news.json') as f:
    news = json.load(f)
    for article in news[:5]:
        print(f'{article[\"title\"]} - {article[\"source\"]}')
"

Automated data collection:

# Daily news collection script
#!/bin/bash
DATE=$(date +%Y%m%d)
ddgs news -k "technology news" -t d -o "tech_news_$DATE.json"
ddgs news -k "business news" -t d -o "business_news_$DATE.json"