web-search

name	web-search
description	Search the web with automatic backend selection. Works out-of-the-box with public SearXNG. Optional Duck API for advanced filters. Supports images, news, videos.
metadata	{"author":"skale","version":"2.1.0"}

Web Search

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

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

Install

Linux / macOS (bash):

cd ~/.pi/agent/skills/web-search && ./install.sh

Windows (cmd):

cd %USERPROFILE%\.pi\agent\skills\web-search && install.bat

Creates a web-search command in ~/.local/bin/ (%USERPROFILE%\.local\bin\ on Windows). Requires uv (auto-installed).

Update

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):

credgoo searx
# Returns: URL@username@password

Or set SEARXNG_URL env var, or create ~/.config/api_keys/searx.json.

Duck API (advanced filters):

credgoo WEB_SEARCH_BEARER

Usage

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

Reference

See references/INDEX.md for detailed examples, region codes, backend comparison, and authentication options.