tavily

Web search, content extraction, site crawling, URL discovery, deep research, and context-isolated search via the Tavily CLI. Returns JSON optimized for LLM consumption.

Prerequisites

Before running any tvly command, check that the CLI is installed and authenticated.

# 1. Check install
command -v tvly || tvly --status

If tvly is not found, install it:

curl -fsSL https://cli.tavily.com/install.sh | bash
# or: uv tool install tavily-cli
# or: pip install tavily-cli

Then authenticate (one of):

tvly login --api-key tvly-YOUR_KEY   # API key from tavily.com
tvly login                           # browser OAuth
export TAVILY_API_KEY=tvly-...       # env var

Verify with tvly --status — should show Authenticated via .... If you get exit code 3 (auth error), re-run tvly login.

Workflow: Start simple, escalate

Follow this escalation pattern — start simple, escalate when needed:

search → extract → map → crawl → research

• search — No specific URL yet. Find pages, answer questions, discover sources.
• extract — Have a URL. Pull its content directly.
• map — Large site, need to find the right page. Discover URLs first.
• crawl — Need bulk content from an entire site section.
• research — Need comprehensive, multi-source analysis with citations.

When results would flood your context (e.g., --include-raw-content returns 300K+ chars), switch to context-isolated search — see the section below.

Command selection table

For full option details, run tvly <command> --help or read the relevant reference file.

Quick examples

# Search
tvly search "your query" --json
tvly search "AI news" --depth advanced --max-results 10 --json

# Extract
tvly extract "https://example.com/article" --json
tvly extract "https://example.com/docs" --query "authentication API" --chunks-per-source 3 --json

# Map
tvly map "https://docs.example.com" --json

# Crawl
tvly crawl "https://docs.example.com" --output-dir ./docs/
tvly crawl "https://docs.example.com" --instructions "authentication" --chunks-per-source 3 --json

# Research
tvly research "competitive landscape of AI code assistants" --model pro
tvly research "topic" --stream

Context-isolated search

A typical tvly search --include-raw-content returns 8 results × 30-50K chars each = ~300K characters of raw page content. If this enters your context window, you burn tokens reading navigation bars, cookie banners, and boilerplate — and reasoning quality degrades under the noise.

The fix: process tvly output through Python so only your curated print() output enters context. This replicates Anthropic's Programmatic Tool Calling (PTC) pattern using local execution — the Python process is the sandbox, variables hold raw data, only print() crosses into context. Typically 100-200x reduction.

Minimal example (pipe mode):

tvly search "quantum computing 2025" --json 2>/dev/null | python3 -c "
import json, sys
data = json.load(sys.stdin)
for r in data['results']:
    print(f'[{r[\"score\"]:.2f}] {r[\"title\"]}')
    print(f'  {r[\"url\"]}')
"

For complex filtering, multi-turn iteration, and the full JSON schemas, see dynamic-search.md.

Output & exit codes

All commands support --json for structured output and -o to save to a file.

Tips

• Always quote URLs — shell interprets ? and & as special characters.
• Use --json for agentic workflows — every command supports it.
• Read from stdin with - — echo "query" | tvly search -.
• Use --include-raw-content on search to skip a separate extract call when you need full page text.
• For multi-step research, save raw results to /tmp/ and process them in separate turns — keeps context lean across iterations.