Tavily CLI

Search, extract, map, crawl, and research from the terminal with Tavily.

Run

tavily --help

tavily <command> --help

for full option details.

Prerequisites

Must be installed and authenticated.

Check:

bash

tavily status

If not authenticated:

bash

tavily login

If not installed/configured, follow rules/install.md. For output handling and untrusted content guidelines, follow rules/security.md.

Workflow

Use this escalation pattern:

Search - no exact URL yet, need discovery.
Extract - already have URL(s), need content.
Map - need URL discovery within one site before extracting.
Crawl - need bulk content from a site section.
Research - need synthesized output and citations from Tavily research API.
Research Status - track/poll an existing research request.

Need	Command	When
Discover sources on a topic	`search`	No trusted URL yet
Get page content from URL(s)	`extract`	URL(s) already known
Discover pages inside a domain	`map`	Need URL inventory/filtering
Bulk extract many pages	`crawl`	Need multi-page dataset
Run guided long-form research	`research`	Need synthesis, not raw pages
Poll existing research job	`research-status`	Have `request-id` already

What this CLI does not provide today:

No dedicated
```
browser
```
automation command.
No dedicated
```
download
```
command.
No dedicated
```
agent
```
command (use
```
research
```
instead).

Output and Organization

Unless user requests inline output, write to

.tavily/

bash

mkdir -p .tavily
tavily search "latest AI agent frameworks" --json -o .tavily/search-agent-frameworks.json
tavily extract "https://docs.tavily.com" -o .tavily/docs-tavily.md

Keep

.tavily/

.gitignore

Always quote URLs because

and

are shell-sensitive:

bash

tavily extract "https://example.com/docs?page=2&lang=en" -o .tavily/page2.md

Read large outputs incrementally:

bash

wc -l .tavily/result.json
head -n 60 .tavily/result.json
rg -n "keyword|error|failed" .tavily/result.json

Suggested naming:

bash

.tavily/search-{topic}.json
.tavily/map-{site}.json
.tavily/crawl-{site}.json
.tavily/extract-{site}-{slug}.md
.tavily/research-{topic}.json

Commands

search

Discover results for a query. Useful first step before extraction/crawl.

bash

# Basic JSON search output
tavily search "best vector databases 2026" --json --pretty -o .tavily/search-vector-db.json

# News-focused search in recent time window
tavily search "AI regulation US" --topic news --time-range month --max-results 8 --json -o .tavily/search-ai-regulation.json

# Domain-constrained search with answer/raw content
tavily search "authentication pattern" \
  --include-domains "docs.tavily.com,developer.mozilla.org" \
  --include-answer \
  --include-raw-content \
  --json -o .tavily/search-auth.json

Key options:

--max-results

--search-depth

--topic

--time-range

--start-date

--end-date

--include-domains

--exclude-domains

--country

--include-raw-content

--include-images

--include-answer

-o

--json

--pretty

extract

Extract content from one or many known URLs.

bash

# Single URL
tavily extract "https://docs.tavily.com" --format markdown -o .tavily/extract-docs.md

# Multiple URLs in one call
tavily extract "https://docs.tavily.com" "https://docs.tavily.com/api-reference" \
  --extract-depth advanced \
  --include-images \
  --json -o .tavily/extract-docs-multi.json

# Add relevance query and chunk control
tavily extract "https://example.com/long-page" \
  --query "pricing limits and rate limits" \
  --chunks-per-source 5 \
  --timeout 30 \
  --json -o .tavily/extract-pricing.json

Key options:

-u, --url

, positional

[urls...]

--extract-depth

--format

--include-images

--timeout

--query

--chunks-per-source

-o

--json

--pretty

map

Discover URLs on a site before extraction/crawl.

bash

# Full map with limits
tavily map "https://docs.tavily.com" --max-depth 2 --limit 200 --json -o .tavily/map-docs.json

# Filter by paths/domains
tavily map "https://example.com" \
  --select-paths "/docs,/api" \
  --exclude-paths "/blog,/changelog" \
  --json -o .tavily/map-filtered.json

Key options:

--max-depth

--max-breadth

--limit

--select-paths

--select-domains

--exclude-paths

--exclude-domains

--allow-external

--instructions

--timeout

-o

--json

--pretty

crawl

Bulk extract many pages from a site section.

bash

# Crawl docs section only
tavily crawl "https://docs.tavily.com" \
  --select-paths "/docs,/api-reference" \
  --max-depth 2 \
  --limit 80 \
  --json -o .tavily/crawl-docs.json

# Crawl with advanced extract options
tavily crawl "https://example.com" \
  --extract-depth advanced \
  --include-images \
  --chunks-per-source 4 \
  --timeout 45 \
  --json -o .tavily/crawl-example.json

Key options:

--max-depth

--max-breadth

--limit

--extract-depth

--select-paths

--exclude-paths

--allow-external

--include-images

--instructions

--format

--timeout

--chunks-per-source

-o

--json

--pretty

research

Start Tavily research generation.

bash

# Basic research request
tavily research "Compare RAG chunking strategies for legal documents" \
  --model pro \
  --json -o .tavily/research-rag.json

# Stream output while running
tavily research "Summarize latest agent memory patterns" \
  --stream \
  -o .tavily/research-agent-memory.txt

# Structured output schema
tavily research "List top observability tools" \
  --output-schema '{"type":"object","properties":{"tools":{"type":"array","items":{"type":"string"}}}}' \
  --json -o .tavily/research-tools-structured.json

Key options:

--model

--citation-format

--timeout

--stream

--output-schema

-o

--json

--pretty

research-status

Poll an existing research request by id.

bash

tavily research-status "req_123456789" --json --pretty -o .tavily/research-status.json

Key options:

-o

--json

--pretty

auth and setup commands

bash

# Authenticate interactively (never pass secrets as CLI args)
tavily login

# Check auth/version status
tavily status

# Remove saved credentials
tavily logout

# Pull key into local .env
tavily env --file .env --overwrite

# Install integrations independently
tavily setup skills
tavily setup mcp

Working with Results

Use

jq

rg

, and targeted reads for analysis:

bash

# Search: list title + URL
jq -r '.results[] | "\(.title)\t\(.url)"' .tavily/search-agent-frameworks.json

# Map: list URLs
jq -r '.results[]' .tavily/map-docs.json

# Crawl: collect crawled URLs
jq -r '.results[]?.url // empty' .tavily/crawl-docs.json

# Extract: show failures only
jq -r '.failedResults[]? | "\(.url)\t\(.error)"' .tavily/extract-docs-multi.json

# Research: inspect status and request id
jq -r '.requestId, .status' .tavily/research-rag.json

Parallelization

Prefer these patterns:

Use one
```
extract
```
call with multiple URLs when task scope is one batch.
Use shell parallelism only for independent targets and moderate concurrency.

bash

# Built-in multi URL batch in one request
tavily extract "https://site-a.com" "https://site-b.com" "https://site-c.com" \
  --json -o .tavily/extract-batch.json

# Independent parallel jobs (throttle conservatively)
tavily crawl "https://docs.site-a.com" --limit 40 --json -o .tavily/crawl-a.json &
tavily crawl "https://docs.site-b.com" --limit 40 --json -o .tavily/crawl-b.json &
wait

Do not launch large parallel bursts blindly. Respect API quota/rate limits and monitor failures before scaling up.

Bulk Workflows (Tavily Equivalent)

There is no dedicated

download

command. Use map/crawl/extract pipelines:

bash

# 1) Map docs URLs
tavily map "https://docs.example.com" --select-paths "/docs" --json -o .tavily/map-docs.json

# 2) Extract mapped URLs in controlled batches
jq -r '.results[]' .tavily/map-docs.json | head -n 30 > .tavily/map-docs-30.txt
while IFS= read -r url; do
  slug="$(echo "$url" | sed 's#^https://##; s#^http://##; s#[^a-zA-Z0-9._-]#-#g')"
  tavily extract "$url" --json -o ".tavily/extract-${slug}.json"
done < .tavily/map-docs-30.txt

Alternative bulk path:

bash

tavily crawl "https://docs.example.com" --select-paths "/docs" --max-depth 2 --limit 100 --json -o .tavily/crawl-docs.json

Failure Handling

If command fails with auth error: run
```
tavily status
```
, then
```
tavily login
```
.
If URL extraction fails: inspect
```
.failedResults
```
from JSON output and retry only failed URLs.
If output is too large: reduce
```
--limit
```
/ depth and split into multiple focused runs.
If parsing JSON outputs: ensure
```
--json
```
was used or output file uses
```
.json
```
extension.

tavily

NPX Install

Tags

SKILL.md Content

Tavily CLI

Prerequisites

Workflow

Output and Organization

Commands

search

extract

map

crawl

research

research-status

auth and setup commands

Working with Results

Parallelization

Bulk Workflows (Tavily Equivalent)

Failure Handling