---
title: Knowledge and RAG
description: Manage knowledge sources, search the index, reindex folders, and seed assistant documentation from the CLI.
---

The CLI exposes two complementary surfaces for retrieval-augmented generation:

- **`knowledge`** — source lifecycle (list, add, remove, reindex, status) plus workspace search.
- **`rag`** — agent-facing retrieval and ingestion helpers (`search`, `ingest`, `status`).

Both commands call the sidecar. Loader credentials are **never** passed on the command line — provision secrets with `vault put` or `secrets set` first, then reference a `location` when adding a source.

## Prerequisites

```bash
akos serve          # local sidecar (or point AKOS_HEADLESS_URL at a remote sidecar)
akos knowledge list
```

## Manage sources

### List sources

```bash
akos knowledge list
akos knowledge list --json
```

### Add a source

```bash
# Local folder
akos knowledge add my-docs ./docs/product

# Remote kinds (credentials resolved server-side)
akos knowledge add handbook https://example.com/docs --kind url --name "Product handbook"
akos knowledge add repo-docs github:org/repo --kind github
```

| Flag | Description |
|---|---|
| `--kind` | `folder`, `url`, `s3`, `notion`, `drive`, or `github` (default: `folder`) |
| `--name` | Display name (defaults to the source id) |
| `--json` | Emit the created source as JSON |

### Remove a source

```bash
akos knowledge remove my-docs
```

Drops the source and its index.

### Reindex

```bash
akos knowledge reindex my-docs
# alias:
akos knowledge rebuild my-docs
```

Queues a full digest rebuild for one source.

### Indexer status

```bash
akos knowledge status
akos knowledge status --json
```

## Search

Search the workspace index (alias: `query`):

```bash
akos knowledge search "how do I configure egress"
akos knowledge search "onboarding checklist" --source my-docs --top-k 10 --json
```

The companion `rag` command exposes the same retrieval path for automation:

```bash
akos rag search "sandbox policy" --top-k 5 --json
akos rag ingest my-docs
akos rag status --json
```

Use `knowledge` when managing sources; use `rag` when scripting retrieval inside agent tooling.

## Seed assistant documentation (operators)

To index the shipped documentation corpus so the in-app assistant can retrieve repo docs (beyond the always-on contract catalog), use the ledgered production seed:

```bash
# Preview what would be registered
akos prod seed --target assistant-knowledge --dry-run

# Apply folder sources + record the seed ledger
akos prod seed --target assistant-knowledge --apply

# Rebuild indexes after apply
akos knowledge reindex assistant-knowledge-for-agents
akos knowledge reindex assistant-knowledge-user-docs
```

| Flag | Description |
|---|---|
| `--dry-run` | Report planned/missing/stale seed entries without writing |
| `--apply` | Apply missing or stale seeds and update the ledger |
| `--force` | With `--apply`, re-apply even when checksums already match |
| `--target` | `demo` (default) or `assistant-knowledge` |
| `--vertical` | Limit demo seeds to one vertical pack |
| `--base-dir` | Override the packs directory |

Until rebuild completes, fumadocs pages are not in assistant RAG folder search — the contract catalog in the system prompt is always on.

## Demo vertical packs

Materialise demo pack fixtures into sidecar stores (development / sales demos):

```bash
akos seed --vertical coding
akos prod seed --target demo --dry-run
akos prod seed --target demo --apply --vertical finance
```

Set `AKOS_DEMO_PACKS=1` in the sidecar environment when demo packs are gated in your deployment.

## Related topics

- **[Knowledge in the app](/docs/using-the-app/knowledge)** — UI for sources and flow RAG nodes.
- **[Integration setup](/docs/using-the-app/integration-setup)** — OAuth providers for Notion/Drive/GitHub sources.
- **[Authentication](/docs/cli/authentication)** — `vault put` and `secrets set` for loader credentials.
- **[Command reference](/docs/cli/command-reference)** — full `knowledge` / `rag` / `prod seed` tables.