Skip to main content

Document commands

The kscli doc group — upload files, import from OSS, track parse status, and manage tags

Document management covers file upload, OSS import, parse status tracking, document deletion, and tag maintenance. Once imported into a Knowledge Base, documents are automatically parsed into chunks. 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.

kscli doc list

List documents in a Knowledge Base along with their parse status. 
kscli doc list --index-id <id> [flags]
Parameters
ParameterTypeRequiredDescription
--index-id <id>stringYesKnowledge Base ID
--page-number <n>numberNoPage number, default 1
--page-size <n>numberNoItems per page, default 10, range 1–100
Output text mode prints one document per line, highlighting FAILED documents in red: 
doc-xxx  COMPLETED  intro.md  md  1024
total: 1
quiet mode prints one doc_id per line. json mode returns the full result.
A document's doc_id inside a Knowledge Base is not necessarily the same as its data center file ID — it depends on the import path. For later operations on Knowledge Base documents (such as doc delete or chunk update), always use the doc_id from this command.
Examples 
# List documents
kscli doc list --index-id idx-xxx

# 100 items per page
kscli doc list --index-id idx-xxx --page-size 100

kscli doc status

Check the execution status of a Knowledge Base import job. 
kscli doc status --index-id <id> --job-id <id> [flags]
Parameters
ParameterTypeRequiredDescription
--index-id <id>stringYesKnowledge Base ID
--job-id <id>stringYesImport job ID, returned by kb create or doc upload
--page-number <n>numberNoPage number, default 1
--page-size <n>numberNoItems per page
--waitswitchNoPoll until the job reaches a terminal state
--poll-interval <seconds>numberNoPolling interval in seconds, default 5
Output 
status: COMPLETED
  doc-xxx  COMPLETED  intro.md
quiet mode prints the overall job status. json mode returns the full result including per-document status. Notes
  • The overall job status is PENDING, RUNNING, or COMPLETED.
  • An individual document may fail to parse (for example PARSE_FAILED); the command then exits non-zero and shows the server error message.
  • A SystemError from the server usually means the job ID does not exist — confirm it from the output of doc upload or kb create.
Examples 
# Query once
kscli doc status --index-id idx-xxx --job-id job-xxx

# Poll until done, every 10 seconds
kscli doc status --index-id idx-xxx --job-id job-xxx --wait --poll-interval 10

kscli doc upload

Upload local files or directories to the data center, optionally importing them into a Knowledge Base. 
kscli doc upload --file <path> [flags]
Parameters
ParameterTypeRequiredDescription
--file <path>arrayYesLocal file or directory path, repeatable. Directories are scanned recursively and unsupported formats are skipped
--index-id <id>stringNoImport into this Knowledge Base after upload; all files become one import job
--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; requires --index-id
--poll-interval <seconds>numberNoPolling interval in seconds, default 5
Output 
intro.md  file-xxx  registered
job: job-xxx
status: COMPLETED

Uploaded 1 file.
quiet mode prints one file ID per line. json mode returns files (paths and file IDs), skipped, index_id, ingestion_id, and final_status. Supported file formats .pdf, .doc, .docx, .ppt, .pptx, .xls, .xlsx, .csv, .md, .txt, .html, .png, .jpg, .jpeg, .bmp, .gif Notes
  • When scanning directories recursively, node_modules, .git, and similar directories are skipped automatically.
  • Multiple files are uploaded sequentially. If some fail, the file IDs already uploaded are listed in the error message so you can resume or clean up.
  • Before uploading a large batch, run --dry-run --verbose to review which files would be uploaded and skipped.
Examples 
# Upload a single file
kscli doc upload --file ./a.md

# Upload several files, import them, and wait for parsing
kscli doc upload --file ./a.md --file ./b.pdf --index-id idx-xxx --wait

# Upload a whole directory
kscli doc upload --file ./docs/

# Dry-run preview
kscli doc upload --file ./docs/ --dry-run --verbose

kscli doc delete

Delete documents and their chunks from a Knowledge Base. 
kscli doc delete --index-id <id> --doc-id <id> [flags]
Parameters
ParameterTypeRequiredDescription
--index-id <id>stringYesKnowledge Base ID
--doc-id <id>arrayYesDocument ID, repeatable
--yesswitchNoSkip the confirmation prompt
Output 
deleted: 2 document(s)
  doc-a
  doc-b
quiet mode prints one deleted doc_id per line. json mode returns the list of IDs actually deleted. Notes
  • This only removes documents from the Knowledge Base index; the data center source files remain. To delete source files, use kscli file delete.
  • Take doc_id from kscli doc list --quiet, not from the file ID returned by doc upload.
  • Deletion is asynchronous: the command returns success immediately, but doc list may still show the document briefly — it clears after roughly 30 seconds.
  • The output lists the IDs actually deleted, which may differ in count from the request; any difference is warned about on stderr.
Examples 
# Delete a single document
kscli doc delete --index-id idx-xxx --doc-id doc-xxx

# Delete several and skip confirmation
kscli doc delete --index-id idx-xxx --doc-id doc-a --doc-id doc-b --yes

kscli doc tag

Batch update tags on data center files. 
kscli doc tag --doc-id <id> --tag <text> [flags]
Parameters
ParameterTypeRequiredDescription
--doc-id <id>arrayYesData center file ID, repeatable, up to 20 per call
--tag <text>arrayYesTag, repeatable, applied to every --doc-id
--mode <mode>stringNoUpdate mode, append (default) or overwrite
Constraints
  • Up to 20 --doc-id values per call
  • Up to 100 tags; each tag up to 32 chars; total tag length up to 700 chars
Output 
tagged: 2 file(s) with [project-a, draft]
quiet mode prints nothing. json mode returns the full result.
--mode overwrite replaces all existing tags on the file with the ones passed in this call, and the replaced tags cannot be recovered. Use it only when you intend to clear the original tags; otherwise stay with the default append.
The same tag set is applied to every --doc-id. To tag different files differently, run the command multiple times. Examples 
# Append tags
kscli doc tag --doc-id file-xxx --tag project-a --tag draft

# Overwrite tags
kscli doc tag --doc-id file-a --doc-id file-b --tag final --mode overwrite

kscli doc import-oss

Batch import files from an authorized OSS bucket into the data center. 
kscli doc import-oss --bucket <name> --region <id> --oss-key <key> [flags]
Parameters
ParameterTypeRequiredDescription
--bucket <name>stringYesAuthorized OSS bucket name
--region <id>stringYesOSS region ID, such as cn-beijing
--oss-key <key>arrayYesOSS object key, repeatable, up to 10 per call
--category-id <id>stringNoTarget data center category, defaults to the default category
--tag <text>arrayNoFile tag, repeatable, up to 10
--overwriteswitchNoOverwrite files previously imported from the same OSS keys
Output 
imported: 2 file(s)
  file-a  SUCCESS  docs/a.pdf
  file-b  SUCCESS  docs/b.docx
quiet mode prints one file ID per line. json mode returns each file's ID, status, and OSS key. Notes
  • The bucket must be authorized for the platform service beforehand. In the RAM console, confirm the AliyunServiceRoleForBailian service-linked role is correctly authorized for the bucket, otherwise the import returns a permission error.
  • The imported file name is taken from the last segment of the OSS key.
  • --overwrite replaces the previously imported file and produces a new file ID, invalidating the old one. If any Knowledge Base or script references the old ID, update it accordingly.
Examples 
# Import a single file
kscli doc import-oss --bucket my-bucket --region cn-beijing --oss-key docs/a.pdf

# Import several files, overwriting earlier imports of the same keys
kscli doc import-oss --bucket my-bucket --region cn-beijing \
  --oss-key docs/a.pdf --oss-key docs/b.docx --overwrite
Getting Started
Playground
Data Ingestion
Knowledge Service
Cookbook
Integration
Settings, Billing & Limits