Browse, organize, and manage the Senso knowledge base folder tree. Create folders, move and rename nodes, view content details, download files, and check sync status. Use when the user wants to structure, reorganize, or explore their KB.
npx @senso-ai/shipables install senso-ai/senso-kb-organizeBrowse and manage the Senso knowledge base folder tree. The KB is structured like a file system — folders organize content, and documents (uploaded files or raw text) hold knowledge.
npm install -g @senso-ai/cli
export SENSO_API_KEY=<your-key>
Every senso command must include --output json --quiet.
kb_node_id, a type (folder or content), and a parent_idparent_id: nullsync-statussenso kb root --output json --quiet
Returns the root folder node with its kb_node_id. Use this ID to list top-level children.
senso kb my-files --output json --quiet
# With pagination
senso kb my-files --limit 50 --offset 0 --output json --quiet
senso kb children <folder_kb_node_id> --output json --quiet
# With pagination
senso kb children <id> --limit 50 --offset 0 --output json --quiet
senso kb get <kb_node_id> --output json --quiet
Returns the full node detail including type, name, parent, and metadata.
senso kb find --query "policy" --output json --quiet
# With pagination
senso kb find --query "policy" --limit 20 --offset 0 --output json --quiet
senso kb ancestors <kb_node_id> --output json --quiet
Returns the ancestor chain from root to the node — useful for showing the user where something lives in the tree.
senso kb get-content <kb_node_id> --output json --quiet
# Get a specific version
senso kb get-content <kb_node_id> --version <version_number> --output json --quiet
senso kb download-url <kb_node_id> --output json --quiet
# For a specific version
senso kb download-url <kb_node_id> --version <version_number> --output json --quiet
Returns a time-limited presigned S3 URL for downloading the original file.
# Create at root level
senso kb create-folder --name "HR Documents" --output json --quiet
# Create inside an existing folder
senso kb create-folder --name "Policies" --parent-id <parent_kb_node_id> --output json --quiet
Rename any node (folder or document):
senso kb rename <kb_node_id> --name "New Name" --output json --quiet
Move a node to a different parent folder:
senso kb move <kb_node_id> --parent-id <new_parent_kb_node_id> --output json --quiet
After moving: Check sync status — the vector index needs to update.
senso kb delete <kb_node_id> --output json --quiet
This is a soft delete. Deleting a folder deletes all its contents recursively.
After deleting: Check sync status.
After any structural change (move, delete, upload), check that the vector index is up to date:
senso kb sync-status --output json --quiet
Search results may be stale until sync completes. Wait for sync before relying on search for recently moved or deleted content.
Create a document directly from text or markdown:
senso kb create-raw --data '{
"title": "Company Vacation Policy",
"text": "# Vacation Policy\n\nAll employees receive 20 days of paid vacation per year...",
"kb_folder_node_id": "<parent-folder-uuid>"
}' --output json --quiet
The kb_folder_node_id is optional — omit to create at root level.
Full replacement (creates a new version):
senso kb update-raw <kb_node_id> --data '{
"title": "Updated Policy Title",
"text": "# Updated Content\n\nNew text here..."
}' --output json --quiet
Partial update (only changes specified fields):
senso kb patch-raw <kb_node_id> --data '{
"title": "Just Update the Title"
}' --output json --quiet
senso kb upload report.pdf slides.pptx --folder-id <kb_node_id> --output json --quiet
Maximum 10 files per call. Without --folder-id, files go to the root.
senso kb update-file <kb_node_id> updated-report.pdf --output json --quiet
This replaces the file and triggers background re-processing.
When the user asks to "organize the KB":
senso kb my-files to understand current statesenso kb create-foldersenso kb movesenso kb renamesenso kb sync-status after all changesTo list content with more detail (processing status, publish status):
senso content list --output json --quiet
# With pagination
senso content list --limit 20 --offset 0 --output json --quiet
| HTTP Status | Meaning | Action |
|---|---|---|
| 401 | Invalid or missing API key | Check SENSO_API_KEY |
| 404 | Node not found | Verify the kb_node_id with senso kb find or senso kb my-files |
| 409 | Conflict — operation in progress | Another operation is running on this node. Wait and retry. |
| 422 | Unprocessable | Check that the target parent is a folder (type: folder), not a content node |
SENSO_API_KEYSenso API key for authenticating CLI commands