Chunk commands

A chunk is the smallest retrievable unit in a Knowledge Base. Documents are split into chunks automatically on import, and you can also add or correct chunks manually. This group has 4 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 chunk add

Add a chunk directly to a Knowledge Base.

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

Parameters

Parameter	Type	Required	Description
`--index-id <id>`	string	Yes	Knowledge Base ID
`--doc-id <id>`	string	Yes	Owning document ID, from `chunk list` or `doc list`
`--content <text>`	string	One of two	Chunk body, up to 6000 chars (document-type); mutually exclusive with `--content-file`
`--content-file <path>`	string	One of two	Read the body from a UTF-8 text file; mutually exclusive with `--content`
`--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	One of two	Arbitrary key-value entry, repeatable, for table and image Knowledge Bases where keys are column headers; mutually exclusive with `--content`, `--content-file`, `--title`, and `--image-url`

The content flags (--content / --content-file / --title / --image-url) and --field are mutually exclusive; provide one group or the other. Output

chunk created (knowledge base: idx-xxx)
List chunks to find the new chunk id.

quiet mode prints nothing and exits 0 on success. json mode returns the full result, but it does not include the new chunk's ID. Notes

Supports document-type, table-type, and image-type Knowledge Bases. Audio and video Knowledge Bases are not supported.
The response does not contain the new chunk's ID — find it with kscli chunk list.
The write rate limit is roughly 10 calls per second, so batch scripts must pace themselves to avoid throttling.
Table and image Knowledge Bases use --field, where keys are the table column headers and values are strings.

Examples

# Add a text chunk
kscli chunk add --index-id idx-xxx --doc-id doc-xxx --content "chunk body" --title "Overview"

# Add a table row
kscli chunk add --index-id idx-xxx --doc-id doc-xxx --field ColA=v1 --field ColB=v2

# Read the body from a file
kscli chunk add --index-id idx-xxx --doc-id doc-xxx --content-file ./chunk.md

kscli chunk list

List chunks in a Knowledge Base with a content preview and retrieval status.

kscli chunk list --index-id <id> [flags]

Parameters

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	Items per page, default 20, range 1–100

Output text mode shows each chunk's ID, owning document, and status, with the body preview truncated at 200 chars:

[chunk] chunk-xxx  (doc: intro.md, doc_id: file-xxx)  status: COMPLETED
  chunk content preview…
total: 1

Chunks excluded from retrieval show [excluded from retrieval] at the end of the line. quiet mode prints one chunk ID per line, ready to pipe into chunk update or chunk delete. json mode returns the full data for each chunk. The chunk IDs and doc_id values in the output are required parameters for chunk update and chunk delete. Examples

# List all chunks
kscli chunk list --index-id idx-xxx

# Only chunks of one document
kscli chunk list --index-id idx-xxx --doc-id file-xxx --page-size 50

kscli chunk update

Update chunk content, or toggle whether it participates in retrieval.

kscli chunk update --index-id <id> --chunk-id <id> --doc-id <id> [flags]

Parameters

Parameter	Type	Required	Description
`--index-id <id>`	string	Yes	Knowledge Base ID
`--chunk-id <id>`	string	Yes	Chunk ID, from `chunk list` output
`--doc-id <id>`	string	Yes	Owning document ID, from `chunk list` output
`--content <text>`	string	No	New content, 10–6000 chars; mutually exclusive with `--content-file`
`--content-file <path>`	string	No	Read the new content from a UTF-8 text file; mutually exclusive with `--content`
`--title <text>`	string	No	Chunk title, 0–50 chars. An empty string clears it; omit to leave it unchanged
`--exclude`	switch	No	Exclude this chunk from retrieval; mutually exclusive with `--include`
`--include`	switch	No	Restore this chunk to retrieval; mutually exclusive with `--exclude`

At least one of --content, --content-file, --title, --exclude, or --include is required. Output

updated: chunk-xxx

quiet mode prints nothing. json mode returns the full result. Notes

New content must be 10–6000 chars and must not exceed the Knowledge Base's chunk size limit.
--content-file accepts UTF-8 plain text only; it does not parse .docx, .pdf, or other document formats.
You can toggle --exclude or --include without supplying new content, leaving the chunk body unchanged. An excluded chunk stays in the Knowledge Base but is no longer matched by retrieval, which suits content that is outdated but must be retained.

Examples

# Correct the content
kscli chunk update --index-id idx-xxx --chunk-id chunk-xxx --doc-id file-xxx \
  --content "corrected text"

# Exclude from retrieval
kscli chunk update --index-id idx-xxx --chunk-id chunk-xxx --doc-id file-xxx --exclude

# Restore to retrieval
kscli chunk update --index-id idx-xxx --chunk-id chunk-xxx --doc-id file-xxx --include

kscli chunk delete

Delete chunks from a Knowledge Base.

kscli chunk delete --index-id <id> --chunk-id <id> [flags]

Parameters

Parameter	Type	Required	Description
`--index-id <id>`	string	Yes	Knowledge Base ID
`--chunk-id <id>`	array	Yes	Chunk ID, repeatable, up to 10 per batch with automatic batching beyond that
`--yes`	switch	No	Skip the confirmation prompt

Output

deleted: 2 chunk(s) in 1 batch(es)

quiet mode prints nothing. json mode returns deleted_count and batches.

Chunks are permanently removed and cannot be recovered. If you only want content to stop appearing in retrieval, use kscli chunk update --exclude instead — that keeps the content and is reversible.

Passing more than 10 chunk IDs submits them in automatic batches. If a batch fails, the operation stops immediately and the successfully deleted batches are listed in the error message. Examples

# Delete several chunks
kscli chunk delete --index-id idx-xxx --chunk-id chunk-a --chunk-id chunk-b

# Skip confirmation
kscli chunk delete --index-id idx-xxx --chunk-id chunk-a --yes

​kscli chunk add

​kscli chunk list

​kscli chunk update

​kscli chunk delete

kscli chunk add

kscli chunk list

kscli chunk update

kscli chunk delete