> ## 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/skills" 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.

## 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
```