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 |
--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.
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.