Guide
CLI
The web command, its five subcommands, the flags, and the JSON envelopes that match the library.
Run it
pnpm add -g @agntn/web
web "your query"
web <query> searches with the first configured provider. The subcommands do the rest:
| Command | Description |
|---|---|
web <query> | Search the web using the default provider |
web search <query...> | Search one or more queries |
web search-image <url> | Find matching pages from a public image URL |
web read <url...> | Read one or more URLs into normalized content |
web providers | List registered providers and their capabilities |
web mcp | Run the MCP server over stdio |
Examples
web --provider brave "your query" --max-results 5
web search "your query" --json
web search "first query" "second query" --provider all --json
web search "your query" --provider firecrawl --sources web,news --categories research
web search "your query" --provider exa --summary --full-text
web search "your query" --provider brave --continuation <opaque-token> --json
web search "your query" --include-domains github.com,stackoverflow.com --start-published-date 2026-01-01
web search-image https://example.com/image.jpg --max-results 5 --json
web read https://example.com --format markdown --max-chars 20000 --json
web read https://example.com --max-chars 20000 --continuation <opaque-token> --json
web read https://example.com/one https://example.com/two --json
web providers --json
Flags
| Flag | Description |
|---|---|
--provider <name> | Provider to use (text: first configured or all; image: SerpAPI; read: auto starting with Jina) |
--max-results <n> | Maximum text or image results (default: 10) |
--no-highlights | Disable the passages picked for the query when supported |
--summary | Request generated summaries from Exa or an answer from Tavily |
--full-text | Request full page text from Exa or Tavily |
--include-domains <a,b> | Include only these domains in text search |
--exclude-domains <a,b> | Exclude these domains from text search |
--sources <a,b> | Source types for providers that support them |
--categories <a,b> | Categories for providers that support them |
--category <name> | One provider category |
--start-published-date <ISO date> | Earliest publication date |
--end-published-date <ISO date> | Latest publication date |
--format <markdown|text|html> | Preferred read format |
--max-tokens <n> | The provider's own maximum of read tokens when supported |
--max-chars <n> | Portable maximum of page content characters |
--continuation <token> | Continue a search page or a truncated read of one URL |
--links | Keep the page's links in a read bounded by --max-chars |
--images | Keep the page's image URLs in a read bounded by --max-chars |
--json | Output as JSON |
Lists are comma separated. Read commands pick the reader automatically unless --provider is set.
JSON envelopes
--json prints the same shapes the library and the agent tools return. One parser for all three, that was the point.
- A single search prints
{ provider, results, ignoredFilters, undeclaredFilters, pagination, metadata? }, plusattemptsandfailureswhen the provider was picked automatically. --provider allprints{ results, successfulProviders, errors, filterReports, providerPagination, providerMetadata? }, withprovidersandevidenceon every result. Provider errors are part of the output, not a reason to exit.- A batch of queries prints one item per query, each with its own result or error.
- A single read prints
{ result, requestedProvider, provider, attempts, failures }. A batch addsurlto each success and keeps the same diagnostics on each exhausted failure. Any failed read item makes the command exit 1, but the successes are still printed.
A failure that ends the command prints one line on stderr and exits 1, whether it is a spent key, a bad token or a date that is not ISO 8601. Nothing lands on stdout, --json included.
MCP
web mcp
starts a Model Context Protocol server over stdio with web_search, web_search_image, web_read and web_providers. Register it with any client:
claude mcp add web --scope user -- web mcp
Agents covers what the tools accept and return.