User intent	Command	When
No specific URL, need to find information	`tvly search`	"search for X", "find me Y", "what's the latest on Z", "look up"
Has specific URL(s), need page content	`tvly extract`	"read this URL", "extract content from", "grab the page at"
Deep analysis needed, multi-source synthesis	`tvly research`	"research X", "investigate", "analyze in depth", "compare X vs Y"

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

Option	Description
`--depth`	`ultra-fast`, `fast`, `basic` (default), `advanced`
`--max-results`	Max results, 0-20 (default: 5)
`--topic`	`general` (default), `news`, `finance`
`--time-range`	`day`, `week`, `month`, `year`
`--start-date`	Results after date (YYYY-MM-DD)
`--end-date`	Results before date (YYYY-MM-DD)
`--include-domains`	Comma-separated domains to include
`--exclude-domains`	Comma-separated domains to exclude
`--country`	Boost results from country
`--include-answer`	Include AI answer (`basic` or `advanced`)
`--include-raw-content`	Include full page content (`markdown` or `text`)
`--include-images`	Include image results
`include-image-descriptions`	Include AI image descriptions
`--chunks-per-source`	Chunks per source (advanced/fast depth only)
`-o, --output`	Save output to file
`--json`	Structured JSON output

Search depth

Depth	Speed	Relevance	Best for
`ultra-fast`	Fastest	Lower	Real-time chat, autocomplete
`fast`	Fast	Good	Need chunks, latency matters
`basic`	Medium	High	General-purpose (default)
`advanced`	Slower	Highest	Precision, specific facts

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

Option	Description
`--query`	Rerank chunks by relevance to this query
`--chunks-per-source`	Chunks per URL (1-5, requires `--query`)
`--extract-depth`	`basic` (default) or `advanced` (for JS pages)
`--format`	`markdown` (default) or `text`
`include-images`	Include image URLs
`--timeout`	Max wait time (1-60 seconds)
`-o, --output`	Save output to file
`--json`	Structured JSON output

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

Option	Description
`--model`	`mini`, `pro`, or `auto` (default)
`--stream`	Stream results in real-time
`--no-wait`	Return request_id immediately (async)
`--output-schema`	Path to JSON schema for structured output
`citation-format`	`numbered`, `mla`, `apa`, `chicago`
`--poll-interval`	Seconds between checks (default: 10)
`--timeout`	Max wait seconds (default: 600)
`-o, --output`	Save output to file
`--json`	Structured JSON output

Model selection

Model	Use for	Speed
`mini`	Single-topic, targeted research	~30s
`pro`	Comprehensive multi-angle analysis	~60-120s
`auto`	API chooses based on complexity	Varies

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

1. Search — tvly search

tavily

tavily — Tavily CLI unified skill

Before running any command

Routing — which command to use