metasearch.sh

search: web search for AI agents

One command sends a query to several of ten search engines at once, fuses the results, and tells you what each search cost.

Install · No keys? · Modes · TikTok, YouTube and more · Reddit and HN · Cost · Extract · Agents · Plugins and MCP

search is a single Rust binary for AI agents and the people who run them. It searches with Serper, Exa, Jina, Brave, Linkup, Parallel, Tavily, Perplexity, SerpApi and xAI, searches TikTok, Instagram, YouTube, Facebook, Threads and X for posts and videos (with transcripts and top comments), searches Reddit and Hacker News with no key, reads pages with two fetchers of its own and then Jina, Firecrawl or Browserless, merges what comes back with reciprocal rank fusion, and prints one JSON document with the results, the engines that answered, the ones that failed and why, and the cost.

search "CRISPR gene therapy trials"

Install

brew install paperfoot/tap/search-cli                 # macOS and Linux

cargo install agent-search # any platform with Rust curl -fsSL https://metasearch.sh/install | sh # macOS and Linux, x86_64 and arm64

The install script downloads the release binary for your platform and checks it against the release's SHA256SUMS before installing. search update downloads the latest GitHub release and replaces the binary, without that check.

The Linux binaries include the stealth fetcher, as the macOS ones do. To build from source on Linux, install cmake, clang, libclang-dev, perl and pkg-config first (BoringSSL needs them), or drop the fetcher with cargo install agent-search --no-default-features.

No keys? search login

search login          # prints a code and opens metasearch.sh in your browser

search "rust async runtimes"

search login signs you in to metasearch.sh with a device code; --no-browser prints the URL for SSH sessions. Logging in is free; searches on metasearch.sh are paid from the balance you top up. After that:

• Engines you have your own key for go direct, as before. Your keys always win.
• Engines you have no key for go through metasearch.sh and are charged to your balance.
• Each search reports its cost in metadata.cost and how each engine was reached in metadata.transport (direct, local or hosted).
• The engines without your key go to metasearch.sh as one call per search. Without -p, metasearch.sh picks the engines: the cheapest one first, a pricier one only when the first list is thin, and two social platforms at most. It also answers a repeated search from its own cache, at the stored price, and marks it metadata.routing.cached. With -p, the engines you name are sent as you give them; in extract and the one-engine modes they are tried one at a time, in order, so only the first that answers is charged. Beside an engine you run with your own key, the call goes to the first engine of the mode you have no key for (in extract, each hosted step keeps its place in the chain), so no engine runs twice.
• --no-cache skips both caches: the one on your machine and the one on metasearch.sh.
• Logging in also turns on model routing and relevance reranking, which are free.

search whoami             # account, balance and key

search logout --revoke # forget the key here and revoke it on the server

On a CI runner or in a container, export a key from the dashboard instead: METASEARCH_API_KEY=ms_live_... (or METASEARCH_TOKEN, which wins when both are set).

Your own keys

Any combination works, even one key. Environment variables beat the config file, so a key exported in a shell or injected by CI always wins.

export SERPER_API_KEY=...                      # the provider's usual variable

export SEARCH_KEYS_EXA=... # or the SEARCH_KEYS_ form echo "$KEY" | search config set keys.brave - # or the config file; "-" reads stdin search config check # which engines have a key search doctor # test each engine you have a key for (one billed query each)

Precedence: _API_KEY env, then SEARCH_KEYS_ env, then the config file. The variables are SERPER_API_KEY, EXA_API_KEY, JINA_API_KEY, BRAVE_API_KEY, LINKUP_API_KEY, PARALLEL_API_KEY, TAVILY_API_KEY, PERPLEXITY_API_KEY, SERPAPI_API_KEY, XAI_API_KEY, FIRECRAWL_API_KEY and BROWSERLESS_API_KEY. The config file is ~/.config/search/config.toml on Linux and ~/Library/Application Support/search/config.toml on macOS, created with mode 0600; config.example.toml lists every setting.

Modes

With no -m, the mode is auto, in search "…" and search search -q "…" alike. Auto applies fixed rules first: a lone URL is extract; "tweets", "Twitter", "on X", x.com/ or a lone @handle is social on X; "tiktok", "instagram reels", "youtube", "youtube comments", "on threads" or "facebook page" is social on that platform (not "youtube api", "tiktok sdk" or "embed a youtube video"); "reddit", "subreddit", "hacker news", "on HN", r/ , "what do people say about", "opinions about" or "experiences with" is community (not "reddit api", "reddit stock", a unit such as "r/min", or "HN" alone); similar to (or "sites like", "alternatives to") is similar; "patent" (not "patent leather"), "prior art" or a patent number such as US 10123456 or EP1234567 is patents; "images of" or "logo for" is images, except system images such as Docker, container or VM images. Web-development uses ("Twitter card", "embed a tweet"), "on X axis", code at-words (@property, @media, @types/node) and email addresses are not X cues. When you are logged in, metasearch.sh's routing model, a small classification model, picks among the remaining modes. Without login, or when the model does not answer within 1.2 s, keyword rules decide (places, scholar, academic, people, then news), and anything else is general. Auto never picks deep, and picks social only on a platform cue: those two cost more and must be asked for.

In news and social, auto turns a time word into a freshness filter when you gave no -f: "today" and "yesterday" mean day; "this week", "latest" and "breaking" mean week; "this month" and "this year" mean month and year. The decision, its source and its reason are in metadata.routing.auto.

Pass -m to choose the mode yourself; an explicit -m or -p is always obeyed. If the engines you name with -p cannot serve the mode auto picked, the search runs as general with source fallback (as community when you name only reddit or hackernews, and social when you name only platforms such as tiktok).

Fused modes (general, news, academic, scholar, deep, social, community) query their engines at once and rank with reciprocal rank fusion: a URL that several engines return ranks above any one engine's top hit, and extra.also_found_by shows which engines agreed. A fused search waits for every engine until the mode's deadline, because an engine that received the query bills for it whether or not the CLI waits; engines still running at the deadline are listed in metadata.providers_timed_out. social is the exception: once one platform has answered, it waits at most 20 s for the rest, so one slow platform cannot hold up the search. extract tries engines in order and stops at the first real page. The other modes use one engine. search agent-info prints this table from the same registry the engine uses.

When you are logged in, results in general, news, academic, scholar, people and deep are reranked by relevance once there are at least 3: metadata.routing.reranked is true and each result carries extra.relevance (0 to 1). A search pinned to one engine with -p keeps that engine's order, --no-rerank keeps the fused order, and a failed rerank keeps it too (reranked: false). Without login, auto and rerank-mode searches carry the note "log in for model routing and reranking (free)" in metadata.notes.

search "who is the CEO of Anthropic"                       # auto picks people

search search -q "transformer interpretability" -m academic search search -q "AI agent frameworks" -m news -f week search search -q https://example.com/post -m extract search search -q "rust error handling" -p exa,serper # only these engines search --x "Claude Code" # X only search --tiktok "Claude Code" # TikTok only (also --instagram, --youtube, --threads)

The shorthand search "…" takes only the global flags (--json, --quiet, --last, --debug, and --x, --tiktok, --instagram, --youtube, --threads). A search flag after it (-m, -p, -c, -f, -d, --no-cache and the rest, --flag=value too) exits 3 with an error that shows the full form, search search -q "…". -f takes day, week, month or year; anything else exits 3.

TikTok, Instagram, YouTube, Facebook, Threads and X

search "mechanical keyboard on tiktok"                             # TikTok only

search search -q "mechanical keyboard" -m social --json # X plus the likeliest platform search "https://www.youtube.com/watch?v=3rKPzh3Pr0o" # the video, transcript, top comments search "https: