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 index 94b083ac..4eb11648 100644 --- a/docs-site/content/docs/cli-reference/index.mdx +++ b/docs-site/content/docs/cli-reference/index.mdx @@ -14,7 +14,7 @@ ktx setup connection list - test + test [connectionId] ingest [connectionId] text [files...] wiki @@ -28,6 +28,7 @@ ktx status dev init [directory] + schema runtime install start diff --git a/docs-site/content/docs/cli-reference/ktx-connection.mdx b/docs-site/content/docs/cli-reference/ktx-connection.mdx index 8ea43126..2d61451f 100644 --- a/docs-site/content/docs/cli-reference/ktx-connection.mdx +++ b/docs-site/content/docs/cli-reference/ktx-connection.mdx @@ -18,13 +18,18 @@ 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 `ktx connection` uses the shared global options such as `--project-dir` and -`--debug`. The `list` and `test` subcommands do not currently define -command-specific options. +`--debug`. + +### `connection test` + +| Flag | Description | Default | +|------|-------------|---------| +| `--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. @@ -38,6 +43,9 @@ 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 ``` @@ -58,13 +66,26 @@ my-warehouse postgres ``` `ktx connection test ` performs a lightweight connection probe. -Database connections report a table count. Metabase connections report a -database count. +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 -Tables: 42 +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 diff --git a/docs-site/content/docs/cli-reference/ktx-dev.mdx b/docs-site/content/docs/cli-reference/ktx-dev.mdx index 9a1a04a4..f124055a 100644 --- a/docs-site/content/docs/cli-reference/ktx-dev.mdx +++ b/docs-site/content/docs/cli-reference/ktx-dev.mdx @@ -20,6 +20,7 @@ ktx dev [options] | Subcommand | Description | |-----------|-------------| | `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` @@ -28,6 +29,12 @@ ktx dev [options] |------|-------------|---------| | `--force` | Rewrite `ktx.yaml` and scaffold files in an existing project | `false` | +## `dev schema` + +| Flag | Description | Default | +|------|-------------|---------| +| `--output ` | Write the schema to a file instead of stdout | — | + ## `dev runtime` Subcommands | Subcommand | Description | @@ -54,6 +61,9 @@ 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 diff --git a/docs-site/content/docs/cli-reference/ktx-status.mdx b/docs-site/content/docs/cli-reference/ktx-status.mdx index 17f15858..dae22857 100644 --- a/docs-site/content/docs/cli-reference/ktx-status.mdx +++ b/docs-site/content/docs/cli-reference/ktx-status.mdx @@ -20,6 +20,7 @@ ktx status [options] |------|-------------|---------| | `--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 @@ -34,6 +35,9 @@ 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 ``` @@ -63,5 +67,6 @@ ktx status --project-dir ./analytics |-------|-------|----------| | 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 78bae6db..ad0e53bf 100644 --- a/docs-site/content/docs/cli-reference/ktx-wiki.mdx +++ b/docs-site/content/docs/cli-reference/ktx-wiki.mdx @@ -30,16 +30,18 @@ need to add or update wiki knowledge. | 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 @@ -55,13 +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. Plain output -is tab-separated. JSON output wraps the items with a command metadata envelope. -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/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 () => {