ktx
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
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:
ktx --help ktx setup --help ktx ingest --help
Command map
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. |
Update notices
Note: The update notifier writes only to stderr and keeps command stdout unchanged.
When a newer package is available on your installed release channel, ktx
prints a short notice after the command finishes:
↑ Update available: ktx 0.9.0 → 0.10.0
npm i -g @kaelio/ktxStable installs compare against the npm latest dist-tag.
Release-candidate installs compare against the next dist-tag and show:
npm i -g @kaelio/ktx@nextThe check is skipped for JSON output, CI, non-TTY stdout, and hidden completion commands. To opt out explicitly, set any of these environment variables:
KTX_NO_UPDATE_CHECK=1 NO_UPDATE_NOTIFIER=1 DO_NOT_TRACK=1
The ktx CLI prints one npm command because globally installed binaries don't
expose a reliable runtime package-manager signal. If you prefer another global
package manager, use the equivalent command:
pnpm add -g @kaelio/ktx yarn global add @kaelio/ktx
Build-view star prompt
During an interactive context build, ktx setup and ktx ingest can show a dim
GitHub star reminder above the Ctrl+C to stop hint. ktx skips this prompt
for CI, non-TTY output, and DO_NOT_TRACK=1.
To suppress only this prompt while keeping other notices enabled, set:
KTX_NO_STAR=1
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
# 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