Retrieval and chat commands

These three commands consume Knowledge Bases: search runs semantic retrieval, chat holds a multi-turn conversation, and retrieve queries a single Knowledge Base directly but is deprecated. Shared conventions for authentication, workspace ID, global flags, and output formats are covered in the CLI overview. The examples below assume the workspace ID is already set in the config file; retrieve does not use a workspace ID.

Choosing a command

Command	Input	When to use
`search`	`--agent-id`	Semantic retrieval. Scope and strategy come from the service config, supporting multiple Knowledge Bases, routing, and reranking
`chat`	`--agent-id`	Multi-turn Q&A. Streams the model-generated answer
`retrieve`	`--index-id`	Deprecated. Queries one Knowledge Base directly, limited in capability and no longer developed

kscli search

Run semantic retrieval against a Knowledge Base.

kscli search --query <text> --agent-id <id> [flags]

Parameters

Parameter	Type	Required	Description
`--query <text>`	string	Yes	Query text, cannot be empty
`--agent-id <id>`	string	Yes	Retrieval service ID, found with `service list --scene search`
`--agent-version <version>`	string	No	Service version, `beta` (draft) or a published number. Defaults to the latest published version
`--image <url>`	array	No	Image URL, repeatable, for multimodal retrieval

Output

[1] (score: 0.9512)
retrieved text content…

[2] (score: 0.8734)
another passage…

With no matches the command prints No results found.. json mode returns the full result including each hit's score and metadata. Notes

Retrieval scope and strategy (multi-Knowledge-Base weighting, routing, reranking, and so on) come from the service configuration behind --agent-id, so only --query and --agent-id are needed — retrieval parameters do not have to be repeated on the command line.
--agent-version beta calls the draft configuration, which is how you validate tuning before publishing.

Examples

# Basic retrieval
kscli search --query "What is RAG" --agent-id aid-xxx

# Multimodal retrieval
kscli search --query "describe this image" --agent-id aid-xxx --image https://example.com/img.jpg

# Validate the draft configuration
kscli search --query "test" --agent-id aid-xxx --agent-version beta

kscli chat

Hold a RAG conversation with a Knowledge Base, with streaming output.

kscli chat --message <text> --agent-id <id> [flags]

Parameters

Parameter	Type	Required	Description
`--message <text>`	array	Yes	Message text, repeatable. Supports a `role:content` prefix to set the role (such as `user:hello`), defaulting to `user`, and follows the OpenAI message format
`--agent-id <id>`	string	Yes	Q&A service ID, found with `service list --scene chat`
`--agent-version <version>`	string	No	Service version, `beta` (draft) or a published number. Defaults to the latest published version
`--image <url>`	array	No	Image URL, repeatable, attached to the last user message

At least one of --message or --image is required — an image-only query can pass --image alone. --image cannot be combined with a structured message that already contains image content. Output In an interactive terminal the answer streams in real time, and the progress label follows the server-side stage:

🔍 Retrieving...
✍️ Generating...
the generated answer streams in character by character…

When output is redirected or piped, the full text is buffered and printed at once. json mode returns:

{
  "answer": "the complete answer text…",
  "request_id": "xxx"
}

quiet mode prints the complete answer text. Notes

Pass conversation history by repeating --message with role: prefixes.
--verbose writes detailed streaming events to stderr, which helps diagnose interruptions or anomalies.
On Chat API error, check that --agent-id exists, the service is published, and the API Key is valid. The error code and message are returned verbatim by the server.

Examples

# Single turn
kscli chat --message "What is RAG" --agent-id aid-xxx

# Multi-turn with history
kscli chat \
  --message "user:What is RAG" \
  --message "assistant:RAG is retrieval-augmented generation…" \
  --message "How does it work" \
  --agent-id aid-xxx

# Multimodal conversation
kscli chat \
  --message "Describe these images" \
  --image https://example.com/a.png \
  --image https://example.com/b.png \
  --agent-id aid-xxx

# Validate the draft configuration
kscli chat --message "test" --agent-id aid-xxx --agent-version beta

kscli retrieve

Query a single Knowledge Base directly.

This command is deprecated and prints a deprecation warning when used. Use search instead: it drives retrieval strategy through --agent-id and supports multiple Knowledge Bases, routing, and reranking, while retrieve operates on a single Knowledge Base ID, is limited in capability, and is no longer developed.

kscli retrieve --index-id <id> --query <text> [flags]

Parameters

Parameter	Type	Required	Description
`--index-id <id>`	string	Yes	Knowledge Base ID
`--query <text>`	string	Yes	Query text
`--dense-similarity-top-k <n>`	number	No	Semantic retrieval recall count
`--sparse-similarity-top-k <n>`	number	No	Keyword retrieval recall count
`--rerank`	switch	No	Enable reranking
`--rerank-top-n <n>`	number	No	Number of results after reranking
`--rerank-model <name>`	string	No	Rerank model name, such as `qwen3-rerank-hybrid`
`--rerank-mode <mode>`	string	No	Rerank mode, `qa`, `similar`, or `custom`
`--rerank-instruct <text>`	string	No	Custom rerank instruction, used with `--rerank-mode custom`
`--top-k <n>`	number	No	Number of results. Deprecated — use `--rerank-top-n`

Output Same format as search. With no matches the command prints No results found.. Notes

This command does not need a workspace ID; it queries --index-id directly without requiring a retrieval service.
--top-k is deprecated and prints a warning on stderr when passed — use --rerank-top-n.

Examples

# Basic retrieval
kscli retrieve --index-id idx-xxx --query "how to configure the chunking strategy"

# With reranking
kscli retrieve --index-id idx-xxx --query "RAG retrieval" \
  --rerank --rerank-model qwen3-rerank-hybrid

​Choosing a command

​kscli search

​kscli chat

​kscli retrieve

Choosing a command

kscli search

kscli chat

kscli retrieve