> ## 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 Quickstart
> Go from nothing installed to a working semantic search against your own documents in about two minutes.
Every command below is real. Copy, paste, substitute the placeholder IDs.
## Prerequisites
* Python **3.12+** (`python --version`)
* [**uv**](https://docs.astral.sh/uv/) installed (`uv --version`). On macOS: `brew install uv`.
* A Knowledge Stack account at [app.knowledgestack.ai](https://app.knowledgestack.ai) — sign up with email/password or Google SSO.
## The happy path
```bash theme={null}
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`.
1. Open [app.knowledgestack.ai](https://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.
```bash theme={null}
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:
```bash theme={null}
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.
Every document lives under a folder. Every tenant has a root folder; you can create subfolders.
```bash theme={null}
# 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.
```bash theme={null}
kscli folders describe --format yaml
```
Create a dedicated subfolder for this tutorial:
```bash theme={null}
kscli folders create \
--name "kscli tutorial" \
--parent-path-part-id
```
Save the `path_part_id` from the response — the next step needs it.
Grab any PDF from your Downloads folder and upload it:
```bash theme={null}
kscli documents ingest \
--file ~/Downloads/some-report.pdf \
--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:
```bash theme={null}
kscli workflows list --limit 5
kscli workflows describe
```
When the workflow is `completed`, the document is fully indexed and searchable. Small PDFs take seconds; large ones take a minute or two.
```bash theme={null}
kscli chunks search \
--query "what does the document say about revenue" \
--parent-path-ids \
--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:
```bash theme={null}
# JSON for scripting
kscli chunks search -q "revenue" --parent-path-ids -f json | jq '.[0]'
# Full-text instead of dense semantic
kscli chunks search -q "exact phrase" --search-type full_text --parent-path-ids
# Filter by chunk type
kscli chunks search -q "quarterly results" --chunk-types TABLE --parent-path-ids
```
```bash theme={null}
# Documents in the folder
kscli documents list --parent-path-part-id
# The latest version of a specific document
kscli documents describe --format yaml
# All chunks in that version
kscli chunks version-chunk-ids
```
```bash theme={null}
kscli documents delete
kscli folders delete
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
| Symptom | Likely cause | Fix |
| ----------------------------------------------------- | ------------------------------------------------------- | --------------------------------------------------------- |
| `Not authenticated. Run: kscli login --api-key ` | No credentials file | Run `kscli login --api-key ...` |
| Exit code `2`, `Session expired...` | Key revoked or invalid | Create a new key in the dashboard and re-login |
| `SSL certificate verification failed` | Self-signed backend / corporate proxy | Set `KSCLI_CA_BUNDLE` or `KSCLI_VERIFY_SSL=false` for dev |
| `kscli: command not found` after install | `uv tool` bin directory not on `PATH` | Run `uv tool update-shell` and open a new terminal |
| Ingestion stuck in `running` | Worker not picking up tasks | `kscli workflows describe ` and check backend logs |
| `422` on `folders create` | Passed a folder `id` where a `path_part_id` is required | Use `--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.
```bash theme={null}
kscli folders describe # id
kscli folders update --name "Renamed" # id
kscli folders delete # id
kscli folders create --parent-path-part-id # path_part_id
kscli documents ingest --path-part-id # path_part_id
kscli chunks search --parent-path-ids # path_part_id
```
`kscli folders describe ... --format yaml` prints both so you can copy the right one.
## Next steps
Bulk ingest, shell scripts, CI pipelines, multi-environment setups
Credential storage, TLS, exit codes
Full reference for every resource and verb
Env vars, config file, precedence rules