ktx/docs-site/content/docs/cli-reference/ktx-wiki.mdx

---
title: "ktx wiki"
description: "List, search, or read wiki pages."
---

List, search, and read wiki pages in your **ktx** project. Wiki pages are
Markdown documents that capture business definitions, rules, and gotchas.
Agents search them for context when answering questions about your data.

## Command signature

```bash
ktx wiki [options] [query...]  # list (bare) or search (with query)
ktx wiki read <key>
```

- Bare `ktx wiki` lists local wiki pages.
- `ktx wiki <query...>` searches local wiki pages. Multi-word queries are
  joined with a space.
- `ktx wiki read <key>` prints the whole Markdown file for one wiki page,
  including YAML frontmatter.

Edit the Markdown files under `wiki/` directly, or ingest source content with
`ktx ingest`, when you need to add or update wiki knowledge.

## Options

| Flag | Description | Default |
|------|-------------|---------|
| `--user-id <id>` | Local user id | `local` |
| `--limit <number>` | Maximum search results (search mode only) | - |
| `--output <mode>` | Output mode: `pretty` (default in TTY), `plain` (TSV), or `json` | `pretty` |
| `--json` | Shortcut for `--output=json` (overrides `--output`) | `false` |

`ktx wiki <query>` uses hybrid search when `storage.search` is `sqlite-fts5`.
**ktx** combines lexical SQLite FTS5 matches, token matches, and semantic matches
from wiki page embeddings stored in `.ktx/db.sqlite`. If embeddings are not
configured or the embedding backend is unavailable, **ktx** skips the semantic lane
and keeps lexical and token results.

## Examples

```bash
# List all wiki pages
ktx wiki

# List all wiki pages as JSON
ktx wiki --json

# Search wiki pages
ktx wiki "monthly recurring revenue"

# Search wiki pages as JSON
ktx wiki "monthly recurring revenue" --json --limit 10

# Print the exact Markdown file for a known page key
ktx wiki read revenue-definitions

# Print search results as TSV
ktx wiki "monthly recurring revenue" --output plain

# Inspect which search lanes were used
ktx --debug wiki "monthly recurring revenue" --json
```

## Output

Wiki commands print clack-style pretty output in a TTY and TSV-style plain
output when requested. JSON output wraps the items with a command metadata
envelope. Search results include `matchReasons` and `lanes` metadata so you can
see whether lexical, token, or semantic search contributed to the ranking. Use
`ktx wiki read <key>` when you need the full page contents. Read output is the
exact Markdown file stored on disk, including YAML frontmatter, and is not
wrapped in pretty, plain, or JSON formatting.
Pretty search output shows `#1`, `#2`, and later rank badges for the displayed
results. Plain and JSON output keep the raw `score` value, which is a ranking
score rather than a percentage.

```json
{
  "kind": "list",
  "data": {
    "items": [
      {
        "key": "revenue-definitions",
        "summary": "Canonical revenue metric definitions",
        "score": 0.92,
        "matchReasons": ["lexical", "semantic"],
        "lanes": [
          {
            "lane": "lexical",
            "status": "available",
            "requestedCandidatePoolLimit": 25,
            "effectiveCandidatePoolLimit": 25,
            "returnedCandidateCount": 3,
            "weight": 1.5
          },
          {
            "lane": "semantic",
            "status": "available",
            "requestedCandidatePoolLimit": 25,
            "effectiveCandidatePoolLimit": 25,
            "returnedCandidateCount": 8,
            "weight": 3
          }
        ]
      }
    ]
  },
  "meta": {
    "command": "wiki search"
  }
}
```

When you pass the global `--debug` flag, **ktx** writes search diagnostics to
stderr and leaves stdout unchanged. This is useful with `--json` because stdout
stays machine-readable:

```text
[debug] wiki search mode=sqlite-fts5 embedding=configured results=2
[debug] wiki search lane=lexical status=available returned=1 weight=1.5
[debug] wiki search lane=token status=available returned=1 weight=0.75
[debug] wiki search lane=semantic status=available returned=2 weight=3
```

## Common errors

| Error | Cause | Recovery |
|-------|-------|----------|
| Search returns no results | The query terms do not match summaries, tags, or content, and the semantic lane is unavailable or has no positive matches | Run with `--debug`, check the semantic lane status, retry with business synonyms, then create a page if the knowledge is missing |
| A page is missing | No Markdown file exists for that business context or `ktx wiki read <key>` used the wrong key | Run `ktx wiki <query>` to find the page key, then retry `ktx wiki read <key>` |