Can I use Voyage AI as a CLI?

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

Can I expose Voyage AI through MCP?

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

Where are Voyage AI credentials stored?

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

Can I deny write access for Voyage AI MCP tools?

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

data

Voyage AI CLI for AI Agents

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

Voyage AI CLI Setup

Voyage AI can be configured headlessly with `kosmokrator integrations:configure voyage-ai`.

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 voyage-ai --set api_key="$VOYAGE_AI_API_KEY" --enable --read allow --write ask --json
kosmokrator integrations:doctor voyage-ai --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`	`VOYAGE_AI_API_KEY`	Secret `secret`	yes	API Key
`url`	`VOYAGE_AI_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 voyage-ai.voyage_ai_create_embedding '{"input":"example_input","model":"example_model","input_type":"example_input_type","truncation":true,"output_dimension":1,"output_dtype":"example_output_dtype","encoding_format":"example_encoding_format"}' --json

Provider shortcut

kosmo integrations:voyage-ai voyage_ai_create_embedding '{"input":"example_input","model":"example_model","input_type":"example_input_type","truncation":true,"output_dimension":1,"output_dtype":"example_output_dtype","encoding_format":"example_encoding_format"}' --json

Discovery

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

Discovery commands

kosmo integrations:docs voyage-ai --json
kosmo integrations:docs voyage-ai.voyage_ai_create_embedding --json
kosmo integrations:schema voyage-ai.voyage_ai_create_embedding --json
kosmo integrations:search "Voyage AI" --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.

`voyage-ai.voyage_ai_create_embedding`

Create text embeddings with Voyage AI. Use input_type=query for search queries and input_type=document for indexed documents.

Read read

Parameters: input, model, input_type, truncation, output_dimension, output_dtype, encoding_format

Generic call

kosmo integrations:call voyage-ai.voyage_ai_create_embedding '{"input":"example_input","model":"example_model","input_type":"example_input_type","truncation":true,"output_dimension":1,"output_dtype":"example_output_dtype","encoding_format":"example_encoding_format"}' --json

Shortcut

kosmo integrations:voyage-ai voyage_ai_create_embedding '{"input":"example_input","model":"example_model","input_type":"example_input_type","truncation":true,"output_dimension":1,"output_dtype":"example_output_dtype","encoding_format":"example_encoding_format"}' --json

`voyage-ai.voyage_ai_create_contextualized_embeddings`

Create contextualized chunk embeddings. Pass inputs as an array of arrays where each inner array contains chunks from one document or one query/document item.

Read read

Parameters: inputs, model, input_type, output_dimension, output_dtype, encoding_format

Generic call

kosmo integrations:call voyage-ai.voyage_ai_create_contextualized_embeddings '{"inputs":"example_inputs","model":"example_model","input_type":"example_input_type","output_dimension":1,"output_dtype":"example_output_dtype","encoding_format":"example_encoding_format"}' --json

Shortcut

kosmo integrations:voyage-ai voyage_ai_create_contextualized_embeddings '{"inputs":"example_inputs","model":"example_model","input_type":"example_input_type","output_dimension":1,"output_dtype":"example_output_dtype","encoding_format":"example_encoding_format"}' --json

`voyage-ai.voyage_ai_create_multimodal_embeddings`

Create Voyage AI multimodal embeddings from inputs containing interleaved text, image, or video content blocks.

Read read

Parameters: inputs, model, input_type, truncation, output_encoding

Generic call

kosmo integrations:call voyage-ai.voyage_ai_create_multimodal_embeddings '{"inputs":"example_inputs","model":"example_model","input_type":"example_input_type","truncation":true,"output_encoding":"example_output_encoding"}' --json

Shortcut

kosmo integrations:voyage-ai voyage_ai_create_multimodal_embeddings '{"inputs":"example_inputs","model":"example_model","input_type":"example_input_type","truncation":true,"output_encoding":"example_output_encoding"}' --json

`voyage-ai.voyage_ai_rerank`

Rerank documents for a query using Voyage AI cross-encoder rerankers. Use after lexical or vector retrieval to improve final context quality.

Read read

Parameters: query, documents, model, top_k, return_documents, truncation

Generic call

kosmo integrations:call voyage-ai.voyage_ai_rerank '{"query":"example_query","documents":"example_documents","model":"example_model","top_k":1,"return_documents":true,"truncation":true}' --json

Shortcut

kosmo integrations:voyage-ai voyage_ai_rerank '{"query":"example_query","documents":"example_documents","model":"example_model","top_k":1,"return_documents":true,"truncation":true}' --json

`voyage-ai.voyage_ai_upload_file`

Upload a JSONL file for Voyage AI Batch API. The file content must already be formatted for the selected batch endpoint.

Write write

Parameters: filename, content, purpose

Generic call

kosmo integrations:call voyage-ai.voyage_ai_upload_file '{"filename":"example_filename","content":"example_content","purpose":"example_purpose"}' --json

Shortcut

kosmo integrations:voyage-ai voyage_ai_upload_file '{"filename":"example_filename","content":"example_content","purpose":"example_purpose"}' --json

`voyage-ai.voyage_ai_list_files`

List Voyage AI files, optionally filtered by purpose and paginated by cursor.

Read read

Parameters: purpose, limit, order, after

Generic call

kosmo integrations:call voyage-ai.voyage_ai_list_files '{"purpose":"example_purpose","limit":1,"order":"example_order","after":"example_after"}' --json

Shortcut

kosmo integrations:voyage-ai voyage_ai_list_files '{"purpose":"example_purpose","limit":1,"order":"example_order","after":"example_after"}' --json

`voyage-ai.voyage_ai_retrieve_file`

Retrieve metadata for a Voyage AI file by file_id.

Read read

Parameters: file_id

Generic call

kosmo integrations:call voyage-ai.voyage_ai_retrieve_file '{"file_id":"example_file_id"}' --json

Shortcut

kosmo integrations:voyage-ai voyage_ai_retrieve_file '{"file_id":"example_file_id"}' --json

`voyage-ai.voyage_ai_retrieve_file_content`

Retrieve raw content for a Voyage AI file, such as batch output or error JSONL.

Read read

Parameters: file_id, accept

Generic call

kosmo integrations:call voyage-ai.voyage_ai_retrieve_file_content '{"file_id":"example_file_id","accept":"example_accept"}' --json

Shortcut

kosmo integrations:voyage-ai voyage_ai_retrieve_file_content '{"file_id":"example_file_id","accept":"example_accept"}' --json

`voyage-ai.voyage_ai_delete_file`

Delete one Voyage AI file by file_id.

Write write

Parameters: file_id

Generic call

kosmo integrations:call voyage-ai.voyage_ai_delete_file '{"file_id":"example_file_id"}' --json

Shortcut

kosmo integrations:voyage-ai voyage_ai_delete_file '{"file_id":"example_file_id"}' --json

`voyage-ai.voyage_ai_bulk_delete_files`

Delete one or more Voyage AI files in an all-or-nothing bulk delete operation.

Write write

Parameters: file_ids

Generic call

kosmo integrations:call voyage-ai.voyage_ai_bulk_delete_files '{"file_ids":"example_file_ids"}' --json

Shortcut

kosmo integrations:voyage-ai voyage_ai_bulk_delete_files '{"file_ids":"example_file_ids"}' --json

`voyage-ai.voyage_ai_create_batch`

Create a Voyage AI batch inference job for embeddings, contextualized embeddings, or rerank requests using an uploaded JSONL file.

Write write

Parameters: endpoint, input_file_id, completion_window, request_params, metadata

Generic call

kosmo integrations:call voyage-ai.voyage_ai_create_batch '{"endpoint":"example_endpoint","input_file_id":"example_input_file_id","completion_window":"example_completion_window","request_params":"example_request_params","metadata":"example_metadata"}' --json

Shortcut

kosmo integrations:voyage-ai voyage_ai_create_batch '{"endpoint":"example_endpoint","input_file_id":"example_input_file_id","completion_window":"example_completion_window","request_params":"example_request_params","metadata":"example_metadata"}' --json

`voyage-ai.voyage_ai_list_batches`

List Voyage AI batch jobs with optional pagination.

Read read

Parameters: limit, after

Generic call

kosmo integrations:call voyage-ai.voyage_ai_list_batches '{"limit":1,"after":"example_after"}' --json

Shortcut

kosmo integrations:voyage-ai voyage_ai_list_batches '{"limit":1,"after":"example_after"}' --json

`voyage-ai.voyage_ai_retrieve_batch`

Retrieve a Voyage AI batch job by batch_id.

Read read

Parameters: batch_id

Generic call

kosmo integrations:call voyage-ai.voyage_ai_retrieve_batch '{"batch_id":"example_batch_id"}' --json

Shortcut

kosmo integrations:voyage-ai voyage_ai_retrieve_batch '{"batch_id":"example_batch_id"}' --json

`voyage-ai.voyage_ai_cancel_batch`

Cancel a Voyage AI batch job that is currently validating or in_progress.

Write write

Parameters: batch_id

Generic call

kosmo integrations:call voyage-ai.voyage_ai_cancel_batch '{"batch_id":"example_batch_id"}' --json

Shortcut

kosmo integrations:voyage-ai voyage_ai_cancel_batch '{"batch_id":"example_batch_id"}' --json

Function Schemas

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

voyage-ai.voyage_ai_create_embedding 7 parameters

Schema command

kosmo integrations:schema voyage-ai.voyage_ai_create_embedding --json

Parameter	Type	Required	Description
`input`	string,array	yes	Single text string or array of text strings.
`model`	string	yes	Embedding model name, e.g. voyage-4, voyage-4-large, voyage-4-lite, voyage-code-3.
`input_type`	string	no	Input intent. Use query or document for retrieval workflows.
`truncation`	boolean	no	Whether to truncate inputs to fit model context. Defaults to true upstream.
`output_dimension`	integer	no	Optional output dimensions: commonly 2048, 1024, 512, or 256 for supported models.
`output_dtype`	string	no	Embedding data type.
`encoding_format`	string	no	Optional base64 encoding for embeddings.

voyage-ai.voyage_ai_create_contextualized_embeddings 6 parameters

Schema command

kosmo integrations:schema voyage-ai.voyage_ai_create_contextualized_embeddings --json

Parameter	Type	Required	Description
`inputs`	array	yes	Array of arrays of strings to embed together with context.
`model`	string	yes	Model name. Recommended: voyage-context-3.
`input_type`	string	no	Input intent. Use query or document for retrieval workflows.
`output_dimension`	integer	no	Output dimensions. voyage-context-3 supports 2048, 1024, 512, 256.
`output_dtype`	string	no	Embedding data type.
`encoding_format`	string	no	Optional base64 encoding for embeddings.

voyage-ai.voyage_ai_create_multimodal_embeddings 5 parameters

Schema command

kosmo integrations:schema voyage-ai.voyage_ai_create_multimodal_embeddings --json

Parameter	Type	Required	Description
`inputs`	array	yes	Array of objects with a content array of text/image/video blocks.
`model`	string	yes	Model name. Recommended: voyage-multimodal-3.5.
`input_type`	string	no	Input intent. Use query or document for retrieval workflows.
`truncation`	boolean	no	Whether to truncate inputs to fit model context.
`output_encoding`	string	no	Optional base64 encoding for embeddings.

voyage-ai.voyage_ai_rerank 6 parameters

Schema command

kosmo integrations:schema voyage-ai.voyage_ai_rerank --json

Parameter	Type	Required	Description
`query`	string	yes	Query to rank documents against.
`documents`	array	yes	Documents to rerank. Maximum 1,000 documents.
`model`	string	yes	Reranker model. Recommended: rerank-2.5 or rerank-2.5-lite.
`top_k`	integer	no	Number of most relevant documents to return.
`return_documents`	boolean	no	Whether to include source documents in the response.
`truncation`	boolean	no	Whether to truncate inputs to fit model context. Defaults to true upstream.

voyage-ai.voyage_ai_upload_file 3 parameters

Schema command

kosmo integrations:schema voyage-ai.voyage_ai_upload_file --json

Parameter	Type	Required	Description
`filename`	string	yes	Filename to send to Voyage AI, usually ending in .jsonl.
`content`	string	yes	Raw JSONL file content.
`purpose`	string	no	File purpose. Currently must be batch. Defaults to batch.

voyage-ai.voyage_ai_list_files 4 parameters

Schema command

kosmo integrations:schema voyage-ai.voyage_ai_list_files --json

Parameter	Type	Required	Description
`purpose`	string	no	Only return files with this purpose.
`limit`	integer	no	Number of files to return. Range: 1-10000.
`order`	string	no	Sort order by created_at.
`after`	string	no	Pagination cursor: file ID after which to continue.

voyage-ai.voyage_ai_retrieve_file 1 parameters

Schema command

kosmo integrations:schema voyage-ai.voyage_ai_retrieve_file --json

Parameter	Type	Required	Description
`file_id`	string	yes	Voyage AI file ID.

voyage-ai.voyage_ai_retrieve_file_content 2 parameters

Schema command

kosmo integrations:schema voyage-ai.voyage_ai_retrieve_file_content --json

Parameter	Type	Required	Description
`file_id`	string	yes	Voyage AI file ID.
`accept`	string	no	Accept header. Defaults to text/plain.

voyage-ai.voyage_ai_delete_file 1 parameters

Schema command

kosmo integrations:schema voyage-ai.voyage_ai_delete_file --json

Parameter	Type	Required	Description
`file_id`	string	yes	Voyage AI file ID to delete.

voyage-ai.voyage_ai_bulk_delete_files 1 parameters

Schema command

kosmo integrations:schema voyage-ai.voyage_ai_bulk_delete_files --json

Parameter	Type	Required	Description
`file_ids`	array	yes	File IDs to delete.

voyage-ai.voyage_ai_create_batch 5 parameters

Schema command

kosmo integrations:schema voyage-ai.voyage_ai_create_batch --json

Parameter	Type	Required	Description
`endpoint`	string	yes	Batch endpoint: v1/embeddings, v1/contextualizedembeddings, or v1/rerank.
`input_file_id`	string	yes	Uploaded JSONL file ID with purpose=batch.
`completion_window`	string	yes	Completion window. Currently only 12h is supported.
`request_params`	object	yes	Endpoint parameters shared by every request in the batch, excluding per-line input data.
`metadata`	object	no	Optional metadata object. Upstream supports up to 16 key-value pairs.

voyage-ai.voyage_ai_list_batches 2 parameters

Schema command

kosmo integrations:schema voyage-ai.voyage_ai_list_batches --json

Parameter	Type	Required	Description
`limit`	integer	no	Number of batches to return. Range: 1-100.
`after`	string	no	Pagination cursor: batch ID after which to continue.

voyage-ai.voyage_ai_retrieve_batch 1 parameters

Schema command

kosmo integrations:schema voyage-ai.voyage_ai_retrieve_batch --json

Parameter	Type	Required	Description
`batch_id`	string	yes	Voyage AI batch ID.

voyage-ai.voyage_ai_cancel_batch 1 parameters

Schema command

kosmo integrations:schema voyage-ai.voyage_ai_cancel_batch --json

Parameter	Type	Required	Description
`batch_id`	string	yes	Voyage AI batch ID to cancel.

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.