mirror of
https://github.com/Kaelio/ktx.git
synced 2026-06-19 08:28:06 +02:00
feat(cli): clean up command surface
This commit is contained in:
Andrey Avtomonov
parent
60457e9407
commit
e15a4ebaec
61 changed files with 406 additions and 2076 deletions
|
|
@ -16,8 +16,7 @@ ktx dev <subcommand> [options]
|
|||
| Subcommand | Description |
|
||||
|-----------|-------------|
|
||||
| `init [directory]` | Initialize a Git-backed KTX project directory |
|
||||
| `doctor` | Check KTX setup, project, and demo readiness |
|
||||
| `doctor setup` | Check KTX install, build, and local runtime readiness |
|
||||
| `runtime` | Install, inspect, and prune the KTX-managed Python runtime |
|
||||
| `scan` | Run or inspect standalone connection scans |
|
||||
| `ingest run` | Run local ingest for one configured connection and source adapter |
|
||||
| `ingest status [runId]` | Print status for a stored local ingest run |
|
||||
|
|
@ -35,19 +34,14 @@ ktx dev <subcommand> [options]
|
|||
| `--name <name>` | Project name written to `ktx.yaml` | — |
|
||||
| `--force` | Rewrite `ktx.yaml` and scaffold files in an existing project | `false` |
|
||||
|
||||
### `dev doctor`
|
||||
### `dev runtime`
|
||||
|
||||
| Flag | Description | Default |
|
||||
|------|-------------|---------|
|
||||
| `--feature <feature>` | Runtime feature level for `install` and `start` (`core` or `local-embeddings`) | `core` |
|
||||
| `--json` | Print JSON output | `false` |
|
||||
| `--no-input` | Disable interactive terminal input | — |
|
||||
|
||||
### `dev doctor setup`
|
||||
|
||||
| Flag | Description | Default |
|
||||
|------|-------------|---------|
|
||||
| `--json` | Print JSON output | `false` |
|
||||
| `--no-input` | Disable interactive terminal input | — |
|
||||
| `--yes` | Confirm runtime install or prune actions where supported | `false` |
|
||||
| `--force` | Reinstall or restart where supported | `false` |
|
||||
|
||||
### `dev scan`
|
||||
|
||||
|
|
@ -115,11 +109,11 @@ ktx dev init ./my-project --name "Analytics Context"
|
|||
# Re-initialize an existing project
|
||||
ktx dev init --force
|
||||
|
||||
# Check project readiness
|
||||
ktx dev doctor
|
||||
# Check managed Python runtime readiness
|
||||
ktx dev runtime doctor
|
||||
|
||||
# Check CLI install readiness
|
||||
ktx dev doctor setup
|
||||
# Start the managed Python daemon
|
||||
ktx dev runtime start
|
||||
|
||||
# Run a low-level ingest with a specific adapter
|
||||
ktx dev ingest run --connection-id my-dbt --adapter dbt
|
||||
|
|
|
|||
|
|
@ -1,74 +0,0 @@
|
|||
---
|
||||
title: "ktx serve"
|
||||
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.
|
||||
|
||||
## Command signature
|
||||
|
||||
```bash
|
||||
ktx serve --mcp stdio [options]
|
||||
```
|
||||
|
||||
## Options
|
||||
|
||||
| Flag | Description | Default |
|
||||
|------|-------------|---------|
|
||||
| `--mcp <mode>` | MCP transport mode (required; only `stdio` is supported) | — |
|
||||
| `--user-id <id>` | Local user id | `local` |
|
||||
| `--semantic-compute` | Enable semantic-layer compute | `false` |
|
||||
| `--semantic-compute-url <url>` | HTTP semantic-layer compute URL | — |
|
||||
| `--database-introspection-url <url>` | Daemon URL for live-database introspection | — |
|
||||
| `--execute-queries` | Allow semantic-layer query execution (requires `--semantic-compute`) | `false` |
|
||||
| `--memory-capture` | Enable memory capture | `false` |
|
||||
| `--memory-model <model>` | Memory capture model | — |
|
||||
|
||||
## Examples
|
||||
|
||||
```bash
|
||||
# Start the MCP server over stdio
|
||||
ktx serve --mcp stdio
|
||||
|
||||
# Start with semantic-layer compute enabled
|
||||
ktx serve --mcp stdio --semantic-compute
|
||||
|
||||
# Start with query execution enabled
|
||||
ktx serve --mcp stdio --semantic-compute --execute-queries
|
||||
|
||||
# Start with a remote semantic compute backend
|
||||
ktx serve --mcp stdio --semantic-compute-url http://localhost:8080
|
||||
|
||||
# Start with memory capture
|
||||
ktx serve --mcp stdio --memory-capture
|
||||
|
||||
# Use a specific project directory
|
||||
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 | Install `@kaelio/ktx` globally with `npm install -g @kaelio/ktx` 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` |
|
||||
|
|
@ -49,7 +49,6 @@ ktx setup [options]
|
|||
| `--agents` | Install agent integration only | `false` |
|
||||
| `--target <target>` | Agent target (`claude-code`, `codex`, `cursor`, `opencode`, `universal`) | — |
|
||||
| `--agent-scope <scope>` | Agent install scope (`project` or `global`) | `project` |
|
||||
| `--agent-install-mode <mode>` | Agent install mode (`cli`, `mcp`, or `both`) | `cli` |
|
||||
| `--project` | Install agent integration into the project scope | `false` |
|
||||
| `--global` | Install agent integration into the global target scope (Claude Code and Codex only) | `false` |
|
||||
| `--skip-agents` | Leave agent integration incomplete for now | `false` |
|
||||
|
|
@ -196,4 +195,4 @@ Agent integration ready: yes (codex:project)
|
|||
| 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` |
|
||||
| Agent integration missing | Setup skipped the agents step | Run `ktx setup --agents --target <target>` |
|
||||
|
|
|
|||
|
|
@ -1,9 +1,11 @@
|
|||
---
|
||||
title: "ktx status"
|
||||
description: "Show current project status."
|
||||
description: "Check KTX setup and project readiness."
|
||||
---
|
||||
|
||||
Print the current setup status of your KTX project — which steps are complete, which need attention, and whether the project is ready for agents.
|
||||
Run the KTX readiness doctor. Inside a KTX project, this checks setup,
|
||||
project configuration, semantic search, connections, and related diagnostics.
|
||||
Outside a project, it checks local CLI setup readiness.
|
||||
|
||||
## Command signature
|
||||
|
||||
|
|
@ -16,6 +18,7 @@ ktx status [options]
|
|||
| Flag | Description | Default |
|
||||
|------|-------------|---------|
|
||||
| `--json` | Print JSON output | `false` |
|
||||
| `--no-input` | Disable interactive terminal input | — |
|
||||
|
||||
## Examples
|
||||
|
||||
|
|
@ -23,22 +26,26 @@ ktx status [options]
|
|||
# Show project status
|
||||
ktx status
|
||||
|
||||
# Get status as JSON (useful for scripting)
|
||||
ktx status --json
|
||||
# Get status as JSON without interactive input
|
||||
ktx status --json --no-input
|
||||
```
|
||||
|
||||
## Output
|
||||
|
||||
`ktx status` prints readiness for each setup area. Agents should use `ktx status --json` when they need to branch on readiness state.
|
||||
`ktx status` prints doctor checks. Agents should use `ktx status --json --no-input`
|
||||
when they need to branch on readiness state.
|
||||
|
||||
```json
|
||||
{
|
||||
"projectReady": true,
|
||||
"llmReady": true,
|
||||
"embeddingsReady": true,
|
||||
"primarySourcesConfigured": true,
|
||||
"contextBuilt": true,
|
||||
"agentIntegrationReady": true
|
||||
"title": "KTX project doctor",
|
||||
"checks": [
|
||||
{
|
||||
"id": "project-config",
|
||||
"label": "Project config",
|
||||
"status": "pass",
|
||||
"detail": "warehouse"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
|
|
@ -46,6 +53,6 @@ ktx status --json
|
|||
|
||||
| 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>` |
|
||||
| No KTX project found | Current directory has no `ktx.yaml` and `KTX_PROJECT_DIR` is unset | `ktx status` runs setup checks; run from a KTX project or set `KTX_PROJECT_DIR` for project checks |
|
||||
| Project config check fails | The project directory is missing or has an invalid `ktx.yaml` | Run `ktx setup` to resume setup |
|
||||
| Semantic search check warns | Embeddings are not configured or the provider probe failed | Run `ktx setup` or inspect the check's `fix` field in JSON output |
|
||||
|
|
|
|||
|
|
@ -8,7 +8,6 @@
|
|||
"ktx-ingest",
|
||||
"ktx-sl",
|
||||
"ktx-wiki",
|
||||
"ktx-serve",
|
||||
"ktx-status",
|
||||
"ktx-agent",
|
||||
"ktx-dev"
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue