mirror of
https://github.com/Kaelio/ktx.git
synced 2026-06-07 07:55:13 +02:00
a11b9e9757
* chore: standardize daemon naming on "KTX daemon"
Replace inconsistent names ("KTX Python daemon", "KTX local embeddings
daemon", "KTX managed daemon", "Python daemon") with the single name
"KTX daemon" in CLI output, errors, command descriptions, test
assertions, smoke scripts, docs, AGENTS.md, issue templates, and
codecov flags. The daemon is a portable compute server with endpoints
for SQL analysis, semantic layer, LookML, database introspection, and
embeddings; the previous labels misrepresented it as embeddings-only or
exposed implementation details ("Python", "managed").
The "KTX Python runtime" concept (installed interpreter + packages) is
deliberately left as-is — it is a separate concept from the daemon
process.
* refactor(release): drop release-policy.json runtime dep and next branch
Strips the release-policy.json fallback from release-version.ts so the CLI
reads its version straight from packages/cli/package.json. dev → 0.0.0-private,
installed @kaelio/ktx → the real semver baked into the published package.json.
KtxCliPackageInfo collapses to { name, version, contextPackageName }; /health
no longer depends on version files surviving past a CI run.
Replaces the dual-branch (main + next) semantic-release model with a single-
branch model on main. rcs and stables interleave on the same branch via
{ name: 'main', prerelease: 'rc', channel: 'next' } / ['main']. Drops
@semantic-release/git and @semantic-release/changelog (nothing is committed
back to the repo on any channel) and the workflow's "Prepare next prerelease
branch" step plus the KTX_PRERELEASE_BRANCH plumbing. The git tag plus the
published npm artifact carry the version forward.
Updates docs/release.md, removes the two now-unused devDeps, regenerates
pnpm-lock.yaml. 611/611 @ktx/cli tests, 173/173 script tests, type-check,
biome, knip all clean.
* fix(release): don't throw on non-main branches at config-load time
knip loads .releaserc.cjs on every PR run, where GITHUB_REF_NAME is the
merge ref (e.g. 180/merge). The previous version of releaseBranches threw
immediately when the branch wasn't main, which made knip fail to evaluate
the config and then mis-flag @semantic-release/exec as an unused dep.
semantic-release already refuses to publish when the current branch doesn't
match a configured release branch, so the explicit throw was redundant.
Drop it (and the unused currentBranch helper) and replace the
"rejects releases from non-main" assertion with one that exercises a CI-
shaped GITHUB_REF_NAME and confirms the config loads.
121 lines
4.4 KiB
Text
121 lines
4.4 KiB
Text
---
|
|
title: "ktx admin"
|
|
description: "Low-level project initialization, runtime, and index management."
|
|
---
|
|
|
|
`ktx admin` contains low-level project initialization, managed Python runtime,
|
|
and local index management commands. Context building lives at the root as
|
|
[`ktx ingest`](/docs/cli-reference/ktx-ingest). Most users should start with
|
|
`ktx setup`; use `ktx admin` when preparing local fixtures, checking the bundled
|
|
runtime, rebuilding local indexes, or debugging runtime state.
|
|
|
|
## Command signature
|
|
|
|
```bash
|
|
ktx admin <subcommand> [options]
|
|
```
|
|
|
|
## Subcommands
|
|
|
|
| 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 |
|
|
| `reindex` | Sync local wiki and semantic-layer search indexes from disk |
|
|
|
|
## `admin init`
|
|
|
|
| Flag | Description | Default |
|
|
|------|-------------|---------|
|
|
| `--force` | Rewrite `ktx.yaml` and scaffold files in an existing project | `false` |
|
|
|
|
## `admin schema`
|
|
|
|
`ktx admin schema` does not require a `ktx.yaml` file or a configured project
|
|
directory. Use it from any directory to generate editor or agent schema files.
|
|
|
|
| Flag | Description | Default |
|
|
|------|-------------|---------|
|
|
| `--output <file>` | Write the schema to a file instead of stdout | - |
|
|
|
|
## `admin runtime` Subcommands
|
|
|
|
| Subcommand | Description |
|
|
|-----------|-------------|
|
|
| `install` | Install the bundled Python runtime wheel into the managed runtime |
|
|
| `start` | Start the KTX daemon |
|
|
| `stop` | Stop the KTX daemon |
|
|
| `status` | Show managed Python runtime status and readiness checks |
|
|
|
|
## `admin 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` | 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
|
|
|
|
```bash
|
|
ktx admin init
|
|
ktx admin init ./my-project
|
|
ktx admin init --force
|
|
|
|
ktx admin schema
|
|
ktx admin schema --output ./ktx.schema.json
|
|
|
|
ktx admin runtime install --yes
|
|
ktx admin runtime install --feature local-embeddings --yes
|
|
ktx admin runtime status
|
|
ktx admin runtime start
|
|
ktx admin runtime start --feature local-embeddings
|
|
ktx admin runtime stop
|
|
ktx admin runtime stop --all
|
|
|
|
ktx admin reindex
|
|
ktx admin reindex --force
|
|
ktx admin reindex --output plain
|
|
ktx admin reindex --json
|
|
```
|
|
|
|
## Output
|
|
|
|
Runtime commands print the runtime root, installed features, daemon URL, daemon
|
|
pid, and log paths where relevant. `ktx admin runtime status --json` includes the
|
|
runtime status plus readiness checks.
|
|
|
|
## `admin reindex`
|
|
|
|
`ktx admin reindex` syncs local wiki and semantic-layer search indexes from
|
|
files on disk into `.ktx/db.sqlite`. The command discovers `wiki/global/`, each
|
|
`wiki/user/<userId>/` directory, and each `semantic-layer/<connectionId>/`
|
|
directory except `_schema`.
|
|
|
|
```bash
|
|
ktx admin reindex
|
|
ktx admin reindex --force
|
|
ktx admin reindex --output plain
|
|
ktx admin reindex --json
|
|
```
|
|
|
|
By default, KTX compares stored search text with the files on disk. It only
|
|
re-embeds changed rows and removes rows for files that no longer exist. With
|
|
`--force`, KTX clears each discovered scope first and then rebuilds it.
|
|
|
|
When embeddings are not configured, KTX still writes lexical FTS rows and
|
|
prints an embeddings warning. If a scope fails, KTX keeps processing the
|
|
remaining scopes and exits with code `1` after output is written. If the local
|
|
state database cannot open or the configured managed embedding runtime is
|
|
missing, KTX prints the error and exits with code `1`.
|
|
|
|
## 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 admin runtime status` |
|
|
| Runtime daemon does not start | The managed Python runtime is missing or stale | Run `ktx admin runtime install --yes`, then `ktx admin runtime start` |
|
|
| Multiple daemon processes remain | Older daemon state files or stray processes exist | Run `ktx admin runtime stop --all`, then start the runtime again |
|