Can I use Perplexity as a CLI?

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

Can I expose Perplexity through MCP?

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

Where are Perplexity credentials stored?

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

Can I deny write access for Perplexity MCP tools?

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

data

Perplexity CLI for AI Agents

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

Perplexity CLI Setup

Perplexity can be configured headlessly with `kosmokrator integrations:configure perplexity`.

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 perplexity --set api_key="$PERPLEXITY_API_KEY" --enable --read allow --write ask --json
kosmokrator integrations:doctor perplexity --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`	`PERPLEXITY_API_KEY`	Secret `secret`	yes	API Key
`url`	`PERPLEXITY_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 perplexity.perplexity_chat '{"messages":"example_messages","model":"example_model","temperature":1,"top_p":1,"max_tokens":1,"stop":"example_stop","response_format":"example_response_format","web_search_options":"example_web_search_options"}' --json

Provider shortcut

kosmo integrations:perplexity perplexity_chat '{"messages":"example_messages","model":"example_model","temperature":1,"top_p":1,"max_tokens":1,"stop":"example_stop","response_format":"example_response_format","web_search_options":"example_web_search_options"}' --json

Discovery

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

Discovery commands

kosmo integrations:docs perplexity --json
kosmo integrations:docs perplexity.perplexity_chat --json
kosmo integrations:schema perplexity.perplexity_chat --json
kosmo integrations:search "Perplexity" --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.

`perplexity.perplexity_chat`

Create a Perplexity Sonar chat completion. Supports multi-turn conversations, web search controls, citations, images, and related questions.

Read read

Parameters: messages, model, temperature, top_p, max_tokens, stop, response_format, web_search_options, search_mode, search_domain_filter, search_language_filter, search_recency_filter, return_images, return_related_questions, disable_search, reasoning_effort, language_preference

Generic call

kosmo integrations:call perplexity.perplexity_chat '{"messages":"example_messages","model":"example_model","temperature":1,"top_p":1,"max_tokens":1,"stop":"example_stop","response_format":"example_response_format","web_search_options":"example_web_search_options"}' --json

Shortcut

kosmo integrations:perplexity perplexity_chat '{"messages":"example_messages","model":"example_model","temperature":1,"top_p":1,"max_tokens":1,"stop":"example_stop","response_format":"example_response_format","web_search_options":"example_web_search_options"}' --json

`perplexity.perplexity_ask`

Ask Perplexity a one-shot question through the Sonar chat endpoint and get an answer with citations and optional search metadata.

Read read

Parameters: query, model, temperature, top_p, max_tokens, response_format, web_search_options, search_mode, search_domain_filter, search_language_filter, return_images, return_related_questions, search_recency_filter, disable_search, reasoning_effort, language_preference

Generic call

kosmo integrations:call perplexity.perplexity_ask '{"query":"example_query","model":"example_model","temperature":1,"top_p":1,"max_tokens":1,"response_format":"example_response_format","web_search_options":"example_web_search_options","search_mode":"example_search_mode"}' --json

Shortcut

kosmo integrations:perplexity perplexity_ask '{"query":"example_query","model":"example_model","temperature":1,"top_p":1,"max_tokens":1,"response_format":"example_response_format","web_search_options":"example_web_search_options","search_mode":"example_search_mode"}' --json

`perplexity.perplexity_search`

Search the web with Perplexity Search API and return relevant page results. Use this when you need sources/content, not a generated answer.

Read read

Parameters: query, country, max_results, max_tokens, max_tokens_per_page, search_language_filter, search_domain_filter, last_updated_after_filter, last_updated_before_filter, search_after_date_filter, search_before_date_filter

Generic call

kosmo integrations:call perplexity.perplexity_search '{"query":"example_query","country":"example_country","max_results":1,"max_tokens":1,"max_tokens_per_page":1,"search_language_filter":"example_search_language_filter","search_domain_filter":"example_search_domain_filter","last_updated_after_filter":"example_last_updated_after_filter"}' --json

Shortcut

kosmo integrations:perplexity perplexity_search '{"query":"example_query","country":"example_country","max_results":1,"max_tokens":1,"max_tokens_per_page":1,"search_language_filter":"example_search_language_filter","search_domain_filter":"example_search_domain_filter","last_updated_after_filter":"example_last_updated_after_filter"}' --json

`perplexity.perplexity_create_async_sonar`

Submit an asynchronous Sonar chat completion request and return the request id/status for later polling.

Read read

Parameters: messages, query, model, idempotency_key, max_tokens, temperature, web_search_options, reasoning_effort

Generic call

kosmo integrations:call perplexity.perplexity_create_async_sonar '{"messages":"example_messages","query":"example_query","model":"example_model","idempotency_key":"example_idempotency_key","max_tokens":1,"temperature":1,"web_search_options":"example_web_search_options","reasoning_effort":"example_reasoning_effort"}' --json

Shortcut

kosmo integrations:perplexity perplexity_create_async_sonar '{"messages":"example_messages","query":"example_query","model":"example_model","idempotency_key":"example_idempotency_key","max_tokens":1,"temperature":1,"web_search_options":"example_web_search_options","reasoning_effort":"example_reasoning_effort"}' --json

`perplexity.perplexity_list_async_sonar`

List asynchronous Sonar chat completion requests for the configured Perplexity account.

Read read

Parameters: none

Generic call

kosmo integrations:call perplexity.perplexity_list_async_sonar '{}' --json

Shortcut

kosmo integrations:perplexity perplexity_list_async_sonar '{}' --json

`perplexity.perplexity_get_async_sonar`

Retrieve status and response data for a Perplexity asynchronous Sonar request.

Read read

Parameters: request_id

Generic call

kosmo integrations:call perplexity.perplexity_get_async_sonar '{"request_id":"example_request_id"}' --json

Shortcut

kosmo integrations:perplexity perplexity_get_async_sonar '{"request_id":"example_request_id"}' --json

`perplexity.perplexity_agent`

Create a Perplexity Agent API response for an input prompt with optional model and tool configuration.

Read read

Parameters: input, model, instructions, tools, temperature, max_output_tokens

Generic call

kosmo integrations:call perplexity.perplexity_agent '{"input":"example_input","model":"example_model","instructions":"example_instructions","tools":"example_tools","temperature":1,"max_output_tokens":1}' --json

Shortcut

kosmo integrations:perplexity perplexity_agent '{"input":"example_input","model":"example_model","instructions":"example_instructions","tools":"example_tools","temperature":1,"max_output_tokens":1}' --json

`perplexity.perplexity_embeddings`

Create Perplexity embeddings for a string or array of strings.

Read read

Parameters: input, model, dimensions, encoding_format

Generic call

kosmo integrations:call perplexity.perplexity_embeddings '{"input":"example_input","model":"example_model","dimensions":1,"encoding_format":"example_encoding_format"}' --json

Shortcut

kosmo integrations:perplexity perplexity_embeddings '{"input":"example_input","model":"example_model","dimensions":1,"encoding_format":"example_encoding_format"}' --json

`perplexity.perplexity_contextualized_embeddings`

Create contextualized embeddings for document chunks grouped by source document.

Read read

Parameters: input, model, dimensions, encoding_format

Generic call

kosmo integrations:call perplexity.perplexity_contextualized_embeddings '{"input":"example_input","model":"example_model","dimensions":1,"encoding_format":"example_encoding_format"}' --json

Shortcut

kosmo integrations:perplexity perplexity_contextualized_embeddings '{"input":"example_input","model":"example_model","dimensions":1,"encoding_format":"example_encoding_format"}' --json

`perplexity.perplexity_list_models`

List Perplexity Agent API models. Returns model IDs in OpenAI-compatible list format.

Read read

Parameters: none

Generic call

kosmo integrations:call perplexity.perplexity_list_models '{}' --json

Shortcut

kosmo integrations:perplexity perplexity_list_models '{}' --json

Function Schemas

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

perplexity.perplexity_chat 17 parameters

Schema command

kosmo integrations:schema perplexity.perplexity_chat --json

Parameter	Type	Required	Description
`messages`	array	yes	Array of message objects, each with "role" (system, user, or assistant) and "content" (string). Example: [{"role": "user", "content": "What is AI?"}].
`model`	string	no	Sonar model to use. Common values: "sonar", "sonar-pro", "sonar-deep-research", "sonar-reasoning-pro". Defaults to "sonar".
`temperature`	number	no	Sampling temperature (0.0–2.0). Lower values are more focused, higher values more creative. Defaults to 0.2.
`top_p`	number	no	Nucleus sampling value between 0 and 1.
`max_tokens`	integer	no	Maximum number of tokens in the response.
`stop`	array	no	Stop sequence string or array of stop sequences.
`response_format`	object	no	Optional response format object, including JSON schema formats supported by Sonar.
`web_search_options`	object	no	Current Perplexity web search options object. Use this for advanced search/image/date filters.
`search_mode`	string	no	Convenience web search option: "web", "academic", or "sec".
`search_domain_filter`	array	no	Convenience web search option: domains to limit search results to (e.g., ["wikipedia.org"]).
`search_language_filter`	array	no	Convenience web search option: ISO 639-1 language codes.
`search_recency_filter`	string	no	Convenience web search option: "hour", "day", "week", "month", or "year".
`return_images`	boolean	no	Convenience web search option: include image results.
`return_related_questions`	boolean	no	Convenience web search option: include related questions.
`disable_search`	boolean	no	Convenience web search option: disable web search.
`reasoning_effort`	string	no	Reasoning effort for supported models: "minimal", "low", "medium", or "high".
`language_preference`	string	no	Preferred response language as an ISO 639-1 code.

perplexity.perplexity_ask 16 parameters

Schema command

kosmo integrations:schema perplexity.perplexity_ask --json

Parameter	Type	Required	Description
`query`	string	yes	The question or prompt to ask Perplexity AI.
`model`	string	no	Sonar model to use. Common values: "sonar", "sonar-pro", "sonar-deep-research", "sonar-reasoning-pro". Defaults to "sonar".
`temperature`	number	no	Sampling temperature (0.0–2.0). Lower values are more focused. Defaults to 0.2.
`top_p`	number	no	Nucleus sampling value between 0 and 1.
`max_tokens`	integer	no	Maximum number of tokens in the response.
`response_format`	object	no	Optional response format object, including JSON schema formats supported by Sonar.
`web_search_options`	object	no	Current Perplexity web search options object. Use this for advanced search/image/date filters.
`search_mode`	string	no	Convenience web search option: "web", "academic", or "sec".
`search_domain_filter`	array	no	List of domains to limit search results to (e.g., ["wikipedia.org"]).
`search_language_filter`	array	no	Convenience web search option: ISO 639-1 language codes.
`return_images`	boolean	no	Whether to return images in the response. Defaults to false.
`return_related_questions`	boolean	no	Whether to return related questions. Defaults to false.
`search_recency_filter`	string	no	Filter search results by recency: "hour", "day", "week", "month", or "year".
`disable_search`	boolean	no	Convenience web search option: disable web search.
`reasoning_effort`	string	no	Reasoning effort for supported models: "minimal", "low", "medium", or "high".
`language_preference`	string	no	Preferred response language as an ISO 639-1 code.

perplexity.perplexity_search 11 parameters

Schema command

kosmo integrations:schema perplexity.perplexity_search --json

Parameter	Type	Required	Description
`query`	string	yes	Search query string or array of query strings.
`country`	string	no	Optional ISO 3166-1 alpha-2 country code.
`max_results`	integer	no	Maximum number of results to return, from 1 to 20.
`max_tokens`	integer	no	Maximum total context tokens.
`max_tokens_per_page`	integer	no	Maximum tokens per returned page.
`search_language_filter`	array	no	ISO 639-1 language codes.
`search_domain_filter`	array	no	Domains to limit search results to.
`last_updated_after_filter`	string	no	Only return pages updated after this date in MM/DD/YYYY format.
`last_updated_before_filter`	string	no	Only return pages updated before this date in MM/DD/YYYY format.
`search_after_date_filter`	string	no	Only return pages published after this date in MM/DD/YYYY format.
`search_before_date_filter`	string	no	Only return pages published before this date in MM/DD/YYYY format.

perplexity.perplexity_create_async_sonar 8 parameters

Schema command

kosmo integrations:schema perplexity.perplexity_create_async_sonar --json

Parameter	Type	Required	Description
`messages`	array	no	Array of message objects. Required unless query is provided.
`query`	string	no	Convenience single user query. Used only when messages is omitted.
`model`	string	no	Sonar model to use. Defaults to "sonar-deep-research".
`idempotency_key`	string	no	Optional unique key to prevent duplicate async requests.
`max_tokens`	integer	no	Maximum number of completion tokens.
`temperature`	number	no	Sampling temperature between 0 and 2.
`web_search_options`	object	no	Current Perplexity web search options object.
`reasoning_effort`	string	no	Reasoning effort for supported models: "minimal", "low", "medium", or "high".

perplexity.perplexity_list_async_sonar 0 parameters

Schema command

kosmo integrations:schema perplexity.perplexity_list_async_sonar --json

Parameter	Type	Required	Description
No parameters.

perplexity.perplexity_get_async_sonar 1 parameters

Schema command

kosmo integrations:schema perplexity.perplexity_get_async_sonar --json

Parameter	Type	Required	Description
`request_id`	string	yes	Async Sonar request id returned by create_async_sonar.

perplexity.perplexity_agent 6 parameters

Schema command

kosmo integrations:schema perplexity.perplexity_agent --json

Parameter	Type	Required	Description
`input`	string	yes	Input prompt for the Agent API.
`model`	string	no	Optional Agent API model id from list_models.
`instructions`	string	no	Optional high-level instructions for the agent response.
`tools`	array	no	Optional Agent API tools array.
`temperature`	number	no	Optional sampling temperature.
`max_output_tokens`	integer	no	Optional maximum output tokens.

perplexity.perplexity_embeddings 4 parameters

Schema command

kosmo integrations:schema perplexity.perplexity_embeddings --json

Parameter	Type	Required	Description
`input`	string	yes	Text string or array of text strings to embed.
`model`	string	no	Embedding model. Defaults to "pplx-embed-v1-0.6b".
`dimensions`	integer	no	Optional output dimensions.
`encoding_format`	string	no	Embedding encoding format: "base64_int8" or "base64_binary".

perplexity.perplexity_contextualized_embeddings 4 parameters

Schema command

kosmo integrations:schema perplexity.perplexity_contextualized_embeddings --json

Parameter	Type	Required	Description
`input`	array	yes	Nested array where each inner array contains chunks from one document.
`model`	string	no	Contextualized embedding model. Defaults to "pplx-embed-context-v1-0.6b".
`dimensions`	integer	no	Optional output dimensions.
`encoding_format`	string	no	Embedding encoding format: "base64_int8" or "base64_binary".

perplexity.perplexity_list_models 0 parameters

Schema command

kosmo integrations:schema perplexity.perplexity_list_models --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.