omnisearch
CLI multi-source search aggregator. Queries 50+ APIs in parallel and returns unified results. Designed for use with Claude Code (JSON output by default).
Install
cargo install --path .
Usage
# Search all configured sources
omnisearch "climate change"
# Filter by category
omnisearch "climate change" -c academic,news
# Filter by specific sources
omnisearch "climate change" -s wikipedia,arxiv,hacker_news
# Output formats: json (default), table, markdown
omnisearch "climate change" -f table
# Limit results
omnisearch "climate change" -n 10
# Custom timeout per source
omnisearch "climate change" -t 15
# Verbose mode (show progress on stderr)
omnisearch "climate change" -v
# List all sources and their status
omnisearch sources
# Manage configuration
omnisearch config init # create default config
omnisearch config show # show current config
omnisearch config set brave # set an API key (read from stdin)
Sources (50)
No API key required (22) — ready out of the box
API key required (28) — free tiers available
Configuration
Config file location: ~/.config/omnisearch/config.toml (macOS: ~/Library/Application Support/omnisearch/config.toml)
# Generate default config
omnisearch config init
# Add API keys (prompted on stdin: the key stays out of shell history)
omnisearch config set brave
gh auth token | omnisearch config set github -
omnisearch config set tmdb "abc123..." # also accepted, but lands in shell history
# Show the config, API keys masked to their last 4 characters
omnisearch config show
Security
- Key storage. The config file holds every API key in plain text. It is written with mode
0600in a0700directory.config showmasks keys. - Keys in URLs. About 20 providers only accept the key as a query parameter (Guardian, NewsAPI, NYT, FRED, Polygon, ...). Keys are URL-encoded, and HTTP errors are stripped of the request URL before they are printed, cached or returned over MCP.
- Plain HTTP providers.
mediastackis called overhttp://: its free plan does not serve HTTPS, so its key travels unencrypted. Disable the source ([sources.mediastack] enabled = false) if that matters on your network.geonamesalso useshttp://with the publicdemoaccount (no secret). - Cache. Results are cached under the user cache directory (
~/Library/Caches/omnisearchon macOS) with mode0600. Errors are never cached. Delete the directory or pass--no-cachefor sensitive queries. - Prompt injection (MCP). Titles, snippets and URLs come from third parties and can contain text written to manipulate an LLM. The MCP
searchtool wraps them in an<untrusted_search_results>block, flattens them to one line, replaces<and>, truncates snippets to 500 characters and capsmax_resultsat 50. This reduces the risk without removing it: do not give an agent that reads these results tools with irreversible effects without a human check. - Response size. Sources that can return very large payloads (
crtsh,common_crawl) are read with a size cap.
Architecture
- Async parallel queries — all sources queried concurrently via tokio
- Per-source timeout (8s default) — slow sources don't block others
- Rate limiting — per-source via governor (GCRA algorithm)
- Partial failure — one source failing doesn't affect others
- URL dedup — results deduplicated by normalized URL
- Relevance ranking — results sorted by source-specific relevance scores
JSON output structure
{
"query": "search terms",
"total_results": 15,
"sources_queried": ["wikipedia", "arxiv", "hacker_news"],
"results": [
{
"title": "Result title",
"url": "https://...",
"snippet": "Description text...",
"source": "wikipedia",
"category": "reference",
"published": "2024-01-15T00:00:00Z",
"author": "Author Name",
"relevance_score": 0.95
}
],
"errors": [
{
"source": "some_source",
"error": "Timeout querying some_source"
}
]
}
Categories
general, academic, news, finance, weather, media, code, reference, security, geo, music