abruptive/ankh.md/duckduckgo-search

DuckDuckGo Search (Firecrawl Fallback)

Free web search using DuckDuckGo. No API key required.

When to Use This

Use this skill ONLY when the web_search tool is not available (i.e., FIRECRAWL_API_KEY is not set). If web_search works, prefer it — it returns richer results with built-in content extraction.

Signs you need this fallback:

• web_search tool is not listed in your available tools
• web_search returns an error about missing FIRECRAWL_API_KEY

Setup

# Install the ddgs package (one-time)
pip install ddgs

Web Search (Primary Use Case)

Via Terminal (ddgs CLI)

# Basic search — returns titles, URLs, and snippets
ddgs text -k "python async programming" -m 5
 
# With region filter
ddgs text -k "best restaurants" -m 5 -r us-en
 
# Recent results only (d=day, w=week, m=month, y=year)
ddgs text -k "latest AI news" -m 5 -t w
 
# JSON output for parsing
ddgs text -k "fastapi tutorial" -m 5 -o json

Via Python (in execute_code)

from hermes_tools import terminal
# Search and get results
result = terminal("ddgs text -k 'python web framework comparison' -m 5")
print(result["output"])

CLI Flags

Other Search Types

# Image search
ddgs images -k "landscape photography" -m 10
 
# News search
ddgs news -k "artificial intelligence" -m 5
 
# Video search
ddgs videos -k "python tutorial" -m 5

Workflow: Search → Extract

DuckDuckGo finds URLs. To get full page content, follow up with web_extract:

1. Search with ddgs to find relevant URLs
2. Extract content using the web_extract tool (if available) or curl

# Step 1: Find URLs
ddgs text -k "fastapi tutorial" -m 3
 
# Step 2: Extract full content from a result URL
# (use web_extract tool if available, otherwise curl)
curl -s "https://example.com/article" | head -200

Limitations

• Rate limiting: DuckDuckGo may throttle after many rapid requests. Add sleep 1 between searches if needed.
• No content extraction: ddgs only returns titles, URLs, and snippets — not full page content. Use web_extract or curl for that.
• Results quality: Generally good but less configurable than Firecrawl's search.
• Availability: DuckDuckGo may block requests from some cloud IPs. If searches return empty, try different keywords or add a short delay.

Pitfalls

• Don't confuse `-k` and `-m`: -k is for keywords (the query), -m is for max results count.
• Package name: The package is ddgs (was previously duckduckgo-search). Install with pip install ddgs.
• Empty results: If ddgs returns nothing, it may be rate-limited. Wait a few seconds and retry.