Mercury CLI
Documentation

Providers

Web search

Mercury provides web search and page reading for every session model, local models included: WebSearch searches the web and official coding sources with no key required, ProviderSearch runs the session provider's own search when available, and WebFetch returns a public page's main text and tables as markdown.

Search tools

  • WebSearch: Returns a bounded JSON result for any session model, below about 2,000 tokens by a characters-divided-by-four estimate. Each hit carries title, url, snippet and source_type. When hits are withheld to fit the budget, a note counts them. Every result names the source that answered and marks web text as unverified evidence.
  • ProviderSearch: Selects only the session provider's native search, without the fallback cascade, when the session model belongs to Anthropic or OpenAI.
  • WebFetch: Reads a public page as markdown in the page's own words, or runs a labelled reading with a helper model when a prompt is supplied.

Automatic search order

WebSearch follows this order:

  1. The session provider's native search, where supported (Anthropic or OpenAI). This uses the session's own account only. The provider's own answer reaches the model as a labelled, unverified note beside its links.
  2. Brave Search, then Tavily, when a key is available: BRAVE_API_KEY and TAVILY_API_KEY in the environment. Keys are never included in results or evaluation kernels.
  3. An official API selected by explicit query words: an error message goes to Stack Exchange; npm, PyPI or crates plus a package name goes to that registry (PyPI matches exact project names); a concept question goes to Wikipedia; news goes to Hacker News. Wikipedia is asked for the exact phrase first and for the words only when no page carries the phrase; the result says which answered. The top three Stack Exchange and Hacker News hits carry a short plain-text excerpt (the question body, or the story's own text or top comment labelled as such), fetched in one extra request per search. GitHub public-code search requires GH_TOKEN; without one, it says so and tries the next source.
  4. A configured SearXNG JSON API. There are no built-in instances; without configuration, this step reports that no metasearch instance is configured. Set MERCURY_SEARCH_SEARXNG_INSTANCES to a JSON array of entries with url (HTTPS, or HTTP on loopback, with no credentials, query or fragment), terms (its policy URL), apiAllowed: true and checked (the date the policy was read). Configure an instance only when its policy permits automated JSON API access.
  5. DuckDuckGo page scraping, unless you turned it off.

DuckDuckGo page scraping is on by default; turning it off keeps general queries to the official sources and your keys. /config → DuckDuckGo page scraping shows its terms and controls the saved choice. MERCURY_SEARCH_KEYLESS=0 overrides the saved choice and disables scraping; MERCURY_SEARCH_KEYLESS=1 enables it. The first use in a session includes a notice naming the DuckDuckGo terms and acceptable-use policy, and every request asks for the us-en region.

Each source is paced separately and server-requested waits are respected. A challenge, rate limit or refusal stops the attempt, and Mercury does not switch hosts to evade it. Successful queries can answer from the ten-minute session cache, labelled as cached. Stack Exchange and Wikipedia results require attribution to their linked pages. If no source answers, the result says to try another wording or source.

MERCURY_SEARCH_BACKEND accepts auto, brave, tavily or duckduckgo. An explicit source does not fall through to another; a missing key or disabled scraping returns an explanation. /health shows the source plan.

Model lookup

When a model name is missing from both mercury://models and mercury://models/known, the model may search the provider's published model page through WebSearch and ask you with links to what it found. A web result does not establish account access or launch a model on its own; an unknown model id always stops for your confirmation.

Web fetch

WebFetch returns a public page's main text as markdown without a model call. For GitHub repositories, issues and pull requests, npm, PyPI and crates.io packages, arXiv abstracts and Stack Overflow questions, WebFetch reads their public keyless APIs first and falls back to generic page fetch when needed. Headings, lists, code and links stay with the page's words, and tables keep their rows and columns; navigation, footers and scripts are filtered out. Passing a prompt asks for a labelled model reading instead, using the session family's helper model first and then the session model if needed.

Fetch requests leave your machine for the site and honour HTTPS_PROXY, HTTP_PROXY and NO_PROXY. Cloud-metadata addresses (169.254.169.254, fd00:ec2::254, 100.100.100.200, metadata.google.internal, metadata.goog, and DNS names or redirects resolving to them) are refused in every mode. When sparse HTML needs a browser, Mercury may send the page's full URL, query string included, to the hosted reader r.jina.ai; the result says read through r.jina.ai, and no cookies, credentials or conversation are sent. MERCURY_FETCH_READER=0 disables the hosted reader, preapproved documentation stays on the direct path, and private addresses (a single-label name, a loopback or private IP, or a host under .local, .internal, .lan, .home, .corp or .home.arpa) are never sent to it.

Each call returns up to 38,000 characters, with the measured count, a rough characters-divided-by-four token estimate and a from offset to continue reading. Repeat reads use a fifteen-minute cache. Fetches honour robots.txt, URL validation and hostname permissions; cross-host redirects are reported and not followed, paywalls and browser challenges ask for another source, and PDFs are saved with their size and a path for Read, plus up to 4,000 characters from the first page. Other binary documents are saved without a text preview. arXiv abstract pages include a PDF link that can be fetched to read the paper.

Pass urls: [url1, url2, url3] instead of url to fetch up to three pages in one call. Results keep the input order, each URL uses its own existing permission check, and a failed page keeps its reason without discarding the other results.

See Web fetch for failures, retries and shared host cooldowns, and Reading documents to continue reading a saved PDF.

Providers and sign-in · Models and effort · Health check · Web fetch · Reading documents