mirror of
https://github.com/Kaelio/ktx.git
synced 2026-06-07 07:55:13 +02:00
d320d54ab2
* feat(completion): complete known argument values
* fix(completion): hide Commander-hidden subcommands from completions
Replace the `__`-prefix name heuristic with Commander's `_hidden` flag so
internal subcommands registered with { hidden: true } (e.g. `mcp serve-internal`)
are excluded from completions, mirroring `ktx --help`.
* test: cover wiki and sl read command routing
* test: cover raw wiki and sl reads
* feat: add wiki read command
* feat: add sl read command
* feat: complete read command entity names
* docs: document wiki and sl read commands
* test: include read commands in command tree
* feat(sl): read and validate unique sources by name
* feat(sl): make read and validate connection id optional
* fix(completion): dedupe semantic source names
* docs(sl): document connection-optional read and validate
* fix(sl): require connection id for query command
* docs(sl): clarify query connection requirement
* fix(completion): don't resolve option values as subcommands
resolveCommand skipped flag tokens but not the value consumed by a
value-taking option in the `--flag value` form, so a connection id like
`query` was matched as the `sl query` subcommand and yielded no `sl`
completions. Track value-taking options and skip their consumed value
before matching subcommands.
* test(telemetry): assert first-run notice via TELEMETRY_NOTICE constant
CI (which tests this branch merged with main) failed because #243 changed
the first-run notice wording in identity.ts (dropped "anonymous") but left
this test grepping for the old literal 'ktx collects anonymous usage data',
so indexOf returned -1. Assert against the exported TELEMETRY_NOTICE
constant instead so the test tracks the source of truth and cannot drift
when the notice text changes again.
86 lines
3.3 KiB
Text
86 lines
3.3 KiB
Text
---
|
|
title: "ktx completion"
|
|
description: "Print a shell completion script for tab completion."
|
|
---
|
|
|
|
Print a shell completion script for **ktx**. Once installed, pressing <kbd>Tab</kbd>
|
|
completes commands, subcommands, and flags, and - inside a **ktx** project - the
|
|
names of things that already exist: semantic-layer source names for
|
|
`ktx sl read` and `ktx sl validate`, wiki page keys for `ktx wiki read`, and
|
|
configured connection ids for `ktx connection test`, `ktx ingest`, and
|
|
`ktx sql`. This saves you from remembering exact source, page, or connection
|
|
names.
|
|
|
|
## Command signature
|
|
|
|
```bash
|
|
ktx completion <shell>
|
|
```
|
|
|
|
`<shell>` must be `zsh` or `bash`. The command writes the script to stdout; it
|
|
does not modify any files. Enable completion by evaluating the script in your
|
|
shell startup file.
|
|
|
|
## Installation
|
|
|
|
Add the matching line to your shell startup file, then restart your shell (or
|
|
`source` the file). `ktx` must be on your `PATH`.
|
|
|
|
```bash
|
|
# zsh — add to ~/.zshrc
|
|
eval "$(ktx completion zsh)"
|
|
```
|
|
|
|
```bash
|
|
# bash — add to ~/.bashrc
|
|
eval "$(ktx completion bash)"
|
|
```
|
|
|
|
To try it for the current session only, run the same `eval` line directly in
|
|
your terminal.
|
|
|
|
## What gets completed
|
|
|
|
| Position | Completions |
|
|
|----------|-------------|
|
|
| `ktx <Tab>` | Top-level commands (`setup`, `sl`, `wiki`, `ingest`, …) |
|
|
| `ktx sl <Tab>` | The `read` / `validate` / `query` subcommands |
|
|
| `ktx sl read <Tab>` | Existing semantic-layer source names |
|
|
| `ktx sl validate <Tab>` | Existing semantic-layer source names |
|
|
| `ktx wiki <Tab>` | The `read` subcommand |
|
|
| `ktx wiki read <Tab>` | Existing wiki page keys |
|
|
| `ktx connection test <Tab>` | Configured connection ids |
|
|
| `ktx ingest <Tab>` | Configured connection ids |
|
|
| `ktx sql --connection <Tab>` | Configured connection ids |
|
|
| `ktx completion <Tab>` | `zsh` or `bash` |
|
|
| `ktx <command> --<Tab>` | The command's flags and inherited global flags |
|
|
| `ktx sl --output <Tab>` | An option's allowed values (here `pretty`, `plain`, `json`) |
|
|
| `ktx sl --connection-id <Tab>` | Configured connection ids |
|
|
|
|
Source names, wiki page keys, and connection ids are read from the **ktx**
|
|
project resolved from your current directory (or `--project-dir` /
|
|
`KTX_PROJECT_DIR`). Outside a **ktx** project, completion still suggests
|
|
commands and flags but no project entities. Bare `ktx sl <Tab>` and
|
|
`ktx wiki <Tab>` complete subcommands instead of entity names because their
|
|
positional arguments are free-text search queries.
|
|
|
|
## Examples
|
|
|
|
```bash
|
|
# Print the zsh completion script
|
|
ktx completion zsh
|
|
|
|
# Print the bash completion script
|
|
ktx completion bash
|
|
|
|
# Install for zsh
|
|
echo 'eval "$(ktx completion zsh)"' >> ~/.zshrc
|
|
```
|
|
|
|
## Common errors
|
|
|
|
| Error | Cause | Recovery |
|
|
|-------|-------|----------|
|
|
| `error: command-argument value '<name>' is invalid for argument 'shell'. Allowed choices are zsh, bash.` | A shell other than `zsh` or `bash` was requested | Re-run with `ktx completion zsh` or `ktx completion bash` |
|
|
| Tab completion does nothing | The script was not evaluated, or `ktx` is not on `PATH` | Confirm the `eval` line is in your startup file, restart the shell, and verify `ktx --version` runs |
|
|
| Source, page, or connection names are missing | The current directory is not inside a **ktx** project | Run from the project directory, or pass `--project-dir`, or set `KTX_PROJECT_DIR` |
|