Skip to main content

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.
Knowledge-base capabilities are currently available only to China site (aliyun.com) accounts.
Append --help to any command for full parameter details, e.g. bl knowledge search --help. High-risk delete operations are blocked unless --yes is explicitly passed (exit code 7); use --dry-run to preview instead. Except for the 2.5.0 migration changes noted below, command details on this page are verified against bl 2.2.1.
See the RAG docs 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. Search a Bailian knowledge base (RAG semantic retrieval). Requires API Key authentication. Usage 
bl knowledge search --query <text> --agent-id <id> [flags]
ParameterTypeRequiredDescription
--query <text>stringyesSearch query text (required, cannot be empty)
--agent-id <id>stringyesRetrieval service ID (find in console knowledge retrieval page)
--workspace-id <id>stringnoWorkspace ID for API endpoint URL (or set BAILIAN_WORKSPACE_ID)
--agent-version <version>stringnoService version to call: beta (draft for debugging) or a published number; default is the latest published version
--image <url>arraynoImage URL for multimodal retrieval (repeatable)
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. Only query and agent_id are required.
  • 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.

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]
ParameterTypeRequiredDescription
--message <text>arraynoMessage text (repeatable). Supports role:content prefix to set role (e.g. user:hello), defaults to user. Follows OpenAI message format
--agent-id <id>stringyesQ&A service ID (find in console knowledge Q&A page)
--workspace-id <id>stringnoWorkspace ID for API endpoint URL (or set BAILIAN_WORKSPACE_ID)
--agent-version <version>stringnoService version to call: beta (draft for debugging) or a published number; default is the latest published version
--image <url>arraynoImage URL (repeatable). Attached to the last user message as multimodal content
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.

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 Knowledge Retrieval for creating, configuring, and publishing services.

Knowledge base management

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]
ParameterTypeRequiredDescription
--name <text>stringyesKnowledge base name (1-20 chars, unique in workspace)
--description <text>stringyesWhat this knowledge base holds and what it is for — tells bases apart in the workspace list (1-500 chars)
--doc-id <id>arraynoData-center file id to import (repeatable); mutually exclusive with --category-id
--category-id <id>arraynoImport every file under this category (repeatable); mutually exclusive with --doc-id
--embedding-model <name>stringnoEmbedding model name (default: text-embedding-v4)
--chunk-size <n>numbernoChunk size in characters (default: 600, recommended 300-800)
--waitswitchnoPoll the initial import job to a terminal state
--poll-interval <seconds>numbernoPolling interval when waiting (default: 5)
--workspace-id <id>stringnoWorkspace 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/sink types are fixed to the default document knowledge base (unstructured, BUILT_IN storage).
  • 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]
ParameterTypeRequiredDescription
--name <text>stringnoFilter by knowledge base name (fuzzy match, 1-20 chars)
--page-number <n>numbernoPage number (default: 1)
--page-size <n>numbernoPage size per request
--workspace-id <id>stringnoWorkspace 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]
ParameterTypeRequiredDescription
--index-id <id>stringyesKnowledge base ID
--workspace-id <id>stringnoWorkspace 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]
ParameterTypeRequiredDescription
--index-id <id>stringyesKnowledge base ID
--name <text>stringnoNew knowledge base name (1-20 chars)
--description <text>stringnoNew knowledge base description
--rerank-min-score <score>numbernoRerank minimum score threshold, range 0-1 (chunks below are filtered)
--workspace-id <id>stringnoWorkspace 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]
ParameterTypeRequiredDescription
--index-id <id>stringyesKnowledge base ID
--workspace-id <id>stringnoWorkspace ID for API endpoint URL (or set BAILIAN_WORKSPACE_ID)
--yesswitchnoConfirm this high-risk operation
This permanently deletes the knowledge base and all of its documents and chunks. Data-center files are not deleted.
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]
ParameterTypeRequiredDescription
--index-id <id>stringyesKnowledge base ID
--start <time>stringnoRange start: Unix seconds or ISO date, must be in the past (default: 24 hours ago)
--end <time>stringnoRange end: Unix seconds or ISO date, must be in the past (default: now)
--workspace-id <id>stringnoWorkspace 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]
ParameterTypeRequiredDescription
--file <path>arrayyesLocal file or directory path (repeatable). Directories are scanned recursively; unsupported formats are skipped
--index-id <id>stringnoImport into this knowledge base after registration (one job for all files)
--category-id <id>stringnoTarget data-center category; defaults to the workspace default category
--tag <text>arraynoFile tag (repeatable), applied to every uploaded file
--waitswitchnoPoll the import job to a terminal state (needs --index-id)
--poll-interval <seconds>numbernoPolling interval when waiting (default: 5)
--workspace-id <id>stringnoWorkspace 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 → PUT to OSS → register file → (with --index-id) create import job.
  • 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-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]
ParameterTypeRequiredDescription
--bucket <name>stringyesAuthorized OSS bucket name
--region <id>stringyesOSS region id (e.g. cn-beijing)
--oss-key <key>arrayyesOSS object key to import (repeatable, 1-10 per call)
--category-id <id>stringnoTarget data-center category (default: the default category)
--tag <text>arraynoFile tag applied to every imported file (repeatable, up to 10)
--overwriteswitchnoOverwrite files previously imported from the same OSS keys
--workspace-id <id>stringnoWorkspace 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]
ParameterTypeRequiredDescription
--index-id <id>stringyesKnowledge base ID
--page-number <n>numbernoPage number (default: 1)
--page-size <n>numbernoPage size per request
--workspace-id <id>stringnoWorkspace 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]
ParameterTypeRequiredDescription
--index-id <id>stringyesKnowledge base ID
--job-id <id>stringyesImport job ID (ingestionId returned by import commands)
--page-number <n>numbernoPage number (default: 1)
--page-size <n>numbernoPage size per request
--waitswitchnoPoll until the job reaches a terminal state
--poll-interval <seconds>numbernoPolling interval when waiting (default: 5)
--workspace-id <id>stringnoWorkspace 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]
ParameterTypeRequiredDescription
--doc-id <id>arrayyesData-center file ID to tag (repeatable, 1-20 per call)
--tag <text>arrayyesTag applied to every --doc-id (repeatable, each up to 32 chars)
--mode <mode>stringnoUpdate mode: append (default) or overwrite
--workspace-id <id>stringnoWorkspace 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]
ParameterTypeRequiredDescription
--index-id <id>stringyesKnowledge base ID
--doc-id <id>arrayyesDocument ID to delete (repeatable)
--workspace-id <id>stringnoWorkspace ID for API endpoint URL (or set BAILIAN_WORKSPACE_ID)
--yesswitchnoConfirm this high-risk operation
This permanently deletes the selected documents and all of their chunks.
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]
ParameterTypeRequiredDescription
--file-id <id>stringyesData-center file ID
--workspace-id <id>stringnoWorkspace 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]
ParameterTypeRequiredDescription
--category-id <id>stringyesCategory to list (find ids via the category list command); exact match
--name <text>stringnoFilter by exact file name without its extension (a.md → pass a)
--file-id <id>arraynoFilter by exact file ID (repeatable)
--next-token <token>stringnoCursor for the next page (from previous output)
--max-result <n>numbernoItems per page
--workspace-id <id>stringnoWorkspace 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]
ParameterTypeRequiredDescription
--file-id <id>stringyesData-center file ID to delete
--workspace-id <id>stringnoWorkspace ID for API endpoint URL (or set BAILIAN_WORKSPACE_ID)
--yesswitchnoConfirm this high-risk operation
This permanently deletes the data-center file. Knowledge-base document indexes that reference it may become invalid.
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. Usage 
bl knowledge chunk add --index-id <id> (--content <text> | --field <k=v>) [flags]
ParameterTypeRequiredDescription
--index-id <id>stringyesKnowledge base ID
--doc-id <id>stringnoOwning document ID from the doc list command; required in practice for all knowledge base types
--content <text>stringnoChunk body text, up to 6000 chars (document-type); alternative to --content-file
--content-file <path>stringnoRead chunk body from a UTF-8 plain text file (.md/.txt etc.)
--title <text>stringnoChunk title, up to 50 chars (document-type)
--image-url <url>arraynoChunk image URL (repeatable, up to 10; document-type)
--field <key=value>arraynoArbitrary field entry (repeatable) for table/image knowledge bases where keys are Excel column headers; mutually exclusive with content/title/image flags
--workspace-id <id>stringnoWorkspace 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]
ParameterTypeRequiredDescription
--index-id <id>stringyesKnowledge base ID
--doc-id <id>stringnoOnly show chunks belonging to this document
--page-number <n>numbernoPage number (default: 1)
--page-size <n>numbernoPage size per request
--workspace-id <id>stringnoWorkspace 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]
ParameterTypeRequiredDescription
--index-id <id>stringyesKnowledge base ID
--chunk-id <id>stringyesChunk ID (metadata._id from the chunk list output)
--doc-id <id>stringyesDocument ID owning the chunk (metadata.doc_id from the chunk list output)
--content <text>stringnoNew chunk content, 10-6000 chars; alternative to --content-file
--content-file <path>stringnoRead new content from a UTF-8 plain text file (.md/.txt etc.)
--title <text>stringnoChunk title, 0-50 chars (empty string clears it; omit to keep unchanged)
--excludeswitchnoExclude this chunk from retrieval
--includeswitchnoInclude this chunk in retrieval (default)
--workspace-id <id>stringnoWorkspace 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]
ParameterTypeRequiredDescription
--index-id <id>stringyesKnowledge base ID
--chunk-id <id>arrayyesChunk ID to delete (repeatable; batches of 10 are sent automatically)
--workspace-id <id>stringnoWorkspace ID for API endpoint URL (or set BAILIAN_WORKSPACE_ID)
--yesswitchnoConfirm this high-risk operation
This permanently deletes the selected chunks and cannot be undone.
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.

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]
ParameterTypeRequiredDescription
--name <text>stringyesCategory name (1-20 chars)
--parent-id <id>stringnoCreate as a sub-category of this category
--collection-id <id>stringnoCreate under this collection (defaults to the platform collection)
--workspace-id <id>stringnoWorkspace 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]
ParameterTypeRequiredDescription
--collection-id <id>stringnoFilter by exact collection ID
--parent-id <id>stringnoList sub-categories of this exact parent category
--name <text>stringnoFilter by category name (exact match, unlike the knowledge base list)
--next-token <token>stringnoCursor for the next page (from previous output)
--max-result <n>numbernoItems per page (default: 20)
--workspace-id <id>stringnoWorkspace 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]
ParameterTypeRequiredDescription
--category-id <id>stringyesCategory ID to delete
--workspace-id <id>stringnoWorkspace ID for API endpoint URL (or set BAILIAN_WORKSPACE_ID)
--yesswitchnoConfirm this high-risk operation
This deletes the selected data-center category and cannot be undone.
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]
ParameterTypeRequiredDescription
--name <text>stringyesCollection name
--description <text>stringyesWhat this collection holds and what it is for — tells collections apart in the list
--store-type <type>stringnoStorage: platform (managed) or custom (your own OSS bucket)
--oss-region <id>stringnoOSS region id (required with --store-type custom)
--oss-bucket <name>stringnoOSS bucket name (required with --store-type custom)
--workspace-id <id>stringnoWorkspace 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]
ParameterTypeRequiredDescription
--collection-id <id>stringnoCollection ID; alternative to --name
--name <text>stringnoCollection name; alternative to --collection-id
--workspace-id <id>stringnoWorkspace 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]
ParameterTypeRequiredDescription
--name <text>stringyesService name (up to 200 chars, unique per scene in the workspace)
--scene <scene>stringyesService scene: chat (Q&A) or search (retrieval)
--description <text>stringnoWhat this service answers and who it serves — recommended: agents read it to pick the right service (up to 1000 chars)
--index-id <id>stringnoBind this knowledge base; other settings use server defaults
--workspace-id <id>stringnoWorkspace 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]
ParameterTypeRequiredDescription
--scene <scene>stringyesService scene: chat (Q&A) or search (retrieval)
--status <status>stringnoFilter by status: draft, deployed (includes edited) or deleted
--name <text>stringnoFilter by service name (fuzzy match)
--agent-id <id>stringnoFilter by exact agent ID
--index-id <id>stringnoFilter by exact linked knowledge base (pipeline) ID
--page-number <n>numbernoPage number (default: 1)
--page-size <n>numbernoPage size per request
--workspace-id <id>stringnoWorkspace 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]
ParameterTypeRequiredDescription
--agent-id <id>stringyesService (agent) ID
--agent-version <version>stringnoSpecific version to inspect (beta or a published number); omit for all versions
--workspace-id <id>stringnoWorkspace 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]
ParameterTypeRequiredDescription
--agent-id <id>stringyesService (agent) ID
--name <text>stringnoNew service name (up to 200 chars)
--description <text>stringnoNew service description (up to 1000 chars)
--agent-version <version>stringnoTarget version (default: beta draft). Published versions only accept --version-desc
--version-desc <text>stringnoVersion description
--policy <policy>stringnoAgent policy: turbo (fast) or agentic (multi-turn)
--model <name>stringnoGeneration model code (must be in the platform allowlist)
--temperature <n>numbernoSampling temperature, range 0-2
--max-llm-calls <n>numbernoMax LLM calls per request, range 1-30
--enable-session-file <bool>stringnoEnable session files: true or false
--enable-refusal <bool>stringnoEnable refusal answers: true or false
--enable-anti-leak <bool>stringnoEnable anti prompt-leak: true or false
--enable-rich-text <bool>stringnoEnable rich text output: true or false
--enable-citation <bool>stringnoEnable citations: true or false
--config-file <path>stringnoJSON file replacing the whole agent_config (for nested settings like kb_search_configs); mutually exclusive with scalar config flags
--workspace-id <id>stringnoWorkspace 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]
ParameterTypeRequiredDescription
--agent-id <id>stringyesService (agent) ID
--version-desc <text>stringnoDescription for the newly published version
--workspace-id <id>stringnoWorkspace ID for API endpoint URL (or set BAILIAN_WORKSPACE_ID)
--yesswitchnoConfirm this high-risk operation
This publishes the current draft as a new version and changes the behavior seen by live callers.
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]
ParameterTypeRequiredDescription
--agent-id <id>stringyesSource service (agent) ID to copy
--workspace-id <id>stringnoWorkspace 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]
ParameterTypeRequiredDescription
--agent-id <id>stringyesService (agent) ID
--workspace-id <id>stringnoWorkspace ID for API endpoint URL (or set BAILIAN_WORKSPACE_ID)
--yesswitchnoConfirm this high-risk operation
This deletes the service and makes its agent ID unavailable for search and chat calls. The operation cannot be undone.
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.