ddg-search

Quick rules

• Prefer your normal primary search tool when it is healthy.
• Use this skill when you need a fallback or a second source.
• Keep searches narrow and intentional.
• Prefer JSON output by default.
• Use

  --text

  only when human-readable terminal output is actually more useful.
• Use

  references/notes.md

  for quick guidance on when this tool fits.

Local setup

.venv

.gitignore

<skill-path>/scripts/bootstrap_venv.sh

<skill-path>/scripts/ddg-search

.venv

Commands

Show built-in help

<skill-path>/scripts/ddg-search help

Text search

<skill-path>/scripts/ddg-search search 'openclaw github'

News search

<skill-path>/scripts/ddg-search search 'bitcoin etf' --type news --timelimit d --max-results 10

Image search

<skill-path>/scripts/ddg-search search 'bitcoin logo' --type images --max-results 10

Video search

<skill-path>/scripts/ddg-search search 'openai launch' --type videos --timelimit w --max-results 10

Restrict to one site

<skill-path>/scripts/ddg-search search 'python dataclasses' --site docs.python.org

Reverse result order

<skill-path>/scripts/ddg-search search 'openai launch' --type videos --max-results 10 --reverse

Instant-answer lookup

<skill-path>/scripts/ddg-search instant 'weather berlin'

Resolve a DuckDuckGo bang

<skill-path>/scripts/ddg-search bang w 'OpenAI'

Workflow

1. Read

   references/notes.md

   if you want quick selection guidance.
2. Ensure the skill-local virtual environment is bootstrapped.
3. Use

   search

   for normal search,

   instant

   for instant-answer lookups, and

   bang

   when a DuckDuckGo bang is the cleanest path.
4. Parse JSON output by default.
5. Cross-check with another source when the question is important.

Expected outputs

--text

• search

  returns query metadata plus

  results

• instant

  returns instant-answer style structured fields

• bang

  returns the DuckDuckGo URL plus the resolved redirect/final URL

Files

• Source repo:

  https://github.com/ropl-btc/ddg-search-cli

• Launcher:

  scripts/ddg-search

• Python implementation:

  scripts/ddg_search.py

• Local bootstrap:

  scripts/bootstrap_venv.sh

• Notes:

  references/notes.md

• .venv/

  is generated local state and can be recreated with

  scripts/bootstrap_venv.sh

When to stop and ask

• turning this into browser automation
• adding scraping-heavy flows
• adding provider-specific hacks that make the wrapper fragile
• changing default behavior from lightweight fallback search to something much broader