ktx/docs-site/content/docs/cli-reference/ktx-dev.mdx

---
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).

## Command signature

```bash
ktx dev <subcommand> [options]
```

## Subcommands

| Subcommand | Description |
|-----------|-------------|
| `init [directory]` | Initialize a Git-backed KTX project directory |
| `runtime` | Install, start, stop, and inspect the KTX-managed Python runtime |

## `dev init`

| Flag | Description | Default |
|------|-------------|---------|
| `--name <name>` | Project name written to `ktx.yaml` | — |
| `--force` | Rewrite `ktx.yaml` and scaffold files in an existing project | `false` |

## `dev runtime`

`ktx dev runtime` supports `install`, `start`, `stop`, and `status`.

| 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` | Confirm runtime install actions where supported | `false` |
| `--force` | Reinstall or restart where supported | `false` |

## Examples

```bash
ktx dev init
ktx dev init ./my-project --name "Analytics Context"
ktx dev init --force

ktx dev runtime install --yes
ktx dev runtime status
ktx dev runtime start
ktx dev runtime stop
```

## 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` |