Can I use Tavily as a CLI?

Yes. KosmoKrator exposes a Tavily CLI through kosmo integrations:call and the provider shortcut command. Commands can return JSON for scripts, CI, and coding agents.

Can I expose Tavily through MCP?

Yes. The KosmoKrator MCP gateway can expose selected Tavily tools to clients such as Claude Code, Cursor, Codex, and other MCP-compatible tools.

Where are Tavily credentials stored?

Tavily credentials are configured in KosmoKrator's local integration settings and reused by CLI, Lua, and MCP gateway surfaces.

Can I deny write access for Tavily MCP tools?

Yes. Start the gateway with --write=deny for read-only clients, or use ask/allow only for trusted workspaces.

data

Tavily CLI for AI Agents

Use the Tavily CLI from KosmoKrator to call Tavily tools headlessly, return JSON, inspect schemas, and automate workflows from coding agents, scripts, and CI.

Tavily CLI Setup

Tavily can be configured headlessly with `kosmokrator integrations:configure tavily`.

Install, configure, and verify

# Install KosmoKrator first if it is not available on PATH.
curl -fsSL https://raw.githubusercontent.com/OpenCompanyApp/kosmokrator/main/install.sh | bash

# Configure and verify this integration.
kosmokrator integrations:configure tavily --set api_key="$TAVILY_API_KEY" --enable --read allow --write ask --json
kosmokrator integrations:doctor tavily --json
kosmokrator integrations:status --json

Credentials

Authentication type: API key api_key. Configure credentials once, then reuse the same stored profile from scripts, coding CLIs, Lua, and MCP.

Key	Env var	Type	Required	Label
`api_key`	`TAVILY_API_KEY`	Secret `secret`	yes	API Key
`project_id`	`TAVILY_PROJECT_ID`	Text `text`	no	Project ID
`url`	`TAVILY_URL`	URL `url`	no	API Base URL

Command Patterns

The generic command is stable across every integration. The provider shortcut is shorter for humans.

Generic CLI call

kosmo integrations:call tavily.tavily_search '{"query":"example_query","search_depth":"example_search_depth","chunks_per_source":1,"max_results":1,"topic":"example_topic","time_range":"example_time_range","start_date":"example_start_date","end_date":"example_end_date"}' --json

Provider shortcut

kosmo integrations:tavily tavily_search '{"query":"example_query","search_depth":"example_search_depth","chunks_per_source":1,"max_results":1,"topic":"example_topic","time_range":"example_time_range","start_date":"example_start_date","end_date":"example_end_date"}' --json

Discovery

These commands return structured output for coding agents that need to inspect capabilities before choosing a function.

Discovery commands

kosmo integrations:docs tavily --json
kosmo integrations:docs tavily.tavily_search --json
kosmo integrations:schema tavily.tavily_search --json
kosmo integrations:search "Tavily" --json
kosmo integrations:list --json

Automation Contexts

The same configured command surface works in these environments. The command does not change unless the host wrapper, credentials, or permissions change.

CI Run integration calls from CI jobs with JSON output, explicit credentials, and predictable exit status. Cron Jobs Schedule repeatable integration workflows from cron while keeping credentials in KosmoKrator config. Shell Scripts Call integration functions from shell scripts with stable JSON input and output. Headless Automation Use KosmoKrator as a non-interactive integration runtime for local automations and wrappers. Coding Agents Let coding agents discover schemas and execute integration functions through CLI commands or MCP.

CLI Functions

Every function below can be called headlessly. Commands are highlighted, copyable, and scroll horizontally when payloads are long.

`tavily.tavily_search`

Search the web with Tavily. Use for current information, source discovery, and AI-ready snippets. Supports answer generation, raw page content, images, recency/date filters, domain filters, country boosting, and usage details.

Read read

Parameters: query, search_depth, chunks_per_source, max_results, topic, time_range, start_date, end_date, include_answer, include_raw_content, include_images, include_image_descriptions, include_favicon, include_domains, exclude_domains, country, auto_parameters, exact_match, include_usage, safe_search

Generic call

kosmo integrations:call tavily.tavily_search '{"query":"example_query","search_depth":"example_search_depth","chunks_per_source":1,"max_results":1,"topic":"example_topic","time_range":"example_time_range","start_date":"example_start_date","end_date":"example_end_date"}' --json

Shortcut

kosmo integrations:tavily tavily_search '{"query":"example_query","search_depth":"example_search_depth","chunks_per_source":1,"max_results":1,"topic":"example_topic","time_range":"example_time_range","start_date":"example_start_date","end_date":"example_end_date"}' --json

`tavily.tavily_extract`

Extract clean markdown or text content from one or more URLs with Tavily. Use after search or map when an agent needs full page content.

Read read

Parameters: urls, query, chunks_per_source, extract_depth, include_images, include_favicon, format, timeout, include_usage

Generic call

kosmo integrations:call tavily.tavily_extract '{"urls":"example_urls","query":"example_query","chunks_per_source":1,"extract_depth":"example_extract_depth","include_images":true,"include_favicon":true,"format":"example_format","timeout":1}' --json

Shortcut

kosmo integrations:tavily tavily_extract '{"urls":"example_urls","query":"example_query","chunks_per_source":1,"extract_depth":"example_extract_depth","include_images":true,"include_favicon":true,"format":"example_format","timeout":1}' --json

`tavily.tavily_crawl`

Crawl a website with Tavily and return extracted content from discovered pages. Use for documentation ingestion, RAG source collection, and targeted site extraction.

Read read

Parameters: url, instructions, chunks_per_source, max_depth, max_breadth, limit, select_paths, select_domains, exclude_paths, exclude_domains, allow_external, include_images, extract_depth, format, include_favicon, timeout, include_usage

Generic call

kosmo integrations:call tavily.tavily_crawl '{"url":"example_url","instructions":"example_instructions","chunks_per_source":1,"max_depth":1,"max_breadth":1,"limit":1,"select_paths":"example_select_paths","select_domains":"example_select_domains"}' --json

Shortcut

kosmo integrations:tavily tavily_crawl '{"url":"example_url","instructions":"example_instructions","chunks_per_source":1,"max_depth":1,"max_breadth":1,"limit":1,"select_paths":"example_select_paths","select_domains":"example_select_domains"}' --json

`tavily.tavily_map`

Map a website with Tavily and return discovered URLs without extracting full page content. Use before targeted extract or crawl jobs.

Read read

Parameters: url, instructions, max_depth, max_breadth, limit, select_paths, select_domains, exclude_paths, exclude_domains, allow_external, timeout, include_usage

Generic call

kosmo integrations:call tavily.tavily_map '{"url":"example_url","instructions":"example_instructions","max_depth":1,"max_breadth":1,"limit":1,"select_paths":"example_select_paths","select_domains":"example_select_domains","exclude_paths":"example_exclude_paths"}' --json

Shortcut

kosmo integrations:tavily tavily_map '{"url":"example_url","instructions":"example_instructions","max_depth":1,"max_breadth":1,"limit":1,"select_paths":"example_select_paths","select_domains":"example_select_domains","exclude_paths":"example_exclude_paths"}' --json

`tavily.tavily_create_research_task`

Create a Tavily Research task for comprehensive multi-source research. The returned request_id can be passed to tavily_get_research_task.

Read read

Parameters: input, model, output_schema, citation_format, stream

Generic call

kosmo integrations:call tavily.tavily_create_research_task '{"input":"example_input","model":"example_model","output_schema":"example_output_schema","citation_format":"example_citation_format","stream":true}' --json

Shortcut

kosmo integrations:tavily tavily_create_research_task '{"input":"example_input","model":"example_model","output_schema":"example_output_schema","citation_format":"example_citation_format","stream":true}' --json

`tavily.tavily_get_research_task`

Get the current status and, when complete, the content and sources for a Tavily Research task by request_id.

Read read

Parameters: request_id

Generic call

kosmo integrations:call tavily.tavily_get_research_task '{"request_id":"example_request_id"}' --json

Shortcut

kosmo integrations:tavily tavily_get_research_task '{"request_id":"example_request_id"}' --json

`tavily.tavily_get_usage`

Get Tavily API key and account usage details, including per-endpoint credit usage and plan limits.

Read read

Parameters: none

Generic call

kosmo integrations:call tavily.tavily_get_usage '{}' --json

Shortcut

kosmo integrations:tavily tavily_get_usage '{}' --json

Function Schemas

Use these parameter tables when building CLI payloads without calling integrations:schema first.

tavily.tavily_search 20 parameters

Schema command

kosmo integrations:schema tavily.tavily_search --json

Parameter	Type	Required	Description
`query`	string	yes	Search query to execute.
`search_depth`	string	no	Latency/relevance tradeoff. advanced costs more and can return multiple chunks.
`chunks_per_source`	integer	no	Relevant chunks per source for advanced search. Range: 1-3.
`max_results`	integer	no	Maximum results to return. Range: 0-20. Default: 5.
`topic`	string	no	Search topic.
`time_range`	string	no	Relative publish/update time range.
`start_date`	string	no	Return results after this YYYY-MM-DD date.
`end_date`	string	no	Return results before this YYYY-MM-DD date.
`include_answer`	boolean,string	no	false, true, basic, or advanced. Adds an LLM-generated answer.
`include_raw_content`	boolean,string	no	false, true, markdown, or text. Adds cleaned page content to results.
`include_images`	boolean	no	Include query and per-result images.
`include_image_descriptions`	boolean	no	Add descriptions for images when include_images is true.
`include_favicon`	boolean	no	Include favicon URL for each result.
`include_domains`	array	no	Only include these domains. Maximum 300 domains.
`exclude_domains`	array	no	Exclude these domains. Maximum 150 domains.
`country`	string	no	Boost results from a documented Tavily country value. Only applies to general topic.
`auto_parameters`	boolean	no	Let Tavily select search parameters from query intent. Explicit values override auto values.
`exact_match`	boolean	no	Require exact quoted phrases in results.
`include_usage`	boolean	no	Include credit usage details.
`safe_search`	boolean	no	Enterprise-only unsafe-content filtering. Not supported for fast or ultra-fast depth.

tavily.tavily_extract 9 parameters

Schema command

kosmo integrations:schema tavily.tavily_extract --json

Parameter	Type	Required	Description
`urls`	string,array	yes	URL or array of URLs to extract.
`query`	string	no	Optional user intent for reranking extracted content chunks.
`chunks_per_source`	integer	no	Chunks per source when query is provided. Range: 1-5.
`extract_depth`	string	no	Extraction depth. advanced retrieves more data with higher latency/cost.
`include_images`	boolean	no	Include images extracted from URLs.
`include_favicon`	boolean	no	Include favicon URL for each result.
`format`	string	no	Output format for raw_content.
`timeout`	number	no	Extraction timeout in seconds. Range: 1-60.
`include_usage`	boolean	no	Include credit usage details.

tavily.tavily_crawl 17 parameters

Schema command

kosmo integrations:schema tavily.tavily_crawl --json

Parameter	Type	Required	Description
`url`	string	yes	Root URL to begin the crawl.
`instructions`	string	no	Natural language crawl instructions. Increases mapping cost when supplied.
`chunks_per_source`	integer	no	Chunks per source when instructions are supplied. Range: 1-5.
`max_depth`	integer	no	Maximum crawl depth. Range: 1-5.
`max_breadth`	integer	no	Maximum links to follow per level. Range: 1-500.
`limit`	integer	no	Maximum number of links to process.
`select_paths`	array	no	Regex path patterns to include.
`select_domains`	array	no	Regex domain patterns to include.
`exclude_paths`	array	no	Regex path patterns to exclude.
`exclude_domains`	array	no	Regex domain patterns to exclude.
`allow_external`	boolean	no	Whether external links may appear in final results.
`include_images`	boolean	no	Include images in crawl results.
`extract_depth`	string	no	Extraction depth for crawled pages.
`format`	string	no	Output format for raw_content.
`include_favicon`	boolean	no	Include favicon URL for each result.
`timeout`	number	no	Crawl timeout in seconds. Range: 10-150.
`include_usage`	boolean	no	Include credit usage details.

tavily.tavily_map 12 parameters

Schema command

kosmo integrations:schema tavily.tavily_map --json

Parameter	Type	Required	Description
`url`	string	yes	Root URL to begin mapping.
`instructions`	string	no	Natural language mapping instructions. Increases cost when supplied.
`max_depth`	integer	no	Maximum mapping depth. Range: 1-5.
`max_breadth`	integer	no	Maximum links to follow per level. Range: 1-500.
`limit`	integer	no	Maximum number of links to process.
`select_paths`	array	no	Regex path patterns to include.
`select_domains`	array	no	Regex domain patterns to include.
`exclude_paths`	array	no	Regex path patterns to exclude.
`exclude_domains`	array	no	Regex domain patterns to exclude.
`allow_external`	boolean	no	Whether external links may appear in final results.
`timeout`	number	no	Map timeout in seconds. Range: 10-150.
`include_usage`	boolean	no	Include credit usage details.

tavily.tavily_create_research_task 5 parameters

Schema command

kosmo integrations:schema tavily.tavily_create_research_task --json

Parameter	Type	Required	Description
`input`	string	yes	Research question or task to investigate.
`model`	string	no	Research agent model. mini is targeted, pro is comprehensive, auto lets Tavily choose.
`output_schema`	object	no	Optional JSON Schema with properties and optional required fields for structured output.
`citation_format`	string	no	Citation format for the research report.
`stream`	boolean	no	Not supported by this tool. Tavily streaming returns SSE rather than JSON.

tavily.tavily_get_research_task 1 parameters

Schema command

kosmo integrations:schema tavily.tavily_get_research_task --json

Parameter	Type	Required	Description
`request_id`	string	yes	Research task request_id returned by tavily_create_research_task.

tavily.tavily_get_usage 0 parameters

Schema command

kosmo integrations:schema tavily.tavily_get_usage --json

Parameter	Type	Required	Description
No parameters.

Permissions

Headless calls still follow the integration read/write permission policy. Configure read/write defaults with integrations:configure. Add --force only for trusted automation that should bypass that policy.