tavily-cli

中文 | English

tavily-cli is a Tavily command-line tool for agents and human users, supporting search, extract (alias fetch), crawl, and research commands.

Quick Start

1) Install Dependencies

uv sync

2) Configure API Key

# Recommended: Multiple keys (comma-separated)
export TAVILY_API_KEYS="tvly-key-1,tvly-key-2"

# Alternative: Single key
export TAVILY_API_KEY="tvly-key"

Priority: TAVILY_API_KEYS > TAVILY_API_KEY. When using multiple keys, one is randomly selected per request.

3) Run

uv run tavily-cli --help
uv run tavily-cli search -q "2026 AI news"

Installation Methods

Development Mode (Recommended)

uv run tavily-cli --help

Install Locally as Command

uv tool install --force --reinstall "git+https://github.com/Linfee/tavily-cli.git"
tavily-cli --help

Run Without Installation

uvx --from "git+https://github.com/Linfee/tavily-cli.git" tavily-cli --help

Install as AI Agent Skill

Install tavily-cli as a skill for AI agents (Claude Code, Cursor, etc.):

npx skills add Linfee/tavily-cli

Command Overview

tavily-cli [GLOBAL_OPTIONS] <command> [command_options]

Commands:

• search
• extract / fetch (fetch is an alias for extract)
• crawl
• research

Global Options:

• --project-id
• --output-format [json|jsonl|markdown|text|yaml]
• --output/-o

Note: --output-format and --output can be placed either before or after the subcommand.

Output Format Semantics

• json: Formatted JSON (preserves full response structure)
• yaml: Full response converted to YAML
• markdown: Readable Markdown (Metadata + results/failed_results/sources/images sections)
• text: Same structure as markdown but without Markdown markers
• jsonl:
  • If response contains non-empty results: one results element per line (outer layer discarded)
  • Otherwise: single-line complete JSON (fallback)

Common Examples

search

# Basic search
tavily-cli search -q "2026 AI news" --max-results 5

# Include advanced answer
tavily-cli search -q "Tavily API" --include-answer advanced

# Raw content as markdown
tavily-cli search -q "Tavily docs" --include-raw-content markdown

extract (alias: fetch)

tavily-cli extract --urls "https://docs.tavily.com/documentation/about" --extract-depth basic
tavily-cli fetch --urls "https://example.com" --query "summary"  # fetch is an alias for extract

crawl

tavily-cli crawl --url "https://docs.tavily.com/documentation/about" --max-depth 1 --limit 3
tavily-cli crawl --url "https://example.com" --no-allow-external

research

# Polling mode
tavily-cli research --input "What is Tavily API in one sentence?" --model mini --poll-interval 2 --max-wait 120

# Streaming mode
tavily-cli research --input "Summarize Tavily docs" --stream

Output to File

tavily-cli search -q "Tavily" --output-format yaml -o result.yaml
tavily-cli search -q "Tavily" --output-format jsonl -o result.jsonl

Exit Codes

Code	Meaning
0	Success
1	Unknown error
2	Validation error
3	Authentication error (missing/invalid API Key)
4	Tavily API error
5	Network or timeout error

Development and Quality Gates

uv run ruff format src tests scripts
uv run ruff check src tests scripts
uv run pyright
uv run pytest

Interactive Golden Regression Script

Script path: scripts/golden_regression.py

# Interactive
uv run python scripts/golden_regression.py

# Non-interactive: Generate baseline
uv run python scripts/golden_regression.py \
  --non-interactive \
  --cmd search \
  --query "Tavily API" \
  --formats json,jsonl,markdown,text,yaml \
  --mode baseline \
  --output-dir tests/golden

# Non-interactive: Compare with baseline
uv run python scripts/golden_regression.py \
  --non-interactive \
  --cmd search \
  --query "Tavily API" \
  --formats jsonl \
  --mode compare \
  --output-dir tests/golden

Mode descriptions:

• preview: Preview only
• baseline: Write baseline files
• compare: Compare current output with baseline (returns non-zero on failure)

Documentation Index

• AGENTS.md
• docs/architecture.md
• docs/security.md
• docs/quality-gates.md
• docs/exec-plans/