Knowledge Base

Manage knowledge base entries, search content, and upload documents from the CLI

Ingest documents, search knowledge, and manage entries from your terminal. Handles text entries (sync), file uploads (async), and URL ingestion (async).

Commands

Command	Description
`chanl kb add`	Add a text entry (sync) or queue a URL/file (async)
`chanl kb upload`	Upload a file or ingest a URL
`chanl kb create`	Create a manual entry
`chanl kb search`	Search the knowledge base
`chanl kb list`	List all entries
`chanl kb get <id>`	Get entry details
`chanl kb update <id>`	Update an entry
`chanl kb delete <id>`	Delete an entry
`chanl kb folders`	Manage folders
`chanl kb sync`	Trigger a manual sync
`chanl kb task <id>`	Check async task status
`chanl kb stats`	View knowledge base statistics

Quick Start

Add text content (sync -- immediate)

chanl kb add \
  --title "Return Policy" \
  --source text \
  --content "Returns accepted within 30 days. Items must be unused and in original packaging." \
  --tags policy,returns

Knowledge Entry Created
───────────────────────────────
ID:      kb_abc123
Title:   Return Policy
Source:  text
Status:  completed

Upload a file (async -- returns task ID)

chanl kb upload ./product-manual.pdf --title "Product Manual v2"

Upload Queued
───────────────────────────────
Task ID:  task_xyz789
File:     product-manual.pdf
Status:   processing

Check status: chanl kb task task_xyz789

Ingest a URL (async)

chanl kb upload --url https://help.example.com/returns \
  --title "Returns Help Article"

Upload Queued
───────────────────────────────
ID:       kb_def456
Task ID:  task_abc012
Status:   pending

Check status: chanl kb task task_abc012

Search

chanl kb search "How do I return a product?"

Search Results (3 found)
───────────────────────────────────────────────────────
Score   Title                    Source    Preview
0.92    Return Policy            text      Returns accepted within 30 days...
0.85    Refund Process           text      To request a refund, contact...
0.78    Shipping & Returns FAQ   url       Our return policy allows...

Source Types

Source	Processing	Best For
`text`	Sync (immediate)	FAQ entries, policies, short content
`url`	Async (returns task ID)	Web pages, help articles
`file`	Async (returns task ID)	PDFs, docs, manuals

Create Entries

Manual entry with content

chanl kb create \
  --title "Shipping Information" \
  --content "Standard: 5-7 days ($5.99). Express: 2-3 days ($12.99)." \
  --source manual \
  --tags shipping,delivery

From a content file

chanl kb create \
  --title "FAQ" \
  --content-file ./faq.txt \
  --source faq

With metadata and folder

chanl kb create \
  --title "Policy Update" \
  --content "New return policy effective March 2026..." \
  --tags policy,2026 \
  --metadata '{"version": "2.0", "author": "Legal Team"}' \
  --folder folder_policies

Upload

Upload a file

chanl kb upload ./document.pdf --title "Product Manual"

chanl kb upload ./policy.pdf \
  --title "Return Policy 2026" \
  --tags policy,returns \
  --folder folder_policies

Ingest a URL with auto-sync

chanl kb upload --url https://help.example.com/faq \
  --title "FAQ Page" \
  --sync weekly

Upload options

Option	Description
`--title`	Entry title (required)
`--tags`	Comma-separated tags
`--folder`	Target folder ID
`--source`	Source type: document, webpage, faq
`--url`	URL to ingest (instead of file path)
`--sync`	Sync frequency: manual, daily, weekly, monthly
`--metadata`	JSON metadata string

Search

Basic search

chanl kb search "return policy"

Search modes

# Hybrid (default) -- vector + text
chanl kb search "return policy" --mode hybrid

# Vector -- semantic similarity
chanl kb search "Can I get my money back?" --mode vector

# Text -- exact keyword matching
chanl kb search "SKU-12345" --mode text

With filters

chanl kb search "shipping options" \
  --mode hybrid \
  --limit 10 \
  --min-score 0.6 \
  --tags shipping \
  --folder folder_shipping \
  --json

Search options

Option	Description	Default
`--mode`	`hybrid`, `vector`, or `text`	`hybrid`
`--limit`	Max results	5
`--min-score`	Minimum relevance score (0.0-1.0)	0.7
`--tags`	Filter by tags	--
`--source`	Filter by source type	--
`--folder`	Filter by folder	--
`--json`	Output as JSON	--

List Entries

chanl kb list

Knowledge Entries (24 total)
───────────────────────────────────────────────────────────────────
ID            Title                    Source    Tags           Updated
kb_abc123     Return Policy            manual    policy         2 days ago
kb_def456     Product Manual v2        document  product        1 week ago
kb_ghi789     FAQ Page                 webpage   faq,help       3 hours ago

Option	Description
`--source`	Filter by source type
`--tags`	Filter by tags (comma-separated)
`--folder`	Filter by folder ID
`--search`	Search by title
`--page`	Page number
`--limit`	Items per page
`--json`	Output as JSON

Get Entry Details

chanl kb get kb_abc123

Knowledge Entry: kb_abc123
────────────────────────────────────────────────────
Title:       Return Policy
Source:      manual
Tags:        policy, returns
Folder:      Policies (folder_abc)
Created:     2026-01-15T10:30:00Z
Updated:     2026-01-20T14:15:00Z
Chunks:      3
Content:
  Returns are accepted within 30 days of purchase.
  Items must be unused and in original packaging.
  Refunds are processed within 5-7 business days.

Full content for long entries:

chanl kb get kb_abc123 --full

Update an Entry

chanl kb update kb_abc123 \
  --title "Updated Return Policy" \
  --tags policy,returns,2026

✓ Updated entry: kb_abc123

Update content:

chanl kb update kb_abc123 --content "New policy content..."
chanl kb update kb_abc123 --content-file ./updated-policy.txt

Move to a folder:

chanl kb update kb_abc123 --folder folder_policies

Delete an Entry

chanl kb delete kb_abc123

Are you sure you want to delete Return Policy? (y/N) y
✓ Deleted entry: kb_abc123

Option	Description
`--force`	Skip confirmation
`--delete-files`	Also delete associated storage files

Folders

List folders

chanl kb folders list

Folders
───────────────────────────────────────────────────
ID              Name              Entries  Description
folder_abc123   Policies          12       Company policies
folder_def456   Products          24       Product documentation
folder_ghi789   FAQs              8        Frequently asked questions

Create a folder

chanl kb folders create \
  --name "Policies" \
  --description "Company policies and procedures"

Nested folder:

chanl kb folders create \
  --name "Return Policies" \
  --parent folder_abc123

Move an entry

chanl kb move kb_abc123 --folder folder_policies

Delete a folder

chanl kb folders delete folder_abc123 --move-to-root

Sync

Configure sync for a URL entry

chanl kb sync-config kb_def456 \
  --enabled true \
  --frequency weekly

Trigger manual sync

chanl kb sync kb_def456

Sync Started
───────────────────────────────
Entry:    kb_def456
Task ID:  task_xyz789
Status:   processing

View sync config

chanl kb sync-config kb_def456

Sync Configuration: kb_def456
───────────────────────────────
Enabled:    true
Frequency:  weekly
Last Sync:  2026-01-18T08:00:00Z
Next Sync:  2026-01-25T08:00:00Z
Source URL: https://help.example.com/faq

Tasks

Check task status

chanl kb task task_xyz789

Task: task_xyz789
───────────────────────────────
Status:      completed
Progress:    100%
Document:    kb_abc123
Duration:    12.5s
Chunks:      8

List tasks

chanl kb tasks
chanl kb tasks --status processing
chanl kb tasks --limit 10

Statistics

chanl kb stats

Knowledge Base Statistics
───────────────────────────────────────────────────
Total Entries:    156
Total Chunks:     1,247
Storage Used:     45.2 MB

By Source:
  manual:     42
  document:   68
  webpage:    32
  faq:        14

By Folder:
  Policies:   24
  Products:   48
  FAQs:       32
  (root):     52

Configuration

chanl kb config

Knowledge Base Configuration
───────────────────────────────────────────────────
Max Documents:     1000
Max File Size:     10 MB
Retention Days:    365
Allowed Types:     pdf, docx, txt, html, md

Search Defaults:
  Mode:            hybrid
  Limit:           5
  Min Score:       0.7

Chunking:
  Chunk Size:      1000 tokens
  Chunk Overlap:   200 tokens

Update config:

chanl kb config update \
  --search-mode hybrid \
  --search-limit 10 \
  --min-score 0.6

Scripting Examples

Batch upload PDFs

for file in ./docs/*.pdf; do
  chanl kb upload "$file" \
    --title "$(basename "$file" .pdf)" \
    --tags batch-upload
  sleep 1
done

Sync all URL entries

chanl kb list --source webpage --json | \
  jq -r '.entries[].id' | \
  xargs -I {} chanl kb sync {}

Clean up old entries

chanl kb list --tags old-version --json | \
  jq -r '.entries[].id' | \
  xargs -I {} chanl kb delete {} --force

CI/CD: sync docs on deploy

- name: Sync knowledge base
  run: |
    for file in ./docs/*.md; do
      chanl kb upload "$file" \
        --title "$(basename "$file" .md)" \
        --folder folder_docs \
        --tags docs,ci
    done
  env:
    CHANL_API_KEY: ${{ secrets.CHANL_API_KEY }}
    CHANL_WORKSPACE_ID: ${{ vars.CHANL_WORKSPACE_ID }}

Troubleshooting

Platform: Knowledge Base

Knowledge base concepts and architecture

SDK: Knowledge Base

Build KB operations into your application

API: Knowledge Base

REST API for knowledge base operations

MCP Integration

Agents search knowledge via MCP automatically

Upload fails with file too large

Search returns no results

Task stuck in processing

URL sync not updating

Platform: Knowledge Base

SDK: Knowledge Base

API: Knowledge Base

MCP Integration

On this page