ddgr

name	ddgr
description	Search the web using DuckDuckGo via the ddgr CLI tool. Use when the user asks to search the web, look something up online, find information on the internet, get instant answers, or needs current/real-time data. Also use for DuckDuckGo Bang searches (e.g., "!w" for Wikipedia, "!so" for StackOverflow).
license	MIT
metadata	{"author":"ysm-dev","version":"1.0.1"}

ddgr Web Search

Search DuckDuckGo from the terminal using ddgr.

When to Use

• User asks to search the web or look something up
• Need current/real-time information not in training data
• User wants to find documentation, tutorials, or resources
• DuckDuckGo Bang searches (Wikipedia, StackOverflow, GitHub, etc.)

Prerequisites

ddgr must be installed: brew install ddgr or pip install ddgr

Basic Usage

ddgr --noua --np --json "search query"

Required flags:

• --noua: Disable user agent (always use this)
• --np (noprompt): Exit after showing results, no interactive prompt
• --json: Output in JSON format for parsing (implies --np)

Options

Flag	Description
-n N	Number of results (0-25, default 10)
-t SPAN	Time filter: d (day), w (week), m (month), y (year)
-w SITE	Search within a specific site
-r REG	Region-specific search (e.g., us-en, uk-en, in-en)
-x	Show full URLs instead of domain only
-j	"I'm Feeling Ducky" - open first result in browser
-i	Retrieve instant answer only
--unsafe	Disable safe search
--rev	List results in reversed order
-p URI	HTTPS proxy (also reads https_proxy env var)

DuckDuckGo Bangs

Bangs redirect searches to other sites. Escape ! in bash/zsh:

ddgr --noua --np \!w "search term"      # Wikipedia
ddgr --noua --np \!so "python error"    # StackOverflow  
ddgr --noua --np \!gh "repo name"       # GitHub
ddgr --noua --np \!yt "video topic"     # YouTube
ddgr --noua --np \!a "product"          # Amazon

Full bang list: https://duckduckgo.com/bang

Search Keywords

ddgr --noua --np --json "filetype:pdf annual report"
ddgr --noua --np --json "site:reddit.com python tips"

Examples

Basic search:

ddgr --noua --np --json "python asyncio tutorial"

Recent results (last week):

ddgr --noua --np --json -t w "latest news topic"

Site-specific search:

ddgr --noua --np --json -w stackoverflow.com "parse JSON"

Region-specific (India, English):

ddgr --noua --np --json -r in-en "IPL cricket"

Instant answer:

ddgr --noua --np -i "weather new york"

Limit to 5 results:

ddgr --noua --np --json -n 5 "quick query"

JSON Output Structure

Each result contains:

• title: Page title
• url: Full URL
• abstract: Description/snippet

Parse with jq:

ddgr --noua --np --json "query" | jq '.[].title'
ddgr --noua --np --json "query" | jq -r '.[0].url'  # First result URL