Tavily CLI

PyPI

tavily-cli

Get API Key

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 from PyPI with pip (requires Python 3.10+):

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)

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.

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

Tavily MCP Server

Tavily Agent Skills

tavily-cli

Partnerships

Integrations

PyPI

Get API Key

Installation

Authentication

Check Your Auth Status

Log Out

Commands

Options

Examples

Options

Examples

Options

Examples

Options

Examples

Options

Subcommands

Examples

Interactive Mode

Global Options

JSON Mode

Environment Variables

Uninstall

Tavily MCP Server

Tavily Agent Skills

tavily-cli

Partnerships

Integrations

PyPI

Get API Key

​Installation

​Authentication

​Check Your Auth Status

​Log Out

​Commands

​Options

​Examples

​Options

​Examples

​Options

​Examples

​Options

​Examples

​Options

​Subcommands

​Examples

​Interactive Mode

​Global Options

​JSON Mode

​Environment Variables

​Uninstall

Installation

Authentication

Check Your Auth Status

Log Out

Commands

Options

Examples

Options

Examples

Options

Examples

Options

Examples

Options

Subcommands

Examples

Interactive Mode

Global Options

JSON Mode

Environment Variables

Uninstall