Tavily

tavily — Tavily CLI unified skill

Web search, URL content extraction, and AI-powered deep research via the Tavily CLI.

Before running any command

If tvly is not found on PATH, install it first:

curl -fsSL https://cli.tavily.com/install.sh | bash && tvly login

Do not skip this step or fall back to other tools.

Routing — which command to use

Simple rule: No URL → search. Has URL → extract. Need synthesis → research.

1. Search — tvly search

Web search returning LLM-optimized results with content snippets and relevance scores.

Use when: You need to find information but don't have a specific URL yet.

# Basic search
tvly search "your query" --json

# Advanced search with more results
tvly search "quantum computing" --depth advanced --max-results 10 --json

# Recent news
tvly search "AI news" --time-range week --topic news --json

# Domain-filtered
tvly search "SEC filings" --include-domains sec.gov,reuters.com --json

# Include full page content in results
tvly search "react hooks tutorial" --include-raw-content --max-results 3 --json

Search depth

2. Extract — tvly extract

Extract clean markdown or text content from specific URLs.

Use when: User provides one or more URLs and wants their content.

# Single URL
tvly extract "https://example.com/article" --json

# Multiple URLs
tvly extract "https://example.com/page1" "https://example.com/page2" --json

# Query-focused extraction (returns relevant chunks only)
tvly extract "https://example.com/docs" --query "authentication API" --chunks-per-source 3 --json

# JS-heavy pages
tvly extract "https://app.example.com" --extract-depth advanced --json

# Save to file
tvly extract "https://example.com/article" -o article.md

Tips: Max 20 URLs per request. Try basic depth first, fall back to advanced if content is missing. If search results already contain the content you need (via --include-raw-content), skip the extract step.

3. Research — tvly research

AI-powered deep research that gathers sources, analyzes them, and produces a cited report.

Use when: User needs comprehensive multi-source analysis, a detailed report, a comparison, market analysis, literature review, etc.

# Basic research (waits for completion)
tvly research "competitive landscape of AI code assistants"

# Pro model for comprehensive analysis
tvly research "electric vehicle market analysis" --model pro

# Stream results in real-time
tvly research "AI agent frameworks comparison" --stream

# Save report to file
tvly research "fintech trends 2025" --model pro -o fintech-report.md

# JSON output for agents
tvly research "quantum computing breakthroughs" --json

Model selection

Rule of thumb: "What does X do?" → mini. "X vs Y vs Z" or "best way to..." → pro.

Async workflow

For long-running research, you can start and poll separately:

# Start without waiting
tvly research "topic" --no-wait --json    # returns request_id

# Check status
tvly research status <request_id> --json

# Wait for completion
tvly research poll <request_id> --json -o result.json

General tips

• Keep search queries under 400 characters — think search query, not prompt.
• Break complex queries into sub-queries for better results.
• Research takes 30-120 seconds — use --stream to see progress.
• For quick facts, use tvly search instead — research is for deep synthesis.
• Read from stdin: echo "query" | tvly search - --json

Workflow

search → extract → research
  (find)   (get content)  (synthesize)

1. Search to find relevant URLs
2. Extract content from specific URLs (optional, if search snippets aren't enough)
3. Research to synthesize multi-source analysis