[H1][TAVILY-TOOLS]
Dictum: Command-specific arguments enforce correct invocation.
Execute Tavily AI web operations through unified Python CLI.
[IMPORTANT] search requires --query; extract requires --urls; crawl/map require --url; research requires --query. 1Password injects API key automatically.
[1][COMMANDS]
| [CMD] |
[REQUIRED_ARG] |
[PURPOSE] |
| search |
--query TEXT |
AI-powered web search with results |
| extract |
--urls URLS |
Extract content from one or more URLs |
| crawl |
--url URL |
Crawl website from base URL |
| map |
--url URL |
Map website URL structure |
| research |
--query TEXT |
Multi-step deep research with report |
[2][USAGE]
# Search
uv run .claude/skills/tavily-tools/scripts/tavily.py search --query "Vite 7 new features"
uv run .claude/skills/tavily-tools/scripts/tavily.py search --query "React 19" --topic news
uv run .claude/skills/tavily-tools/scripts/tavily.py search --query "Effect-TS" --search-depth advanced --max-results 20
# Extract content from URLs
uv run .claude/skills/tavily-tools/scripts/tavily.py extract --urls "https://example.com"
uv run .claude/skills/tavily-tools/scripts/tavily.py extract --urls "https://a.com,https://b.com" --format text
# Crawl website
uv run .claude/skills/tavily-tools/scripts/tavily.py crawl --url "https://docs.effect.website"
uv run .claude/skills/tavily-tools/scripts/tavily.py crawl --url "https://nx.dev" --max-depth 3 --max-breadth 50
# Map site structure
uv run .claude/skills/tavily-tools/scripts/tavily.py map --url "https://nx.dev"
uv run .claude/skills/tavily-tools/scripts/tavily.py map --url "https://effect.website" --max-depth 2 --limit 200
# Deep research (multi-step, structured report)
uv run .claude/skills/tavily-tools/scripts/tavily.py research --query "Nx 22 migration strategies"
uv run .claude/skills/tavily-tools/scripts/tavily.py research --query "Effect vs RxJS comparison" --model pro
[3][ARGUMENTS]
search: --query TEXT [options]
--query — Search query (required)--topic — Topic: general, news (default: general)--search-depth — Depth: basic, advanced (default: basic)--max-results — Number of results (default: 10)--include-images — Include images in results (flag)--include-raw-content — Include raw HTML (flag)--include-domains — Comma-separated whitelist--exclude-domains — Comma-separated blacklist--time-range — Time filter (e.g., day, week, month, year)--country — Country code for localized results
extract: --urls URLS [options]
--urls — Comma-separated URLs (required)--extract-depth — Depth: basic, advanced (default: basic)--format — Output: markdown, text (default: markdown)--include-images — Include images (flag)
crawl: --url URL [options]
--url — Base URL to crawl (required)--max-depth — Crawl depth (default: 1)--max-breadth — Pages per depth level (default: 20)--limit — Total page limit (default: 50)--allow-external — Follow external links (flag)--select-paths — Comma-separated path filters--instructions — Natural language crawl instructions
map: --url URL [options]
--url — Base URL to map (required)--max-depth — Map depth (default: 1)--max-breadth — URLs per depth level (default: 20)--limit — Total URL limit (default: 50)--allow-external — Include external URLs (flag)
research: --query TEXT [options]
--query — Research question (required)--model — Research agent: mini, pro, auto (default: auto)
[4][OUTPUT]
Commands return: {"status": "success|error", ...}.
| [INDEX] |
[CMD] |
[RESPONSE] |
| [1] |
search |
{query, results[], images[], answer} |
| [2] |
extract |
{urls[], results[], failed[]} |
| [3] |
crawl |
{base_url, results[], urls_crawled} |
| [4] |
map |
{base_url, urls[], total_mapped} |
| [5] |
research |
{query, report, sources[]} |
[5][ENVIRONMENT]
| [VAR] |
[REQUIRED] |
[DESCRIPTION] |
TAVILY_API_KEY |
Yes |
Tavily API key (1Password injected) |
[6][ERROR_HANDLING]
- HTTP errors print
[ERROR] <status>: <body> and exit 1
- Rate limit (429): retry after backoff
extract reports per-URL failures in failed[] array (partial success)crawl/map respect --limit to prevent runaway requestsresearch uses extended timeout for multi-step processing
1---2name: tavily-tools3description: Executes Tavily AI search, extraction, crawling, mapping, and deep research via Python CLI. Use when web search, URL content extraction, site crawling, or multi-step research needed.4---56# [H1][TAVILY-TOOLS]7>**Dictum:** *Command-specific arguments enforce correct invocation.*89<br>1011Execute Tavily AI web operations through unified Python CLI.1213[IMPORTANT] `search` requires `--query`; `extract` requires `--urls`; `crawl`/`map` require `--url`; `research` requires `--query`. 1Password injects API key automatically.1415---16## [1][COMMANDS]1718| [CMD] | [REQUIRED_ARG] | [PURPOSE] |19| -------- | -------------- | ------------------------------------- |20| search | `--query TEXT` | AI-powered web search with results |21| extract | `--urls URLS` | Extract content from one or more URLs |22| crawl | `--url URL` | Crawl website from base URL |23| map | `--url URL` | Map website URL structure |24| research | `--query TEXT` | Multi-step deep research with report |2526---27## [2][USAGE]2829```bash30# Search31uv run .claude/skills/tavily-tools/scripts/tavily.py search --query "Vite 7 new features"32uv run .claude/skills/tavily-tools/scripts/tavily.py search --query "React 19" --topic news33uv run .claude/skills/tavily-tools/scripts/tavily.py search --query "Effect-TS" --search-depth advanced --max-results 203435# Extract content from URLs36uv run .claude/skills/tavily-tools/scripts/tavily.py extract --urls "https://example.com"37uv run .claude/skills/tavily-tools/scripts/tavily.py extract --urls "https://a.com,https://b.com" --format text3839# Crawl website40uv run .claude/skills/tavily-tools/scripts/tavily.py crawl --url "https://docs.effect.website"41uv run .claude/skills/tavily-tools/scripts/tavily.py crawl --url "https://nx.dev" --max-depth 3 --max-breadth 504243# Map site structure44uv run .claude/skills/tavily-tools/scripts/tavily.py map --url "https://nx.dev"45uv run .claude/skills/tavily-tools/scripts/tavily.py map --url "https://effect.website" --max-depth 2 --limit 2004647# Deep research (multi-step, structured report)48uv run .claude/skills/tavily-tools/scripts/tavily.py research --query "Nx 22 migration strategies"49uv run .claude/skills/tavily-tools/scripts/tavily.py research --query "Effect vs RxJS comparison" --model pro50```5152---53## [3][ARGUMENTS]5455**search**: `--query TEXT [options]`56- `--query` — Search query (required)57- `--topic` — Topic: `general`, `news` (default: `general`)58- `--search-depth` — Depth: `basic`, `advanced` (default: `basic`)59- `--max-results` — Number of results (default: `10`)60- `--include-images` — Include images in results (flag)61- `--include-raw-content` — Include raw HTML (flag)62- `--include-domains` — Comma-separated whitelist63- `--exclude-domains` — Comma-separated blacklist64- `--time-range` — Time filter (e.g., `day`, `week`, `month`, `year`)65- `--country` — Country code for localized results6667**extract**: `--urls URLS [options]`68- `--urls` — Comma-separated URLs (required)69- `--extract-depth` — Depth: `basic`, `advanced` (default: `basic`)70- `--format` — Output: `markdown`, `text` (default: `markdown`)71- `--include-images` — Include images (flag)7273**crawl**: `--url URL [options]`74- `--url` — Base URL to crawl (required)75- `--max-depth` — Crawl depth (default: `1`)76- `--max-breadth` — Pages per depth level (default: `20`)77- `--limit` — Total page limit (default: `50`)78- `--allow-external` — Follow external links (flag)79- `--select-paths` — Comma-separated path filters80- `--instructions` — Natural language crawl instructions8182**map**: `--url URL [options]`83- `--url` — Base URL to map (required)84- `--max-depth` — Map depth (default: `1`)85- `--max-breadth` — URLs per depth level (default: `20`)86- `--limit` — Total URL limit (default: `50`)87- `--allow-external` — Include external URLs (flag)8889**research**: `--query TEXT [options]`90- `--query` — Research question (required)91- `--model` — Research agent: `mini`, `pro`, `auto` (default: `auto`)9293---94## [4][OUTPUT]9596Commands return: `{"status": "success|error", ...}`.9798| [INDEX] | [CMD] | [RESPONSE] |99| :-----: | ---------- | -------------------------------------- |100| [1] | `search` | `{query, results[], images[], answer}` |101| [2] | `extract` | `{urls[], results[], failed[]}` |102| [3] | `crawl` | `{base_url, results[], urls_crawled}` |103| [4] | `map` | `{base_url, urls[], total_mapped}` |104| [5] | `research` | `{query, report, sources[]}` |105106---107## [5][ENVIRONMENT]108109| [VAR] | [REQUIRED] | [DESCRIPTION] |110| ---------------- | ---------- | ----------------------------------- |111| `TAVILY_API_KEY` | Yes | Tavily API key (1Password injected) |112113---114## [6][ERROR_HANDLING]115116- HTTP errors print `[ERROR] <status>: <body>` and exit 1117- Rate limit (429): retry after backoff118- `extract` reports per-URL failures in `failed[]` array (partial success)119- `crawl`/`map` respect `--limit` to prevent runaway requests120- `research` uses extended timeout for multi-step processing
bsamiee