version: "1.0.0" name: tavily-cli description: | Set up, authenticate, update, troubleshoot, or choose between Tavily CLI web commands. Use when the user asks about the Tavily CLI, installing Tavily skills, first-time setup, authentication, keyless limits, CLI updates, or which Tavily command to use. For an ordinary web task, use the specific search, extract, map, crawl, research, or dynamic-search skill instead. compatibility: Requires Tavily CLI (tvly) and network access; authenticated access for map, crawl, and research.

Tavily CLI

Web search, content extraction, site crawling, URL discovery, and deep research. Returns JSON optimized for LLM consumption.

Requires tavily-cli. Search and extract support capped keyless access; map, crawl, and research require authentication.

Run tvly --help or tvly <command> --help for full option details.

Setup

This power already bundles the skills. Install only the CLI if tvly is missing:

uv tool install tavily-cli
# Alternative when uv is unavailable:
# pip install tavily-cli

Use tvly --help and tvly <command> --help to check the installed CLI's options. Do not run the default skill installer or bare tvly init from this power; those can install another copy of these skills into other editors.

Search and extract support capped keyless access. Try the requested command without authentication first. Optional setup and verification with the already bundled skills:

tvly init --skip-skills --skip-auth

Map, crawl, and research require authentication. When it is needed, use:

tvly login
# Or guided authentication and verification without reinstalling skills:
tvly init --skip-skills

If a search or extract reaches the keyless cap in an interactive session, use tvly login, then retry the original request once. In an unattended environment, report the authentication requirement instead of opening an interactive flow. Check the current state only when needed with tvly --status --json.

Browser OAuth requires a localhost callback on the machine running tvly. tvly login --no-browser prints the sign-in link; remote sessions may require port forwarding. For unattended use or API-key-only operations, use a securely provided TAVILY_API_KEY. Do not print credentials or write them to this power.

CLI credentials and the MCP connection's host-managed credentials are separate. Use tavily-mcp for connection guidance.

Check for CLI updates with tvly update --check; use tvly update when an update is requested or needed. Update this power to refresh its bundled skills.

Workflow

Follow this escalation pattern — start simple, escalate when needed:

1. Search — No specific URL. Find pages, answer questions, discover sources.
2. Extract — Have a URL. Pull its content directly.
3. Map — Large site, need to find the right page. Discover URLs first.
4. Crawl — Need bulk content from an entire site section.
5. Research — Need comprehensive, multi-source analysis with citations.

For detailed command reference, use the individual skill for each command (e.g., tavily-search, tavily-crawl) or run tvly <command> --help.

Run tvly without a subcommand for the interactive REPL.

Output

Search, extract, crawl, map, and research support --json for structured output. Result-producing commands support -o to save the JSON response; crawl also supports --output-dir for one Markdown file per page. Setup, authentication, status, and update commands expose --json where documented but do not support -o.

tvly search "react hooks" --json -o results.json
tvly extract "https://example.com/docs" -o docs.json
tvly crawl "https://docs.example.com" --output-dir ./docs/

Tips

• Always quote URLs — shell interprets ? and & as special characters.
• Use `--json` for agentic workflows when the selected command exposes it.
• Read from stdin with `-` — echo "query" | tvly search -
• Exit codes: 0 = success, 1 = setup/update failure, 2 = bad input, 3 = auth error, 4 = API or live-verification error.