Tavily CLI

Search, extract, crawl, map, and research the web from your terminal.

PyPI

tavily-cli

Get API Key

Sign up at tavily.com

The Tavily CLI (tvly) brings the full Tavily API to your command line. Run web searches, extract content from URLs, crawl websites, discover sitemaps, and launch deep research — all from a single tool.

Every command supports --json for machine-readable output, making it easy to integrate into scripts, pipelines, and AI agent workflows.

Installation

Install with the official installer:

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

Or install manually:

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

Verify the install:

tvly --version

Authentication

You need a Tavily API key to use the CLI. Get one for free at tavily.com.

Option 1: Login with an API key (recommended)

tvly login --api-key tvly-YOUR_API_KEY

This stores your key in ~/.tavily/config.json (readable only by your user).

Option 2: Browser-based OAuth

tvly login

This opens your browser for authentication. Tokens are stored in ~/.mcp-auth/.

OAuth login requires Node.js/npx to be available on your system.

Option 3: Environment variable

export TAVILY_API_KEY=tvly-YOUR_API_KEY

Check Your Auth Status

tvly auth

Log Out

tvly logout

This removes stored credentials from disk.

Session Tracking

The CLI automatically attaches a unique session_id to every command it runs, so requests from the same shell invocation can be grouped together. This applies to tvly search, extract, crawl, map, and research.

To also associate requests with a specific end-user, set the TAVILY_HUMAN_ID environment variable:

export TAVILY_HUMAN_ID=h_4f9ac

Alternatively, add a human_id field to ~/.tavily/config.json — the environment variable takes precedence if both are set.

For security, Tavily hashes human IDs before processing or storing them. See Session Tracking in the API reference for details.

Commands

tvly search

Search the web using Tavily’s AI-optimized search engine.

tvly search "your search query"

Reading from stdin:

echo "your query" | tvly search -

Options

Option	Type	Default	Description
--depth	ultra-fast | fast | basic | advanced	basic	Search depth. Higher depth returns more detailed results.
--max-results	0–20	5	Number of results to return.
--topic	general | news | finance	general	Optimize search for a specific topic.
--time-range	day | week | month | year	—	Filter results to a relative time window.
--start-date	YYYY-MM-DD	—	Only include results published after this date.
--end-date	YYYY-MM-DD	—	Only include results published before this date.
--include-domains	comma-separated	—	Restrict results to these domains.
--exclude-domains	comma-separated	—	Exclude results from these domains.
--country	country code	—	Boost results from a specific country.
--include-answer	basic | advanced	—	Include an AI-generated answer with results.
--include-raw-content	markdown | text	—	Include full page content for each result.
--include-images	flag	false	Include image results.
--include-image-descriptions	flag	false	Include AI-generated image descriptions.
--chunks-per-source	integer	—	Number of content chunks per source (requires fast or advanced depth).
-o / --output	file path	—	Save output to a file.
--json	flag	false	Output raw JSON.

Examples

# Basic search
tvly search "best programming languages 2025"

# News from the past week
tvly search "AI regulation" --topic news --time-range week

# Advanced search with AI answer
tvly search "how does transformer architecture work" --depth advanced --include-answer advanced

# Restrict to specific sites
tvly search "python tutorials" --include-domains realpython.com,docs.python.org

# Save results to a file
tvly search "climate change data" -o results.txt

tvly extract

Extract clean, readable content from one or more URLs.

tvly extract <url> [<url> ...]

You can pass up to 20 URLs at once.

Options

Option	Type	Default	Description
--query	string	—	Rerank extracted chunks by relevance to this query.
--chunks-per-source	1–5	—	Number of content chunks per URL (requires --query).
--extract-depth	basic | advanced	basic	Extraction depth. advanced handles JavaScript-rendered pages.
--format	markdown | text	markdown	Output format for extracted content.
--include-images	flag	false	Include image URLs found on the page.
--timeout	1–60	—	Maximum wait time in seconds.
-o / --output	file path	—	Save output to a file.
--json	flag	false	Output raw JSON.

Examples

# Extract content from a URL
tvly extract https://example.com/article

# Extract multiple URLs
tvly extract https://example.com/page1 https://example.com/page2

# Extract with relevance filtering
tvly extract https://docs.python.org/3/tutorial/ --query "list comprehensions" --chunks-per-source 3

# Extract JavaScript-rendered content
tvly extract https://example.com/spa-page --extract-depth advanced

tvly crawl

Crawl a website starting from a URL and extract content from every discovered page.

tvly crawl <url>

Options

Option	Type	Default	Description
--max-depth	1–5	1	How many levels deep to crawl from the start URL.
--max-breadth	integer	20	Maximum links to follow per page.
--limit	integer	50	Total page cap for the crawl.
--instructions	string	—	Natural language guidance for the crawler (e.g., “only follow documentation pages”).
--chunks-per-source	1–5	—	Chunks per page (requires --instructions).
--extract-depth	basic | advanced	basic	Extraction depth for crawled pages.
--format	markdown | text	markdown	Output format for extracted content.
--select-paths	comma-separated regex	—	Only crawl paths matching these patterns.
--exclude-paths	comma-separated regex	—	Skip paths matching these patterns.
--select-domains	comma-separated regex	—	Only follow links to matching domains.
--exclude-domains	comma-separated regex	—	Skip links to matching domains.
--allow-external / --no-external	flag	—	Whether to follow links to external domains.
--include-images	flag	false	Include images found on pages.
--timeout	10–150	—	Maximum wait time in seconds.
-o / --output	file path	—	Save full JSON output to a file.
--output-dir	directory path	—	Save each crawled page as a separate .md file.
--json	flag	false	Output raw JSON.

Examples

# Crawl a docs site (1 level deep)
tvly crawl https://docs.example.com

# Deep crawl with a page limit
tvly crawl https://docs.example.com --max-depth 3 --limit 100

# Crawl only blog posts
tvly crawl https://example.com --select-paths "/blog/.*"

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

# Guided crawl
tvly crawl https://docs.example.com --instructions "focus on API reference pages"

tvly map

Discover all URLs on a website without extracting content. Useful for building sitemaps or understanding site structure.

tvly map <url>

Options

Option	Type	Default	Description
--max-depth	1–5	1	How many levels deep to discover links.
--max-breadth	integer	20	Maximum links to follow per page.
--limit	integer	50	Maximum total URLs to discover.
--instructions	string	—	Natural language guidance for URL discovery.
--select-paths	comma-separated regex	—	Only include URLs matching these path patterns.
--exclude-paths	comma-separated regex	—	Exclude URLs matching these path patterns.
--select-domains	comma-separated regex	—	Only include URLs from matching domains.
--exclude-domains	comma-separated regex	—	Exclude URLs from matching domains.
--allow-external / --no-external	flag	—	Whether to include external domain links.
--timeout	10–150	—	Maximum wait time in seconds.
-o / --output	file path	—	Save output to a file.
--json	flag	false	Output raw JSON.

Examples

# Discover URLs on a site
tvly map https://example.com

# Deep URL discovery
tvly map https://docs.example.com --max-depth 3 --limit 200

# Only find API doc URLs
tvly map https://docs.example.com --select-paths "/api/.*"

# Save URL list to a file
tvly map https://example.com -o urls.txt

tvly research

Launch deep, multi-step research on any topic. Tavily’s research engine searches the web, synthesizes sources, and produces a comprehensive report with citations.

tvly research "your research topic"

This is equivalent to tvly research run "your research topic".

Reading from stdin:

echo "your topic" | tvly research -

Options

Option	Type	Default	Description
--model	mini | pro | auto	auto	Research model. mini is faster, pro is more thorough, auto picks the best fit.
--no-wait	flag	false	Return the request_id immediately without waiting for completion.
--stream	flag	false	Stream results in real-time as the research progresses.
--output-schema	file path	—	Path to a JSON schema file for structured output.
--citation-format	numbered | mla | apa | chicago	—	Citation style for the research report.
--poll-interval	seconds	10	How often to check for completion.
--timeout	seconds	600	Maximum time to wait for results.
-o / --output	file path	—	Save the report to a file.
--json	flag	false	Output raw JSON.

Subcommands

Check status of a running research task:

tvly research status <request_id>

Poll a research task until it completes:

tvly research poll <request_id>

The poll subcommand accepts --poll-interval, --timeout, -o, and --json.

Examples

# Quick research
tvly research "comparison of React vs Vue in 2025"

# Thorough research with the pro model
tvly research "impact of AI on healthcare" --model pro

# Stream results as they come in
tvly research "quantum computing breakthroughs" --stream

# Fire-and-forget: get the ID, poll later
tvly research "market analysis of EVs" --no-wait
# ... later:
tvly research poll <request_id>

# Save the report to a file with APA citations
tvly research "effects of remote work on productivity" --citation-format apa -o report.md

Interactive Mode

Run tvly with no arguments to enter an interactive REPL where you can run commands without the tvly prefix:

tvly

❯ search "latest AI news"
❯ extract https://example.com
❯ exit

Global Options

These options work with the top-level tvly command:

Option	Description
--version	Print the CLI version and exit.
--status	Print the version and authentication status.
--json	Output as JSON (applies to --version and --status).
--help	Show help for any command.

tvly --version
tvly --status
tvly search --help

JSON Mode

Add --json to any command to get machine-readable JSON output. This is useful for piping into other tools like jq, or for integration with scripts and AI agents.

# Pipe search results through jq
tvly search "AI news" --json | jq '.results[].title'

# Use in a shell script
RESULTS=$(tvly search "latest papers on RAG" --json)

All human-readable output (spinners, status messages) is written to stderr, so stdout contains only the clean JSON when --json is used.

Environment Variables

Variable	Description
TAVILY_API_KEY	Your Tavily API key. Takes precedence over stored credentials.

Exit Codes

Code	Meaning
0	Success.
2	Invalid input or usage error (e.g., missing required argument).
3	Authentication error (no API key found, or login failed).
4	API error (rate limit, invalid request, server error).

Uninstall

pip uninstall tavily-cli

To also remove stored credentials:

rm -rf ~/.tavily ~/.mcp-auth