| name | tavily-search |
| description | Web research through the Tavily CLI as one skill — search (ranked fact-finding with a server-side synthesized answer so raw pages never enter context), research (a cited multi-source report), extract (clean markdown from up to 20 known URLs), map (a site's URL list, no content), and crawl (bulk page content to disk). Default for any current-web question. Triggered by "search for", "look up", "find", "research", "investigate", "compare X vs Y", "what's the latest on", "extract"/"read this page", "map the site"/"find the URL for", and "crawl"/"download the docs"/"get all the pages". Indexed library and framework documentation belongs to context7-mcp; a multi-agent, adversarially-verified report belongs to deep-research. |
| allowed-tools | Bash(uvx *), Bash(python3 *), Bash(jq *) |
[TAVILY_SEARCH]
tvly owns live-web retrieval as one intent surface, and the cheapest verb that answers wins. An open question is search — --include-answer returns a synthesized answer with no follow-up call, and --include-raw-content markdown folds the top results' full content into that same call when you will read them anyway. Known URLs are extract. A site is one crawl --instructions, or a map recon first when the URLs must be inventoried and picked by hand. A cited multi-source report is research. Live web content routes here over WebFetch — WebFetch reads one URL blind, while tvly ranks, scopes, and filters server-side.
Relevance resolves server-side, never a local post-filter: --include-answer on search, --query with --chunks-per-source on extract, --instructions with --chunks-per-source on crawl. Triage on the score and snippet every search result carries and pull full content only for the URLs that earn it — or skip the round-trip with --include-raw-content when the whole top set is wanted. Bulk output routes to disk, -o for the JSON envelope and --output-dir for one markdown file per crawled page, never into the window.
crawl starts shallow — --max-depth 1, a tight --limit — and widens once the site's shape is known; --instructions focuses it semantically and collapses a map-then-extract round-trip into one call, leaving map for cheap URL recon alone. research is the loose heavy lane, a cited report over 30-120 seconds: run it detached when it outlives the turn, take --output-schema for a structured result, and never spend it on a fact one search settles.
[01]-[USAGE]
Every command runs as uvx --from tavily-cli tvly <verb> under the ambient TAVILY_API_KEY; search and extract also run key-free under a rate cap. --json returns the typed envelope, -o writes it to a file, and each verb's full flag roster lives behind --help; add --extract-depth advanced when extract or crawl hits a JavaScript-rendered page. Reach for the one-call command that fits:
uvx --from tavily-cli tvly search "QUERY" --include-answer advanced --max-results 8
uvx --from tavily-cli tvly search "QUERY" --include-raw-content markdown --max-results 8 --json
uvx --from tavily-cli tvly extract URL_A URL_B --query "QUESTION" --chunks-per-source 3 --format markdown
uvx --from tavily-cli tvly crawl https://example.com --max-depth 1 --limit 20 --instructions "GOAL" --chunks-per-source 3
uvx --from tavily-cli tvly crawl https://example.com --max-depth 2 --limit 50 --output-dir DIR
uvx --from tavily-cli tvly research run "QUERY" --citation-format numbered -o report.md
Take a second call only when one will not do; --max-results and --limit keep the feed inside extract's 20-URL cap:
uvx --from tavily-cli tvly search "QUERY" --json | jq -r '.results[] | select(.score > 0.5) | .url' | xargs uvx --from tavily-cli tvly extract --query "QUESTION" --chunks-per-source 3
uvx --from tavily-cli tvly map https://example.com --instructions "GOAL" --limit 20 --json | jq -r '.results[]'
uvx --from tavily-cli tvly extract PICKED_URL --query "QUESTION" --chunks-per-source 3
uvx --from tavily-cli tvly research run "QUERY" --no-wait
uvx --from tavily-cli tvly research poll REQUEST_ID -o report.md
