> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tavily.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Tavily CLI

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

<CardGroup cols={2}>
  <Card title="PyPI" icon="python" href="https://github.com/tavily-ai/tavily-cli" horizontal>
    `tavily-cli`
  </Card>

  <Card title="Get API Key" icon="key" href="https://app.tavily.com" horizontal>
    Sign up at tavily.com
  </Card>
</CardGroup>

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:

```bash theme={null}
curl -fsSL https://cli.tavily.com/install.sh | bash
```

Or install manually:

```bash theme={null}
uv tool install tavily-cli   # or: pip install tavily-cli
```

Verify the install:

```bash theme={null}
tvly --version
```

## Authentication

You need a Tavily API key to use the CLI. Get one for free at [tavily.com](https://tavily.com).

<AccordionGroup>
  <Accordion title="Option 1: Login with an API key (recommended)" icon="key" defaultOpen="true">
    ```bash theme={null}
    tvly login --api-key tvly-YOUR_API_KEY
    ```

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

  <Accordion title="Option 2: Browser-based OAuth" icon="browser">
    ```bash theme={null}
    tvly login
    ```

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

    <Note>OAuth login requires Node.js/npx to be available on your system.</Note>
  </Accordion>

  <Accordion title="Option 3: Environment variable" icon="code">
    ```bash theme={null}
    export TAVILY_API_KEY=tvly-YOUR_API_KEY
    ```
  </Accordion>
</AccordionGroup>

### Check Your Auth Status

```bash theme={null}
tvly auth
```

### Log Out

```bash theme={null}
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:

```bash theme={null}
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](/documentation/api-reference/introduction#session--user-tracking) in the API reference for details.

## Commands

<AccordionGroup>
  <Accordion title="tvly search" icon="magnifying-glass">
    Search the web using Tavily's AI-optimized search engine.

    ```bash theme={null}
    tvly search "your search query"
    ```

    **Reading from stdin:**

    ```bash theme={null}
    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

    ```bash theme={null}
    # 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
    ```
  </Accordion>

  <Accordion title="tvly extract" icon="file-lines">
    Extract clean, readable content from one or more URLs.

    ```bash theme={null}
    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

    ```bash theme={null}
    # 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
    ```
  </Accordion>

  <Accordion title="tvly crawl" icon="spider-web">
    Crawl a website starting from a URL and extract content from every discovered page.

    ```bash theme={null}
    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

    ```bash theme={null}
    # 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"
    ```
  </Accordion>

  <Accordion title="tvly map" icon="sitemap">
    Discover all URLs on a website without extracting content. Useful for building sitemaps or understanding site structure.

    ```bash theme={null}
    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

    ```bash theme={null}
    # 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
    ```
  </Accordion>

  <Accordion title="tvly research" icon="magnifying-glass-chart">
    Launch deep, multi-step research on any topic. Tavily's research engine searches the web, synthesizes sources, and produces a comprehensive report with citations.

    ```bash theme={null}
    tvly research "your research topic"
    ```

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

    **Reading from stdin:**

    ```bash theme={null}
    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:**

    ```bash theme={null}
    tvly research status <request_id>
    ```

    **Poll a research task until it completes:**

    ```bash theme={null}
    tvly research poll <request_id>
    ```

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

    #### Examples

    ```bash theme={null}
    # 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
    ```
  </Accordion>
</AccordionGroup>

## Interactive Mode

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

```bash theme={null}
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. |

```bash theme={null}
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.

```bash theme={null}
# 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. |

<Accordion title="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). |
</Accordion>

## Uninstall

```bash theme={null}
pip uninstall tavily-cli
```

To also remove stored credentials:

```bash theme={null}
rm -rf ~/.tavily ~/.mcp-auth
```