Introduction
# Tavily Search š
AI-powered web search platform with 5 modes: Search, Extract, Crawl, Map, and Research.
## Requirements
- `TAVILY_API_KEY` environment variable
## Configuration
| Env Variable | Default | Description | |---|---|---| | `TAVILY_API_KEY` | ā | **Required.** Tavily API key |
Set in OpenClaw config: ```json { "env": { "TAVILY_API_KEY": "tvly-..." } } ```
## Script Location
```bash python3 skills/tavily/lib/tavily_search.py <command> "query" [options] ```
---
## Commands
### search ā Web Search (Default)
General-purpose web search with optional LLM-synthesized answer.
```bash python3 lib/tavily_search.py search "query" [options] ```
**Examples:** ```bash # Basic search python3 lib/tavily_search.py search "latest AI news"
# With LLM answer python3 lib/tavily_search.py search "what is quantum computing" --answer
# Advanced depth (better results, 2 credits) python3 lib/tavily_search.py search "climate change solutions" --depth advanced
# Time-filtered python3 lib/tavily_search.py search "OpenAI announcements" --time week
# Domain filtering python3 lib/tavily_search.py search "machine learning" --include-domains arxiv.org,nature.com
# Country boost python3 lib/tavily_search.py search "tech startups" --country US
# With raw content and images python3 lib/tavily_search.py search "solar energy" --raw --images -n 10
# JSON output python3 lib/tavily_search.py search "bitcoin price" --json ```
**Output format (text):** ``` Answer: <LLM-synthesized answer if --answer>
Results: 1. Result Title https://example.com/article Content snippet from the page...
2. Another Result https://example.com/other Another snippet... ```
---
### news ā News Search
Search optimized for news articles. Sets `topic=news`.
```bash python3 lib/tavily_search.py news "query" [options] ```
**Examples:** ```bash python3 lib/tavily_search.py news "AI regulation" python3 lib/tavily_search.py news "Israel tech" --time day --answer python3 lib/tavily_search.py news "stock market" --time week -n 10 ```
---
### finance ā Finance Search
Search optimized for financial data and news. Sets `topic=finance`.
```bash python3 lib/tavily_search.py finance "query" [options] ```
**Examples:** ```bash python3 lib/tavily_search.py finance "NVIDIA stock analysis" python3 lib/tavily_search.py finance "cryptocurrency market trends" --time month python3 lib/tavily_search.py finance "S&P 500 forecast 2026" --answer ```
---
### extract ā Extract Content from URLs
Extract readable content from one or more URLs.
```bash python3 lib/tavily_search.py extract URL [URL...] [options] ```
**Parameters:** - `urls`: One or more URLs to extract (positional args) - `--depth basic|advanced`: Extraction depth - `--format markdown|text`: Output format (default: markdown) - `--query "text"`: Rerank extracted chunks by relevance to query
**Examples:** ```bash # Extract single URL python3 lib/tavily_search.py extract "https://example.com/article"
# Extract multiple URLs python3 lib/tavily_search.py extract "https://url1.com" "https://url2.com"
# Advanced extraction with relevance reranking python3 lib/tavily_search.py extract "https://arxiv.org/paper" --depth advanced --query "transformer architecture"
# Text format output python3 lib/tavily_search.py extract "https://example.com" --format text ```
**Output format:** ``` URL: https://example.com/article āāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāā <Extracted content in markdown/text>
URL: https://another.com/page āāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāā <Extracted content> ```
---
### crawl ā Crawl a Website
Crawl a website starting from a root URL, following links.
```bash python3 lib/tavily_search.py crawl URL [options] ```
**Parameters:** - `url`: Root URL to start crawling - `--depth basic|advanced`: Crawl depth - `--max-depth N`: Maximum link depth to follow (default: 2) - `--max-breadth N`: Maximum pages per depth level (default: 10) - `--limit N`: Maximum total pages (default: 10) - `--instructions "text"`: Natural language crawl instructions - `--select-paths p1,p2`: Only crawl these path patterns - `--exclude-paths p1,p2`: Skip these path patterns - `--format markdown|text`: Output format
**Examples:** ```bash # Basic crawl python3 lib/tavily_search.py crawl "https://docs.example.com"
# Focused crawl with instructions python3 lib/tavily_search.py crawl "https://docs.python.org" --instructions "Find all asyncio documentation" --limit 20
# Crawl specific paths only python3 lib/tavily_search.py crawl "https://example.com" --select-paths "/blog,/docs" --max-depth 3 ```
**Output format:** ``` Crawled 5 pages from https://docs.example.com
Page 1: https://docs.example.com/intro āāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāā <Content>
Page 2: https://docs.example.com/guide āāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāā <Content> ```
---
### map ā Sitemap Discovery
Discover all URLs on a website (sitemap).
```bash python3 lib/tavily_search.py map URL [options] ```
**Parameters:** - `url`: Root URL to map - `--max-depth N`: Depth to follow (default: 2) - `--max-breadth N`: Breadth per level (default: 20) - `--limit N`: Maximum URLs (default: 50)
**Examples:** ```bash # Map a site python3 lib/tavily_search.py map "https://example.com"
# Deep map python3 lib/tavily_search.py map "https://docs.python.org" --max-depth 3 --limit 100 ```
**Output format:** ``` Sitemap for https://example.com (42 URLs found):
1. https://example.com/ 2. https://example.com/about 3. https://example.com/blog ... ```
---
### research ā Deep Research
Comprehensive AI-powered research on a topic with citations.
```bash python3 lib/tavily_search.py research "query" [options] ```
**Parameters:** - `query`: Research question - `--model mini|pro|auto`: Research model (default: auto) - `mini`: Faster, cheaper - `pro`: More thorough - `auto`: Let Tavily decide - `--json`: JSON output (supports structured output schema)
**Examples:** ```bash # Basic research python3 lib/tavily_search.py research "Impact of AI on healthcare in 2026"
# Pro model for thorough research python3 lib/tavily_search.py research "Comparison of quantum computing approaches" --model pro
# JSON output python3 lib/tavily_search.py research "Electric vehicle market analysis" --json ```
**Output format:** ``` Research: Impact of AI on healthcare in 2026
<Comprehensive research report with citations>
Sources: [1] https://source1.com [2] https://source2.com ... ```
---
## Options Reference
| Option | Applies To | Description | Default | |---|---|---|---| | `--depth basic\|advanced` | search, news, finance, extract | Search/extraction depth | basic | | `--time day\|week\|month\|year` | search, news, finance | Time range filter | none | | `-n NUM` | search, news, finance | Max results (0-20) | 5 | | `--answer` | search, news, finance | Include LLM answer | off | | `--raw` | search, news, finance | Include raw page content | off | | `--images` | search, news, finance | Include image URLs | off | | `--include-domains d1,d2` | search, news, finance | Only these domains | none | | `--exclude-domains d1,d2` | search, news, finance | Exclude these domains | none | | `--country XX` | search, news, finance | Boost country results | none | | `--json` | all | Structured JSON output | off | | `--format markdown\|text` | extract, crawl | Content format | markdown | | `--query "text"` | extract | Relevance reranking query | none | | `--model mini\|pro\|auto` | research | Research model | auto | | `--max-depth N` | crawl, map | Max link depth | 2 | | `--max-breadth N` | crawl, map | Max pages per level | 10/20 | | `--limit N` | crawl, map | Max total pages/URLs | 10/50 | | `--instructions "text"` | crawl | Natural language instructions | none | | `--select-paths p1,p2` | crawl | Include path patterns | none | | `--exclude-paths p1,p2` | crawl | Exclude path patterns | none |
---
## Error Handling
- **Missing API key:** Clear error message with setup instructions. - **401 Unauthorized:** Invalid API key. - **429 Rate Limit:** Rate limit exceeded, try again later. - **Network errors:** Descriptive error with cause. - **No results:** Clean "No results found." message. - **Timeout:** 30-second timeout on all HTTP requests.
---
## Credits & Pricing
| API | Basic | Advanced | |---|---|---| | Search | 1 credit | 2 credits | | Extract | 1 credit/URL | 2 credits/URL | | Crawl | 1 credit/page | 2 credits/page | | Map | 1 credit | 1 credit | | Research | Varies by model | - |
---
## Install
```bash bash skills/tavily/install.sh ```