> ## 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

> The Knowledge Stack command line — ingest documents, run semantic search, and manage folders without leaving your terminal.

<Frame caption="▶ Watch the 45-second demo — from uv tool install to semantic search">
  <a href="https://docs.knowledgestack.ai/kscli/demo">
    <img src="https://docs.knowledgestack.ai/assets/kscli/hero-poster.png" alt="kscli 45-second demo — click to play" />
  </a>
</Frame>

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

```bash theme={null}
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

<CardGroup cols={2}>
  <Card title="Quickstart" icon="rocket" href="/cli/quickstart">
    Zero to first semantic search in under two minutes. Includes dashboard screenshots for API key creation.
  </Card>

  <Card title="Authentication" icon="key" href="/cli/authentication">
    How to create an API key, how `kscli login` stores it, TLS, and exit codes.
  </Card>

  <Card title="Commands" icon="terminal" href="/cli/commands">
    Full reference for every resource group and verb — folders, documents, chunks, tags, workflows, threads, and more.
  </Card>

  <Card title="Recipes" icon="book" href="/cli/recipes">
    Bulk ingest, shell scripts, CI pipelines, pipe-into-jq tricks, multi-environment setups.
  </Card>
</CardGroup>

## Install

Requires **Python 3.12+** and [uv](https://docs.astral.sh/uv/).

<Tabs>
  <Tab title="uv (recommended)">
    ```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`.
  </Tab>

  <Tab title="pipx">
    ```bash theme={null}
    pipx install kscli
    ```
  </Tab>

  <Tab title="pip">
    ```bash theme={null}
    pip install kscli
    ```
  </Tab>

  <Tab title="From source">
    ```bash theme={null}
    git clone https://github.com/knowledgestack/ks-cli.git
    cd ks-cli
    uv sync --all-extras --group dev
    ```
  </Tab>
</Tabs>

## Get an API key in 60 seconds

<Steps>
  <Step title="Open the dashboard">
    Go to [app.knowledgestack.ai](https://app.knowledgestack.ai) and sign in. New users can sign up with email/password or Google SSO.
  </Step>

  <Step title="Open My Account → API Keys">
    Click your avatar (top-right) → **My Account** → **API Keys** tab.
  </Step>

  <Step title="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-`.
  </Step>

  <Step title="Log in from the terminal">
    ```bash theme={null}
    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`.
  </Step>

  <Step title="Verify">
    ```bash theme={null}
    kscli whoami
    ```
  </Step>
</Steps>

<Note>
  Revoke a key at any time from the same dashboard page. See [Authentication](/cli/authentication) for the full auth model and TLS options.
</Note>

## Two-minute quickstart

```bash theme={null}
# 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
```

<Card title="Full walkthrough →" icon="arrow-right" href="/cli/quickstart">
  Step-by-step quickstart with embedded screencasts for each step.
</Card>

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

```bash theme={null}
# 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

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

  ```bash theme={null}
  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.
</Warning>

## 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:

```bash theme={null}
kscli --base-url http://localhost:8000 folders list
```

Full reference: [Configuration](/cli/configuration).

## Where to next

<CardGroup cols={2}>
  <Card title="Quickstart →" icon="rocket" href="/cli/quickstart">
    Step-by-step with screenshots
  </Card>

  <Card title="Authentication →" icon="key" href="/cli/authentication">
    API keys, credential storage, TLS
  </Card>

  <Card title="Commands →" icon="terminal" href="/cli/commands">
    Every resource and verb
  </Card>

  <Card title="Configuration →" icon="gear" href="/cli/configuration">
    Env vars and precedence
  </Card>

  <Card title="Recipes →" icon="book" href="/cli/recipes">
    Bulk ingest, CI, scripting tricks
  </Card>

  <Card title="GitHub →" icon="github" href="https://github.com/knowledgestack/ks-cli">
    Source, issues, releases
  </Card>
</CardGroup>