A Knowledge Base stores the indexed content produced by parsing documents and is the data carrier for retrieval. This group has 6 commands.
Shared conventions for authentication, workspace ID, global flags, output formats, confirmation prompts, and dry-run mode are covered in the CLI overview. The examples below assume the workspace ID is already set in the config file, so --workspace-id is omitted.
kscli kb list
List Knowledge Bases in the workspace.
Parameters
| Parameter | Type | Required | Description |
|---|
--name <text> | string | No | Fuzzy filter by Knowledge Base name, 1–20 chars |
--page-number <n> | number | No | Page number, default 1 |
--page-size <n> | number | No | Items per page, default 20, range 1–100 |
text mode prints one Knowledge Base per line with fields separated by double spaces, followed by the total:
idx-xxx my-kb text-embedding-v4 600 product docs
total: 1
quiet mode prints one Knowledge Base ID per line. json mode returns the full result, with the list under data.rows.
The ID in the output is what you pass as --index-id to later commands.
Examples
# List all Knowledge Bases
kscli kb list
# Filter by name and paginate
kscli kb list --name demo --page-number 2 --page-size 50
kscli kb info
Show Knowledge Base configuration details.
kscli kb info --index-id <id> [flags]
| Parameter | Type | Required | Description |
|---|
--index-id <id> | string | Yes | Knowledge Base ID |
text mode groups the settings by dimension:
Basic:
id: idx-xxx
name: my-kb
description: product docs
Indexing: [immutable — recreate required to change]
embeddingModelName: text-embedding-v4
embeddingDimension: 1024
chunkSize: 600
overlapSize: 100
Retrieval:
rerankModelName: qwen3-rerank
rerankMinScore: 0.2
rerankTopN: 5
enableRewrite: true
Data:
sourceType: DATA_CENTER_FILE
quiet mode prints the Knowledge Base ID. json mode returns the full configuration.
The index settings under the Indexing group (embedding model, embedding dimension, chunk size, overlap size, chunk mode, and so on) cannot be changed after the Knowledge Base is created. Adjusting them requires recreating the Knowledge Base and reimporting the documents.
kscli kb info --index-id idx-xxx
kscli kb create
Create a Knowledge Base and import data center files or categories.
kscli kb create --name <text> (--doc-id <id> | --category-id <id>) [flags]
| Parameter | Type | Required | Description |
|---|
--name <text> | string | Yes | Knowledge Base name, 1–20 chars, unique in the workspace |
--doc-id <id> | array | One of two | Data center file ID, repeatable; mutually exclusive with --category-id |
--category-id <id> | array | One of two | Import every file under this category, repeatable; mutually exclusive with --doc-id |
--embedding-model <name> | string | No | Embedding model name, default text-embedding-v4 |
--chunk-size <n> | number | No | Chunk size in characters, default 600, recommended 300–800 |
--wait | switch | No | Poll the initial import job to a terminal state |
--poll-interval <seconds> | number | No | Polling interval in seconds, default 5 |
--doc-id and --category-id are mutually exclusive; exactly one is required.
Output
index_id: idx-xxx
ingestion_id: job-xxx
status: COMPLETED
quiet mode prints only the Knowledge Base ID. json mode returns the Knowledge Base ID and import job ID, plus a final_status field when --wait is used.
Notes
- The created Knowledge Base is document-type (unstructured).
- Use the returned
ingestion_id with kscli doc status to track import progress, or pass --wait to block until it finishes.
- With
--wait, if some documents fail to parse the command exits non-zero, but the Knowledge Base itself was created successfully — the error message names the failed documents.
Examples
# Create from specific files
kscli kb create --name demo --doc-id file-xxx
# Import from a category and wait for completion
kscli kb create --name demo --category-id cate-xxx --wait
# Specify embedding model and chunk size
kscli kb create --name my-kb --doc-id file-a --doc-id file-b \
--embedding-model text-embedding-v4 --chunk-size 400
kscli kb update
Update the Knowledge Base name, description, or rerank score threshold.
kscli kb update --index-id <id> [flags]
| Parameter | Type | Required | Description |
|---|
--index-id <id> | string | Yes | Knowledge Base ID |
--name <text> | string | No | New name, 1–20 chars |
--description <text> | string | No | New description |
--rerank-min-score <score> | number | No | Rerank minimum score threshold, range 0–1; chunks below it are filtered out |
--name, --description, or --rerank-min-score is required, otherwise the command reports Nothing to update.
Output
quiet mode prints nothing. json mode returns the full result.
Examples
# Update the description
kscli kb update --index-id idx-xxx --description "product docs v2"
# Adjust the rerank threshold
kscli kb update --index-id idx-xxx --rerank-min-score 0.3
kscli kb delete
Delete a Knowledge Base along with all its documents and chunks.
kscli kb delete --index-id <id> [flags]
| Parameter | Type | Required | Description |
|---|
--index-id <id> | string | Yes | Knowledge Base ID |
--yes | switch | No | Skip the confirmation prompt |
Deletion is irreversible — the Knowledge Base and all of its indexed content are permanently removed. Without --yes, the command first shows the Knowledge Base name and document count for confirmation.
kscli file delete.
Examples
# Delete with an interactive confirmation
kscli kb delete --index-id idx-xxx
# Skip confirmation, for automated scripts
kscli kb delete --index-id idx-xxx --yes
kscli kb stats
Show storage usage and QPS metrics for a Knowledge Base.
kscli kb stats --index-id <id> [flags]
| Parameter | Type | Required | Description |
|---|
--index-id <id> | string | Yes | Knowledge Base ID |
--start <time> | string | No | Range start, Unix seconds or ISO date, must be in the past, default 24 hours ago |
--end <time> | string | No | Range end, Unix seconds or ISO date, must be in the past, default now |
plan: standard
storage: 100 / 1000
peak qps: 5
qps windows: 24 data point(s)
quiet and json modes return the full storage and QPS monitoring data.
--start and --end accept both Unix second timestamps and ISO dates (such as 2026-07-30); millisecond timestamps are handled automatically.
Examples
# Last 24 hours
kscli kb stats --index-id idx-xxx
# A specific date range
kscli kb stats --index-id idx-xxx --start 2026-07-30 --end 2026-07-31