Skip to main content
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 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
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:
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.
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.
Create a dedicated subfolder for this tutorial:
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:
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:
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
You’ll get a Rich table of top chunks sorted by relevance score. The content column holds the actual text that matched. Try:
7

Browse what got ingested

8

Clean up (optional)

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

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