ddgr

Ddgr Plugin

DuckDuckGo from the terminal. Web search with JSON output, no API key needed.

Commands

Self

• ddgr self version — Print ddgr version (v2.2+)

Web

• ddgr web search — Interactive search (non-JSON, prompts for next actions)
• ddgr web json — Structured JSON search (returns array of results)

Passthrough

• ddgr _ _ — Full passthrough for any ddgr flags
• sc ddgr --json --np <query> — Recommended for agent/script usage

Usage Examples

• "Search for Rust CLI frameworks"
• "Find documentation about async/await in Python"
• "Look up the latest news about LLMs"
• "Search for TypeScript testing libraries"
• "Search GitHub for a specific repository"

Installation

pip install ddgr

Examples

# Best for agents: JSON output, no prompt
sc ddgr --json --np "rust cli frameworks"

# Or use the named command
sc ddgr web json "async await python"

# Version check
sc ddgr self version

# Limit results (0-25)
sc ddgr --json --np -n 5 "rust async framework"

# Time range (d=day, w=week, m=month, y=year)
sc ddgr --json --np -t w "latest LLM news"

# Site-specific search
sc ddgr --json --np -w docs.rs "rust async"

# Disable user agent (may help with rate limiting)
sc ddgr --json --np --noua "search query"

# Region-specific (e.g., us-en, gb-en, fr-fr)
sc ddgr --json --np --reg us-en "python jobs"

Output Format

JSON mode returns structured results:

{
  "version": "1.0",
  "command": "ddgr.passthrough",
  "duration_ms": 1068,
  "data": [
    {
      "title": "Result Title",
      "url": "https://example.com",
      "abstract": "Result description..."
    }
  ]
}

Key Features

• DuckDuckGo search, no API key needed
• JSON output with --json flag
• Result count control with -n (0-25)
• Time range filter (-t d/w/m/y)
• Site-specific search (-w site.com)
• Region-specific search (--reg region-code)
• Safe search with --unsafe
• Privacy-respecting (no tracking)
• Works in scripts/automation

Caveats & Pitfalls

Rate Limiting (HTTP 202)

DuckDuckGo aggressively rate-limits automated queries. When rate-limited, ddgr returns:

[ERROR] HTTP Error 202: Accepted
[]

This is a DDG-side protection, not a plugin bug. The plugin works correctly when not rate-limited.

Mitigations:

• Add delays between searches (3-5 seconds minimum)
• Use --noua to disable user agent (may help)
• Consider using a proxy with -p URI for bulk queries
• Accept that some queries will fail — retry with delay

Interactive Mode Requires --np

Without --np, ddgr enters interactive mode and waits for user input (next/prev/open). Always use --np in scripts/agents to exit immediately after results.

Empty Results

Rate-limited queries return empty arrays []. Always check data.length before processing results. Empty results may indicate rate limiting, not zero actual matches.

Binary Location

The plugin expects ddgr binary in PATH. If not found, ensure it's installed via pip install ddgr.

Supercli Wrapper vs Direct ddgr

The supercli plugin wraps the ddgr binary via passthrough. All ddgr flags work identically through sc ddgr. Use the supercli wrapper for consistent JSON output formatting.