Ddgs Search

DDGS Search

Workflow

1. Clarify the user’s intent and translate it into a concise ddgs query (e.g., “OpenClaw agent capabilities”, “台北市立大學 markeTech 2026”, “AI-generated music licensing summary”).
2. Choose the appropriate ddgs subcommand (text, news, images, videos, books) and supply the query via -q/--query plus any filters you need.
3. Run the CLI with the desired flags. Example:

   uvx ddgs text \
     -q "OpenClaw agent" \
     -b google \
     -p 1 \
     --output json \
     --verify False
   

4. Pull the most relevant titles, snippets, and URLs (or file paths) from the generated output, summarize key findings, cite the sources/engines, and ask if the user wants deeper digging.

Command reference

• uvx ddgs text → General web search. Supports -b/--backend (e.g., duckduckgo, bing, google, auto), -p/--page, -m/--max_results, -r/--region, and -t/--timelimit.
• uvx ddgs news → News sources only; pair with -r/--region or -t/--timelimit to narrow to breaking stories.
• uvx ddgs images, uvx ddgs videos, uvx ddgs books → Media-specific metasearches; capture title, href, and any metadata exposed in JSON output (e.g., ext, download paths).

Available backends

Mode-specific options

text (general web searches)

• Pass the search phrase with -q/--query (text only); -k/--keywords is deprecated.
• -r/--region (e.g., us-en, uk-en, ru-ru) and -s/--safesearch (on, moderate, off) control localization and content sensitivity.
• -t/--timelimit accepts d, w, m, or y for day/week/month/year windows; omit for all-time.
• -m/--max_results limits how many entries ddgs returns (default 10) and -p/--page picks the page number (default 1).
• -b/--backend lets you pin engines (comma-delimited names or auto to pick automatically). Works with the backend list above.

news (news-focused search)

• Same core flags as text (-q, -r, -s, -t, -m, -p, -b), but ddgs only queries news outlets.
• Use -t to keep results fresh (day/week/month), and prefer bing, duckduckgo, or yahoo backends for broader coverage.

images

• Inherits the general -q, -r, -s, -t, -m, -p, -b flags with backend locked to duckduckgo.
• Extra filters include --size (Small, Medium, Large, Wallpaper), --color (Red, Orange, Yellow, Green, Blue, Purple, Pink, Brown, Black, Gray, Teal, White, Monochrome, color), --type (photo, clipart, gif, transparent, line), --layout (Square, Tall, Wide), and --license (e.g., any, Public, Share, ShareCommercially, Modify, ModifyCommercially).

videos

• Core flags work the same (-q, -r, -s, -t, -m, -p, -b) with duckduckgo as the backend.
• Additional filters: --resolution (high, standard), --duration (short, medium, long), --license (creativeCommon, youtube).

books

• Only supports -q, -m, -p, and -b (backend defaults to annasarchive). Use this mode to find e-books or archived copies.

Flags & options

• -q/--query, -r/--region, -s/--safesearch, -t/--timelimit, -m/--max_results, -p/--page, and -b/--backend cover the shared behaviors across modes (text/news/images/videos/books).
• -o/--output writes structured CSV/JSON (or filename.json) for easy parsing.
• --verify False is often necessary here to bypass TLS certificate issues; True performs strict verification.
• --download/--download-directory fetch results locally—useful for images or videos that need inspection.

Result files

• When you use --output json, ddgs saves the results to a timestamped file (text_<query>_<YYYYMMDD>_<HHMMSS>.json). Open that file to read titles, snippets, and URLs, then delete or archive it once the insight is shared.
• If --download runs, note the download directories (default ./downloads/ or the one you provided) and mention them to the user.

Environmental notes

• Ensure uvx is on PATH before running anything (which uvx). On this system it now lives in /usr/local/bin, so the command is available globally.
• Re-run uvx ddgs --help occasionally to confirm the CLI has not changed.
• Record the exact command arguments you used so future agents can reproduce the search.

Notes

• Always mention which search engine/backends you queried when it matters (some users trust DuckDuckGo’s privacy, others expect Google/Bing coverage).
• If ddgs returns sparse context, rerun with --output json and focus on the body/snippet fields before synthesizing your response.