web-search v2.2.1A

Immutable. This exact content is served forever at /api/v1/blob/c21898eb3d2d9cbf.

---
name: web-search
version: "2.2.1"
description: "Search the web with automatic backend selection — public SearXNG works out-of-the-box (no credentials); an optional Duck API adds advanced filters (site, filetype, inurl, exact). Returns text, image, news, or video results. Use when the user wants to search the web, look something up, or find images/news/videos. Triggers on: web search, search for, google, look up, find online, image/news/video search."
---

# Web Search

```bash
web-search "your query"              # That's it.
```

Works globally after install. No credentials needed (public SearXNG).

## Install

This skill ships in the **skale-skills** pi package — install the repo once:

```bash
pi install git:github.com/devskale/skale-skills
```

That loads the skill into pi. To also get a global `web-search` shell command, run the installer from **this skill's own directory** (next to `SKILL.md`):

```bash
./install.sh        # → creates ~/.local/bin/web-search (uv auto-installed)
install.bat         # Windows, same directory
```

## Update

```bash
web-search --update                  # Manual update (git pull + uv sync)
web-search --selfcheck               # Show version + last update date
```

Auto-updates in the background every 7 days. No search is blocked — the update runs in a detached process.

## Configure Backends (optional)

Public SearXNG works out of the box. For better reliability:

**Private SearXNG** (recommended):

```bash
credgoo searx        # Returns: URL@username@password
```

Or set the `SEARXNG_URL` env var (bare URL, or `URL@user@pass`).

**Duck API** (advanced filters):

```bash
credgoo WEB_SEARCH_BEARER
```

**No `credgoo` command?** Install it once (the skill prefers a global install):

```bash
uv tool install "credgoo @ git+https://github.com/devskale/python-openutils.git#subdirectory=packages/credgoo"
```

## Usage

```bash
web-search "react hooks tutorial"
web-search "cats" --categories images
web-search "AI news" --categories news
web-search "query" --max 20
web-search "query" --time-range day
web-search "query" -v                      # verbose (shows backend on stderr)
web-search "query" --json                  # raw JSON to stdout
```

## Options

| Option | Description |
|--------|-------------|
| `--max N` | Max results (default: 10) |
| `--page N` | Results page (default: 1) |
| `--categories CAT` | images, news, videos |
| `--time-range RANGE` | day, week, month, year — works on both backends |
| `--language LANG` | Search language (default: en). SearXNG only. |
| `--region CODE` | Region (e.g., us-en, de-de). Default: wt-wt. |
| `--json` | Output raw JSON |
| `-v, --verbose` | Show backend (printed to stderr) |
| `--api` | Force Duck API backend |
| `--searxng` | Force SearXNG backend |
| `--engines LIST` | Comma-separated engines (SearXNG only) |
| `--update` | Update the skill now |
| `--selfcheck` | Show version and last update |

### Advanced (requires Duck API token)

| Option | Description |
|--------|-------------|
| `--site DOMAIN` | Filter by domain |
| `--filetype EXT` | Filter by file type (pdf, txt, etc.) |
| `--inurl TEXT` | URL must contain text |
| `--exclude TERMS` | Comma-separated terms to exclude |
| `--exact` | Exact phrase match |
| `--timelimit D/W/M/Y` | Time filter shorthand (Duck API only). Prefer `--time-range`. |

> **Duck API filters** (`--site`, `--filetype`, `--inurl`, `--exclude`, `--exact`) are silently ignored on SearXNG with a warning.

## Edge Cases

- `--time-range` values must be **lowercase**: `day`, `week`, `month`, `year`
- `-v, --verbose` output goes to **stderr** — safe to pipe stdout
- Exit codes: `0` = success, `1` = search error

## Troubleshooting

| Problem | Fix |
|---------|-----|
| `web-search: command not found` | Add `~/.local/bin` to PATH: `export PATH="$HOME/.local/bin:$PATH"` |
| `uv: command not found` | Run `install.sh` again — it auto-installs uv |
| Dependency errors | `web-search --update` |
| All SearXNG instances fail | Configure a private instance via `credgoo searx` |

## References

- [references/INDEX.md](references/INDEX.md) — worked examples, region/language codes, backend comparison, and authentication options. **Read when** you need region tuning, backend details, or advanced Duck-API filters (`--site`/`--filetype`/`--inurl`).