RAG

Bailian CLI command reference for knowledge bases, documents, chunks, and retrieval/Q&A services.

Invoke the full Bailian knowledge-base surface from the terminal: retrieval/Q&A service calls, knowledge base lifecycle management, document and chunk management, and category/collection management.

See the RAG knowledge base for feature-page usage.

Retrieval and Q&A

search and chat call a published retrieval/Q&A service via --agent-id; the actual retrieval strategy (multi-index recall, ranking, reranking, etc.) is driven by the service's server-side configuration.

bl knowledge search

Search a Bailian knowledge base (RAG semantic retrieval). Requires API Key authentication.

Usage

bl knowledge search --agent-id <id> (--query <text> | --image <url>) [flags]

Parameter	Type	Required	Description
--query <text>	string	no	Search text; provide at least one of --query or --image
--agent-id <id>	string	yes	Retrieval service ID (find in console knowledge retrieval page)
--workspace-id <id>	string	no	Workspace ID for API endpoint URL (or set BAILIAN_WORKSPACE_ID)
--agent-version <version>	string	no	Service version to call: beta (draft for debugging) or a published number; default is the latest published version
--image <url>	array	no	Image URL for multimodal retrieval (repeatable); supports image-only search
--kb-search-configs-file <path>	string	no	JSON array file with knowledge base IDs and online search_filters

Example: Search a knowledge base using query and agent ID

bl knowledge search --query "What is RAG?" --agent-id aid-xxx --workspace-id ws-xxx

• Retrieval scope and strategy (multi-index weighting, routing, reranking, etc.) are driven by the agent_id service config. agent_id is required; provide at least one of query or image.
• Pass online retrieval filters with --kb-search-configs-file, which specifies search_filters per knowledge base.
• Auth: uses DashScope API Key (Bearer token). Get yours from the console API Key page.
• --workspace-id can be set via BAILIAN_WORKSPACE_ID env or kscli config set workspace_id <id>.
• --agent-version beta calls the draft config for debugging before it is deployed.
• JSON output preserves request_id, data.total, data.cost_time, and data.nodes returned by the API. Each node contains score, text, and metadata such as title, document ID, URL, page number, and media URLs.
• Text mode prints the score, text, and media summary for each node.

bl knowledge chat

Chat with a Bailian knowledge base (RAG Q&A with streaming). Requires API Key authentication.

Usage

bl knowledge chat --message <text> --agent-id <id> [flags]

Parameter	Type	Required	Description
--message <text>	array	no	Message text (repeatable). Supports role:content prefix to set role (e.g. user:hello), defaults to user. Follows OpenAI message format
--agent-id <id>	string	yes	Q&A service ID (find in console knowledge Q&A page)
--workspace-id <id>	string	no	Workspace ID for API endpoint URL (or set BAILIAN_WORKSPACE_ID)
--agent-version <version>	string	no	Service version to call: beta (draft for debugging) or a published number; default is the latest published version
--image <url>	array	no	Image URL (repeatable). Attached to the last user message as multimodal content
--messages-file <path>	string	no	Complete messages JSON array, including tool history (exclusive with --message and --image)
--enable-cache-control <true|false>	boolean	no	Explicit context cache control
--request-id <id>	string	no	Business request ID
--session-file-id <fileId>	array	no	Session file ID (repeatable, up to 10; requires service-side file preprocessing)

Example: Chat with a knowledge base using message and agent ID

bl knowledge chat --message "What is RAG?" --agent-id aid-xxx --workspace-id ws-xxx

• Response is returned as SSE stream events. Event lifecycle: tool_calling → tool_return → plan_start → planning → plan_end → generation_start → generating → generation_end. tool_calling → tool_return may loop multiple times.
• Auth: uses DashScope API Key (Bearer token). Get yours from the console API Key page.
• --workspace-id can be set via BAILIAN_WORKSPACE_ID env or kscli config set workspace_id <id>.
• Multi-turn: use --message "user:..." and --message "assistant:..." to pass conversation history.
• --agent-version beta calls the draft config for debugging before it is deployed.
• Structured output separates the final answer from phases, tools, sources, and usage. Quiet mode hides only progress and informational messages while preserving the final answer, complete results, warnings, and errors.
• In JSON output, read the final answer from answer and process information from phases, tools, docs, usage, and events. Scripts that extracted answers from quiet output should read JSON fields instead.

Migrate from retrieve

Bailian CLI 2.5.0 removed bl knowledge retrieve and kscli retrieve. Use bl knowledge search instead, or kscli search when using the standalone Knowledge Studio CLI.

Pass the ID of a retrieval service bound to the target knowledge base as --agent-id; do not reuse the old --index-id value. Recall, ranking, and reranking strategies are configured in the retrieval service, so the old retrieval parameters cannot be carried over directly. See bl knowledge search above for syntax and examples, and “Retrieval/Q&A service management” below for creating, configuring, and publishing services.

Knowledge base management

bl knowledge init

Initialize a knowledge base and verify sample retrieval. Requires API Key authentication.

Usage

bl knowledge init [--name <name>] [--state-file <path>] [flags]

Parameter	Type	Required	Description
--name <name>	string	no	Knowledge base name (1-20 characters; default: cli-demo)
--state-file <path>	string	no	Recovery checkpoint (default: ~/.bailian/knowledge/init/<key>.json, keyed by workspace and name)
--poll-interval <seconds>	number	no	Polling interval (default: 5 seconds)
--workspace-id <id>	string	no	Workspace ID for API endpoint URL (or set BAILIAN_WORKSPACE_ID)
--yes	switch	no	Confirm knowledge base creation and billing

Example: Preview the initialization plan

bl knowledge init --dry-run

Example: Run initialization after confirmation

bl knowledge init --yes

• Runs sample upload, knowledge base creation, retrieval service creation, and first retrieval verification, with recovery and resource reuse.
• Uses the retrieval service beta draft; it does not publish a service or create a Q&A service.
• Dry-run requires credentials and reads existing resources, but makes no resource or checkpoint changes. Keep the state file for recovery.
• See Knowledge base billing.

bl knowledge create

Create a knowledge base and import data-center files or categories. Requires API Key authentication.

Usage

bl knowledge create --name <text> --description <text> (--doc-id <id> | --category-id <id>) [flags]

Parameter	Type	Required	Description
--name <text>	string	yes	Knowledge base name (1-20 chars, unique in workspace)
--description <text>	string	yes	What this knowledge base holds and what it is for — tells bases apart in the workspace list (1-500 chars)
--doc-id <id>	array	no	Data-center file id to import (repeatable); mutually exclusive with --category-id
--category-id <id>	array	no	Import every file under this category (repeatable); mutually exclusive with --doc-id
--embedding-model <name>	string	no	Embedding model name (document default: text-embedding-v4; multimedia/visual scene: qwen3-vl-embedding)
--knowledge-type <document|multimedia>	string	no	Knowledge type: document or multimedia
--knowledge-scene <scene>	string	no	Knowledge scene; requires --knowledge-type
--multimodal-embedding-model <name>	string	no	Multimodal embedding model; alias of --embedding-model in multimedia/visual scenes
--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 when waiting (default: 5)
--workspace-id <id>	string	no	Workspace ID for API endpoint URL (or set BAILIAN_WORKSPACE_ID)

Example: Create a knowledge base with name, description, and document

bl knowledge create --name demo --description 'product docs' --doc-id file-xxx --workspace-id ws-xxx

• Structure and sink types are unstructured and BUILT_IN. Multimedia knowledge bases use basic_multimedia_qa, qwen3-vl-embedding, and qwen3-vl-rerank with similar reranking. Explicit models are validated by the server.
• A knowledge base starts incurring running-time charges when created, even without queries. The one-time 720-hour Standard Edition allowance is shared across knowledge bases and is valid for 30 days after activation for new users; model calls are billed separately. See Knowledge base billing.
• Returns the knowledge base id (pipelineId) and the initial import job id (ingestionId).
• Use the import job status command (or --wait) to track the initial import.

bl knowledge list

List knowledge bases in the workspace. Requires API Key authentication.

Usage

bl knowledge list [flags]

Parameter	Type	Required	Description
--name <text>	string	no	Filter by knowledge base name (fuzzy match, 1-20 chars)
--page-number <n>	number	no	Page number (default: 1)
--page-size <n>	number	no	Page size per request
--workspace-id <id>	string	no	Workspace ID for API endpoint URL (or set BAILIAN_WORKSPACE_ID)

Example: List knowledge bases in the specified workspace

bl knowledge list --workspace-id ws-xxx

• Auth: uses DashScope API Key (Bearer token).
• --workspace-id can be set via BAILIAN_WORKSPACE_ID env or config workspace_id.
• Use the returned id as --index-id in knowledge base / document management commands.

bl knowledge info

Show knowledge base configuration details. Requires API Key authentication.

Usage

bl knowledge info --index-id <id> [flags]

Parameter	Type	Required	Description
--index-id <id>	string	yes	Knowledge base ID
--workspace-id <id>	string	no	Workspace ID for API endpoint URL (or set BAILIAN_WORKSPACE_ID)

Example: Show configuration details for a knowledge base

bl knowledge info --index-id idx-xxx --workspace-id ws-xxx

• Indexing settings are immutable; changing them requires recreating the knowledge base.

bl knowledge update

Update knowledge base name, description or rerank threshold. Requires API Key authentication.

Usage

bl knowledge update --index-id <id> [flags]

Parameter	Type	Required	Description
--index-id <id>	string	yes	Knowledge base ID
--name <text>	string	no	New knowledge base name (1-20 chars)
--description <text>	string	no	New knowledge base description
--rerank-min-score <score>	number	no	Rerank minimum score threshold, range 0-1 (chunks below are filtered)
--workspace-id <id>	string	no	Workspace ID for API endpoint URL (or set BAILIAN_WORKSPACE_ID)

Example: Update knowledge base description and settings

bl knowledge update --index-id idx-xxx --description 'product docs v2' --workspace-id ws-xxx

• Indexing settings (embedding model, chunk size, etc.) are immutable — recreate the knowledge base to change them.

bl knowledge delete

Delete a knowledge base with all its documents and chunks. Requires API Key authentication.

Usage

bl knowledge delete --index-id <id> [flags]

Parameter	Type	Required	Description
--index-id <id>	string	yes	Knowledge base ID
--workspace-id <id>	string	no	Workspace ID for API endpoint URL (or set BAILIAN_WORKSPACE_ID)
--yes	switch	no	Confirm this high-risk operation

Example: Delete a knowledge base with all its documents

bl knowledge delete --index-id idx-xxx --workspace-id ws-xxx

• Irreversible — the knowledge base and all indexed content are permanently removed.
• Files in the data center are not affected; only the knowledge base index is deleted.

bl knowledge stats

Show knowledge base storage and QPS monitoring data. Requires API Key authentication.

Usage

bl knowledge 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)
--workspace-id <id>	string	no	Workspace ID for API endpoint URL (or set BAILIAN_WORKSPACE_ID)

Example: Show storage and QPS monitoring data for a knowledge base

bl knowledge stats --index-id idx-xxx --workspace-id ws-xxx

• Defaults to the last 24 hours when --start/--end are omitted.
• Timestamps are normalized to epoch seconds as required by the server.
• Future timestamps are rejected for --start and clamped to now for --end, since the monitor API only returns past data.

Document and file management

A data-center file is the raw asset; once imported into a knowledge base it becomes a document. Deleting a file and deleting a document are independent operations.

bl knowledge doc upload

Upload local files or directories to the data center and optionally import into a knowledge base. Requires API Key authentication.

Usage

bl knowledge doc upload --file <path> [flags]

Parameter	Type	Required	Description
--file <path>	array	yes	Local file or directory path (repeatable). Directories are scanned recursively; unsupported formats are skipped
--index-id <id>	string	no	Import into this knowledge base after registration (one job for all files)
--category-id <id>	string	no	Target data-center category; defaults to the workspace default category
--tag <text>	array	no	File tag (repeatable), applied to every uploaded file
--category-type <UNSTRUCTURED|SESSION_FILE>	string	no	File category type; SESSION_FILE for temporary chat attachments
--parser <name>	string	no	File parser, e.g. AUTO_SELECT or DOCMIND_LLM_VERSION_MEDIA
--parser-config-file <path>	string	no	JSON object file containing parser configuration
--wait	switch	no	Poll the import job to a terminal state (needs --index-id)
--poll-interval <seconds>	number	no	Polling interval when waiting (default: 5)
--workspace-id <id>	string	no	Workspace ID for API endpoint URL (or set BAILIAN_WORKSPACE_ID)

Example: Upload local files to the data center

bl knowledge doc upload --file ./a.md --workspace-id ws-xxx

• Pipeline: apply upload lease → streaming PUT to OSS → register file → (with --index-id) create import job.
• Audio and video files support up to 2 GiB each. With --index-id, at most 50 local media files are processed per call; no automatic splitting.
• Without --category-id the workspace default category is resolved automatically.
• Directories are scanned recursively; node_modules, .git, and similar are skipped automatically.
• Multiple files are processed sequentially; on failure, already-registered file ids are listed in the error hint.

bl knowledge doc import

Import existing data-center files into an existing knowledge base. Requires API Key authentication.

Usage

bl knowledge doc import --index-id <id> (--doc-id <fileId> ... | --category-id <id> ...) [flags]

Parameter	Type	Required	Description
--index-id <id>	string	yes	Existing knowledge base ID
--doc-id <fileId>	array	no	Data-center file ID (repeatable); mutually exclusive with --category-id
--category-id <id>	array	no	Data-center category ID (repeatable); mutually exclusive with --doc-id
--chunk-mode <h1|h2|h3|h4|h5|length|page|regex>	string	no	Document chunk mode (not video time slicing)
--chunk-size <characters>	number	no	Document chunk size, 1-6000 characters
--overlap-size <characters>	number	no	Document overlap size, 0-1024 characters
--separator <regex>	string	no	Separator for regex chunk mode
--enable-headers <true|false>	boolean	no	Enable document header extraction
--wait	switch	no	Wait for the import job to finish
--poll-interval <seconds>	number	no	Polling interval (default: 5 seconds)
--workspace-id <id>	string	no	Workspace ID for API endpoint URL (or set BAILIAN_WORKSPACE_ID)

Example: Import data-center files and wait for completion

bl knowledge doc import --index-id idx-xxx --doc-id file-xxx --wait

Example: Preview importing a category

bl knowledge doc import --index-id idx-xxx --category-id category-xxx --dry-run

• Reuses file IDs without uploading again.
• Importing may start parsing and indexing.

bl knowledge doc sync

Synchronize a local document directory to a knowledge base. Requires API Key authentication.

Usage

bl knowledge doc sync --dir <path> --index-id <id> [flags]

Parameter	Type	Required	Description
--dir <path>	string	yes	Local document directory
--index-id <id>	string	yes	Target knowledge base ID
--category-id <id>	string	no	Data-center category ID (defaults to the workspace default on first run)
--delete	switch	no	Delete managed index documents missing locally
--sync-id <uuid>	string	no	Synchronization set UUID
--state-file <path>	string	no	Checkpoint path (default: <dir>/.bailian/sync/<key>.json, keyed by knowledge base ID)
--poll-interval <seconds>	number	no	Polling interval (default: 5 seconds)
--yes	switch	no	Confirm this high-risk operation

Example: Preview the synchronization plan

bl knowledge doc sync --dir ./docs --index-id idx-example --dry-run

Example: Run the synchronization

bl knowledge doc sync --dir ./docs --index-id idx-example --yes

Example: Preview deleting documents missing locally

bl knowledge doc sync --dir ./docs --index-id idx-example --delete --dry-run

• Source files remain local.
• Keep the state file and allow only one writer per synchronization set, including across CI machines.
• Importing may incur model charges. Deleting documents does not stop knowledge base running-time charges.

bl knowledge doc import-oss

Batch import files from an authorized OSS bucket into the data center. Requires API Key authentication.

Usage

bl knowledge doc import-oss --bucket <name> --region <id> --oss-key <key> [flags]

Parameter	Type	Required	Description
--bucket <name>	string	yes	Authorized OSS bucket name
--region <id>	string	yes	OSS region id (e.g. cn-beijing)
--oss-key <key>	array	yes	OSS object key to import (repeatable, 1-10 per call)
--category-id <id>	string	no	Target data-center category (default: the default category)
--tag <text>	array	no	File tag applied to every imported file (repeatable, up to 10)
--overwrite	switch	no	Overwrite files previously imported from the same OSS keys
--workspace-id <id>	string	no	Workspace ID for API endpoint URL (or set BAILIAN_WORKSPACE_ID)

Example: Import files from an authorized OSS bucket

bl knowledge doc import-oss --bucket my-bucket --region cn-beijing --oss-key docs/a.pdf --workspace-id ws-xxx

• The bucket must be authorized to the platform service role beforehand; permission errors from the server are passed through with a pointer to check AliyunServiceRoleForBailian in the RAM console.
• File names are derived from the OSS key basename.
• --overwrite replaces the previously imported file and issues a NEW fileId (the old one becomes invalid) — verified live.

bl knowledge doc list

List documents in a knowledge base with parse/index status. Requires API Key authentication.

Usage

bl knowledge doc list --index-id <id> [flags]

Parameter	Type	Required	Description
--index-id <id>	string	yes	Knowledge base ID
--page-number <n>	number	no	Page number (default: 1)
--page-size <n>	number	no	Page size per request
--workspace-id <id>	string	no	Workspace ID for API endpoint URL (or set BAILIAN_WORKSPACE_ID)

Example: List documents in a knowledge base with their status

bl knowledge doc list --index-id idx-xxx --workspace-id ws-xxx

• Documents with status FAILED are highlighted in text mode — use the import job status command to inspect failures.
• Page size defaults to 10 (server default), max 100.

bl knowledge doc status

Check knowledge base import job status. Requires API Key authentication.

Usage

bl knowledge doc status --index-id <id> --job-id <id> [flags]

Parameter	Type	Required	Description
--index-id <id>	string	yes	Knowledge base ID
--job-id <id>	string	yes	Import job ID (ingestionId returned by import commands)
--page-number <n>	number	no	Page number (default: 1)
--page-size <n>	number	no	Page size per request
--wait	switch	no	Poll until the job reaches a terminal state
--poll-interval <seconds>	number	no	Polling interval when waiting (default: 5)
--workspace-id <id>	string	no	Workspace ID for API endpoint URL (or set BAILIAN_WORKSPACE_ID)

Example: Check the status of a knowledge base import job

bl knowledge doc status --index-id idx-xxx --job-id job-xxx --workspace-id ws-xxx

• Both --index-id and --job-id are required (passing only one returns SystemError).
• If you see a SystemError, the job may not exist — check the ingestion id in the document list output.
• Overall job states are PENDING / RUNNING / COMPLETED; per-document failures (for example PARSE_FAILED) exit non-zero with the error message passed through.

bl knowledge doc tag

Batch update tags on data-center files. Requires API Key authentication.

Usage

bl knowledge doc tag --doc-id <id> --tag <text> [flags]

Parameter	Type	Required	Description
--doc-id <id>	array	yes	Data-center file ID to tag (repeatable, 1-20 per call)
--tag <text>	array	yes	Tag applied to every --doc-id (repeatable, each up to 32 chars)
--mode <mode>	string	no	Update mode: append (default) or overwrite
--workspace-id <id>	string	no	Workspace ID for API endpoint URL (or set BAILIAN_WORKSPACE_ID)

Example: Apply tags to multiple data-center files

bl knowledge doc tag --doc-id file-xxx --tag project-a --tag draft --workspace-id ws-xxx

• The same tag set is applied to every --doc-id; run the command multiple times for different tag sets.
• Server limits: up to 100 tags per file, total tag length up to 700 chars, tag up to 32 chars.

bl knowledge doc delete

Delete documents and their chunks from a knowledge base. Requires API Key authentication.

Usage

bl knowledge doc delete --index-id <id> --doc-id <id> [flags]

Parameter	Type	Required	Description
--index-id <id>	string	yes	Knowledge base ID
--doc-id <id>	array	yes	Document ID to delete (repeatable)
--workspace-id <id>	string	no	Workspace ID for API endpoint URL (or set BAILIAN_WORKSPACE_ID)
--yes	switch	no	Confirm this high-risk operation

Example: Preview deletion of documents from a knowledge base

bl knowledge doc delete --index-id idx-xxx --doc-id file-xxx --workspace-id ws-xxx --dry-run

• Removes documents from the knowledge base index only; the source files remain in the data center.
• Use the doc_id from knowledge doc list --quiet, not the fileId from knowledge doc upload. For documents created via knowledge create --doc-id, the doc_id equals the fileId; for documents imported via knowledge doc upload --index-id, the doc_id may include a workspace suffix.
• Deletion may take up to ~30s to propagate — the document may still appear in the doc list briefly.
• The output lists the ids actually deleted.

bl knowledge file get

Show data-center file details (size, MD5, tags, timestamps). Requires API Key authentication.

Usage

bl knowledge file get --file-id <id> [flags]

Parameter	Type	Required	Description
--file-id <id>	string	yes	Data-center file ID
--workspace-id <id>	string	no	Workspace ID for API endpoint URL (or set BAILIAN_WORKSPACE_ID)

Example: Show details of a data-center file

bl knowledge file get --file-id file-xxx --workspace-id ws-xxx

bl knowledge file list

List files in a data-center category. Requires API Key authentication.

Usage

bl knowledge file list --category-id <id> [flags]

Parameter	Type	Required	Description
--category-id <id>	string	yes	Category to list (find ids via the category list command); exact match
--name <text>	string	no	Filter by exact file name without its extension (a.md → pass a)
--file-id <id>	array	no	Filter by exact file ID (repeatable)
--next-token <token>	string	no	Cursor for the next page (from previous output)
--max-result <n>	number	no	Items per page
--workspace-id <id>	string	no	Workspace ID for API endpoint URL (or set BAILIAN_WORKSPACE_ID)

Example: List files in a specific data-center category

bl knowledge file list --category-id cate-xxx --workspace-id ws-xxx

• A real category id is required — the default value is not resolved here. Find the id via the category list command.
• --name matches the exact file name without its extension (for a.md pass a); partial keywords return no results.
• Pagination is cursor-based: reuse the printed next token to continue.

bl knowledge file delete

Permanently delete a file from the data center. Requires API Key authentication.

Usage

bl knowledge file delete --file-id <id> [flags]

Parameter	Type	Required	Description
--file-id <id>	string	yes	Data-center file ID to delete
--workspace-id <id>	string	no	Workspace ID for API endpoint URL (or set BAILIAN_WORKSPACE_ID)
--yes	switch	no	Confirm this high-risk operation

Example: Delete a file from the data center using file and workspace IDs

bl knowledge file delete --file-id file-xxx --workspace-id ws-xxx

• Irreversible. If knowledge bases reference this file, their related document indexes become invalid.
• To remove a document from a single knowledge base only, use the document delete command instead.

Chunk management

bl knowledge chunk add

Add a chunk directly to a knowledge base. Requires API Key authentication. Multimedia knowledge bases do not support adding chunks.

Usage

bl knowledge chunk add --index-id <id> (--content <text> | --field <k=v>) [flags]

Parameter	Type	Required	Description
--index-id <id>	string	yes	Knowledge base ID
--doc-id <id>	string	no	Owning document ID from the doc list command; required in practice for all knowledge base types
--content <text>	string	no	Chunk body text, up to 6000 chars (document-type); alternative to --content-file
--content-file <path>	string	no	Read chunk body from a UTF-8 plain text file (.md/.txt etc.)
--title <text>	string	no	Chunk title, up to 50 chars (document-type)
--image-url <url>	array	no	Chunk image URL (repeatable, up to 10; document-type)
--field <key=value>	array	no	Arbitrary field entry (repeatable) for table/image knowledge bases where keys are Excel column headers; mutually exclusive with content/title/image flags
--workspace-id <id>	string	no	Workspace ID for API endpoint URL (or set BAILIAN_WORKSPACE_ID)

Example: Add a text chunk to a knowledge base with title and workspace ID

bl knowledge chunk add --index-id idx-xxx --content "chunk text" --title intro --workspace-id ws-xxx

• Document / table / image knowledge bases are supported; audio-video ones are not.
• --doc-id is required in practice for all knowledge base types. Use the document-level id from the doc list command; the per-row doc_id in chunk list output is not accepted.
• Image-type documents do not support text chunks. Target a text-type document (docx/pdf/txt) instead.
• The API is idempotent but rate-limited to 10 calls per second — throttle batch scripts.
• The response carries no chunk id; list chunks afterwards to find the new one.
• For table/image knowledge bases use --field with Excel column headers as keys; values are passed through as strings.

bl knowledge chunk list

List chunks in a knowledge base with content and status. Requires API Key authentication.

Usage

bl knowledge chunk list --index-id <id> [flags]

Parameter	Type	Required	Description
--index-id <id>	string	yes	Knowledge base ID
--doc-id <id>	string	no	Only show chunks belonging to this document
--page-number <n>	number	no	Page number (default: 1)
--page-size <n>	number	no	Page size per request
--workspace-id <id>	string	no	Workspace ID for API endpoint URL (or set BAILIAN_WORKSPACE_ID)

Example: List chunks in a knowledge base using index and workspace IDs

bl knowledge chunk list --index-id idx-xxx --workspace-id ws-xxx

• Use metadata._id as the chunk id and metadata.doc_id as the document id in chunk update/delete commands.
• Page size defaults to 20 (server default), max 100.

bl knowledge chunk update

Update chunk content or toggle its retrieval visibility. Requires API Key authentication.

Usage

bl knowledge chunk update --index-id <id> --chunk-id <id> --doc-id <id> [flags]

Parameter	Type	Required	Description
--index-id <id>	string	yes	Knowledge base ID
--chunk-id <id>	string	yes	Chunk ID (metadata._id from the chunk list output)
--doc-id <id>	string	yes	Document ID owning the chunk (metadata.doc_id from the chunk list output)
--content <text>	string	no	New chunk content, 10-6000 chars; alternative to --content-file
--content-file <path>	string	no	Read new content from a UTF-8 plain text file (.md/.txt etc.)
--title <text>	string	no	Chunk title, 0-50 chars (empty string clears it; omit to keep unchanged)
--exclude	switch	no	Exclude this chunk from retrieval
--include	switch	no	Include this chunk in retrieval (default)
--workspace-id <id>	string	no	Workspace ID for API endpoint URL (or set BAILIAN_WORKSPACE_ID)

Example: Update chunk content for a specific chunk and document in a knowledge base

bl knowledge chunk update --index-id idx-xxx --chunk-id chunk-xxx --doc-id file-xxx --content "corrected text"

• Content must be 10-6000 characters and within the knowledge base's max chunk size.
• --content-file expects a UTF-8 plain text file; document formats (.docx/.pdf) are not parsed here.
• Toggling --exclude/--include without new content re-submits the existing content automatically.

bl knowledge chunk delete

Delete chunks from a knowledge base (irreversible). Requires API Key authentication.

Usage

bl knowledge chunk delete --index-id <id> --chunk-id <id> [flags]

Parameter	Type	Required	Description
--index-id <id>	string	yes	Knowledge base ID
--chunk-id <id>	array	yes	Chunk ID to delete (repeatable; batches of 10 are sent automatically)
--workspace-id <id>	string	no	Workspace ID for API endpoint URL (or set BAILIAN_WORKSPACE_ID)
--yes	switch	no	Confirm this high-risk operation

Example: Delete one or more chunks from a knowledge base using index and chunk IDs

bl knowledge chunk delete --index-id idx-xxx --chunk-id chunk-a --chunk-id chunk-b --workspace-id ws-xxx

• Accepts at most 10 chunk ids per call; larger sets are batched automatically.
• When batch deletion fails, the command reports completed batches, batches with unconfirmed results, and unexecuted parts separately.

Category and collection management

Categories organize data-center files by business domain. Collections define where files are stored — platform-managed storage by default, or a custom OSS bucket.

bl knowledge category add

Create a data-center category. Requires API Key authentication.

Usage

bl knowledge category add --name <text> [flags]

Parameter	Type	Required	Description
--name <text>	string	yes	Category name (1-20 chars)
--parent-id <id>	string	no	Create as a sub-category of this category
--collection-id <id>	string	no	Create under this collection (defaults to the platform collection)
--workspace-id <id>	string	no	Workspace ID for API endpoint URL (or set BAILIAN_WORKSPACE_ID)

Example: Create a new category in the data center with a name and workspace ID

bl knowledge category add --name product-docs --workspace-id ws-xxx

• Use categories to organize data-center files by business domain.

bl knowledge category list

List data-center categories. Requires API Key authentication.

Usage

bl knowledge category list [flags]

Parameter	Type	Required	Description
--collection-id <id>	string	no	Filter by exact collection ID
--parent-id <id>	string	no	List sub-categories of this exact parent category
--name <text>	string	no	Filter by category name (exact match, unlike the knowledge base list)
--next-token <token>	string	no	Cursor for the next page (from previous output)
--max-result <n>	number	no	Items per page (default: 20)
--workspace-id <id>	string	no	Workspace ID for API endpoint URL (or set BAILIAN_WORKSPACE_ID)

Example: List all categories in the data center using workspace ID

bl knowledge category list --workspace-id ws-xxx

• Categories marked [default] are where files land when no category is specified.
• Pagination is cursor-based: reuse the printed next token to continue.

bl knowledge category delete

Delete a data-center category. Requires API Key authentication.

Usage

bl knowledge category delete --category-id <id> [flags]

Parameter	Type	Required	Description
--category-id <id>	string	yes	Category ID to delete
--workspace-id <id>	string	no	Workspace ID for API endpoint URL (or set BAILIAN_WORKSPACE_ID)
--yes	switch	no	Confirm this high-risk operation

Example: Delete a category from the data center using category and workspace IDs

bl knowledge category delete --category-id cate-xxx --workspace-id ws-xxx

• Behavior for categories containing files or sub-categories is server-defined — the server error is passed through as-is.

bl knowledge collection create

Create a FILE data collection. Requires API Key authentication.

Usage

bl knowledge collection create --name <text> --description <text> [flags]

Parameter	Type	Required	Description
--name <text>	string	yes	Collection name
--description <text>	string	yes	What this collection holds and what it is for — tells collections apart in the list
--store-type <type>	string	no	Storage: platform (managed) or custom (your own OSS bucket)
--oss-region <id>	string	no	OSS region id (required with --store-type custom)
--oss-bucket <name>	string	no	OSS bucket name (required with --store-type custom)
--workspace-id <id>	string	no	Workspace ID for API endpoint URL (or set BAILIAN_WORKSPACE_ID)

Example: Create a new file collection with name, description, and workspace ID

bl knowledge collection create --name my-collection --description 'team docs' --workspace-id ws-xxx

• Store type defaults to platform (managed storage); custom uses your authorized OSS bucket.
• Custom buckets must carry the bucket tag bailian-connector-access=ReadAndWrite (Bailian's tag-based access control); without it the server rejects creation with a misleading 'setBucketCORS failed' error.
• There is no collection delete API — create collections deliberately.

bl knowledge collection get

Show data collection details. Requires API Key authentication.

Usage

bl knowledge collection get (--collection-id <id> | --name <text>) [flags]

Parameter	Type	Required	Description
--collection-id <id>	string	no	Collection ID; alternative to --name
--name <text>	string	no	Collection name; alternative to --collection-id
--workspace-id <id>	string	no	Workspace ID for API endpoint URL (or set BAILIAN_WORKSPACE_ID)

Example: Retrieve details of a specific collection using collection and workspace IDs

bl knowledge collection get --collection-id conn-xxx --workspace-id ws-xxx

Retrieval/Q&A service management

A service (agent) is the entry point for search and chat: create a service, bind a knowledge base, verify against the beta draft, then deploy to publish.

bl knowledge service create

Create a retrieval / Q&A service (initial status: draft, version: beta). Requires API Key authentication.

Usage

bl knowledge service create --name <text> --scene <chat|search> [flags]

Parameter	Type	Required	Description
--name <text>	string	yes	Service name (up to 200 chars, unique per scene in the workspace)
--scene <scene>	string	yes	Service scene: chat (Q&A) or search (retrieval)
--description <text>	string	no	What this service answers and who it serves — recommended: agents read it to pick the right service (up to 1000 chars)
--index-id <id>	string	no	Bind this knowledge base; other settings use server defaults
--workspace-id <id>	string	no	Workspace ID for API endpoint URL (or set BAILIAN_WORKSPACE_ID)

Example: Create a Q&A service with name, scene, description, and workspace ID

bl knowledge service create --name my-qa --scene chat --description 'answers product FAQs' --workspace-id ws-xxx

• Without an explicit configuration the server applies its default agent settings.
• The draft (beta) version can be tested via --agent-version beta on search/chat before deploying.
• Requires the knowledge-base create permission in the workspace.

bl knowledge service list

List retrieval / Q&A services (agents) in the workspace. Requires API Key authentication.

Usage

bl knowledge service list --scene <chat|search> [flags]

Parameter	Type	Required	Description
--scene <scene>	string	yes	Service scene: chat (Q&A) or search (retrieval)
--status <status>	string	no	Filter by status: draft, deployed (includes edited) or deleted
--name <text>	string	no	Filter by service name (fuzzy match)
--agent-id <id>	string	no	Filter by exact agent ID
--index-id <id>	string	no	Filter by exact linked knowledge base (pipeline) ID
--page-number <n>	number	no	Page number (default: 1)
--page-size <n>	number	no	Page size per request
--workspace-id <id>	string	no	Workspace ID for API endpoint URL (or set BAILIAN_WORKSPACE_ID)

Example: List Q&A services in the workspace filtered by scene and workspace ID

bl knowledge service list --scene chat --workspace-id ws-xxx

• A scene (chat or search) is required — run once per scene to see both.
• Use the returned agent_id with the search or chat commands, or with service management commands.

bl knowledge service get

Show service (agent) details including per-version configuration. Requires API Key authentication.

Usage

bl knowledge service get --agent-id <id> [flags]

Parameter	Type	Required	Description
--agent-id <id>	string	yes	Service (agent) ID
--agent-version <version>	string	no	Specific version to inspect (beta or a published number); omit for all versions
--workspace-id <id>	string	no	Workspace ID for API endpoint URL (or set BAILIAN_WORKSPACE_ID)

Example: Retrieve service details using agent and workspace IDs

bl knowledge service get --agent-id aid-xxx --workspace-id ws-xxx

• Without --agent-version all versions are returned (beta draft plus published numbers).
• The version value is passed through as-is; the valid set is server-side state.

bl knowledge service update

Update service name, description or draft configuration. Requires API Key authentication.

Usage

bl knowledge service update --agent-id <id> [flags]

Parameter	Type	Required	Description
--agent-id <id>	string	yes	Service (agent) ID
--name <text>	string	no	New service name (up to 200 chars)
--description <text>	string	no	New service description (up to 1000 chars)
--agent-version <version>	string	no	Target version (default: beta draft). Published versions only accept --version-desc
--version-desc <text>	string	no	Version description
--policy <policy>	string	no	Agent policy: turbo (fast) or agentic (multi-turn)
--model <name>	string	no	Generation model code (must be in the platform allowlist)
--temperature <n>	number	no	Sampling temperature, range 0-2
--max-llm-calls <n>	number	no	Max LLM calls per request, range 1-30
--enable-session-file <bool>	string	no	Enable session files: true or false
--enable-refusal <bool>	string	no	Enable refusal answers: true or false
--enable-anti-leak <bool>	string	no	Enable anti prompt-leak: true or false
--enable-rich-text <bool>	string	no	Enable rich text output: true or false
--enable-citation <bool>	string	no	Enable citations: true or false
--config-file <path>	string	no	JSON file replacing the whole agent_config (for nested settings like kb_search_configs); mutually exclusive with scalar config flags
--workspace-id <id>	string	no	Workspace ID for API endpoint URL (or set BAILIAN_WORKSPACE_ID)

Example: Update service configuration with specified temperature and IDs

bl knowledge service update --agent-id aid-xxx --temperature 0.7 --workspace-id ws-xxx

• Configuration changes only apply to the beta draft; published versions accept --version-desc only.
• To change the configuration of a published version, first update the beta draft (this command without --agent-version or with --agent-version beta), then run service deploy to publish a new version.
• Scalar config flags merge into the current draft config (read-merge-write); --config-file replaces the whole config and is mutually exclusive with them.
• After updating the draft, verify with --agent-version beta on search/chat, then deploy.
• Requires the knowledge-base modify permission in the workspace.

bl knowledge service deploy

Publish the beta draft of a service as a new version. Requires API Key authentication.

Usage

bl knowledge service deploy --agent-id <id> [flags]

Parameter	Type	Required	Description
--agent-id <id>	string	yes	Service (agent) ID
--version-desc <text>	string	no	Description for the newly published version
--workspace-id <id>	string	no	Workspace ID for API endpoint URL (or set BAILIAN_WORKSPACE_ID)
--yes	switch	no	Confirm this high-risk operation

Example: Publish beta draft as a new service version using agent and workspace IDs

bl knowledge service deploy --agent-id aid-xxx --workspace-id ws-xxx

• The version number auto-increments; status becomes deployed.
• Publishing affects live callers — the confirmation prompt guards against accidents.
• Requires the knowledge-base modify permission in the workspace.

bl knowledge service copy

Copy a service into a new draft (name gets a copy_ prefix). Requires API Key authentication.

Usage

bl knowledge service copy --agent-id <id> [flags]

Parameter	Type	Required	Description
--agent-id <id>	string	yes	Source service (agent) ID to copy
--workspace-id <id>	string	no	Workspace ID for API endpoint URL (or set BAILIAN_WORKSPACE_ID)

Example: Copy a service into a new draft with a copy_ prefixed name using agent and workspace IDs

bl knowledge service copy --agent-id aid-xxx --workspace-id ws-xxx

• The copy starts as a beta draft; test it with --agent-version beta, then deploy to publish.
• Requires the knowledge-base create permission in the workspace.

bl knowledge service delete

Delete a retrieval / Q&A service (soft delete, idempotent). Requires API Key authentication.

Usage

bl knowledge service delete --agent-id <id> [flags]

Parameter	Type	Required	Description
--agent-id <id>	string	yes	Service (agent) ID
--workspace-id <id>	string	no	Workspace ID for API endpoint URL (or set BAILIAN_WORKSPACE_ID)
--yes	switch	no	Confirm this high-risk operation

Example: Soft-delete a service using agent and workspace IDs

bl knowledge service delete --agent-id aid-xxx --workspace-id ws-xxx

• Deletion cannot be undone; the agent_id becomes unusable for search and chat calls.
• Idempotent — deleting an already-deleted service does not fail.
• Requires the knowledge-base delete permission in the workspace.