mirror of
https://github.com/Kaelio/ktx.git
synced 2026-06-07 07:55:13 +02:00
Revise CLI reference docs (#100)
* docs: revise CLI reference * docs: sync CLI reference with current commands
This commit is contained in:
Luca Martial
GitHub
parent
a9c7c152f1
commit
5cf2c89093
12 changed files with 430 additions and 73 deletions
|
|
@ -89,11 +89,12 @@ ktx connection list --project-dir "$PROJECT_DIR"
|
|||
ktx connection test warehouse --project-dir "$PROJECT_DIR"
|
||||
```
|
||||
|
||||
The connection test prints the configured driver and discovered table count:
|
||||
The connection test prints the configured driver and connector-specific status:
|
||||
|
||||
```text
|
||||
Connection test passed: warehouse
|
||||
Driver: sqlite
|
||||
Tables: 1
|
||||
Status: ok
|
||||
```
|
||||
|
||||
## What's in a project
|
||||
|
|
|
|||
78
docs-site/content/docs/cli-reference/index.mdx
Normal file
78
docs-site/content/docs/cli-reference/index.mdx
Normal file
|
|
@ -0,0 +1,78 @@
|
|||
---
|
||||
title: "Overview"
|
||||
description: "Command map and shared options for the KTX CLI."
|
||||
---
|
||||
|
||||
The `ktx` CLI sets up local projects, builds agent-ready context, checks
|
||||
connections, queries semantic-layer sources, searches wiki pages, and manages
|
||||
the bundled Python runtime.
|
||||
|
||||
## Command Map
|
||||
|
||||
```text
|
||||
ktx
|
||||
setup
|
||||
connection
|
||||
list
|
||||
test [connectionId]
|
||||
ingest [connectionId]
|
||||
text [files...]
|
||||
wiki
|
||||
list
|
||||
search <query>
|
||||
sl
|
||||
list
|
||||
search <query>
|
||||
validate <sourceName>
|
||||
query
|
||||
status
|
||||
dev
|
||||
init [directory]
|
||||
schema
|
||||
runtime
|
||||
install
|
||||
start
|
||||
stop
|
||||
status
|
||||
```
|
||||
|
||||
The public context-build entrypoint is `ktx ingest [connectionId]` or
|
||||
`ktx ingest --all`. Legacy command shapes such as `ktx scan`, `ktx ingest run`,
|
||||
`ktx ingest status`, `ktx ingest replay`, `ktx ingest watch`, and
|
||||
`ktx setup status` are not part of the current public CLI.
|
||||
|
||||
## 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 --all
|
||||
|
||||
# Search semantic-layer sources and wiki pages
|
||||
ktx sl search "revenue"
|
||||
ktx wiki search "revenue recognition"
|
||||
```
|
||||
|
|
@ -4,8 +4,8 @@ description: "List and test configured data sources."
|
|||
---
|
||||
|
||||
Inspect configured connections in your KTX project. Connections define how KTX
|
||||
reaches your data warehouse, BI tools, and context sources. Use `ktx setup` to
|
||||
add, remove, or reconfigure connections.
|
||||
reaches databases, warehouses, BI tools, source projects, and knowledge
|
||||
systems. Use `ktx setup` to add, remove, or reconfigure them.
|
||||
|
||||
## Command signature
|
||||
|
||||
|
|
@ -18,24 +18,21 @@ ktx connection <subcommand> [options]
|
|||
| Subcommand | Description |
|
||||
|-----------|-------------|
|
||||
| `list` | List configured connections |
|
||||
| `test <connectionId>` | Test a configured connection |
|
||||
| `test [connectionId]` | Test one configured connection, or every connection with `--all` |
|
||||
|
||||
## Options
|
||||
|
||||
The `connection` command has command-level options for listing and testing
|
||||
existing connections.
|
||||
|
||||
### `connection list`
|
||||
|
||||
| Flag | Description | Default |
|
||||
|------|-------------|---------|
|
||||
| `--json` | Print JSON output | `false` |
|
||||
`ktx connection` uses the shared global options such as `--project-dir` and
|
||||
`--debug`.
|
||||
|
||||
### `connection test`
|
||||
|
||||
| Flag | Description | Default |
|
||||
|------|-------------|---------|
|
||||
| `--json` | Print JSON output | `false` |
|
||||
| `--all` | Test every configured connection and print a summary list | `false` |
|
||||
|
||||
Project directory resolution defaults to `KTX_PROJECT_DIR`, then the nearest
|
||||
`ktx.yaml`, then the current working directory.
|
||||
|
||||
## Examples
|
||||
|
||||
|
|
@ -45,6 +42,12 @@ ktx connection list
|
|||
|
||||
# Test a connection
|
||||
ktx connection test my-warehouse
|
||||
|
||||
# Test every configured connection
|
||||
ktx connection test --all
|
||||
|
||||
# Test a connection from outside the project
|
||||
ktx connection test my-warehouse --project-dir ./analytics
|
||||
```
|
||||
|
||||
## Setup-managed connections
|
||||
|
|
@ -55,24 +58,41 @@ Metabase mapping prompts for BI-to-warehouse mappings.
|
|||
|
||||
## Output
|
||||
|
||||
Commands with `--json` return machine-readable JSON suitable for scripts and
|
||||
agents.
|
||||
`ktx connection list` prints a table of configured ids and drivers.
|
||||
|
||||
```json
|
||||
{
|
||||
"connections": [
|
||||
{
|
||||
"id": "my-warehouse",
|
||||
"driver": "postgres"
|
||||
}
|
||||
]
|
||||
}
|
||||
```text
|
||||
ID DRIVER
|
||||
my-warehouse postgres
|
||||
```
|
||||
|
||||
`ktx connection test <connectionId>` performs a lightweight connection probe.
|
||||
Native database connections report `Status: ok` when the connector probe
|
||||
passes. Source connectors report connector-specific details such as Metabase
|
||||
database count, Looker user, Notion bot, or Git repo URL.
|
||||
|
||||
```text
|
||||
Connection test passed: my-warehouse
|
||||
Driver: postgres
|
||||
Status: ok
|
||||
```
|
||||
|
||||
`ktx connection test --all` prints one row per configured connection and exits
|
||||
non-zero if any probe fails.
|
||||
|
||||
```text
|
||||
╭ connection test --all
|
||||
│
|
||||
│ • warehouse postgres ✓ ok Status: ok
|
||||
│ • metabase metabase ✓ ok Databases: 2
|
||||
│
|
||||
╰ 2 tested · 2 passed
|
||||
```
|
||||
|
||||
## Common errors
|
||||
|
||||
| Error | Cause | Recovery |
|
||||
|-------|-------|----------|
|
||||
| No connections configured | The project has no entries under `connections` | Run `ktx setup` and add a database or source connection |
|
||||
| Connection test fails | Credentials, network access, database, warehouse, or schema is invalid | Verify the same URL with the database's native client, then rerun `ktx setup` and reconfigure the connection |
|
||||
| Mapping validation fails during setup | BI database mappings do not point at valid warehouse connections | Rerun `ktx setup` and update the source mapping selections |
|
||||
| Notion page picker cannot run | The terminal is non-interactive or Notion discovery failed | Rerun interactive `ktx setup`, or use non-interactive setup flags with explicit root page ids |
|
||||
|
|
|
|||
|
|
@ -3,7 +3,11 @@ title: "ktx dev"
|
|||
description: "Low-level project initialization and runtime management."
|
||||
---
|
||||
|
||||
`ktx dev` contains development-only project initialization and managed runtime commands. Context building lives at the root as [`ktx ingest`](/docs/cli-reference/ktx-ingest).
|
||||
`ktx dev` contains low-level project initialization and managed Python runtime
|
||||
commands. Context building lives at the root as
|
||||
[`ktx ingest`](/docs/cli-reference/ktx-ingest). Most users should start with
|
||||
`ktx setup`; use `ktx dev` when preparing local fixtures, checking the bundled
|
||||
runtime, or debugging runtime state.
|
||||
|
||||
## Command signature
|
||||
|
||||
|
|
@ -15,7 +19,8 @@ ktx dev <subcommand> [options]
|
|||
|
||||
| Subcommand | Description |
|
||||
|-----------|-------------|
|
||||
| `init [directory]` | Initialize a Git-backed KTX project directory |
|
||||
| `init [directory]` | Initialize a Git-backed KTX project directory for maintenance scripts |
|
||||
| `schema` | Print a JSON Schema describing `ktx.yaml` |
|
||||
| `runtime` | Install, start, stop, and inspect the KTX-managed Python runtime |
|
||||
|
||||
## `dev init`
|
||||
|
|
@ -24,16 +29,30 @@ ktx dev <subcommand> [options]
|
|||
|------|-------------|---------|
|
||||
| `--force` | Rewrite `ktx.yaml` and scaffold files in an existing project | `false` |
|
||||
|
||||
## `dev runtime`
|
||||
## `dev schema`
|
||||
|
||||
`ktx dev runtime` supports `install`, `start`, `stop`, and `status`.
|
||||
| Flag | Description | Default |
|
||||
|------|-------------|---------|
|
||||
| `--output <file>` | Write the schema to a file instead of stdout | — |
|
||||
|
||||
## `dev runtime` Subcommands
|
||||
|
||||
| Subcommand | Description |
|
||||
|-----------|-------------|
|
||||
| `install` | Install the bundled Python runtime wheel into the managed runtime |
|
||||
| `start` | Start the KTX-managed Python HTTP daemon |
|
||||
| `stop` | Stop the KTX-managed Python HTTP daemon |
|
||||
| `status` | Show managed Python runtime status and readiness checks |
|
||||
|
||||
## `dev runtime` Options
|
||||
|
||||
| Flag | Description | Default |
|
||||
|------|-------------|---------|
|
||||
| `--feature <feature>` | Runtime feature level for `install` and `start` (`core` or `local-embeddings`) | `core` |
|
||||
| `--json` | Print JSON output for `status` | `false` |
|
||||
| `--yes` | Confirm runtime install actions where supported | `false` |
|
||||
| `--force` | Reinstall or restart where supported | `false` |
|
||||
| `--yes` | Accepted by `install` for scripted install commands | `false` |
|
||||
| `--force` | Reinstall for `install`, or restart for `start` | `false` |
|
||||
| `--all` | Stop all recorded or discoverable KTX daemon processes with `stop` | `false` |
|
||||
|
||||
## Examples
|
||||
|
||||
|
|
@ -42,15 +61,28 @@ ktx dev init
|
|||
ktx dev init ./my-project
|
||||
ktx dev init --force
|
||||
|
||||
ktx dev schema
|
||||
ktx dev schema --output ./ktx.schema.json
|
||||
|
||||
ktx dev runtime install --yes
|
||||
ktx dev runtime install --feature local-embeddings --yes
|
||||
ktx dev runtime status
|
||||
ktx dev runtime start
|
||||
ktx dev runtime start --feature local-embeddings
|
||||
ktx dev runtime stop
|
||||
ktx dev runtime stop --all
|
||||
```
|
||||
|
||||
## Output
|
||||
|
||||
Runtime commands print the runtime root, installed features, daemon URL, daemon
|
||||
pid, and log paths where relevant. `ktx dev runtime status --json` includes the
|
||||
runtime status plus readiness checks.
|
||||
|
||||
## Common errors
|
||||
|
||||
| Error | Cause | Recovery |
|
||||
|-------|-------|----------|
|
||||
| Runtime status reports missing pieces | Packages, Python environment, or linked CLI are not ready | Run `pnpm install`, `pnpm run setup:dev`, `uv sync --all-groups`, then `ktx dev runtime status` |
|
||||
| Runtime daemon does not start | The managed Python runtime is missing or stale | Run `ktx dev runtime install --yes`, then `ktx dev runtime start` |
|
||||
| Multiple daemon processes remain | Older daemon state files or stray processes exist | Run `ktx dev runtime stop --all`, then start the runtime again |
|
||||
|
|
|
|||
|
|
@ -6,23 +6,25 @@ description: "Build or refresh KTX context from configured connections."
|
|||
`ktx ingest` builds or refreshes KTX context from configured connections.
|
||||
Database connections build schema context. Context-source connections ingest
|
||||
metadata from tools such as dbt, Looker, Metabase, MetricFlow, LookML, and
|
||||
Notion.
|
||||
Notion. The current public command is connection-centric: pass one
|
||||
`connectionId`, or pass `--all`.
|
||||
|
||||
## Command signature
|
||||
|
||||
```bash
|
||||
ktx ingest [options] [connectionId]
|
||||
ktx ingest text [options] [files...]
|
||||
```
|
||||
|
||||
Use a connection id to build one configured connection. Use `--all` to build
|
||||
every configured connection. Database connections run before context-source
|
||||
connections when you use `--all`.
|
||||
|
||||
## Build options
|
||||
## `ktx ingest` Options
|
||||
|
||||
| Flag | Description | Default |
|
||||
|------|-------------|---------|
|
||||
| `--all` | Build every configured connection | `false` |
|
||||
| `--all` | Ingest all configured connections | `false` |
|
||||
| `--fast` | Use deterministic database schema ingest | Stored connection default, or `fast` |
|
||||
| `--deep` | Use AI-enriched database ingest | Stored connection default, or `fast` |
|
||||
| `--query-history` | Include database query-history usage patterns | Stored connection default |
|
||||
|
|
@ -30,25 +32,75 @@ connections when you use `--all`.
|
|||
| `--query-history-window-days <days>` | Query-history lookback window for this run | Stored connection default |
|
||||
| `--plain` | Print plain text output | `true` |
|
||||
| `--json` | Print JSON output | `false` |
|
||||
| `--no-input` | Disable interactive terminal input | `false` |
|
||||
| `--no-input` | Disable interactive terminal input | — |
|
||||
|
||||
`--fast` and `--deep` are mutually exclusive. Depth flags apply only to
|
||||
database connections. Query-history flags apply only to database connections
|
||||
that support query history.
|
||||
that support query history. Query-history ingest runs after schema ingest and
|
||||
requires deep ingest readiness.
|
||||
|
||||
When `--all` selects both databases and context sources, database ingest runs
|
||||
first, then source ingest and memory updates run for source connections.
|
||||
|
||||
## `ktx ingest text` Options
|
||||
|
||||
Use `ktx ingest text` to capture free-form text artifacts into KTX memory.
|
||||
Provide files, pass `--text` one or more times, or use `-` as a file argument to
|
||||
read one item from stdin.
|
||||
|
||||
| Flag | Description | Default |
|
||||
|------|-------------|---------|
|
||||
| `--text <content>` | Text content to ingest; repeat for a batch | `[]` |
|
||||
| `--connection-id <connectionId>` | Optional KTX connection id for semantic-layer capture | — |
|
||||
| `--user-id <id>` | Memory user id for capture attribution | `local-cli` |
|
||||
| `--json` | Print JSON output | `false` |
|
||||
| `--fail-fast` | Stop after the first failed text item | `false` |
|
||||
|
||||
## Examples
|
||||
|
||||
```bash
|
||||
# Build one database or source connection
|
||||
ktx ingest warehouse
|
||||
|
||||
# Force deterministic database schema ingest
|
||||
ktx ingest warehouse --fast
|
||||
|
||||
# Force AI-enriched database ingest
|
||||
ktx ingest warehouse --deep
|
||||
|
||||
# Include query-history usage patterns
|
||||
ktx ingest warehouse --deep --query-history
|
||||
ktx ingest warehouse --query-history-window-days 30
|
||||
|
||||
# Build a source connection
|
||||
ktx ingest notion
|
||||
|
||||
# Build all configured connections
|
||||
ktx ingest --all
|
||||
ktx ingest --all --deep
|
||||
|
||||
# Capture local Markdown notes into memory
|
||||
ktx ingest text docs/revenue-notes.md --connection-id warehouse
|
||||
|
||||
# Capture one stdin item
|
||||
printf "Refunds are excluded from net revenue." | ktx ingest text -
|
||||
```
|
||||
|
||||
## Output
|
||||
|
||||
Plain output summarizes each target and the operations that ran.
|
||||
|
||||
```text
|
||||
Ingest finished
|
||||
|
||||
Source Database schema Query history Source ingest Memory update
|
||||
warehouse done done skipped skipped
|
||||
notion skipped skipped done done
|
||||
```
|
||||
|
||||
Use `--json` when a script or agent needs the selected plan and per-target
|
||||
results.
|
||||
|
||||
## Common errors
|
||||
|
||||
| Error | Cause | Recovery |
|
||||
|
|
@ -57,3 +109,5 @@ ktx ingest --all --deep
|
|||
| Deep readiness is missing | `--deep` or query history needs model, embedding, and scan-enrichment configuration | Run `ktx setup` or rerun with `--fast` |
|
||||
| Query history is unsupported | The selected database driver does not support query history | Run schema ingest without query-history flags |
|
||||
| No ingest target was selected | No connection id was provided and `--all` was omitted | Run `ktx ingest <connectionId>` or `ktx ingest --all` |
|
||||
| Source options were ignored | Depth and query-history flags were supplied for a non-database source | Omit database-only flags when ingesting source connections |
|
||||
| Text ingest stops early | `--fail-fast` was used and one item failed | Fix the failed item or rerun without `--fail-fast` to collect all failures |
|
||||
|
|
|
|||
|
|
@ -3,7 +3,14 @@ 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.
|
||||
`ktx setup` is the guided configuration flow for a local KTX project. It can
|
||||
create or resume `ktx.yaml`, configure LLM and embedding providers, add
|
||||
database and context-source connections, build initial context, and install
|
||||
agent integrations.
|
||||
|
||||
When you run bare `ktx` in an interactive terminal outside any KTX project, the
|
||||
CLI starts this same setup flow. Inside an existing project, `ktx setup`
|
||||
resumes from incomplete setup state or opens the setup menu.
|
||||
|
||||
## Command signature
|
||||
|
||||
|
|
@ -11,27 +18,117 @@ Interactive wizard that walks you through configuring LLM credentials, embedding
|
|||
ktx setup [options]
|
||||
```
|
||||
|
||||
## Options
|
||||
## Visible 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
|
||||
The help output intentionally keeps setup focused on the common interactive
|
||||
flags. Automation flags are accepted by the same command and are documented
|
||||
below.
|
||||
|
||||
| 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` |
|
||||
| `--target <target>` | Agent target: `claude-code`, `codex`, `cursor`, `opencode`, or `universal` | - |
|
||||
| `--global` | Install agent integration into the global target scope for `claude-code` or `codex` | `false` |
|
||||
| `--yes` | Accept safe defaults in non-interactive setup | `false` |
|
||||
| `--no-input` | Disable interactive terminal input | - |
|
||||
|
||||
The setup wizard is the public configuration interface. It prompts for LLM
|
||||
credentials, embeddings, database connections, context sources, query history,
|
||||
and agent integration when those values are needed.
|
||||
Use the global `--project-dir <path>` option when setup should target a
|
||||
specific directory.
|
||||
|
||||
## Automation Options
|
||||
|
||||
These flags are useful for repeatable setup in examples, tests, CI fixtures, and
|
||||
scripted project creation. They are not shown in `ktx setup --help`.
|
||||
|
||||
### Project Mode
|
||||
|
||||
| Flag | Description | Default |
|
||||
|------|-------------|---------|
|
||||
| `--new` | Create a new KTX project before setup | `false` |
|
||||
| `--existing` | Use an existing KTX project | `false` |
|
||||
|
||||
### LLM Provider
|
||||
|
||||
| Flag | Description |
|
||||
|------|-------------|
|
||||
| `--llm-backend <backend>` | LLM backend: `anthropic` or `vertex` |
|
||||
| `--anthropic-api-key-env <name>` | Environment variable containing the Anthropic API key |
|
||||
| `--anthropic-api-key-file <path>` | File containing the Anthropic API key |
|
||||
| `--anthropic-model <model>` | Anthropic model ID to validate and save |
|
||||
| `--vertex-project <project>` | Vertex AI project ID, `env:NAME`, or `file:/path` reference |
|
||||
| `--vertex-location <location>` | Vertex AI location, `env:NAME`, or `file:/path` reference |
|
||||
| `--skip-llm` | Leave LLM setup incomplete |
|
||||
|
||||
Choose only one Anthropic credential source. Anthropic credential flags are only
|
||||
valid with the Anthropic backend; Vertex flags are only valid with the Vertex
|
||||
backend.
|
||||
|
||||
### Embeddings
|
||||
|
||||
| Flag | Description |
|
||||
|------|-------------|
|
||||
| `--embedding-backend <backend>` | Embedding backend: `openai` or `sentence-transformers` |
|
||||
| `--embedding-api-key-env <name>` | Environment variable containing the embedding provider API key |
|
||||
| `--embedding-api-key-file <path>` | File containing the embedding provider API key |
|
||||
| `--skip-embeddings` | Leave embedding setup incomplete |
|
||||
|
||||
`sentence-transformers` uses the KTX-managed Python runtime. Choose only one
|
||||
embedding credential source.
|
||||
|
||||
### Databases
|
||||
|
||||
| Flag | Description |
|
||||
|------|-------------|
|
||||
| `--database <driver>` | Database driver to configure; repeatable. Choices: `sqlite`, `postgres`, `mysql`, `clickhouse`, `sqlserver`, `bigquery`, `snowflake` |
|
||||
| `--database-connection-id <id>` | Existing selected connection id; repeatable |
|
||||
| `--new-database-connection-id <id>` | Connection id for one new database connection |
|
||||
| `--database-url <url>` | URL, `env:NAME`, or `file:/path` for one new URL-style database connection; also used as the SQLite path |
|
||||
| `--database-schema <schema>` | Database schema or dataset to include; repeatable |
|
||||
| `--skip-databases` | Leave database setup incomplete |
|
||||
|
||||
KTX needs at least one database connection before it can build database
|
||||
context. Use `--skip-databases` only when intentionally leaving the project
|
||||
incomplete.
|
||||
|
||||
### Query History
|
||||
|
||||
| Flag | Description |
|
||||
|------|-------------|
|
||||
| `--enable-query-history` | Enable query-history ingest when the selected database supports it |
|
||||
| `--disable-query-history` | Disable query-history ingest for the selected database |
|
||||
| `--query-history-window-days <number>` | Query-history lookback window |
|
||||
| `--query-history-min-executions <number>` | Minimum executions for a query-history template |
|
||||
| `--query-history-service-account-pattern <pattern>` | Query-history service-account regex; repeatable |
|
||||
| `--query-history-redaction-pattern <pattern>` | Query-history SQL-literal redaction regex; repeatable |
|
||||
|
||||
Query history setup is supported for Postgres, BigQuery, and Snowflake. Enabling
|
||||
query history makes deep ingest readiness matter for later `ktx ingest` runs.
|
||||
|
||||
### Context Sources
|
||||
|
||||
| Flag | Description |
|
||||
|------|-------------|
|
||||
| `--source <type>` | Source connector type: `dbt`, `metricflow`, `metabase`, `looker`, `lookml`, or `notion` |
|
||||
| `--source-connection-id <id>` | Connection id for source setup |
|
||||
| `--source-path <path>` | Local source path for dbt, MetricFlow, or LookML |
|
||||
| `--source-git-url <url>` | Git URL for dbt, MetricFlow, or LookML |
|
||||
| `--source-branch <branch>` | Git branch for source setup |
|
||||
| `--source-subpath <path>` | Repo subpath for source setup |
|
||||
| `--source-auth-token-ref <ref>` | `env:` or `file:` credential reference for source repo auth |
|
||||
| `--source-url <url>` | Source service URL for Metabase or Looker |
|
||||
| `--source-api-key-ref <ref>` | `env:` or `file:` API key reference for Metabase or Notion |
|
||||
| `--source-client-id <id>` | Looker client id |
|
||||
| `--source-client-secret-ref <ref>` | `env:` or `file:` Looker client secret reference |
|
||||
| `--source-warehouse-connection-id <id>` | Warehouse connection id used for source mapping |
|
||||
| `--source-project-name <name>` | dbt project name override |
|
||||
| `--source-profiles-path <path>` | dbt profiles path |
|
||||
| `--source-target <target>` | dbt target or source-specific mapping target |
|
||||
| `--metabase-database-id <id>` | Metabase database id to map |
|
||||
| `--notion-crawl-mode <mode>` | Notion crawl mode: `all_accessible` or `selected_roots` |
|
||||
| `--notion-root-page-id <id>` | Notion root page id; repeatable |
|
||||
| `--skip-sources` | Mark optional source setup complete with no sources |
|
||||
|
||||
Choose only one source location: `--source-path` or `--source-git-url`.
|
||||
|
||||
## Examples
|
||||
|
||||
|
|
@ -42,14 +139,37 @@ 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
|
||||
# Script a Postgres connection that reads its URL from the environment
|
||||
ktx setup \
|
||||
--project-dir ./analytics \
|
||||
--no-input \
|
||||
--skip-llm \
|
||||
--skip-embeddings \
|
||||
--database postgres \
|
||||
--new-database-connection-id warehouse \
|
||||
--database-url env:DATABASE_URL \
|
||||
--database-schema public
|
||||
|
||||
# Install agent integration globally for Codex
|
||||
ktx setup --agents --target codex --global
|
||||
# Enable Postgres query history while setting up a database
|
||||
ktx setup \
|
||||
--project-dir ./analytics \
|
||||
--database postgres \
|
||||
--new-database-connection-id warehouse \
|
||||
--database-url env:DATABASE_URL \
|
||||
--enable-query-history \
|
||||
--query-history-min-executions 5
|
||||
|
||||
# Check setup readiness
|
||||
ktx status
|
||||
# Add a Metabase source mapped to an existing warehouse connection
|
||||
ktx setup \
|
||||
--source metabase \
|
||||
--source-connection-id prod_metabase \
|
||||
--source-url https://metabase.example.com \
|
||||
--source-api-key-ref env:METABASE_API_KEY \
|
||||
--source-warehouse-connection-id warehouse \
|
||||
--metabase-database-id 1
|
||||
|
||||
# Install project-scoped agent integration for Codex
|
||||
ktx setup --agents --target codex
|
||||
```
|
||||
|
||||
## Output
|
||||
|
|
@ -68,11 +188,16 @@ KTX context built: yes
|
|||
Agent integration ready: yes (codex:project)
|
||||
```
|
||||
|
||||
Use `ktx status` for repeatable readiness checks after setup exits.
|
||||
|
||||
## 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 |
|
||||
| Setup cannot run in CI | Required values are missing and `--no-input` disables prompts | Provide the relevant automation flags or create a fixture `ktx.yaml` |
|
||||
| Provider health check fails | Provider key, model id, Vertex project, or Vertex location is invalid | Fix the `env:` or `file:` reference and rerun setup |
|
||||
| `--enable-query-history` is rejected | The selected database driver does not support query history | Use Postgres, BigQuery, or Snowflake, or rerun without query-history flags |
|
||||
| Source setup rejects location flags | Both `--source-path` and `--source-git-url` were supplied | Choose the local path or the Git URL, not both |
|
||||
| Agent integration missing | Setup skipped the agents step | Run `ktx setup --agents --target <target>` |
|
||||
| Global agent install is rejected | `--global` was used with a target other than `claude-code` or `codex` | Omit `--global`, or choose `--target claude-code` or `--target codex` |
|
||||
|
|
|
|||
|
|
@ -3,7 +3,9 @@ title: "ktx sl"
|
|||
description: "List, search, validate, or query semantic-layer sources."
|
||||
---
|
||||
|
||||
Interact with your project's semantic layer. Semantic sources are YAML definitions that describe your tables, columns, measures, joins, and grain - the vocabulary agents use to generate correct SQL.
|
||||
Interact with your project's semantic layer. Semantic sources are YAML
|
||||
definitions that describe tables, columns, measures, joins, segments, and grain:
|
||||
the vocabulary agents use to generate correct SQL.
|
||||
|
||||
## Command signature
|
||||
|
||||
|
|
@ -60,8 +62,13 @@ ktx sl <subcommand> [options]
|
|||
| `--include-empty` | Include empty rows | `false` |
|
||||
| `--format <format>` | Output format: `json` or `sql` | `json` |
|
||||
| `--execute` | Execute the compiled query against the database | `false` |
|
||||
| `--yes` | Install the managed Python runtime without prompting when required | `false` |
|
||||
| `--no-input` | Disable interactive managed runtime installation | - |
|
||||
| `--max-rows <n>` | Maximum rows to return when executing | - |
|
||||
|
||||
`sl query` requires at least one `--measure` unless `--query-file` is set.
|
||||
`--query-file` should point to a JSON semantic-layer query object.
|
||||
|
||||
## Examples
|
||||
|
||||
```bash
|
||||
|
|
@ -113,6 +120,13 @@ ktx sl query \
|
|||
--execute \
|
||||
--max-rows 1000
|
||||
|
||||
# Compile or execute without prompting for runtime installation
|
||||
ktx sl query \
|
||||
--connection-id my-warehouse \
|
||||
--measure orders.count \
|
||||
--execute \
|
||||
--yes
|
||||
|
||||
# Execute a query from a JSON file
|
||||
ktx sl query \
|
||||
--connection-id my-warehouse \
|
||||
|
|
@ -123,7 +137,10 @@ ktx sl query \
|
|||
|
||||
## Output
|
||||
|
||||
Semantic-layer commands return human-readable output by default. Use `--json` or `--format json` when an agent needs structured output; use `--format sql` to inspect generated SQL before execution.
|
||||
Semantic-layer list and search commands return human-readable output by
|
||||
default. Use `--json` on `list` or `search` when an agent needs structured
|
||||
output. Use `--format sql` on `query` to inspect generated SQL before
|
||||
execution, or leave `--format json` for the compiled query and optional rows.
|
||||
|
||||
```json
|
||||
{
|
||||
|
|
@ -145,3 +162,4 @@ Semantic-layer commands return human-readable output by default. Use `--json` or
|
|||
| Validation fails | YAML references missing columns, invalid joins, or invalid SQL expressions | Fix the source YAML and rerun `ktx sl validate` |
|
||||
| Query compile fails | Measure, dimension, filter, or segment name is invalid | Search sources with `ktx sl search`, inspect the source YAML in your project files, then retry using declared fields |
|
||||
| Execution returns too many rows | `--max-rows` is missing or too high | Add `--max-rows` with a bounded value before executing |
|
||||
| Runtime install is blocked | Query execution needs the managed Python runtime and prompts are disabled | Run `ktx dev runtime install --feature core --yes`, or rerun `ktx sl query --yes` |
|
||||
|
|
|
|||
|
|
@ -4,8 +4,9 @@ description: "Check KTX setup and project readiness."
|
|||
---
|
||||
|
||||
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.
|
||||
project configuration, semantic search, query history, connections, and related
|
||||
diagnostics. Outside a project, it checks local CLI setup readiness so you know
|
||||
whether `ktx setup` can run.
|
||||
|
||||
## Command signature
|
||||
|
||||
|
|
@ -18,6 +19,8 @@ ktx status [options]
|
|||
| Flag | Description | Default |
|
||||
|------|-------------|---------|
|
||||
| `--json` | Print JSON output | `false` |
|
||||
| `-v`, `--verbose` | Show every check, including passing ones | `false` |
|
||||
| `--validate` | Only validate the `ktx.yaml` schema; skip readiness checks | `false` |
|
||||
| `--no-input` | Disable interactive terminal input | - |
|
||||
|
||||
## Examples
|
||||
|
|
@ -28,12 +31,21 @@ ktx status
|
|||
|
||||
# Get status as JSON without interactive input
|
||||
ktx status --json --no-input
|
||||
|
||||
# Show all checks, not only warnings and failures
|
||||
ktx status --verbose
|
||||
|
||||
# Validate ktx.yaml without running readiness checks
|
||||
ktx status --validate
|
||||
|
||||
# Check a project from another directory
|
||||
ktx status --project-dir ./analytics
|
||||
```
|
||||
|
||||
## Output
|
||||
|
||||
`ktx status` prints doctor checks. Agents should use `ktx status --json --no-input`
|
||||
when they need to branch on readiness state.
|
||||
`ktx status` prints grouped doctor checks. Agents should use
|
||||
`ktx status --json --no-input` when they need to branch on readiness state.
|
||||
|
||||
```json
|
||||
{
|
||||
|
|
@ -55,4 +67,6 @@ when they need to branch on readiness state.
|
|||
|-------|-------|----------|
|
||||
| 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 |
|
||||
| Schema validation fails | `ktx.yaml` does not match the current config schema | Run `ktx status --validate --json` for structured issue details, then edit `ktx.yaml` or rerun `ktx 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 |
|
||||
| Query history check warns | A database has query history enabled but the warehouse prerequisites are missing | Fix the warehouse extension, grants, or history access, then rerun `ktx status` |
|
||||
|
|
|
|||
|
|
@ -3,7 +3,9 @@ title: "ktx wiki"
|
|||
description: "List or search wiki pages."
|
||||
---
|
||||
|
||||
Manage wiki pages in your KTX project. Wiki pages are Markdown documents that capture business definitions, rules, and gotchas. Agents search them for context when answering questions about your data.
|
||||
List and search wiki pages in your KTX project. Wiki pages are Markdown
|
||||
documents that capture business definitions, rules, and gotchas. Agents search
|
||||
them for context when answering questions about your data.
|
||||
|
||||
## Command signature
|
||||
|
||||
|
|
@ -18,22 +20,28 @@ ktx wiki <subcommand> [options]
|
|||
| `list` | List local wiki pages |
|
||||
| `search <query>` | Search local wiki pages |
|
||||
|
||||
The current public CLI lists and searches wiki pages. Edit the Markdown files
|
||||
under `wiki/` directly, or ingest source content with `ktx ingest`, when you
|
||||
need to add or update wiki knowledge.
|
||||
|
||||
## Options
|
||||
|
||||
### `wiki list`
|
||||
|
||||
| Flag | Description | Default |
|
||||
|------|-------------|---------|
|
||||
| `--json` | Print JSON output | `false` |
|
||||
| `--user-id <id>` | Local user id | `local` |
|
||||
| `--output <mode>` | Output mode: `pretty` (default in TTY), `plain` (TSV), or `json` | `pretty` |
|
||||
| `--json` | Shortcut for `--output=json` (overrides `--output`) | `false` |
|
||||
|
||||
### `wiki search`
|
||||
|
||||
| Flag | Description | Default |
|
||||
|------|-------------|---------|
|
||||
| `--json` | Print JSON output | `false` |
|
||||
| `--user-id <id>` | Local user id | `local` |
|
||||
| `--limit <number>` | Maximum search results | - |
|
||||
| `--output <mode>` | Output mode: `pretty` (default in TTY), `plain` (TSV), or `json` | `pretty` |
|
||||
| `--json` | Shortcut for `--output=json` (overrides `--output`) | `false` |
|
||||
|
||||
## Examples
|
||||
|
||||
|
|
@ -49,12 +57,17 @@ ktx wiki search "monthly recurring revenue"
|
|||
|
||||
# Search wiki pages as JSON
|
||||
ktx wiki search "monthly recurring revenue" --json --limit 10
|
||||
|
||||
# Print search results as TSV
|
||||
ktx wiki search "monthly recurring revenue" --output plain
|
||||
```
|
||||
|
||||
## Output
|
||||
|
||||
Wiki commands print local wiki page listings and search results. Open the
|
||||
matching Markdown files directly when you need the full page contents.
|
||||
Wiki commands print clack-style pretty output in a TTY and TSV-style plain
|
||||
output when requested. JSON output wraps the items with a command metadata
|
||||
envelope. Open the matching Markdown files directly when you need the full page
|
||||
contents.
|
||||
|
||||
```json
|
||||
{
|
||||
|
|
|
|||
|
|
@ -2,6 +2,7 @@
|
|||
"title": "CLI Reference",
|
||||
"defaultOpen": true,
|
||||
"pages": [
|
||||
"index",
|
||||
"ktx-setup",
|
||||
"ktx-connection",
|
||||
"ktx-ingest",
|
||||
|
|
|
|||
|
|
@ -100,7 +100,7 @@ schema context:
|
|||
```
|
||||
Testing postgres-warehouse
|
||||
Connection test passed
|
||||
Driver: PostgreSQL - Tables: 42
|
||||
Driver: PostgreSQL - Status: ok
|
||||
|
||||
Building schema context for postgres-warehouse
|
||||
Running fast database ingest
|
||||
|
|
|
|||
|
|
@ -181,8 +181,9 @@ describe('standalone example docs', () => {
|
|||
|
||||
assert.match(connectionReference, /ktx connection list/);
|
||||
assert.match(connectionReference, /ktx connection test my-warehouse/);
|
||||
assert.match(connectionReference, /ktx connection test --all/);
|
||||
assert.match(quickstart, /Connection test passed/);
|
||||
assert.match(quickstart, /Driver: PostgreSQL .* Tables: 42/);
|
||||
assert.match(quickstart, /Driver: PostgreSQL .* Status: ok/);
|
||||
});
|
||||
|
||||
it('documents public npm and managed runtime usage', async () => {
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue