mirror of
https://github.com/Kaelio/ktx.git
synced 2026-06-07 07:55:13 +02:00
698efdcef8
* feat(cli): show cached update notices after commands * docs(cli): describe update notices * fix(cli): type update check environment * fix(cli): decouple update notice display from refresh and harden suppression Display a cached "update available" notice based solely on the lastNoticeAt 24h throttle, independent of checkedAt refresh freshness, matching the design's independent display/refresh decisions. Suppress the check unconditionally under --json, CI, and non-TTY before consulting output-mode preferences, so a KTX_OUTPUT=pretty override can no longer make CI/non-TTY contexts phone npm.
150 lines
3.4 KiB
Text
150 lines
3.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. |
|
|
|
|
## 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:
|
|
|
|
```text
|
|
↑ Update available: ktx 0.9.0 → 0.10.0
|
|
npm i -g @kaelio/ktx
|
|
```
|
|
|
|
Stable installs compare against the npm `latest` dist-tag.
|
|
Release-candidate installs compare against the `next` dist-tag and show:
|
|
|
|
```text
|
|
npm i -g @kaelio/ktx@next
|
|
```
|
|
|
|
The check is skipped for JSON output, CI, non-TTY stdout, and hidden completion
|
|
commands. To opt out explicitly, set any of these environment variables:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
pnpm add -g @kaelio/ktx
|
|
yarn global add @kaelio/ktx
|
|
```
|
|
|
|
## 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
|
|
```
|