mirror of
https://github.com/Kaelio/ktx.git
synced 2026-06-07 07:55:13 +02:00
d320d54ab2
* feat(completion): complete known argument values
* fix(completion): hide Commander-hidden subcommands from completions
Replace the `__`-prefix name heuristic with Commander's `_hidden` flag so
internal subcommands registered with { hidden: true } (e.g. `mcp serve-internal`)
are excluded from completions, mirroring `ktx --help`.
* test: cover wiki and sl read command routing
* test: cover raw wiki and sl reads
* feat: add wiki read command
* feat: add sl read command
* feat: complete read command entity names
* docs: document wiki and sl read commands
* test: include read commands in command tree
* feat(sl): read and validate unique sources by name
* feat(sl): make read and validate connection id optional
* fix(completion): dedupe semantic source names
* docs(sl): document connection-optional read and validate
* fix(sl): require connection id for query command
* docs(sl): clarify query connection requirement
* fix(completion): don't resolve option values as subcommands
resolveCommand skipped flag tokens but not the value consumed by a
value-taking option in the `--flag value` form, so a connection id like
`query` was matched as the `sl query` subcommand and yielded no `sl`
completions. Track value-taking options and skip their consumed value
before matching subcommands.
* test(telemetry): assert first-run notice via TELEMETRY_NOTICE constant
CI (which tests this branch merged with main) failed because #243 changed
the first-run notice wording in identity.ts (dropped "anonymous") but left
this test grepping for the old literal 'ktx collects anonymous usage data',
so indexOf returned -1. Assert against the exported TELEMETRY_NOTICE
constant instead so the test tracks the source of truth and cannot drift
when the notice text changes again.
112 lines
2.4 KiB
Text
112 lines
2.4 KiB
Text
---
|
|
title: "ktx"
|
|
description: "Root command map, global options, and project resolution for the ktx CLI."
|
|
---
|
|
|
|
The `ktx` CLI sets up local projects, builds agent-ready context, checks
|
|
connections, queries semantic sources, searches wiki pages, runs the MCP
|
|
server, and manages the bundled Python runtime.
|
|
|
|
## Command signature
|
|
|
|
```bash
|
|
ktx [global-options] <command>
|
|
```
|
|
|
|
When you run bare `ktx` in an interactive terminal outside any **ktx** project, the
|
|
CLI starts the same guided setup flow as `ktx setup`. Inside an existing
|
|
project, use command-specific help:
|
|
|
|
```bash
|
|
ktx --help
|
|
ktx setup --help
|
|
ktx ingest --help
|
|
```
|
|
|
|
## Command map
|
|
|
|
```text
|
|
ktx
|
|
setup
|
|
connection
|
|
list
|
|
test [connectionId]
|
|
ingest [connectionId]
|
|
text [files...]
|
|
wiki
|
|
list
|
|
search <query>
|
|
read <key>
|
|
sl
|
|
list
|
|
search <query>
|
|
read <sourceName>
|
|
validate <sourceName>
|
|
query
|
|
sql
|
|
status
|
|
mcp
|
|
start
|
|
stop
|
|
status
|
|
logs
|
|
admin
|
|
init [directory]
|
|
schema
|
|
runtime
|
|
install
|
|
start
|
|
stop
|
|
status
|
|
reindex
|
|
completion <shell>
|
|
```
|
|
|
|
The public context-build entrypoint is `ktx ingest [connectionId]` or
|
|
`ktx ingest --all`.
|
|
|
|
## Global options
|
|
|
|
| Flag | Description |
|
|
|------|-------------|
|
|
| `--project-dir <path>` | **ktx** project directory. Defaults to `KTX_PROJECT_DIR`, then the nearest `ktx.yaml`, then the current working directory. |
|
|
| `--debug` | Print diagnostic dispatch and project-resolution details to stderr. |
|
|
| `-v`, `--version` | Show the CLI package name and version. |
|
|
| `-h`, `--help` | Show help for the current command. |
|
|
|
|
## Project resolution
|
|
|
|
Most commands are project-aware. Pass `--project-dir <path>` when scripting or
|
|
when you are outside the project directory. If you omit it, **ktx** checks
|
|
`KTX_PROJECT_DIR`, then walks upward for the nearest `ktx.yaml`, then falls back
|
|
to the current directory.
|
|
|
|
## Common workflows
|
|
|
|
```bash
|
|
# Start or resume setup
|
|
ktx setup
|
|
|
|
# Check readiness
|
|
ktx status
|
|
|
|
# Build one configured connection
|
|
ktx ingest warehouse
|
|
|
|
# Build every configured connection
|
|
ktx ingest
|
|
|
|
# Search semantic sources and wiki pages
|
|
ktx sl "revenue"
|
|
ktx wiki "revenue recognition"
|
|
|
|
# Print a known wiki page or semantic source
|
|
ktx wiki read revenue-definitions
|
|
ktx sl --connection-id warehouse read orders
|
|
|
|
# Execute read-only SQL
|
|
ktx sql --connection warehouse "select count(*) from public.orders"
|
|
|
|
# Start the local MCP server for agent clients
|
|
ktx mcp start
|
|
```
|