# ddg-search

Adopt this skill: https://proskills.md/skills/other/robin-liquidium-ddg-search-cli-skills-ddg-search

Page: https://proskills.md/skills/other/robin-liquidium-ddg-search-cli-skills-ddg-search
This document is the public skill bundle for that page. It contains SKILL.md and every helper file the catalog carries. No login is required.

## File: skills/ddg-search/SKILL.md
size: 3184
upstream: https://github.com/robin-liquidium/ddg-search-cli/blob/main/skills/ddg-search/SKILL.md

````text
---
name: ddg-search
description: Search the web with DuckDuckGo as a no-API-key fallback or second source. Use when the normal web_search tool or primary search provider is rate-limited, failing, unavailable, not delivering enough useful results, or producing weak/inaccurate results, and you want quick text, news, image, or video search results, instant-answer lookups, or DuckDuckGo bang resolution without browser automation.
---

# ddg-search

Use the installed `ddg-search` CLI for lightweight DuckDuckGo search.

This skill exists to make fallback web search simple and low-noise instead of rebuilding ad hoc search helpers each time.

## 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.

## Installation preference

Prefer an installed CLI over hardcoded script paths.

Preferred install:

```bash
pipx install git+https://github.com/ropl-btc/ddg-search-cli.git
```

Fallback inside a repo checkout:

```bash
pip install .
```

After install, use:

`ddg-search`

## Commands

### Show built-in help

```bash
ddg-search help
```

### Text search

```bash
ddg-search search 'openclaw github'
```

### News search

```bash
ddg-search search 'bitcoin etf' --type news --timelimit d --max-results 10
```

### Image search

```bash
ddg-search search 'bitcoin logo' --type images --max-results 10
```

### Video search

```bash
ddg-search search 'openai launch' --type videos --timelimit w --max-results 10
```

### Restrict to one site

```bash
ddg-search search 'python dataclasses' --site docs.python.org
```

### Reverse result order

```bash
ddg-search search 'openai launch' --type videos --max-results 10 --reverse
```

### Instant-answer lookup

```bash
ddg-search instant 'weather berlin'
```

### Resolve a DuckDuckGo bang

```bash
ddg-search bang w 'OpenAI'
```

## Workflow

1. Read `references/notes.md` if you want quick selection guidance.
2. Ensure the `ddg-search` CLI is installed.
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

The CLI returns JSON by default. Parse it instead of scraping text.

Use `--text` when you want a readable terminal view.

`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

- Package repo: `https://github.com/ropl-btc/ddg-search-cli`
- Compatibility wrapper: `scripts/ddg_search.py`
- Notes: `references/notes.md`

## When to stop and ask

Stop and ask before:
- 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
````

## File: README.md
upstream: https://github.com/robin-liquidium/ddg-search-cli/blob/main/README.md

````text
> Update: new self-contained skill without the need for installing CLI is here: https://github.com/ropl-btc/agent-skills

# ddg-search-cli

Small DuckDuckGo search CLI for **OpenClaw**, **Claude Code**, and other AI agents that need a simple fallback web search tool without an API key.

This repo gives you two things:
- a small installable CLI: `ddg-search`
- a matching OpenClaw skill in `skills/ddg-search`

## What this is

- a small **DuckDuckGo search CLI** built on `ddgs`
- intentionally minimal and easy to use in scripts, shells, and agent workflows
- a matching **OpenClaw skill** under `skills/ddg-search`
- opinionated defaults for quick fallback web search
- designed to be easy for humans and AI agents to use repeatedly

## What this is not

- not a browser automation tool
- not a scraping framework
- not a full wrapper for every DuckDuckGo feature
- not meant to replace your primary search provider when that provider is healthy

## Features

- install a real shell command: `ddg-search`
- run text, news, image, and video search
- return JSON by default for agent-friendly parsing
- switch to readable text output with `--text`
- restrict search to one site with `--site`
- reverse result order with `--reverse`
- tune backend selection and pagination with `--backend` and `--page`
- fetch DuckDuckGo instant-answer style data with `instant`
- resolve DuckDuckGo bangs to final URLs with `bang`
- work as a no-API-key fallback when another search provider is rate-limited, failing, or weak

## Commands

- `help`
- `search`
- `instant`
- `bang`

Run built-in help:

```bash
ddg-search help
```

## Requirements

- Python 3.10+

## Install

### Preferred: pipx

```bash
pipx install git+https://github.com/ropl-btc/ddg-search-cli.git
```

Then run:

```bash
ddg-search help
```

### Fallback: local venv

```bash
git clone https://github.com/ropl-btc/ddg-search-cli.git
cd ddg-search-cli
python3 -m venv .venv
. .venv/bin/activate
pip install --upgrade pip
pip install .
```

Then run:

```bash
ddg-search help
```

### Developer mode

```bash
pip install -e .
```

## Usage examples

### Show help

```bash
ddg-search help
```

### Text search

```bash
ddg-search search 'openclaw github'
```

### News search

```bash
ddg-search search 'bitcoin etf' --type news --timelimit d --max-results 10
```

### Image search

```bash
ddg-search search 'bitcoin logo' --type images --max-results 10
```

### Video search

```bash
ddg-search search 'openai launch' --type videos --timelimit w --max-results 10
```

### Restrict to one site

```bash
ddg-search search 'python dataclasses' --site docs.python.org
```

### Reverse result order

```bash
ddg-search search 'openai launch' --type videos --max-results 10 --reverse
```

### Human-readable output

```bash
ddg-search search 'site:docs.openclaw.ai browser' --text
```

### Set region and safesearch

```bash
ddg-search search 'liquid staking' --region us-en --safesearch off
```

or:

```bash
ddg-search search 'liquid staking' --region us-en --unsafe
```

### Choose backend and page

```bash
ddg-search search 'open source ai agents' --backend auto --page 2 --max-results 10
```

### Instant answers

```bash
ddg-search instant 'weather berlin'
```

### Resolve DuckDuckGo bangs

```bash
ddg-search bang w 'OpenAI'
```

```bash
ddg-search bang gh 'openclaw openclaw'
```

## Output

Default output is JSON.

That is intentional: AI agents should parse structured output instead of scraping plain text.

Use `--text` when you want a readable terminal view.

### Search output shape

`search` returns metadata plus `results`:

```json
{
  "query": "python dataclasses site:docs.python.org",
  "type": "text",
  "site": "docs.python.org",
  "region": "wt-wt",
  "safesearch": "moderate",
  "timelimit": null,
  "max_results": 5,
  "page": 1,
  "backend": "auto",
  "reverse": false,
  "results": []
}
```

`instant` returns fields like `heading`, `abstract`, `answer`, `definition`, and `related_topics`.

`bang` returns the DuckDuckGo query URL plus the resolved redirect/final URL.

## OpenClaw / AI-agent usage

This repo includes an OpenClaw skill under:

- `skills/ddg-search/SKILL.md`
- `skills/ddg-search/scripts/ddg_search.py`
- `skills/ddg-search/references/notes.md`

That subfolder is the one to use for skill-specific packaging and publishing.

The main intended interface for end users and agents is still the installed `ddg-search` command.

## Why this exists

Many agent setups already have a primary search provider.

This wrapper exists for the annoying cases where:
- the primary provider is rate-limited
- the primary provider is temporarily failing
- the default search path is weak or inaccurate
- you want a second source to cross-check results
- you want a fast no-key search command inside scripts and agent workflows

## License

MIT
````
