npm
@tavily/cliGitHub
tavily-ai/clitvly) 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
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:
- How do you want to sign in? Browser login, paste an API key, or continue without a key. An existing credential is reused.
- Which agents do you want to install to? Every detected agent (Claude Code, Codex, Cursor) is pre-checked.
--agentpicks the agents and skips the question. - What should I install? Tavily skills and the hosted MCP server are checked by default; the official workflows from
tavily-ai/official-workflowsare not.
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
Option 1: Browser login
~/.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.Option 2: API key
Option 2: API key
~/.tavily/config.json, readable only by your user.Option 3: Environment variable
Option 3: Environment variable
Check Your Auth Status
Log Out
TAVILY_API_KEY.
Session Tracking
The CLI attaches asession_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:
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
tvly search
tvly search
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 Reading from stdin:
=== [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.Options
Examples
tvly extract
tvly extract
tvly crawl
tvly crawl
tvly map
tvly map
tvly research
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.This is equivalent to Poll a research task until it completes:The
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 subcommand accepts --poll-interval, --timeout, -o, and --json.Examples
tvly setup mcp
tvly setup mcp
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.tvly set-default
tvly set-default
Make Tavily the web tool your coding agents use by disabling their built-in web search.
tvly unset-default reverses it.tvly update
tvly update
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
Runtvly 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-leveltvly 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.
--json is used.
Environment Variables
Exit Codes
Exit Codes