A highly resilient, token-efficient, and feature-rich Command Line Interface (CLI) wrapper around the DuckDuckGo Search (ddgs) Python library. It features built-in proxy rotation, rate-limiting, custom token-saving ASCII rendering, webpage extraction, and direct content fetching.
- π Comprehensive Query Support: Subcommands for
text,images,videos,news,books, and web page extraction/fetching. - π Resilient Proxy Rotation: Accepts single proxy URLs, comma-separated lists, or files containing lists of proxies. Automatically rotates proxy servers sequentially on failure.
- β±οΈ Process-Safe Rate Limiting: Randomised delays (between 1.0s to 2.5s) are tracked per proxy/IP using system-level lock files to allow parallel requests across different proxies while safely serializing requests on the same proxy.
- β‘ Direct Web Fetching (
fetch): Inspired by Charmbracelet'scrushtool. Directly fetches and converts webpages usinghttpx,BeautifulSoup, andmarkdownifyinto beautiful plain text, markdown, or HTML, with auto-truncation limits (e.g., 100KB) to preserve context windows. - π Token-Efficient Outputs: Defaults to
plaintext outputs for maximum token conservation. Includes a customtableASCII layout that automatically wraps content to fit terminal widths cleanly without truncating data, preserving readability and tokens.
It is recommended to install and manage ddgo-search using uv.
To install it globally so that the ddgo-search command is available from anywhere:
# Install directly from PyPI
uv tool install ddgo-search
# Or install from GitHub
uv tool install git+https://github.com/twn39/ddgo-search.gitIf you want to clone the repository and run it locally:
# Clone the repository
git clone https://github.com/twn39/ddgo-search.git
cd ddgo-search
# Install dependencies and sync virtual environment
uv syncInvoke ddgo-search directly using uv:
uv run ddgo-search [GLOBAL-OPTIONS] COMMAND [ARGS]...These options must be passed before any subcommand:
-p, --proxy TEXT: Proxy URL, comma-separated list of proxy URLs, or file path containing proxies (one per line). Falls back to theDDGS_PROXYenvironment variable.-t, --timeout INTEGER: Request timeout in seconds (default:10).--verify / --no-verify: Enable/disable SSL certification verification (default:--verify).-r, --max-retries INTEGER: Maximum retries upon server failures or timeouts (default:3).
You can narrow down search results using built-in options or standard search syntax operators directly in the query string:
- CLI Options:
--region TEXT: Limits results to a specific region/country code (default:us-en, e.g.cn-zh,uk-en).--timelimit [d|w|m|y]: Retrieves only recent results from the past day, week, month, or year.--safesearch [on|moderate|off]: Controls content filtering (default:moderate).
- Search Operators (within QUERY):
site:example.com: Only return results within a specific website.-site:example.com: Exclude a specific website from results.filetype:pdf: Filter by file format (e.g., pdf, doc, xls).intitle:keyword: Require keyword in the page title."exact phrase": Match exact word combination.
Example:
uv run ddgo-search text "python site:stackoverflow.com" --timelimit mSearch the web for text results with custom formatting.
uv run ddgo-search text "artificial intelligence" --format plain
uv run ddgo-search text "python programming" --format table --max-results 5Query and filter DuckDuckGo images.
uv run ddgo-search images "cute kittens" --size Large --color Monochrome
uv run ddgo-search images "space nebula" --layout Wide --format jsonSearch for videos with specific duration, resolution, or license filters.
uv run ddgo-search videos "golang tutorial" --resolution high --duration shortNote: The CLI standard resolution parameter accepts standard English spelling "standard". The underlying adapter layer automatically maps this to the third-party library's expected "standart" spelling.
Query recent news.
uv run ddgo-search news "climate change" --timelimit w --format csvSearch DuckDuckGo books.
uv run ddgo-search books "machine learning" --max-results 10Fetch and extract webpage content using DuckDuckGo's internal extraction backend.
uv run ddgo-search extract "https://example.com" --format markdownDirectly fetch a URL via httpx and convert its HTML content locally to Markdown, clean text (excluding scripts, styles, headers, footers), or HTML. Includes auto-truncation.
# Direct fetch and convert to Markdown
uv run ddgo-search fetch "https://example.com" --format markdown
# Direct fetch and extract readable plain text
uv run ddgo-search fetch "https://example.com" --format text
# Direct fetch and write to file
uv run ddgo-search fetch "https://example.com" --format markdown --output doc.md
# Set custom truncation limit (e.g. 5KB)
uv run ddgo-search fetch "https://example.com" --max-size 5120You can integrate ddgo-search as a custom skill in Codex, Antigravity, Crush, Claude Code, and other supported agents to handle all web search and page fetching tasks.
To allow agents to automatically call the ddgo-search skill across all your projects:
- Install the CLI globally so it is available from any workspace directory:
# Install globally using uv uv tool install .
- Install the Skills Configuration using the CLI installer:
# Install skills globally (for Codex, Antigravity, Crush, and Claude Code) ddgo-search skills install
If you only want this skill available inside this project directory:
- Install the skills locally:
# Install skills locally ddgo-search skills install --local - The packaged skill configuration is located at:
- Skill: SKILL.md
Once the skill and subagent are installed globally, Codex can delegate searches automatically when prompted. You can trigger it explicitly by prompting:
"δ½Ώη¨η½η»ζ₯ζΎε ³δΊ..."
Run the comprehensive unit test suite:
uv run pytestOur tests mock the DDGSAdapter and the underlying ddgs.DDGS library to ensure that CLI routing, parameter translations, and network activities are validated robustly, instantly, and offline.