---
title: "tavily-ai/skills"
description: "Agent Skills from tavily-ai/skills."
source: https://github.com/tavily-ai/skills
ref: main
license: MIT
licenseName: "MIT License"
canonical: https://skillsdocs.com/tavily-ai/skills
base: https://github.com/tavily-ai/skills/blob/main/
provenance: authored
chapters: 8
inlined: 8
withheld: 0
words: 2844
updated: 2026-09-04T15:16:07Z
generator: "Skills Docs"
---

> **tavily-ai/skills** — every Agent Skill in this repository, inlined verbatim.
>
> Canonical HTML: https://skillsdocs.com/tavily-ai/skills
> Per-skill Markdown: https://skillsdocs.com/tavily-ai/skills/<skill>.md
> Machine manifest: https://skillsdocs.com/tavily-ai/skills/.well-known/agent-skills/index.json
> JSON: https://skillsdocs.com/api/v1/books/tavily-ai/skills
> Install: `npx skills add tavily-ai/skills`
> Upstream: https://github.com/tavily-ai/skills @ `main`
> Licence: MIT
>
> Content is mirrored from GitHub and © its authors, served unmodified. Takedown: https://github.com/DreambaseAI/skillsdocs/issues/new?labels=takedown&title=Takedown+request

# tavily-ai/skills


- **Skills:** 8
- **Inlined:** 8 (licence detected)
- **Words:** 2,844
- **Reading time:** 12 min
- **Stars:** 486

## Table of contents

1. [tavily-best-practices](https://skillsdocs.com/tavily-ai/skills/tavily-best-practices.md) — Build production-ready Tavily integrations with best practices baked in. Reference documentation for developers using coding assistants (Claude Code, Cursor, e…
2. [tavily-cli](https://skillsdocs.com/tavily-ai/skills/tavily-cli.md) — Set up, authenticate, update, troubleshoot, or choose between Tavily CLI web commands. Use when the user asks about the Tavily CLI, installing Tavily skills, f…
3. [tavily-crawl](https://skillsdocs.com/tavily-ai/skills/tavily-crawl.md) — Crawl websites and extract content from multiple pages via the Tavily CLI. Use this skill when the user wants to crawl a site, download documentation, extract…
4. [tavily-dynamic-search](https://skillsdocs.com/tavily-ai/skills/tavily-dynamic-search.md) — Programmatic Tavily search with context isolation. Use when web search or extraction will return large results that need filtering, deduplication, or multi-ste…
5. [tavily-extract](https://skillsdocs.com/tavily-ai/skills/tavily-extract.md) — Extract clean markdown or text content from specific URLs via the Tavily CLI. Use this skill when the user has one or more URLs and wants their content, says "…
6. [tavily-map](https://skillsdocs.com/tavily-ai/skills/tavily-map.md) — Discover and list all URLs on a website without extracting content, via the Tavily CLI. Use this skill when the user wants to find a specific page on a large s…
7. [tavily-research](https://skillsdocs.com/tavily-ai/skills/tavily-research.md) — Conduct comprehensive AI-powered research with citations via the Tavily CLI. Use this skill when the user wants deep research, a detailed report, a comparison,…
8. [tavily-search](https://skillsdocs.com/tavily-ai/skills/tavily-search.md) — Search the web with LLM-optimized results via the Tavily CLI. Use this skill when the user wants to search the web, find articles, look up information, get rec…


## Front matter

_The repository README, verbatim except that relative links are resolved against https://github.com/tavily-ai/skills/blob/main/._

# Tavily Agent Skills

Web search, content extraction, site crawling, URL discovery, and deep research — powered by the Tavily CLI.

## Installation

### Recommended: guided CLI setup

Install the [Tavily CLI](https://github.com/tavily-ai/tavily-cli):

```bash
curl -fsSL https://cli.tavily.com/install.sh | bash
```

On a fresh interactive desktop install, the installer starts `tvly init`
automatically. Otherwise run it after installation:

```bash
tvly init

# Prefer to open the sign-in link yourself
tvly init --no-browser
```

`tvly init` authenticates, detects Claude Code, Codex, and Cursor, installs
these skills, and verifies a live search. It reuses an existing credential and
is safe to rerun. Skills installed this way are pinned to the CLI release, so
run `tvly update` before `tvly init` when refreshing them.

`tvly search` and `tvly extract` also work without authentication, subject to
a keyless rate-limit cap. Use `tvly init --skip-auth` to keep keyless mode while
installing the skills. `map`, `crawl`, and `research` require authentication.

Browser-based OAuth is the preferred interactive sign-in method. `--no-browser`
simply prints the sign-in link instead of opening it automatically; the flow
still returns to a localhost callback on the machine running `tvly`. In remote
sessions, make sure that callback is reachable (SSH may require port
forwarding). For unattended agents or CI, authenticate beforehand or provide
`TAVILY_API_KEY` securely so the process does not wait for human input.

### Manual skill installation

For other agents, or when you only want to install the skills:

```bash
npx skills add https://github.com/tavily-ai/skills
```

Install the CLI separately if needed:

```bash
uv tool install tavily-cli   # or: pip install tavily-cli
```

Then use `tvly init --skip-skills` for guided authentication and verification,
or `tvly login` when you only need to authenticate.

### Keep the CLI current

```bash
tvly update --check
tvly update
```

## Available Skills

| Skill | Description |
|-------|-------------|
| **[tavily-search](https://github.com/tavily-ai/skills/blob/main/skills/tavily-search/SKILL.md)** | Search the web with LLM-optimized results. Supports domain filtering, time ranges, and multiple search depths. |
| **[tavily-extract](https://github.com/tavily-ai/skills/blob/main/skills/tavily-extract/SKILL.md)** | Extract clean markdown/text content from specific URLs. Handles JS-rendered pages. |
| **[tavily-crawl](https://github.com/tavily-ai/skills/blob/main/skills/tavily-crawl/SKILL.md)** | Crawl websites and extract content from multiple pages. Save as local markdown files. |
| **[tavily-map](https://github.com/tavily-ai/skills/blob/main/skills/tavily-map/SKILL.md)** | Discover all URLs on a website without extracting content. Faster than crawling. |
| **[tavily-research](https://github.com/tavily-ai/skills/blob/main/skills/tavily-research/SKILL.md)** | Comprehensive AI-powered research with citations. Multi-source synthesis in 30-120s. |
| **[tavily-dynamic-search](https://github.com/tavily-ai/skills/blob/main/skills/tavily-dynamic-search/SKILL.md)** | Filter and deduplicate large search or extraction results without flooding agent context. |
| **[tavily-cli](https://github.com/tavily-ai/skills/blob/main/skills/tavily-cli/SKILL.md)** | Overview skill with workflow guide, install/auth instructions. |
| **[tavily-best-practices](https://github.com/tavily-ai/skills/blob/main/skills/tavily-best-practices/SKILL.md)** | Reference docs for building production-ready Tavily integrations. |

## Workflow

Start simple, escalate when needed:

1. **Search** — Find pages on a topic (`tvly search "query" --json`)
2. **Extract** — Get content from a specific URL (`tvly extract "https://..." --json`)
3. **Map** — Discover URLs on a site (`tvly map "https://..." --json`)
4. **Crawl** — Bulk extract from a site section (`tvly crawl "https://..." --output-dir ./docs/`)
5. **Research** — Deep multi-source analysis (`tvly research "topic" --model pro`)

---

<!-- chapter:begin slug=tavily-best-practices position=1 -->

## 1. tavily-best-practices

- **Source:** https://github.com/tavily-ai/skills/blob/main/skills/tavily-best-practices/SKILL.md
- **Raw:** https://raw.githubusercontent.com/tavily-ai/skills/main/skills/tavily-best-practices/SKILL.md
- **Markdown:** https://skillsdocs.com/tavily-ai/skills/tavily-best-practices.md
- **Licence:** MIT — https://spdx.org/licenses/MIT.html

Bundled files (6), referenced from this skill's directory:
  - `references/crawl.md` — https://raw.githubusercontent.com/tavily-ai/skills/main/skills/tavily-best-practices/references/crawl.md
  - `references/extract.md` — https://raw.githubusercontent.com/tavily-ai/skills/main/skills/tavily-best-practices/references/extract.md
  - `references/integrations.md` — https://raw.githubusercontent.com/tavily-ai/skills/main/skills/tavily-best-practices/references/integrations.md
  - `references/research.md` — https://raw.githubusercontent.com/tavily-ai/skills/main/skills/tavily-best-practices/references/research.md
  - `references/sdk.md` — https://raw.githubusercontent.com/tavily-ai/skills/main/skills/tavily-best-practices/references/sdk.md
  - `references/search.md` — https://raw.githubusercontent.com/tavily-ai/skills/main/skills/tavily-best-practices/references/search.md

<!-- Verbatim upstream SKILL.md follows, YAML frontmatter included. -->

---
name: tavily-best-practices
description: "Build production-ready Tavily integrations with best practices baked in. Reference documentation for developers using coding assistants (Claude Code, Cursor, etc.) to implement web search, content extraction, crawling, and research in agentic workflows, RAG systems, or autonomous agents."
---

# Tavily

Tavily is a search API designed for LLMs, enabling AI applications to access real-time web data.

## Installation

**Python:**
```bash
pip install tavily-python
```

**JavaScript:**
```bash
npm install @tavily/core
```

See **[references/sdk.md](references/sdk.md)** for complete SDK reference.

## Client Initialization

```python
from tavily import TavilyClient

# Uses TAVILY_API_KEY env var (recommended)
client = TavilyClient()

#With project tracking (for usage organization)
client = TavilyClient(project_id="your-project-id")

# Async client for parallel queries
from tavily import AsyncTavilyClient
async_client = AsyncTavilyClient()
```

## Choosing the Right Method

**For custom agents/workflows:**

| Need | Method |
|------|--------|
| Web search results | `search()` |
| Content from specific URLs | `extract()` |
| Content from entire site | `crawl()` |
| URL discovery from site | `map()` |

**For out-of-the-box research:**

| Need | Method |
|------|--------|
| End-to-end research with AI synthesis | `research()` |

## Quick Reference

### search() - Web Search

```python
response = client.search(
    query="quantum computing breakthroughs",  # Keep under 400 chars
    max_results=10,
    search_depth="advanced"
)
print(response)
```
Key parameters: `query`, `max_results`, `search_depth` (ultra-fast/fast/basic/advanced), `include_domains`, `exclude_domains`, `time_range`

See **[references/search.md](references/search.md)** for complete search reference.

### extract() - URL Content Extraction

```python
# Simple one-step extraction
response = client.extract(
    urls=["https://docs.example.com"],
    extract_depth="advanced"
)
print(response)
```
Key parameters: `urls` (max 20), `extract_depth`, `query`, `chunks_per_source` (1-5)

See **[references/extract.md](references/extract.md)** for complete extract reference.

### crawl() - Site-Wide Extraction

```python
response = client.crawl(
    url="https://docs.example.com",
    instructions="Find API documentation pages",  # Semantic focus
    extract_depth="advanced"
)
print(response)
```
Key parameters: `url`, `max_depth`, `max_breadth`, `limit`, `instructions`, `chunks_per_source`, `select_paths`, `exclude_paths`

See **[references/crawl.md](references/crawl.md)** for complete crawl reference.

### map() - URL Discovery

```python
response = client.map(
    url="https://docs.example.com"
)
print(response)
```

### research() - AI-Powered Research

```python
import time

# For comprehensive multi-topic research
result = client.research(
    input="Analyze competitive landscape for X in SMB market",
    model="pro"  # or "mini" for focused queries, "auto" when unsure
)
request_id = result["request_id"]

# Poll until completed
response = client.get_research(request_id)
while response["status"] not in ["completed", "failed"]:
    time.sleep(10)
    response = client.get_research(request_id)

print(response["content"])  # The research report
```

Key parameters: `input`, `model` ("mini"/"pro"/"auto"), `stream`, `output_schema`, `citation_format`

See **[references/research.md](references/research.md)** for complete research reference.

## Detailed Guides

For complete parameters, response fields, patterns, and examples:

- **[references/sdk.md](references/sdk.md)** - Python & JavaScript SDK reference, async patterns, Hybrid RAG
- **[references/search.md](references/search.md)** - Query optimization, search depth selection, domain filtering, async patterns, post-filtering
- **[references/extract.md](references/extract.md)** - One-step vs two-step extraction, query/chunks for targeting, advanced mode
- **[references/crawl.md](references/crawl.md)** - Crawl vs Map, instructions for semantic focus, use cases, Map-then-Extract pattern
- **[references/research.md](references/research.md)** - Prompting best practices, model selection, streaming, structured output schemas
- **[references/integrations.md](references/integrations.md)** - LangChain, LlamaIndex, CrewAI, Vercel AI SDK, and framework integrations

<!-- chapter:end slug=tavily-best-practices -->

---

<!-- chapter:begin slug=tavily-cli position=2 -->

## 2. tavily-cli

- **Source:** https://github.com/tavily-ai/skills/blob/main/skills/tavily-cli/SKILL.md
- **Raw:** https://raw.githubusercontent.com/tavily-ai/skills/main/skills/tavily-cli/SKILL.md
- **Markdown:** https://skillsdocs.com/tavily-ai/skills/tavily-cli.md
- **Licence:** MIT — https://spdx.org/licenses/MIT.html

<!-- Verbatim upstream SKILL.md follows, YAML frontmatter included. -->

---
name: tavily-cli
description: |
  Set up, authenticate, update, troubleshoot, or choose between Tavily CLI web commands. Use when the user asks about the Tavily CLI, installing Tavily skills, first-time setup, authentication, keyless limits, CLI updates, or which Tavily command to use. For an ordinary web task, use the specific search, extract, map, crawl, research, or dynamic-search skill instead.
allowed-tools: Bash(tvly *)
---

# Tavily CLI

Web search, content extraction, site crawling, URL discovery, and deep research. Returns JSON optimized for LLM consumption.

Requires `tavily-cli`. Search and extract support capped keyless access; map,
crawl, and research require authentication.

Run `tvly --help` or `tvly <command> --help` for full option details.

## Setup

If `tvly` is not installed:

```bash
curl -fsSL https://cli.tavily.com/install.sh | bash
```

Or manually: `uv tool install tavily-cli` / `pip install tavily-cli`

For agent setup, start keyless unless the user asks to sign in or the requested
task needs map, crawl, or research. If the installer did not already complete
setup, run:

```bash
tvly init --skip-auth
```

This installs or updates the Tavily skills and verifies a live keyless search.
Do not look for an API key or authenticate before the first search or extract
request.

When authentication is requested or required, use guided setup:

```bash
tvly init

# Prefer to open the sign-in link yourself
tvly init --no-browser
```

`tvly init` reuses an existing credential, installs or updates the Tavily
skills bundled with that CLI release, and verifies a live search. Run `tvly
update` first when refreshing bundled skills. Use `tvly init --skip-skills`
when the skills are already installed and only authentication or verification
is needed.

Search and extract can run immediately without authentication, subject to a
keyless rate-limit cap. If either command reaches that cap in an interactive
session, run `tvly login` to open browser OAuth, then retry the original command
once. In an unattended environment, report the cap and authentication options
instead of starting an interactive flow. Map, crawl, and research require
authentication. Check the current state only when needed with `tvly --status
--json`.

For authentication without full setup, use `tvly login`, `tvly login
--no-browser`, `tvly login --api-key tvly-YOUR_KEY`, or `TAVILY_API_KEY`.

Browser-based OAuth is the preferred interactive sign-in method. `--no-browser`
simply prints the sign-in link instead of opening it automatically; the flow
still returns to a localhost callback on the machine running `tvly`. In remote
sessions, make sure that callback is reachable (SSH may require port
forwarding). In an unattended agent or CI environment, leave authentication to
the user or use a securely provided `TAVILY_API_KEY`, then resume the original
command.

Keep an existing installation current with `tvly update --check` and `tvly
update`.

## Workflow

Follow this escalation pattern — start simple, escalate when needed:

1. **Search** — No specific URL. Find pages, answer questions, discover sources.
2. **Extract** — Have a URL. Pull its content directly.
3. **Map** — Large site, need to find the right page. Discover URLs first.
4. **Crawl** — Need bulk content from an entire site section.
5. **Research** — Need comprehensive, multi-source analysis with citations.

| Need | Command | When |
|------|---------|------|
| Find pages on a topic | `tvly search` | No specific URL yet |
| Get a page's content | `tvly extract` | Have a URL |
| Find URLs within a site | `tvly map` | Need to locate a specific subpage |
| Bulk extract a site section | `tvly crawl` | Need many pages (e.g., all /docs/) |
| Deep research with citations | `tvly research` | Need multi-source synthesis |

For detailed command reference, use the individual skill for each command (e.g., `tavily-search`, `tavily-crawl`) or run `tvly <command> --help`.

Run `tvly` without a subcommand for the interactive REPL.

## Output

Search, extract, crawl, map, and research support `--json` for structured output.
Result-producing commands support `-o` to save the JSON response; crawl also
supports `--output-dir` for one Markdown file per page. Setup, authentication,
status, and update commands expose `--json` where documented but do not support
`-o`.

```bash
tvly search "react hooks" --json -o results.json
tvly extract "https://example.com/docs" -o docs.json
tvly crawl "https://docs.example.com" --output-dir ./docs/
```

## Tips

- **Always quote URLs** — shell interprets `?` and `&` as special characters.
- **Use `--json` for agentic workflows** when the selected command exposes it.
- **Read from stdin with `-`** — `echo "query" | tvly search -`
- **Exit codes**: 0 = success, 1 = setup/update failure, 2 = bad input, 3 = auth error, 4 = API or live-verification error.

<!-- chapter:end slug=tavily-cli -->

---

<!-- chapter:begin slug=tavily-crawl position=3 -->

## 3. tavily-crawl

- **Source:** https://github.com/tavily-ai/skills/blob/main/skills/tavily-crawl/SKILL.md
- **Raw:** https://raw.githubusercontent.com/tavily-ai/skills/main/skills/tavily-crawl/SKILL.md
- **Markdown:** https://skillsdocs.com/tavily-ai/skills/tavily-crawl.md
- **Licence:** MIT — https://spdx.org/licenses/MIT.html

<!-- Verbatim upstream SKILL.md follows, YAML frontmatter included. -->

---
name: tavily-crawl
description: |
  Crawl websites and extract content from multiple pages via the Tavily CLI. Use this skill when the user wants to crawl a site, download documentation, extract an entire docs section, bulk-extract pages, save a site as local markdown files, or says "crawl", "get all the pages", "download the docs", "extract everything under /docs", "bulk extract", or needs content from many pages on the same domain. Supports depth/breadth control, path filtering, semantic instructions, and saving each page as a local markdown file.
allowed-tools: Bash(tvly *)
---

# tavily crawl

Crawl a website and extract content from multiple pages. Supports saving each page as a local markdown file.

## Before running

Crawl requires authentication. Run the requested command directly when `tvly`
is already authenticated; do not add a status check to every invocation.

If `tvly` is missing, follow the [tavily-cli setup](../tavily-cli/SKILL.md#setup).
If an installed CLI reports an authentication error, use `tvly login` for
authentication only, or `tvly init --skip-skills` when guided verification is
also useful. Browser-based OAuth is preferred when an interactive user can
complete it. `--no-browser` prints the sign-in link instead of opening it, but
still waits for a localhost callback. In an unattended agent or CI environment,
leave authentication to the user or use a securely provided `TAVILY_API_KEY`.
Do not start a second login immediately after guided setup has completed.

## When to use

- You need content from many pages on a site (e.g., all `/docs/`)
- You want to download documentation for offline use
- Step 4 in the [workflow](../tavily-cli/SKILL.md): search → extract → map → **crawl** → research

## Quick start

```bash
# Basic crawl
tvly crawl "https://docs.example.com" --json

# Save each page as a markdown file
tvly crawl "https://docs.example.com" --output-dir ./docs/

# Deeper crawl with limits
tvly crawl "https://docs.example.com" --max-depth 2 --limit 50 --json

# Filter to specific paths
tvly crawl "https://example.com" --select-paths "/api/.*,/guides/.*" --exclude-paths "/blog/.*" --json

# Semantic focus (returns relevant chunks, not full pages)
tvly crawl "https://docs.example.com" --instructions "Find authentication docs" --chunks-per-source 3 --json
```

## Options

| Option | Description |
|--------|-------------|
| `--max-depth` | Levels deep (1-5, default: 1) |
| `--max-breadth` | Links per page (default: 20) |
| `--limit` | Total pages cap (default: 50) |
| `--instructions` | Natural language guidance for semantic focus |
| `--chunks-per-source` | Chunks per page (1-5, requires `--instructions`) |
| `--extract-depth` | `basic` (default) or `advanced` |
| `--format` | `markdown` (default) or `text` |
| `--select-paths` | Comma-separated regex patterns to include |
| `--exclude-paths` | Comma-separated regex patterns to exclude |
| `--select-domains` | Comma-separated regex for domains to include |
| `--exclude-domains` | Comma-separated regex for domains to exclude |
| `--allow-external / --no-external` | Include external links (default: allow) |
| `--include-images` | Include images |
| `--timeout` | Max wait (10-150 seconds) |
| `-o, --output` | Save JSON output to file |
| `--output-dir` | Save each page as a .md file in directory |
| `--json` | Structured JSON output |

## Crawl for context vs. data collection

**For agentic use** (feeding results to an LLM):

Always use `--instructions` + `--chunks-per-source`. Returns only relevant chunks instead of full pages — prevents context explosion.

```bash
tvly crawl "https://docs.example.com" --instructions "API authentication" --chunks-per-source 3 --json
```

**For data collection** (saving to files):

Use `--output-dir` without `--chunks-per-source` to get full pages as markdown files.

```bash
tvly crawl "https://docs.example.com" --max-depth 2 --output-dir ./docs/
```

## Tips

- **Start conservative** — `--max-depth 1`, `--limit 20` — and scale up.
- **Use `--select-paths`** to focus on the section you need.
- **Use map first** to understand site structure before a full crawl.
- **Always set `--limit`** to prevent runaway crawls.

## See also

- [tavily-map](../tavily-map/SKILL.md) — discover URLs before deciding to crawl
- [tavily-extract](../tavily-extract/SKILL.md) — extract individual pages
- [tavily-search](../tavily-search/SKILL.md) — find pages when you don't have a URL

<!-- chapter:end slug=tavily-crawl -->

---

<!-- chapter:begin slug=tavily-dynamic-search position=4 -->

## 4. tavily-dynamic-search

- **Source:** https://github.com/tavily-ai/skills/blob/main/skills/tavily-dynamic-search/SKILL.md
- **Raw:** https://raw.githubusercontent.com/tavily-ai/skills/main/skills/tavily-dynamic-search/SKILL.md
- **Markdown:** https://skillsdocs.com/tavily-ai/skills/tavily-dynamic-search.md
- **Licence:** MIT — https://spdx.org/licenses/MIT.html

<!-- Verbatim upstream SKILL.md follows, YAML frontmatter included. -->

---
name: tavily-dynamic-search
description: |
  Programmatic Tavily search with context isolation. Use when web search or extraction will return large results that need filtering, deduplication, or multi-step triage before they enter the model context. Use tavily-search for ordinary lookups and tavily-research for end-to-end cited synthesis.
allowed-tools: Bash(tvly *), Bash(python3 *), Bash(uv run *), Bash(jq *)
---

# Tavily Dynamic Search

Keep large raw web payloads on disk and return only the evidence needed for the
task. This is useful when using `--include-raw-content`, combining several
queries, or extracting multiple long pages. Do not use this workflow for a
simple lookup that a normal `tvly search --json` can answer directly.

## Before running

Search and extract support capped keyless access. Run them directly when `tvly`
is available. If `tvly` is missing, follow the
[tavily-cli setup](../tavily-cli/SKILL.md#setup). Do not look for an API key or
authenticate before the first request. If the keyless cap is reached in an
interactive session, run `tvly login` to open browser OAuth, then retry the
blocked request once. In an unattended environment, report the cap and
authentication options instead of starting an interactive flow.

## Workflow

1. Search broadly without raw content and inspect titles, URLs, scores, and
   snippets.
2. Fetch full content only for the best sources.
3. When raw output could be large, save it with `-o` and filter the file before
   printing anything to the model context.
4. Preserve source URLs beside every extracted fact.

When the user restricts evidence to official or named domains, validate the
hostname of every selected URL during local filtering. `--include-domains`
narrows the search but is not proof that every returned result belongs to an
allowed host. If full-page extraction is unavailable, label conclusions as
search-snippet evidence instead of implying that the page body was verified.

Keep the process in one turn when the relevant sources and filters are already
known. Use another turn only when the first search changes what should be
extracted.

Create a unique temporary task directory before saving evidence so concurrent
agents do not overwrite one another. Python's `tempfile.mkdtemp()` is available
when `mktemp` is not permitted. Reuse that directory for all raw and filtered
artifacts from the task.

## Small result: filter a direct JSON response

For a small search response, a pipe is enough:

```bash
tvly search "query" --max-results 5 --json | python3 -c '
import json, sys
data = json.load(sys.stdin)
for result in data.get("results", []):
    score = result.get("score") or 0
    title = result.get("title") or ""
    print(f"[{score:.2f}] {title}")
    print(result.get("url", ""))
    print(result.get("content", "")[:300])
'
```

Do not discard stderr. Authentication failures, keyless-cap messages, and API
errors are actionable and must remain visible.

## Large result: save first, then filter

Use the CLI's file output so raw page content does not pass through the tool
response:

```bash
tvly search "query" \
  --include-raw-content markdown \
  --max-results 8 \
  --json \
  -o /tmp/tavily-search-results.json
```

Then print only bounded evidence:

```bash
python3 -c '
import json
from pathlib import Path

data = json.loads(Path("/tmp/tavily-search-results.json").read_text())
for result in data.get("results", []):
    title = result.get("title") or ""
    url = result.get("url") or ""
    print(f"## {title}")
    print(f"URL: {url}")
    print((result.get("raw_content") or result.get("content") or "")[:1200])
    print()
'
```

Adjust the filtering logic to the question. Prefer relevant paragraphs or
fields over fixed character slices when the target information is known. Aim
for roughly 150-600 tokens per source unless a table or code block genuinely
requires more.

## Targeted extraction

When search identifies the right URLs, extract only those pages:

```bash
tvly extract "https://example.com/article" \
  --json \
  -o /tmp/tavily-extract-results.json
```

For topic-focused pages, let Tavily reduce the response before local filtering:

```bash
tvly extract "https://example.com/docs" \
  --query "authentication API" \
  --chunks-per-source 3 \
  --json \
  -o /tmp/tavily-extract-results.json
```

## Multiple queries

For multi-angle research, run a small set of focused searches, deduplicate by
URL, and rank before extracting. Use `subprocess.run(..., capture_output=True,
text=True)` when orchestrating commands in Python. Check `returncode`; if a
command fails, surface its stderr and stop or retry deliberately. Never use a
blanket `except Exception: continue` that hides missing evidence.

## Response shapes

`tvly search --json` returns `query`, optional `answer`, `results`, and
`response_time`. Each result commonly contains `url`, `title`, `content`,
`score`, and optional `raw_content`.

`tvly extract --json` returns `results`, `failed_results`, and
`response_time`. Each successful result commonly contains `url`,
`raw_content`, and optional images.

Treat fields as optional and use `.get()` while filtering. Inspect
`failed_results` instead of assuming every requested URL succeeded.

## Useful options

| Option | Purpose |
|--------|---------|
| `--max-results` | Bound the search result count; default 5, maximum 20 |
| `--depth` | Choose `ultra-fast`, `fast`, `basic`, or `advanced` |
| `--time-range` | Restrict results to `day`, `week`, `month`, or `year` |
| `--include-domains` | Restrict results to a comma-separated list of trusted domains |
| `--exclude-domains` | Exclude a comma-separated list of domains |
| `--include-raw-content` | Include full content as `markdown` or `text` |
| `-o, --output` | Save the complete response to a file |

Use `jq` only for short filters when Python is unavailable:

```bash
tvly search "query" --json | jq '[.results[] | {title, url, score, content}]'
```

<!-- chapter:end slug=tavily-dynamic-search -->

---

<!-- chapter:begin slug=tavily-extract position=5 -->

## 5. tavily-extract

- **Source:** https://github.com/tavily-ai/skills/blob/main/skills/tavily-extract/SKILL.md
- **Raw:** https://raw.githubusercontent.com/tavily-ai/skills/main/skills/tavily-extract/SKILL.md
- **Markdown:** https://skillsdocs.com/tavily-ai/skills/tavily-extract.md
- **Licence:** MIT — https://spdx.org/licenses/MIT.html

<!-- Verbatim upstream SKILL.md follows, YAML frontmatter included. -->

---
name: tavily-extract
description: |
  Extract clean markdown or text content from specific URLs via the Tavily CLI. Use this skill when the user has one or more URLs and wants their content, says "extract", "grab the content from", "pull the text from", "get the page at", "read this webpage", or needs clean text from web pages. Handles JavaScript-rendered pages, returns LLM-optimized markdown, and supports query-focused chunking for targeted extraction. Can process up to 20 URLs in a single call.
allowed-tools: Bash(tvly *)
---

# tavily extract

Extract clean markdown or text content from one or more URLs.

## Before running

Run extract directly when `tvly` is available. Extract supports capped keyless
access, so do not look for an API key or authenticate before the first request.

If `tvly` is missing, follow the [tavily-cli setup](../tavily-cli/SKILL.md#setup)
before retrying. If the keyless cap is reached in an interactive session, run
`tvly login` to open browser OAuth, then retry the original extraction once. In
an unattended environment, report the cap and authentication options instead
of starting an interactive flow. Do not start a second login immediately after
guided setup has completed.

## When to use

- You have a specific URL and want its content
- You need text from JavaScript-rendered pages
- Step 2 in the [workflow](../tavily-cli/SKILL.md): search → **extract** → map → crawl → research

## Quick start

```bash
# 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.json
```

## Options

| 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 the JSON response to a file |
| `--json` | Structured JSON output |

## Extract depth

| Depth | When to use |
|-------|-------------|
| `basic` | Simple pages, fast — try this first |
| `advanced` | JS-rendered SPAs, dynamic content, tables |

## Tips

- **Max 20 URLs per request** — batch larger lists into multiple calls.
- **Use `--query` + `--chunks-per-source`** to get only relevant content instead of full pages.
- **Try `basic` first**, fall back to `advanced` if content is missing.
- **Set `--timeout`** for slow pages (up to 60s).
- **Inspect `failed_results` even after exit code 0.** A successful request can
  still return no extracted pages. Retry the affected URL with `advanced` when
  appropriate, otherwise report the per-URL failure instead of treating the
  request as complete.
- If search results already contain the content you need (via `--include-raw-content`), skip the extract step.

## See also

- [tavily-search](../tavily-search/SKILL.md) — find pages when you don't have a URL
- [tavily-crawl](../tavily-crawl/SKILL.md) — extract content from many pages on a site

<!-- chapter:end slug=tavily-extract -->

---

<!-- chapter:begin slug=tavily-map position=6 -->

## 6. tavily-map

- **Source:** https://github.com/tavily-ai/skills/blob/main/skills/tavily-map/SKILL.md
- **Raw:** https://raw.githubusercontent.com/tavily-ai/skills/main/skills/tavily-map/SKILL.md
- **Markdown:** https://skillsdocs.com/tavily-ai/skills/tavily-map.md
- **Licence:** MIT — https://spdx.org/licenses/MIT.html

<!-- Verbatim upstream SKILL.md follows, YAML frontmatter included. -->

---
name: tavily-map
description: |
  Discover and list all URLs on a website without extracting content, via the Tavily CLI. Use this skill when the user wants to find a specific page on a large site, list all URLs, see the site structure, find where something is on a domain, or says "map the site", "find the URL for", "what pages are on", "list all pages", or "site structure". Faster than crawling — returns URLs only. Essential when you know the site but not the exact page. Combine with extract for targeted content retrieval.
allowed-tools: Bash(tvly *)
---

# tavily map

Discover URLs on a website without extracting content. Faster than crawling.

## Before running

Map requires authentication. Run the requested command directly when `tvly`
is already authenticated; do not add a status check to every invocation.

If `tvly` is missing, follow the [tavily-cli setup](../tavily-cli/SKILL.md#setup).
If an installed CLI reports an authentication error, use `tvly login` for
authentication only, or `tvly init --skip-skills` when guided verification is
also useful. Browser-based OAuth is preferred when an interactive user can
complete it. `--no-browser` prints the sign-in link instead of opening it, but
still waits for a localhost callback. In an unattended agent or CI environment,
leave authentication to the user or use a securely provided `TAVILY_API_KEY`.
Do not start a second login immediately after guided setup has completed.

## When to use

- You need to find a specific subpage on a large site
- You want a list of all URLs before deciding what to extract or crawl
- Step 3 in the [workflow](../tavily-cli/SKILL.md): search → extract → **map** → crawl → research

## Quick start

```bash
# Discover all URLs
tvly map "https://docs.example.com" --json

# With natural language filtering
tvly map "https://docs.example.com" --instructions "Find API docs and guides" --json

# Filter by path
tvly map "https://example.com" --select-paths "/blog/.*" --limit 500 --json

# Deep map
tvly map "https://example.com" --max-depth 3 --limit 200 --json
```

## Options

| Option | Description |
|--------|-------------|
| `--max-depth` | Levels deep (1-5, default: 1) |
| `--max-breadth` | Links per page (default: 20) |
| `--limit` | Max URLs to discover (default: 50) |
| `--instructions` | Natural language guidance for URL filtering |
| `--select-paths` | Comma-separated regex patterns to include |
| `--exclude-paths` | Comma-separated regex patterns to exclude |
| `--select-domains` | Comma-separated regex for domains to include |
| `--exclude-domains` | Comma-separated regex for domains to exclude |
| `--allow-external / --no-external` | Include external links |
| `--timeout` | Max wait (10-150 seconds) |
| `-o, --output` | Save the JSON response to a file |
| `--json` | Structured JSON output |

## Map + Extract pattern

Use `map` to find the right page, then `extract` it. This is often more efficient than crawling an entire site:

```bash
# Step 1: Find the authentication docs
tvly map "https://docs.example.com" --instructions "authentication" --json

# Step 2: Extract the specific page you found
tvly extract "https://docs.example.com/api/authentication" --json
```

## Tips

- **Map is URL discovery only** — no content extraction. Use `extract` or `crawl` for content.
- **Map + extract beats crawl** when you only need a few specific pages from a large site.
- **Use `--instructions`** for semantic filtering when path patterns aren't enough.

## See also

- [tavily-extract](../tavily-extract/SKILL.md) — extract content from URLs you discover
- [tavily-crawl](../tavily-crawl/SKILL.md) — bulk extract when you need many pages

<!-- chapter:end slug=tavily-map -->

---

<!-- chapter:begin slug=tavily-research position=7 -->

## 7. tavily-research

- **Source:** https://github.com/tavily-ai/skills/blob/main/skills/tavily-research/SKILL.md
- **Raw:** https://raw.githubusercontent.com/tavily-ai/skills/main/skills/tavily-research/SKILL.md
- **Markdown:** https://skillsdocs.com/tavily-ai/skills/tavily-research.md
- **Licence:** MIT — https://spdx.org/licenses/MIT.html

<!-- Verbatim upstream SKILL.md follows, YAML frontmatter included. -->

---
name: tavily-research
description: |
  Conduct comprehensive AI-powered research with citations via the Tavily CLI. Use this skill when the user wants deep research, a detailed report, a comparison, market analysis, literature review, or says "research", "investigate", "analyze in depth", "compare X vs Y", "what does the market look like for", or needs multi-source synthesis with explicit citations. Returns a structured report grounded in web sources. Takes 30-120 seconds. For quick fact-finding, use tavily-search instead.
allowed-tools: Bash(tvly *)
---

# tavily research

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

## Before running

Research requires authentication. Run the requested command directly when
`tvly` is already authenticated; do not add a status check to every invocation.

If `tvly` is missing, follow the [tavily-cli setup](../tavily-cli/SKILL.md#setup).
If an installed CLI reports an authentication error, use `tvly login` for
authentication only, or `tvly init --skip-skills` when guided verification is
also useful. Browser-based OAuth is preferred when an interactive user can
complete it. `--no-browser` prints the sign-in link instead of opening it, but
still waits for a localhost callback. In an unattended agent or CI environment,
leave authentication to the user or use a securely provided `TAVILY_API_KEY`.
Do not start a second login immediately after guided setup has completed.

## When to use

- You need comprehensive, multi-source analysis
- The user wants a comparison, market report, or literature review
- Quick searches aren't enough — you need synthesis with citations
- Step 5 in the [workflow](../tavily-cli/SKILL.md): search → extract → map → crawl → **research**

## Quick start

```bash
# 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.json

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

## Options

| 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 the JSON response to a 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:

```bash
# 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
```

## Tips

- **Research takes 30-120 seconds** — use `--stream` to see progress in real-time.
- **Use `--model pro`** for complex comparisons or multi-faceted topics.
- **Use `--output-schema`** to get structured JSON output matching a custom schema.
- **For quick facts**, use `tvly search` instead — research is for deep synthesis.
- Read from stdin: `echo "query" | tvly research - --json`

## See also

- [tavily-search](../tavily-search/SKILL.md) — quick web search for simple lookups
- [tavily-crawl](../tavily-crawl/SKILL.md) — bulk extract from a site for your own analysis

<!-- chapter:end slug=tavily-research -->

---

<!-- chapter:begin slug=tavily-search position=8 -->

## 8. tavily-search

- **Source:** https://github.com/tavily-ai/skills/blob/main/skills/tavily-search/SKILL.md
- **Raw:** https://raw.githubusercontent.com/tavily-ai/skills/main/skills/tavily-search/SKILL.md
- **Markdown:** https://skillsdocs.com/tavily-ai/skills/tavily-search.md
- **Licence:** MIT — https://spdx.org/licenses/MIT.html

<!-- Verbatim upstream SKILL.md follows, YAML frontmatter included. -->

---
name: tavily-search
description: |
  Search the web with LLM-optimized results via the Tavily CLI. Use this skill when the user wants to search the web, find articles, look up information, get recent news, discover sources, or says "search for", "find me", "look up", "what's the latest on", "find articles about", or needs current information from the internet. Returns relevant results with content snippets, relevance scores, and metadata — optimized for LLM consumption. Supports domain filtering, time ranges, and multiple search depths.
allowed-tools: Bash(tvly *)
---

# tavily search

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

## Before running

Run search directly when `tvly` is available. Search supports capped keyless
access, so do not look for an API key or authenticate before the first request.

If `tvly` is missing, follow the [tavily-cli setup](../tavily-cli/SKILL.md#setup)
before retrying. If the keyless cap is reached in an interactive session, run
`tvly login` to open browser OAuth, then retry the original search once. In an
unattended environment, report the cap and authentication options instead of
starting an interactive flow. Do not start a second login immediately after
guided setup has completed.

## When to use

- You need to find information on any topic
- You don't have a specific URL yet
- First step in the [workflow](../tavily-cli/SKILL.md): **search** → extract → map → crawl → research

## Quick start

```bash
# 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
```

## Options

| 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 the JSON response to a 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 |

## Tips

- **Keep queries under 400 characters** — think search query, not prompt.
- **Break complex queries into sub-queries** for better results.
- **Use `--include-raw-content`** when you need full page text (saves a separate extract call).
- **Use `--include-domains`** to focus on trusted sources.
- **Use `--time-range`** for recent information.
- **Verify identity-sensitive facts at the exact primary source.** For releases,
  versions, ownership, or similarly named projects, confirm the official
  repository or domain instead of trusting a generated answer or package-name
  match alone.
- Read from stdin: `echo "query" | tvly search - --json`

## See also

- [tavily-extract](../tavily-extract/SKILL.md) — extract content from specific URLs
- [tavily-research](../tavily-research/SKILL.md) — comprehensive multi-source research

<!-- chapter:end slug=tavily-search -->