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.

End-to-end quickstart — install, login, ingest, search
Every command below is real. Copy, paste, substitute the placeholder IDs.

​
Prerequisites

  • Python 3.12+ (python --version)
  • uv installed (uv --version). On macOS: brew install uv.
  • A Knowledge Stack account at app.knowledgestack.ai — sign up with email/password or Google SSO.

​
The happy path

1

Install kscli

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

Create an API key

Creating an API key from the My Account → API Keys dashboard
  1. Open app.knowledgestack.ai and sign in.
  2. Click your avatar (top-right) → My Account.
  3. Open the API Keys tab.
  4. Click Create API key.
  5. Give the key a descriptive label — kscli on macbook, kscli ingest job, etc.
  6. Copy the key now. It is shown exactly once.
Treat the key like a password. Anyone with the key can act as you, including uploading and deleting documents.
3

Log in

kscli login validating the key and writing credentials
kscli login --api-key sk-user-xxxxxxxxxxxxxxxxxxxxxxxxxxxx
What happens:
  1. kscli calls GET /users/me with the key as a bearer token.
  2. On success, the key is written to /tmp/kscli/.credentials with mode 0600.
  3. The resolved base URL and TLS settings are saved to ~/.config/kscli/config.json.
  4. You should see Logged in successfully (https://api-staging.knowledgestack.ai).
Verify:
kscli whoami
kscli whoami --format yaml   # includes tenant_id, email, roles
Different environment? Pass --url http://localhost:8000 (dev) or --url https://api.knowledgestack.ai (prod) to login. It is persisted to the config file.
4

Find a folder to put documents in

Every document lives under a folder. Every tenant has a root folder; you can create subfolders.
# See the whole folder tree
kscli folders list --format tree
Pick a folder and grab its path_part_id — not id. The two are different UUIDs; see the note at the bottom of this page.
kscli folders describe <folder-id> --format yaml
Create a dedicated subfolder for this tutorial:
kscli folders create \
    --name "kscli tutorial" \
    --parent-path-part-id <parent-path-part-id>
Save the path_part_id from the response — the next step needs it.
5

Ingest a document

Ingesting a PDF and watching the workflow progress
Grab any PDF from your Downloads folder and upload it:
kscli documents ingest \
    --file ~/Downloads/some-report.pdf \
    --path-part-id <tutorial-folder-path-part-id> \
    --name "Some report"
Ingestion runs in the background: the file is uploaded, queued onto an ingestion workflow, then chunked, embedded, and indexed. kscli returns immediately with the new document’s id and a workflow handle.Watch the workflow progress:
kscli workflows list --limit 5
kscli workflows describe <workflow-id>
When the workflow is completed, the document is fully indexed and searchable. Small PDFs take seconds; large ones take a minute or two.
6

Run your first semantic search

kscli chunks search rendering a Rich table of ranked results
kscli chunks search \
    --query "what does the document say about revenue" \
    --parent-path-ids <tutorial-folder-path-part-id> \
    --limit 5
You’ll get a Rich table of top chunks sorted by relevance score. The content column holds the actual text that matched. Try:
# JSON for scripting
kscli chunks search -q "revenue" --parent-path-ids <id> -f json | jq '.[0]'

# Full-text instead of dense semantic
kscli chunks search -q "exact phrase" --search-type full_text --parent-path-ids <id>

# Filter by chunk type
kscli chunks search -q "quarterly results" --chunk-types TABLE --parent-path-ids <id>
7

Browse what got ingested

# Documents in the folder
kscli documents list --parent-path-part-id <tutorial-folder-path-part-id>

# The latest version of a specific document
kscli documents describe <document-id> --format yaml

# All chunks in that version
kscli chunks version-chunk-ids <version-id>
8

Clean up (optional)

kscli documents delete <document-id>
kscli folders delete <folder-id>
kscli logout
kscli logout removes the credentials file. The API key on the server is still valid — revoke it from the dashboard if you’re done with it.

​
Troubleshooting

SymptomLikely causeFix
Not authenticated. Run: kscli login --api-key <key>No credentials fileRun kscli login --api-key ...
Exit code 2, Session expired...Key revoked or invalidCreate a new key in the dashboard and re-login
SSL certificate verification failedSelf-signed backend / corporate proxySet KSCLI_CA_BUNDLE or KSCLI_VERIFY_SSL=false for dev
kscli: command not found after installuv tool bin directory not on PATHRun uv tool update-shell and open a new terminal
Ingestion stuck in runningWorker not picking up taskskscli workflows describe <id> and check backend logs
422 on folders createPassed a folder id where a path_part_id is requiredUse --format yaml on describe to see both

​
PathPart vs domain ID

This is the one conceptual bump newcomers hit. Every folder has two UUIDs:
  • id — the folder’s own 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 update    <folder_id> --name "Renamed"         # id
kscli folders delete    <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.

​
Next steps

Recipes

Bulk ingest, shell scripts, CI pipelines, multi-environment setups

Authentication

Credential storage, TLS, exit codes

Commands

Full reference for every resource and verb

Configuration

Env vars, config file, precedence rules