| name | tavily |
| description | Unified Tavily CLI skill — web search, URL extraction, and deep research via `tvly`. Use this skill when the user wants to search the web, extract content from URLs, conduct research, find articles, look up information, or needs current information from the internet. Routes to the appropriate sub-command based on user intent.
|
| allowed-tools | Bash(tvly *) |
| tags | ["Search","Web","Research"] |
| aliases | ["搜索网页","联网查资料","提取URL内容","深度调研"] |
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
| 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.
tvly search "your query" --json
tvly search "quantum computing" --depth advanced --max-results 10 --json
tvly search "AI news" --time-range week --topic news --json
tvly search "SEC filings" --include-domains sec.gov,reuters.com --json
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.
tvly extract "https://example.com/article" --json
tvly extract "https://example.com/page1" "https://example.com/page2" --json
tvly extract "https://example.com/docs" --query "authentication API" --chunks-per-source 3 --json
tvly extract "https://app.example.com" --extract-depth advanced --json
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.
tvly research "competitive landscape of AI code assistants"
tvly research "electric vehicle market analysis" --model pro
tvly research "AI agent frameworks comparison" --stream
tvly research "fintech trends 2025" --model pro -o fintech-report.md
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:
tvly research "topic" --no-wait --json
tvly research status <request_id> --json
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
