mirror of
https://github.com/Kaelio/ktx.git
synced 2026-06-07 07:55:13 +02:00
c2750dd797
Hide advanced/internal `ktx setup` options from --help output using .hideHelp() so the command surface is approachable for new users. Remove the --project, --agent-scope, and --skip-initial-source-ingest flags that are no longer needed. Update docs and tests to match. Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
78 lines
2.7 KiB
Text
78 lines
2.7 KiB
Text
---
|
|
title: "ktx setup"
|
|
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.
|
|
|
|
## Command signature
|
|
|
|
```bash
|
|
ktx setup [options]
|
|
```
|
|
|
|
## Options
|
|
|
|
### General
|
|
|
|
| Flag | Description | Default |
|
|
|------|-------------|---------|
|
|
| `--project-dir <path>` | KTX project directory | `KTX_PROJECT_DIR`, nearest `ktx.yaml`, or cwd |
|
|
| `--yes` | Accept safe defaults in non-interactive setup | `false` |
|
|
| `--no-input` | Disable interactive terminal input | — |
|
|
|
|
### Agent Integration
|
|
|
|
| Flag | Description | Default |
|
|
|------|-------------|---------|
|
|
| `--agents` | Install agent integration only | `false` |
|
|
| `--target <target>` | Agent target (`claude-code`, `codex`, `cursor`, `opencode`, `universal`) | — |
|
|
| `--global` | Install agent integration into the global target scope (Claude Code and Codex only) | `false` |
|
|
|
|
The setup wizard is the public configuration interface. It prompts for LLM
|
|
credentials, embeddings, database connections, context sources, Historic SQL,
|
|
and agent integration when those values are needed.
|
|
|
|
## Examples
|
|
|
|
```bash
|
|
# Run the interactive setup wizard
|
|
ktx setup
|
|
|
|
# Run setup for a specific project directory
|
|
ktx setup --project-dir ./analytics
|
|
|
|
# Install agent integration for Claude Code only
|
|
ktx setup --agents --target claude-code
|
|
|
|
# Install agent integration globally for Codex
|
|
ktx setup --agents --target codex --global
|
|
|
|
# Check setup readiness
|
|
ktx status
|
|
```
|
|
|
|
## Output
|
|
|
|
Interactive setup renders prompts and progress messages. Use `ktx status` to
|
|
check setup and context readiness after setup exits.
|
|
|
|
```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 | Run setup interactively before CI, or provide a fixture `ktx.yaml` for automated tests |
|
|
| Agent integration missing | Setup skipped the agents step | Run `ktx setup --agents --target <target>` |
|