From 5cf2c890932c3e6aa4eaf0ea566a1c75f1364810 Mon Sep 17 00:00:00 2001 From: Luca Martial <48870843+luca-martial@users.noreply.github.com> Date: Thu, 14 May 2026 12:53:55 -0400 Subject: [PATCH] Revise CLI reference docs (#100) * docs: revise CLI reference * docs: sync CLI reference with current commands --- README.md | 5 +- .../content/docs/cli-reference/index.mdx | 78 ++++++++ .../docs/cli-reference/ktx-connection.mdx | 66 ++++--- .../content/docs/cli-reference/ktx-dev.mdx | 44 ++++- .../content/docs/cli-reference/ktx-ingest.mdx | 64 ++++++- .../content/docs/cli-reference/ktx-setup.mdx | 173 +++++++++++++++--- .../content/docs/cli-reference/ktx-sl.mdx | 22 ++- .../content/docs/cli-reference/ktx-status.mdx | 22 ++- .../content/docs/cli-reference/ktx-wiki.mdx | 23 ++- .../content/docs/cli-reference/meta.json | 1 + .../docs/getting-started/quickstart.mdx | 2 +- scripts/examples-docs.test.mjs | 3 +- 12 files changed, 430 insertions(+), 73 deletions(-) create mode 100644 docs-site/content/docs/cli-reference/index.mdx diff --git a/README.md b/README.md index f2e4ed15..92a2a8dd 100644 --- a/README.md +++ b/README.md @@ -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 diff --git a/docs-site/content/docs/cli-reference/index.mdx b/docs-site/content/docs/cli-reference/index.mdx new file mode 100644 index 00000000..4eb11648 --- /dev/null +++ b/docs-site/content/docs/cli-reference/index.mdx @@ -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 + sl + list + search + validate + 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 ` | 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 ` 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" +``` diff --git a/docs-site/content/docs/cli-reference/ktx-connection.mdx b/docs-site/content/docs/cli-reference/ktx-connection.mdx index 68b7f496..2d61451f 100644 --- a/docs-site/content/docs/cli-reference/ktx-connection.mdx +++ b/docs-site/content/docs/cli-reference/ktx-connection.mdx @@ -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 [options] | Subcommand | Description | |-----------|-------------| | `list` | List configured connections | -| `test ` | 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 ` 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 | diff --git a/docs-site/content/docs/cli-reference/ktx-dev.mdx b/docs-site/content/docs/cli-reference/ktx-dev.mdx index 333b6f35..f124055a 100644 --- a/docs-site/content/docs/cli-reference/ktx-dev.mdx +++ b/docs-site/content/docs/cli-reference/ktx-dev.mdx @@ -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 [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 [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 ` | 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 ` | 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 | diff --git a/docs-site/content/docs/cli-reference/ktx-ingest.mdx b/docs-site/content/docs/cli-reference/ktx-ingest.mdx index e7b8bbe5..a0bca58f 100644 --- a/docs-site/content/docs/cli-reference/ktx-ingest.mdx +++ b/docs-site/content/docs/cli-reference/ktx-ingest.mdx @@ -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 ` | 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 ` | Text content to ingest; repeat for a batch | `[]` | +| `--connection-id ` | Optional KTX connection id for semantic-layer capture | — | +| `--user-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 ` 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 | diff --git a/docs-site/content/docs/cli-reference/ktx-setup.mdx b/docs-site/content/docs/cli-reference/ktx-setup.mdx index bca86c48..4de40ecb 100644 --- a/docs-site/content/docs/cli-reference/ktx-setup.mdx +++ b/docs-site/content/docs/cli-reference/ktx-setup.mdx @@ -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 ` | 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 ` | Agent target (`claude-code`, `codex`, `cursor`, `opencode`, `universal`) | - | -| `--global` | Install agent integration into the global target scope (Claude Code and Codex only) | `false` | +| `--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 ` 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 ` | LLM backend: `anthropic` or `vertex` | +| `--anthropic-api-key-env ` | Environment variable containing the Anthropic API key | +| `--anthropic-api-key-file ` | File containing the Anthropic API key | +| `--anthropic-model ` | Anthropic model ID to validate and save | +| `--vertex-project ` | Vertex AI project ID, `env:NAME`, or `file:/path` reference | +| `--vertex-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 ` | Embedding backend: `openai` or `sentence-transformers` | +| `--embedding-api-key-env ` | Environment variable containing the embedding provider API key | +| `--embedding-api-key-file ` | 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 ` | Database driver to configure; repeatable. Choices: `sqlite`, `postgres`, `mysql`, `clickhouse`, `sqlserver`, `bigquery`, `snowflake` | +| `--database-connection-id ` | Existing selected connection id; repeatable | +| `--new-database-connection-id ` | Connection id for one new database connection | +| `--database-url ` | URL, `env:NAME`, or `file:/path` for one new URL-style database connection; also used as the SQLite path | +| `--database-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 ` | Query-history lookback window | +| `--query-history-min-executions ` | Minimum executions for a query-history template | +| `--query-history-service-account-pattern ` | Query-history service-account regex; repeatable | +| `--query-history-redaction-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 ` | Source connector type: `dbt`, `metricflow`, `metabase`, `looker`, `lookml`, or `notion` | +| `--source-connection-id ` | Connection id for source setup | +| `--source-path ` | Local source path for dbt, MetricFlow, or LookML | +| `--source-git-url ` | Git URL for dbt, MetricFlow, or LookML | +| `--source-branch ` | Git branch for source setup | +| `--source-subpath ` | Repo subpath for source setup | +| `--source-auth-token-ref ` | `env:` or `file:` credential reference for source repo auth | +| `--source-url ` | Source service URL for Metabase or Looker | +| `--source-api-key-ref ` | `env:` or `file:` API key reference for Metabase or Notion | +| `--source-client-id ` | Looker client id | +| `--source-client-secret-ref ` | `env:` or `file:` Looker client secret reference | +| `--source-warehouse-connection-id ` | Warehouse connection id used for source mapping | +| `--source-project-name ` | dbt project name override | +| `--source-profiles-path ` | dbt profiles path | +| `--source-target ` | dbt target or source-specific mapping target | +| `--metabase-database-id ` | Metabase database id to map | +| `--notion-crawl-mode ` | Notion crawl mode: `all_accessible` or `selected_roots` | +| `--notion-root-page-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 ` 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 ` | +| 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` | diff --git a/docs-site/content/docs/cli-reference/ktx-sl.mdx b/docs-site/content/docs/cli-reference/ktx-sl.mdx index 2d2835f5..3d7fd8d9 100644 --- a/docs-site/content/docs/cli-reference/ktx-sl.mdx +++ b/docs-site/content/docs/cli-reference/ktx-sl.mdx @@ -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 [options] | `--include-empty` | Include empty rows | `false` | | `--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 ` | 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` | diff --git a/docs-site/content/docs/cli-reference/ktx-status.mdx b/docs-site/content/docs/cli-reference/ktx-status.mdx index 669ab4c5..dae22857 100644 --- a/docs-site/content/docs/cli-reference/ktx-status.mdx +++ b/docs-site/content/docs/cli-reference/ktx-status.mdx @@ -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` | diff --git a/docs-site/content/docs/cli-reference/ktx-wiki.mdx b/docs-site/content/docs/cli-reference/ktx-wiki.mdx index a148ea73..ad0e53bf 100644 --- a/docs-site/content/docs/cli-reference/ktx-wiki.mdx +++ b/docs-site/content/docs/cli-reference/ktx-wiki.mdx @@ -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 [options] | `list` | List local wiki pages | | `search ` | 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 ` | Local user id | `local` | +| `--output ` | 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 ` | Local user id | `local` | | `--limit ` | Maximum search results | - | +| `--output ` | 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 { diff --git a/docs-site/content/docs/cli-reference/meta.json b/docs-site/content/docs/cli-reference/meta.json index 093f75ae..46aafb4c 100644 --- a/docs-site/content/docs/cli-reference/meta.json +++ b/docs-site/content/docs/cli-reference/meta.json @@ -2,6 +2,7 @@ "title": "CLI Reference", "defaultOpen": true, "pages": [ + "index", "ktx-setup", "ktx-connection", "ktx-ingest", diff --git a/docs-site/content/docs/getting-started/quickstart.mdx b/docs-site/content/docs/getting-started/quickstart.mdx index 3d0a4063..4f0c3a65 100644 --- a/docs-site/content/docs/getting-started/quickstart.mdx +++ b/docs-site/content/docs/getting-started/quickstart.mdx @@ -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 diff --git a/scripts/examples-docs.test.mjs b/scripts/examples-docs.test.mjs index 23553853..5e6a93d7 100644 --- a/scripts/examples-docs.test.mjs +++ b/scripts/examples-docs.test.mjs @@ -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 () => {