Skip to main content

npm

@tavily/cli

GitHub

tavily-ai/cli
The Tavily CLI (tvly) runs web search, content extraction, crawling, URL discovery, and deep research from the command line, and sets up Tavily skills and the MCP server for Claude Code, Codex, and Cursor. Every command supports --json, and output switches to plain text when piped or run from a coding agent’s shell.

Installation

This installs tvly globally, signs you in, sets up your coding agents, and verifies a live search. Requires Node.js 20.1 or later. To install without running setup, use your package manager and run tvly init afterwards:
pnpm add -g, yarn global add, and bun add -g work the same way. Verify the install with tvly --version.

Setup

tvly init asks three questions:
  1. How do you want to sign in? Browser login, paste an API key, or continue without a key. An existing credential is reused.
  2. Which agents do you want to install to? Every detected agent (Claude Code, Codex, Cursor) is pre-checked. --agent picks the agents and skips the question.
  3. What should I install? Tavily skills and the hosted MCP server are checked by default; the official workflows from tavily-ai/official-workflows are not.
It then verifies the CLI with a live search. Rerunning tvly init updates installed skills to the latest published version.
--yes, --json, and runs without a terminal take the defaults without asking. Skills and the MCP server are installed with npx skills and npx add-mcp, so both need npx on your PATH.

Authentication

Search and extract work without an account, within a fair-use rate limit. Crawl, map, and research need a credential. Get a free API key at tavily.com.

Option 1: Browser login

This opens your browser to sign in. Tokens are stored in ~/.mcp-auth/. Add --no-browser to print the login URL instead of opening it; the CLI still waits for a callback on 127.0.0.1.Browser login goes through Tavily’s MCP endpoint, which rejects some search, crawl, and research options. Use an API key for the full option set.
This stores your key in ~/.tavily/config.json, readable only by your user.
The environment variable takes priority over stored credentials, so use it for CI and SSH sessions.

Check Your Auth Status

Log Out

This revokes browser-login tokens and removes stored credentials from disk. It cannot unset TAVILY_API_KEY.

Session Tracking

The CLI attaches a session_id to every request. The ID is tied to the shell that runs tvly, so all commands from one terminal or one coding-agent session group together, and a new terminal gets a new ID. To also associate requests with a specific end user, set the TAVILY_HUMAN_ID environment variable:
Alternatively, add a human_id field to ~/.tavily/config.json. The environment variable takes precedence if both are set. Tavily hashes human IDs before processing or storing them. See Session Tracking in the API reference for details.

Commands

Search the web using Tavily’s AI-optimized search engine.
Several queries at once: pass up to 5 queries to run them in parallel with the same options. Results print under a === [1/2] <query> header for each query, and --json returns a list of responses in query order. A failed query reports its error without stopping the others.
Reading from stdin:

Options

Examples

Extract clean, readable content from one or more URLs.
You can pass up to 20 URLs at once.

Options

Examples

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

Options

Examples

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

Options

Examples

Launch deep, multi-step research on any topic. Tavily’s research engine searches the web, synthesizes sources, and produces a comprehensive report with citations.
This is equivalent to tvly research run "your research topic". Streaming, structured output, and async research need an API key.Reading from stdin:

Options

Subcommands

Check status of a running research task:
Poll a research task until it completes:
The poll subcommand accepts --poll-interval, --timeout, -o, and --json.

Examples

Add the hosted Tavily MCP server (https://mcp.tavily.com/mcp/) to Claude Code, Codex, and Cursor. tvly init does this by default; use this command to add it later or to more agents.
With TAVILY_API_KEY exported, the config references the variable and the key itself is never written to disk. Without it, the agent opens a browser to sign in the first time it uses the server. Restart the agent after adding the server.
Make Tavily the web tool your coding agents use by disabling their built-in web search. tvly unset-default reverses it.
Check for a newer release and update through the package manager that installed the CLI.
The CLI also checks for a newer release at most once a day and prints a one-line notice on stderr. It stays silent under --json, when stderr is not a terminal, when run through npx, or when CI or NO_UPDATE_NOTIFIER is set.

Interactive Mode

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

Global Options

These options work with the top-level tvly command:

Output in Pipes and Agent Shells

At a terminal, the CLI prints formatted output with colors. When stdout is not a terminal, for example in a pipe, a file redirect, or a coding agent’s shell, it prints plain text instead:

Saving results

-o <path> saves the full JSON response to that path and creates missing folders. -o with no value saves it under .tavily/ with a generated name, such as .tavily/search-ai-news-142310-3f9a1c.json, and prints the path. A new .tavily/ folder gets its own .gitignore, so saved results stay out of git. Nothing is saved without -o. When stdout is not a terminal, tvly search -o also prints the results. An agent can read the snippets first and open the saved file only for the results it needs.

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.
All human-readable output (spinners, status messages) is written to stderr, so stdout contains only the clean JSON when --json is used.

Environment Variables

Uninstall

To also remove stored credentials: