mirror of
https://github.com/Kaelio/ktx.git
synced 2026-06-07 07:55:13 +02:00
d1c84e5564
* fix: improve setup wizard behavior * fix: derive runtime versions from release metadata * test: validate metabase source mapping requirements * Fix boundary check release identifiers
91 lines
3.2 KiB
Text
91 lines
3.2 KiB
Text
---
|
|
title: "ktx dev"
|
|
description: "Low-level project initialization and runtime management."
|
|
---
|
|
|
|
`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
|
|
|
|
```bash
|
|
ktx dev <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 |
|
|
|
|
## `dev init`
|
|
|
|
| Flag | Description | Default |
|
|
|------|-------------|---------|
|
|
| `--force` | Rewrite `ktx.yaml` and scaffold files in an existing project | `false` |
|
|
|
|
## `dev schema`
|
|
|
|
`ktx dev 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 | — |
|
|
|
|
## `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` | 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 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 |
|