apunkt/ktx
1
0
Fork 0
mirror of https://github.com/Kaelio/ktx.git synced 2026-06-10 08:05:14 +02:00
Code Issues Projects Releases Packages Wiki Activity

docs(docs-site): normalize CLI references for agents

Browse source
This commit is contained in:
Luca Martial 2026-05-11 16:43:08 -07:00
parent 9580bd243d
commit 885072d2a9
10 changed files with 245 additions and 10 deletions
Download patch file Download diff file Expand all files Collapse all files

24
docs-site/content/docs/cli-reference/ktx-agent.mdx
View file

@ -7,7 +7,7 @@ Hidden commands that provide machine-readable JSON output for coding agents. The
All `ktx agent` subcommands require `--json` and produce structured JSON output on stdout.
## Usage
## Command signature
```bash
ktx agent <subcommand> --json [options]
@ -124,3 +124,25 @@ ktx agent sql execute --json \
--sql-file /tmp/query.sql \
--max-rows 500
```
## Output
Every `ktx agent` command writes JSON to stdout and diagnostic text to stderr. Agents should parse stdout as JSON and treat a non-zero exit code as a failed tool call.
```json
{
"ok": true,
"data": {
"type": "agent-response"
}
}
```
## Common errors
| Error | Cause | Recovery |
|-------|-------|----------|
| Missing JSON output | `--json` was omitted | Re-run the same subcommand with `--json` |
| Unknown connection id | The requested connection is not configured in `ktx.yaml` | Call `ktx agent context --json` or `ktx connection list` to discover valid ids |
| Query file cannot be read | `--query-file` points to a missing or invalid JSON file | Write the query payload to a real file and pass its absolute path |
| SQL execution rejected | SQL is not read-only or `--max-rows` is missing | Use semantic-layer queries first; for direct SQL, pass read-only SQL and an explicit row limit |

27
docs-site/content/docs/cli-reference/ktx-connection.mdx
View file

@ -5,7 +5,7 @@ description: "Add, list, test, and map data sources."
Manage database and source connections in your KTX project. Connections define how KTX reaches your data warehouse, BI tools, and context sources.
## Usage
## Command signature
```bash
ktx connection <subcommand> [options]
@ -147,3 +147,28 @@ ktx connection mapping refresh metabase-prod --auto-accept
# Pick Notion root pages interactively
ktx connection notion pick my-notion
```
## Output
Interactive commands render prompts and status text. Commands with `--json` return machine-readable JSON suitable for scripts and agents.
```json
{
"connections": [
{
"id": "my-warehouse",
"driver": "postgres",
"readonly": false
}
]
}
```
## Common errors
| Error | Cause | Recovery |
|-------|-------|----------|
| Connection test fails | Credentials, network access, database, warehouse, or schema is invalid | Verify the same URL with the database's native client, then rerun `ktx connection add ... --force` |
| Literal credentials rejected | KTX avoids writing raw secrets to `ktx.yaml` by default | Use `env:NAME` or `file:/path/to/secret`; use `--allow-literal-credentials` only for local throwaway projects |
| Mapping validation fails | BI database mappings do not point at valid warehouse connections | Run `ktx connection mapping refresh <connectionId> --auto-accept`, then set invalid mappings explicitly |
| Notion pick cannot run non-interactively | `--no-input` was used without root page or database ids | Pass `--root-page-id`, `--root-database-id`, or `--root-data-source-id` with `--no-input` |

21
docs-site/content/docs/cli-reference/ktx-dev.mdx
View file

@ -5,7 +5,7 @@ description: "Low-level diagnostics, scans, adapter commands, and mapping tools.
Hidden commands for low-level project management, diagnostics, direct adapter control, and shell completion. Most users interact with these through higher-level commands like [`ktx ingest`](/docs/cli-reference/ktx-ingest) and [`ktx setup`](/docs/cli-reference/ktx-setup), but `ktx dev` provides direct access when you need fine-grained control.
## Usage
## Command signature
```bash
ktx dev <subcommand> [options]
@ -145,3 +145,22 @@ ktx dev completion zsh
# Install zsh completions
ktx dev completion zsh --install
```
## Output
`ktx dev` commands are diagnostic and may print plain text, JSON, or visual reports depending on the selected flags.
| Mode | How to request it | Use case |
|------|-------------------|----------|
| Plain text | `--plain` or default diagnostic output | Human-readable terminal inspection |
| JSON | `--json` | Agent parsing and automation |
| Visual report | `--viz` | Interactive memory-flow and ingest debugging |
## Common errors
| Error | Cause | Recovery |
|-------|-------|----------|
| Doctor reports missing runtime pieces | Packages, Python environment, or linked CLI are not ready | Run `pnpm install`, `pnpm run setup:dev`, and `uv sync --all-groups` |
| Ingest run cannot find adapter | `--adapter` does not match a supported source adapter | Use configured source names from `ktx.yaml` or run higher-level `ktx ingest` |
| Replay/report file cannot be read | The report path is wrong or the run id is not stored locally | Run `ktx dev ingest status --json` to discover stored run ids and report files |
| Visual output fails in CI | TUI rendering requires an interactive terminal | Use `--plain --no-input` or `--json --no-input` |

27
docs-site/content/docs/cli-reference/ktx-ingest.mdx
View file

@ -5,7 +5,7 @@ description: "Build and refresh context from configured sources."
Ingest context from your configured sources — dbt, Looker, Metabase, MetricFlow, LookML, or Notion. The ingest process extracts metadata from your tools, then uses an LLM agent to reconcile it with existing context, writing semantic sources and knowledge pages to your project.
## Usage
## Command signature
```bash
ktx ingest [connectionId] [options]
@ -68,3 +68,28 @@ ktx ingest status --json
## Low-level ingest commands
For adapter-level control, use `ktx dev ingest`. See [`ktx dev`](/docs/cli-reference/ktx-dev) for the full low-level ingest surface including `run`, `status`, `watch`, and `replay` with output mode options (`--plain`, `--json`, `--viz`).
## Output
Ingest run commands print progress and create a stored ingest report. `ktx ingest status --json` returns the run state, adapter, connection, and summary information.
```json
{
"runId": "ingest-local-abc123",
"status": "completed",
"connectionId": "dbt-main",
"summary": {
"semanticSourcesChanged": 4,
"knowledgePagesChanged": 2
}
}
```
## Common errors
| Error | Cause | Recovery |
|-------|-------|----------|
| No eligible sources | `ktx.yaml` has no configured context source for ingest | Add a source with `ktx setup` or `ktx connection add`, then rerun ingest |
| Ingest needs credentials | The source adapter requires API or git access | Configure the referenced environment variable or secret file |
| Latest run not found | No ingest run has been started in this project | Run `ktx ingest <connectionId>` or `ktx ingest --all` first |
| Report watch fails in a non-interactive shell | Visual report needs a terminal | Use `ktx ingest status --json` for agent and CI workflows |

26
docs-site/content/docs/cli-reference/ktx-scan.mdx
View file

@ -7,7 +7,7 @@ Discover your database schema — tables, columns, types, constraints, and relat
Scan commands live under `ktx dev scan`. See also the [Building Context](/docs/guides/building-context) guide for a walkthrough.
## Usage
## Command signature
```bash
ktx dev scan <connectionId> [options]
@ -143,3 +143,27 @@ ktx dev scan relationship-calibration --accept-threshold 0.9 --review-threshold
# Get threshold advice based on review decisions
ktx dev scan relationship-thresholds
```
## Output
Scan commands write scan artifacts under the KTX project directory and print status or report summaries. Use `--json` on report and relationship commands when an agent needs structured output.
```json
{
"runId": "scan-local-abc123",
"status": "completed",
"mode": "structural",
"changes": {
"tablesAdded": 42
}
}
```
## Common errors
| Error | Cause | Recovery |
|-------|-------|----------|
| Scan cannot connect | Connection credentials or network access are invalid | Run `ktx connection test <connectionId>` and update the connection before scanning |
| Enriched scan cannot describe columns | LLM credentials are missing or invalid | Complete LLM setup with `ktx setup` before enriched scans |
| Relationship apply writes nothing | No accepted candidates match the provided run id or candidate ids | Inspect `ktx dev scan relationships <runId> --status accepted` first |
| Calibration is not ready | Too few reviewed relationship labels exist | Review and accept/reject more candidates, then rerun calibration |

25
docs-site/content/docs/cli-reference/ktx-serve.mdx
View file

@ -5,7 +5,7 @@ description: "Run the MCP stdio server."
Start a Model Context Protocol (MCP) server that exposes your KTX project's context to coding agents. The server runs over stdio and provides tools for querying semantic sources, searching knowledge, managing connections, and running ingests.
## Usage
## Command signature
```bash
ktx serve --mcp stdio [options]
@ -49,3 +49,26 @@ ktx serve --mcp stdio --project-dir /path/to/my-project
## Agent integration
The MCP server is typically configured through `ktx setup --agents` rather than started manually. See the [Serving Agents](/docs/guides/serving-agents) guide and [Agent Clients](/docs/integrations/agent-clients) integration page for per-tool configuration.
## Output
`ktx serve --mcp stdio` communicates through MCP messages on stdio. It is meant to be launched by an agent client, not read directly by a human terminal session.
```json
{
"command": "ktx",
"args": ["serve", "--mcp", "stdio", "--semantic-compute", "--execute-queries"],
"env": {
"KTX_PROJECT_DIR": "/home/user/analytics"
}
}
```
## Common errors
| Error | Cause | Recovery |
|-------|-------|----------|
| Agent cannot start server | The agent config cannot find the `ktx` binary | Run `pnpm run link:dev` or use an absolute command path in the agent config |
| Semantic tools are unavailable | Server was started without `--semantic-compute` | Add `--semantic-compute` or `--semantic-compute-url` to the server args |
| Query execution is denied | Server was started without `--execute-queries` | Add `--execute-queries` only for trusted projects where read-only execution is intended |
| Context resolves to wrong project | `KTX_PROJECT_DIR` is missing or points elsewhere | Set `KTX_PROJECT_DIR` to the project containing the intended `ktx.yaml` |

26
docs-site/content/docs/cli-reference/ktx-setup.mdx
View file

@ -5,7 +5,7 @@ description: "Set up or resume a local KTX project."
Interactive wizard that walks you through configuring LLM credentials, embeddings, database connections, context sources, and agent integrations. When run without flags in a directory that has no `ktx.yaml`, it launches the full guided flow. When run in an existing project, it resumes from the first incomplete step.
## Usage
## Command signature
```bash
ktx setup [options]
@ -173,3 +173,27 @@ ktx setup context watch
# Run the packaged demo
ktx setup demo
```
## Output
Interactive setup renders prompts and progress messages. `ktx setup status` is the best command for agents because it summarizes readiness in one response.
```text
KTX project: /home/user/analytics
Project ready: yes
LLM ready: yes (claude-sonnet-4-6)
Embeddings ready: yes (text-embedding-3-small)
Primary sources configured: yes (postgres-warehouse)
Context sources configured: yes (dbt-main)
KTX context built: yes
Agent integration ready: yes (codex:project)
```
## Common errors
| Error | Cause | Recovery |
|-------|-------|----------|
| Setup resumes an unexpected project | `KTX_PROJECT_DIR` or nearest `ktx.yaml` points to another directory | Pass `--project-dir <path>` explicitly |
| Health check for model fails | Provider key or model id is invalid | Set the correct environment variable or secret file and rerun setup |
| Setup cannot run in CI | Interactive prompts need a TTY | Use `--yes --no-input` with explicit flags for required values |
| Agent integration missing | Setup skipped the agents step | Run `ktx setup --agents --target <target> --agent-install-mode both` |

27
docs-site/content/docs/cli-reference/ktx-sl.mdx
View file

@ -5,7 +5,7 @@ description: "List, read, validate, query, or write semantic-layer sources."
Interact with your project's semantic layer. Semantic sources are YAML definitions that describe your tables, columns, measures, joins, and grain — the vocabulary agents use to generate correct SQL.
## Usage
## Command signature
```bash
ktx sl <subcommand> [options]
@ -120,3 +120,28 @@ ktx sl query \
--execute \
--max-rows 1000
```
## Output
Semantic-layer commands return human-readable output by default. Use `--json` or `--format json` when an agent needs structured output; use `--format sql` to inspect generated SQL before execution.
```json
{
"sql": "SELECT orders.status, SUM(orders.total_amount) AS total_revenue FROM public.orders GROUP BY orders.status",
"rows": [
{
"orders.status": "completed",
"total_revenue": 125000
}
]
}
```
## Common errors
| Error | Cause | Recovery |
|-------|-------|----------|
| Source not found | Source name or connection id is wrong | Run `ktx sl list --json` and retry with an exact source name and connection id |
| Validation fails | YAML references missing columns, invalid joins, or invalid SQL expressions | Fix the source YAML and rerun `ktx sl validate` |
| Query compile fails | Measure, dimension, filter, or segment name is invalid | Read the source with `ktx sl read`, then retry using declared fields |
| Execution returns too many rows | `--max-rows` is missing or too high | Add `--max-rows` with a bounded value before executing |

25
docs-site/content/docs/cli-reference/ktx-status.mdx
View file

@ -5,7 +5,7 @@ description: "Show current project status."
Print the current setup status of your KTX project — which steps are complete, which need attention, and whether the project is ready for agents.
## Usage
## Command signature
```bash
ktx status [options]
@ -26,3 +26,26 @@ ktx status
# Get status as JSON (useful for scripting)
ktx status --json
```
## Output
`ktx status` prints readiness for each setup area. Agents should use `ktx status --json` when they need to branch on readiness state.
```json
{
"projectReady": true,
"llmReady": true,
"embeddingsReady": true,
"primarySourcesConfigured": true,
"contextBuilt": true,
"agentIntegrationReady": true
}
```
## Common errors
| Error | Cause | Recovery |
|-------|-------|----------|
| No KTX project found | Current directory has no `ktx.yaml` and `KTX_PROJECT_DIR` is unset | Run from a KTX project or set `KTX_PROJECT_DIR` |
| Project ready is false | One or more setup steps are incomplete | Run `ktx setup` to resume setup |
| Agent integration ready is false | No agent target has been installed | Run `ktx setup --agents --target <target>` |

27
docs-site/content/docs/cli-reference/ktx-wiki.mdx
View file

@ -5,7 +5,7 @@ description: "List, read, search, or write knowledge pages."
Manage knowledge pages in your KTX project. Knowledge pages are Markdown documents that capture business definitions, rules, and gotchas. Agents search them for context when answering questions about your data.
## Usage
## Command signature
```bash
ktx wiki <subcommand> [options]
@ -90,3 +90,28 @@ ktx wiki write data-freshness \
--content "The orders table refreshes every 15 minutes..." \
--ref "https://wiki.example.com/data-pipelines"
```
## Output
Wiki commands print local knowledge pages and search results. Agents should search first, then read the most relevant page by key.
```json
{
"results": [
{
"key": "revenue-definitions",
"summary": "Canonical revenue metric definitions",
"score": 0.92
}
]
}
```
## Common errors
| Error | Cause | Recovery |
|-------|-------|----------|
| Search returns no results | The query terms do not match summaries, tags, or content | Retry with business synonyms, then create a page if the knowledge is missing |
| Read fails for a key | The page key is wrong or scoped to a different user | Run `ktx wiki list` or search again to get the exact key |
| Write fails due to missing fields | `--summary` or `--content` was omitted | Pass both fields, and keep the summary short enough for search results |
| Agent writes duplicate pages | It did not search existing pages first | Always run `ktx wiki search` before `ktx wiki write` |