kscli

kscli 45-second demo — click to play — ▶ Watch the 45-second demo — from uv tool install to semantic search

kscli is the official command-line interface for Knowledge Stack. It wraps the auto-generated ksapi Python SDK with a resource-first routing pattern (kscli <resource> <verb>, e.g. kscli folders list, kscli documents ingest) and a Click-based UX designed for humans and scripts.

uv tool install kscli
kscli login --api-key sk-user-...
kscli documents ingest --file report.pdf --path-part-id <folder-path-part-id>
kscli chunks search --query "quarterly revenue" --parent-path-ids <folder-path-part-id>

Start here

Quickstart

Zero to first semantic search in under two minutes. Includes dashboard screenshots for API key creation.

Authentication

How to create an API key, how kscli login stores it, TLS, and exit codes.

Commands

Full reference for every resource group and verb — folders, documents, chunks, tags, workflows, threads, and more.

Recipes

Bulk ingest, shell scripts, CI pipelines, pipe-into-jq tricks, multi-environment setups.

Install

Requires Python 3.12+ and uv.

uv (recommended)
pipx
pip
From source

uv tool install kscli
kscli --version

uv tool install builds an isolated venv and puts kscli on your PATH. Upgrade later with uv tool upgrade kscli.

pipx install kscli

pip install kscli

git clone https://github.com/knowledgestack/ks-cli.git
cd ks-cli
uv sync --all-extras --group dev

Get an API key in 60 seconds

Open the dashboard

Go to app.knowledgestack.ai and sign in. New users can sign up with email/password or Google SSO.

Open My Account → API Keys

Click your avatar (top-right) → My Account → API Keys tab.

Create and copy the key

Click Create API key, give it a descriptive label (e.g. kscli on my laptop), and copy the key immediately — it is shown exactly once. Keys begin with sk-user-.

kscli login --api-key sk-user-xxxxxxxxxxxxxxxxxxxxxxxxxxxx

kscli validates the key by calling /users/me, stores it at /tmp/kscli/.credentials with mode 0600, and records the resolved base URL in ~/.config/kscli/config.json.

Verify

kscli whoami

Revoke a key at any time from the same dashboard page. See Authentication for the full auth model and TLS options.

Two-minute quickstart

# 1. Find the folder you want to drop documents into
kscli folders list --format tree

# 2. Grab a folder's path_part_id (not its id — they are different UUIDs)
kscli folders describe <folder-id> --format yaml

# 3. Create a subfolder to keep things tidy (optional)
kscli folders create --name "Q4 Reports" --parent-path-part-id <parent-path-part-id>

# 4. Ingest a PDF. The server chunks, embeds, and indexes in the background.
kscli documents ingest \
    --file ~/Downloads/q4-2025.pdf \
    --path-part-id <folder-path-part-id> \
    --name "Q4 2025 earnings"

# 5. Watch the ingestion workflow
kscli workflows list --limit 5

# 6. Run semantic search scoped to that folder
kscli chunks search \
    --query "what drove revenue growth in Q4" \
    --parent-path-ids <folder-path-part-id> \
    --limit 5

Full walkthrough →

Step-by-step quickstart with embedded screencasts for each step.

Key features

Resource-first commands — every resource (folders, documents, chunks, tags, workflows, …) has consistent verbs: list, describe, create, update, delete
Multiple output formats — table (default), json, yaml, tree, id-only
Bulk operations — kscli folders bulk-ingest ./dir --folder-id <id> uploads entire directory trees in one shot
Semantic + full-text search — kscli chunks search --search-type dense_only|full_text
Workflow monitoring — track ingestion with kscli workflows list, describe, cancel, rerun
Scriptable — pipe --format id-only into xargs, pipe --format json into jq

Output formats

Format	Description	Use case
`table`	Rich formatted table	Interactive use (default)
`json`	Pretty-printed JSON	Scripting, API debugging
`yaml`	YAML output	Eyeballing config, readability
`id-only`	One ID per line	Piping into other commands
`tree`	Hierarchical tree view	Viewing folder / document structure

Suppress table headers with --no-header (or -H). Set a persistent default with the KSCLI_FORMAT env var.

# Delete every empty folder under a parent
kscli folders list --parent-path-part-id <id> -f id-only | \
  xargs -I {} kscli folders delete {}

# Pretty-print the first search hit
kscli chunks search -q "latency SLO" -f json | jq '.[0]'

PathPart vs domain ID

Every folder has two UUIDs:

id — the folder’s record ID. Use with describe, update, delete.
path_part_id — its position in the folder tree. Use with anything that needs a parent — creating a child folder, ingesting a document under the folder, scoping a search.

kscli folders describe  <folder_id>                          # id
kscli folders create    --parent-path-part-id <path_part_id> # path_part_id
kscli documents ingest  --path-part-id <path_part_id>        # path_part_id
kscli chunks search     --parent-path-ids <path_part_id>     # path_part_id

kscli folders describe ... --format yaml prints both so you can copy the right one.

Configuration

Resolution order: CLI flags > environment variables > config file > defaults.

Env var	Description	Default
`KSCLI_BASE_URL`	API base URL	`https://api-staging.knowledgestack.ai`
`KSCLI_FORMAT`	Default output format	`table`
`KSCLI_VERIFY_SSL`	Enable TLS verification	`true`
`KSCLI_CA_BUNDLE`	Custom CA certificate bundle	certifi / system default
`KSCLI_CONFIG`	Config file path	`~/.config/kscli/config.json`
`KSCLI_CREDENTIALS_PATH`	Credentials directory	`/tmp/kscli`

Point at a different environment for a single command:

kscli --base-url http://localhost:8000 folders list

Full reference: Configuration.

Where to next

Quickstart →

Step-by-step with screenshots

Authentication →

API keys, credential storage, TLS

Commands →

Every resource and verb

Configuration →

Env vars and precedence

Recipes →

Bulk ingest, CI, scripting tricks

GitHub →

Source, issues, releases

Get Started

SDKs & MCP

Cookbook

Concepts

Ingestion Pipeline

Agent

Infrastructure

Design

Operations

Start here

Quickstart

Authentication

Commands

Recipes

Install

Get an API key in 60 seconds

Two-minute quickstart

Full walkthrough →

Key features

Output formats

PathPart vs domain ID

Configuration

Where to next

Quickstart →

Authentication →

Commands →

Configuration →

Recipes →

GitHub →

​Start here

Quickstart

Authentication

Commands

Recipes

​Install

​Get an API key in 60 seconds

​Two-minute quickstart

Full walkthrough →

​Key features

​Output formats

​PathPart vs domain ID

​Configuration

​Where to next

Quickstart →

Authentication →

Commands →

Configuration →

Recipes →

GitHub →

Start here

Install

Get an API key in 60 seconds

Two-minute quickstart

Key features

Output formats

PathPart vs domain ID

Configuration

Where to next