clik-kb CLI

Command-line tool for clik-kb — manage collections, folders, files, chunks, search, and RAG from the terminal or from AI coding agents (Claude Code, Codex).

Installation

npm install -g clik-kb

Or run without installing:

npx clik-kb --help

Setup

Create a .env file or export environment variables:

CLIK_KB_API_KEY=ck_...           # generate in Settings → API Keys
CLIK_KB_WORKSPACE=<workspace-id> # find in workspace URL or Settings
CLIK_KB_URL=http://localhost:3001 # default; change for production

You can also pass auth inline per-command:

clik-kb --api-key ck_... --workspace <id> collections list

Quick start

# List collections
clik-kb collections list --pretty

# Ingest a markdown file
clik-kb files ingest --collection <id> --name "API Spec" --file ./openapi.md

# Search
clik-kb search --collection <id> --query "how to configure auth"

# Ask a question (RAG)
clik-kb ask --query "What are the system requirements?" --collection <id>

Commands

| Group | Commands | |---|---| | collections | list, create, delete | | folders | list, create, rename, move, delete | | files | list, get, ingest, rename, move, delete, upsert, upsert-folder, re-embed, purge-vectors | | chunks | list, create, update, delete | | search | semantic / hybrid search | | ask | RAG query with LLM answer + citations |

Run clik-kb <group> --help for options on any group, or clik-kb <group> <command> --help for a specific command.

Full command reference: COMMANDS.md

For AI agents (Claude Code / Codex)

This CLI is designed to be called directly by AI coding agents. All output is JSON to stdout by default — pipe-friendly for jq and shell scripts. Add --pretty for readable output.

Example agent workflow

# Discover what collections exist
clik-kb collections list | jq '.[].name'

# Find a collection ID
COL=$(clik-kb collections list | jq -r '.[] | select(.name=="Product Docs") | .id')

# List files in it
clik-kb files list --collection $COL --pretty

# Ingest a new document
clik-kb files ingest --collection $COL --name "Release Notes" --file ./release.md

# Embed it
FILE_ID=$(clik-kb files list --collection $COL | jq -r '.[] | select(.name=="Release Notes") | .id')
clik-kb files upsert --collection $COL --id $FILE_ID

# Search it
clik-kb search --collection $COL --query "breaking changes in v2"

MCP alternative

For tighter agent integration, use the MCP server instead — it exposes the same operations as native tool calls with no shell overhead:

Endpoint: http://localhost:3001/mcp
Auth:     X-API-Key: ck_...

Output format

• stdout: JSON response from the API
• stderr: errors and warnings
• exit code 0: success; exit code 1: error

# Extract IDs with jq
clik-kb files list --collection <id> | jq '[.[].id]'

# Filter by status
clik-kb files list --collection <id> | jq '[.[] | select(.status=="CHUNKED")]'

License

MIT