CLI Overview

kscli (Knowledge Studio CLI) is the command-line tool for Knowledge Bases. Its 34 commands span Knowledge Base setup, content maintenance, retrieval service management, and retrieval/chat. It fits local debugging, scripting, and CI/CD pipelines.

Installation

Requires Node.js 20 or later.

npm install -g knowledge-studio-cli

Verify the installation:

kscli --version

Upgrade to the latest version:

kscli update

Initial configuration

Write the API Key and default workspace ID to the config file so later commands do not need to repeat them:

kscli config set --key api_key --value sk-xxxxxxxxxxxxxxxx
kscli config set --key workspace_id --value ws-xxxxxxxx

View the current configuration:

kscli config show

You can then run commands directly:

kscli kb list

Create the API Key on the console API Key page. Find the workspace ID in the console address bar or on the workspace details page.

Core concepts

Commands are organized around three resource layers. Understanding the hierarchy helps you pick the right command:

Layer	Resources	Description	Command groups
Data	Collection / Category / File	File storage and organization. Files enter the data center first, then get imported into Knowledge Bases, and one file can be referenced by several Knowledge Bases	`collection`, `category`, `file`
Index	Knowledge Base / Document / Chunk	Documents are parsed into chunks and indexed. Index settings are immutable after creation	`kb`, `doc`, `chunk`
Service	Retrieval service	The retrieval entry point for Knowledge Bases, holding model, policy, and rerank settings, with a beta draft and published versions	`service`

Data flow: local files or OSS objects → data center (doc upload / doc import-oss) → Knowledge Base (kb create / doc upload --index-id) → retrieval service (service create --index-id) → retrieval or chat (search / chat).

Shared conventions

Authentication

All commands authenticate with an API Key, resolved in this order:

The --api-key <key> flag
The DASHSCOPE_API_KEY environment variable
api_key in the config file

Workspace ID

Knowledge Base resources belong to a workspace, so every command except retrieve needs a workspace ID, resolved in this order:

The --workspace-id <id> flag
The BAILIAN_WORKSPACE_ID environment variable
workspace_id in the config file

Missing values produce Workspace ID is required.. Examples in this document and the command manuals assume the workspace ID is already set in the config file, so --workspace-id is omitted.

Global flags

These flags apply to every command and are not repeated in the per-command parameter tables:

Flag	Type	Description
`--output <format>`	string	Output format, `text` (default) or `json`
`--api-key <key>`	string	API Key
`--workspace-id <id>`	string	Workspace ID
`--base-url <url>`	string	API base URL, rarely needed
`--timeout <seconds>`	number	Request timeout in seconds
`--quiet`	switch	Quiet mode, prints only the essential result
`--verbose`	switch	Verbose mode, prints request details to stderr
`--dry-run`	switch	Dry-run mode, previews the operation without submitting it
`--config <name>`	string	Run with the named config profile

Output formats

text (default): structured text for terminal reading.
json (--output json): the full JSON result, for scripting and programmatic parsing.
quiet (--quiet): the most compact output, usually just IDs, for piping.

For example, pipe all chunk IDs of a document into a delete command:

kscli chunk list --index-id idx-xxx --doc-id doc-xxx --quiet

Confirmation prompts

These commands prompt for confirmation before executing: kb delete, doc delete, chunk delete, file delete, category delete, service delete, service deploy. Pass --yes to skip the prompt in automated scripts.

Dry-run mode

--dry-run previews the operation without submitting any change. Some commands still run local validation in dry-run mode — for example, doc upload checks file formats and lists the files it would skip, which helps catch problems early:

kscli doc upload --file ./docs/ --dry-run --verbose

Common workflows

Build a Knowledge Base from scratch and retrieve

# 1. Upload a local file to the data center; returns a file ID
kscli doc upload --file ./docs/intro.md

# 2. Create a Knowledge Base from the file; returns the KB ID and import job ID
kscli kb create --name my-kb --doc-id file-xxx --wait

# 3. Create a retrieval service bound to the KB; returns the service ID
kscli service create --name my-search --scene search --index-id idx-xxx

# 4. Publish the service
kscli service deploy --agent-id aid-xxx --yes

# 5. Retrieve
kscli search --query "What is RAG" --agent-id aid-xxx

Bulk import a directory into an existing Knowledge Base

# 1. Upload the whole directory and import it, polling to completion
kscli doc upload --file ./docs/ --index-id idx-xxx --wait

# 2. Check document parse status
kscli doc list --index-id idx-xxx

# 3. If a document failed, inspect the import job
kscli doc status --index-id idx-xxx --job-id job-xxx

Create and tune a Q&A service

# 1. Create a chat-scene service; starts as draft with a beta version
kscli service create --name my-qa --scene chat --index-id idx-xxx

# 2. Adjust the draft config
kscli service update --agent-id aid-xxx --model qwen-max --temperature 0.7

# 3. Validate against the beta draft
kscli chat --message "What is RAG" --agent-id aid-xxx --agent-version beta

# 4. Publish once validated
kscli service deploy --agent-id aid-xxx --version-desc "first release" --yes

Correct Knowledge Base content

# 1. List chunks to get chunk IDs and owning document IDs
kscli chunk list --index-id idx-xxx

# 2. Fix chunk content
kscli chunk update --index-id idx-xxx --chunk-id chunk-xxx --doc-id doc-xxx --content "corrected text"

# 3. Exclude an outdated chunk from retrieval while keeping the content
kscli chunk update --index-id idx-xxx --chunk-id chunk-xxx --doc-id doc-xxx --exclude

# 4. Add a chunk manually
kscli chunk add --index-id idx-xxx --doc-id doc-xxx --content "new knowledge snippet" --title "Addendum"

Reuse an existing service config

# 1. Copy the service into a new draft; the name gets a copy_ prefix
kscli service copy --agent-id aid-source

# 2. Adjust the copy
kscli service update --agent-id aid-new --name "improved" --temperature 0.5

# 3. Validate and publish
kscli chat --message "test" --agent-id aid-new --agent-version beta
kscli service deploy --agent-id aid-new --yes

Bulk import from OSS

# 1. Import files from an authorized OSS bucket into the data center
kscli doc import-oss \
  --bucket my-bucket --region cn-beijing \
  --oss-key docs/a.pdf --oss-key docs/b.docx

# 2. Create a Knowledge Base from those files
kscli kb create --name oss-kb --doc-id file-a --doc-id file-b --wait

Command groups

Knowledge Bases

The kb group, 6 commands. Create, inspect, update, and delete Knowledge Bases; query storage and QPS metrics.

Documents

The doc group, 6 commands. Upload local files, import from OSS, track parse status, delete, and tag.

Chunks

The chunk group, 4 commands. Add, list, update, and delete chunks in a Knowledge Base.

Retrieval services

The service group, 7 commands. Create, configure, publish, copy, and delete retrieval and Q&A services.

Retrieval and chat

The search, chat, and retrieve commands. Consume Knowledge Bases through a retrieval service.

Data center collections

The collection and category groups, 5 commands. Manage data center containers and category hierarchies.

Data center files

The file group, 3 commands. Inspect and delete source files in the data center.

Command reference table

Command	Purpose	Key flags
`kscli kb list`	List Knowledge Bases	`--name`
`kscli kb info`	Knowledge Base details	`--index-id`
`kscli kb create`	Create a Knowledge Base	`--name`, `--doc-id` / `--category-id`
`kscli kb update`	Update a Knowledge Base	`--index-id`, `--name` / `--description` / `--rerank-min-score`
`kscli kb delete`	Delete a Knowledge Base	`--index-id`, `--yes`
`kscli kb stats`	Storage and QPS metrics	`--index-id`, `--start` / `--end`
`kscli doc list`	List documents	`--index-id`
`kscli doc status`	Import job status	`--index-id`, `--job-id`, `--wait`
`kscli doc upload`	Upload files	`--file`, `--index-id`, `--wait`
`kscli doc delete`	Delete documents	`--index-id`, `--doc-id`
`kscli doc tag`	Tag files	`--doc-id`, `--tag`, `--mode`
`kscli doc import-oss`	Import from OSS	`--bucket`, `--region`, `--oss-key`
`kscli chunk add`	Add a chunk	`--index-id`, `--content` / `--field`
`kscli chunk list`	List chunks	`--index-id`, `--doc-id`
`kscli chunk update`	Update a chunk	`--index-id`, `--chunk-id`, `--doc-id`
`kscli chunk delete`	Delete chunks	`--index-id`, `--chunk-id`, `--yes`
`kscli service list`	List services	`--scene`
`kscli service get`	Service details	`--agent-id`
`kscli service create`	Create a service	`--name`, `--scene`, `--index-id`
`kscli service update`	Update a service	`--agent-id` plus config flags
`kscli service deploy`	Publish a service	`--agent-id`, `--yes`
`kscli service delete`	Delete a service	`--agent-id`, `--yes`
`kscli service copy`	Copy a service	`--agent-id`
`kscli search`	Semantic retrieval	`--query`, `--agent-id`
`kscli chat`	RAG conversation	`--message`, `--agent-id`
`kscli retrieve`	Direct retrieval (deprecated)	`--index-id`, `--query`
`kscli file list`	List files	`--category-id`
`kscli file get`	File details	`--file-id`
`kscli file delete`	Delete a file	`--file-id`, `--yes`
`kscli collection create`	Create a collection	`--name`, `--description`
`kscli collection get`	Collection details	`--collection-id` / `--name`
`kscli category list`	List categories	`--collection-id`, `--parent-id`
`kscli category add`	Create a category	`--name`, `--parent-id`
`kscli category delete`	Delete a category	`--category-id`, `--yes`

Troubleshooting

Workspace ID is required

Knowledge Base resources belong to a workspace, and commands need the workspace ID to locate them. Provide it in any of these ways:

# Flag
kscli kb list --workspace-id ws-xxx

# Environment variable
export BAILIAN_WORKSPACE_ID=ws-xxx

# Config file (recommended)
kscli config set --key workspace_id --value ws-xxx

Knowledge base not found

The --index-id you passed does not exist in the current workspace. Run kscli kb list to confirm the ID, and check that the configured workspace is correct.

Import job query returns SystemError

This usually means the --job-id does not exist, or the Knowledge Base has no import job. Take the job ID from the output of kscli doc upload or kscli kb create.

Deleting a document reports it does not exist

A document's doc_id inside a Knowledge Base is not necessarily the same as the file ID returned at upload time — it depends on the import path. Run kscli doc list --quiet to get the authoritative doc_id before deleting.

retrieve prints a deprecation warning

retrieve is deprecated; use search instead. search drives retrieval strategy through --agent-id and supports multiple Knowledge Bases, routing, and reranking. retrieve operates on a single Knowledge Base ID, is limited in capability, and is no longer developed.

OSS import returns a permission error

The target bucket is not authorized for the platform service. In the RAM console, confirm the AliyunServiceRoleForBailian service-linked role is correctly authorized for that bucket.

chat returns Chat API error

Check that --agent-id exists, the service has been published, and the API Key is valid. The error code and message are returned verbatim by the server — follow what they say.

file list returns an empty list

--category-id must be a real category ID; the literal default is not accepted. Get the real ID from kscli category list or the category field in kscli file get output.

There is no command to delete a collection

The platform does not support deleting data collections, so the CLI has no such command. Confirm the name and purpose before creating one. To isolate data, create a new collection and migrate the files.

​Installation

​Initial configuration

​Core concepts

​Shared conventions

​Authentication

​Workspace ID

​Global flags

​Output formats

​Confirmation prompts

​Dry-run mode

​Common workflows

​Build a Knowledge Base from scratch and retrieve

​Bulk import a directory into an existing Knowledge Base

​Create and tune a Q&A service

​Correct Knowledge Base content

​Reuse an existing service config

​Bulk import from OSS

​Command groups