Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.knowledgestack.ai/llms.txt

Use this file to discover all available pages before exploring further.

kscli 45-second demo — click to play
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.

​
Get an API key in 60 seconds

1

Open the dashboard

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

Open My Account → API Keys

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

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-.
4

Log in from the terminal

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.
5

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

FormatDescriptionUse case
tableRich formatted tableInteractive use (default)
jsonPretty-printed JSONScripting, API debugging
yamlYAML outputEyeballing config, readability
id-onlyOne ID per linePiping into other commands
treeHierarchical tree viewViewing 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 varDescriptionDefault
KSCLI_BASE_URLAPI base URLhttps://api-staging.knowledgestack.ai
KSCLI_FORMATDefault output formattable
KSCLI_VERIFY_SSLEnable TLS verificationtrue
KSCLI_CA_BUNDLECustom CA certificate bundlecertifi / system default
KSCLI_CONFIGConfig file path~/.config/kscli/config.json
KSCLI_CREDENTIALS_PATHCredentials 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