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

---
title: "ktx"
description: "Root command map, global options, and project resolution for the ktx CLI."
---

The `ktx` CLI sets up local projects, builds agent-ready context, checks
connections, queries semantic sources, searches wiki pages, runs the MCP
server, and manages the bundled Python runtime.

## Command signature

```bash
ktx [global-options] <command>
```

When you run bare `ktx` in an interactive terminal outside any **ktx** project, the
CLI starts the same guided setup flow as `ktx setup`. Inside an existing
project, use command-specific help:

```bash
ktx --help
ktx setup --help
ktx ingest --help
```

## Command map

```text
ktx
  setup
  connection
    list
    test [connectionId]
  ingest [connectionId]
    text [files...]
  wiki
    list
    search <query>
    read <key>
  sl
    list
    search <query>
    read <sourceName>
    validate <sourceName>
    query
  sql
  status
  mcp
    start
    stop
    status
    logs
  admin
    init [directory]
    schema
    runtime
      install
      start
      stop
      status
    reindex
  completion <shell>
```

The public context-build entrypoint is `ktx ingest [connectionId]` or
`ktx ingest --all`.

## Global options

| Flag | Description |
|------|-------------|
| `--project-dir <path>` | **ktx** project directory. Defaults to `KTX_PROJECT_DIR`, then the nearest `ktx.yaml`, then the current working directory. |
| `--debug` | Print diagnostic dispatch and project-resolution details to stderr. |
| `-v`, `--version` | Show the CLI package name and version. |
| `-h`, `--help` | Show help for the current command. |

## Update notices

> **Note:** The update notifier writes only to stderr and keeps command stdout
> unchanged.

When a newer package is available on your installed release channel, `ktx`
prints a short notice after the command finishes:

```text
↑ Update available: ktx 0.9.0 → 0.10.0
  npm i -g @kaelio/ktx
```

Stable installs compare against the npm `latest` dist-tag.
Release-candidate installs compare against the `next` dist-tag and show:

```text
npm i -g @kaelio/ktx@next
```

The check is skipped for JSON output, CI, non-TTY stdout, and hidden completion
commands. To opt out explicitly, set any of these environment variables:

```bash
KTX_NO_UPDATE_CHECK=1
NO_UPDATE_NOTIFIER=1
DO_NOT_TRACK=1
```

The `ktx` CLI prints one npm command because globally installed binaries don't
expose a reliable runtime package-manager signal. If you prefer another global
package manager, use the equivalent command:

```bash
pnpm add -g @kaelio/ktx
yarn global add @kaelio/ktx
```

## Project resolution

Most commands are project-aware. Pass `--project-dir <path>` when scripting or
when you are outside the project directory. If you omit it, **ktx** checks
`KTX_PROJECT_DIR`, then walks upward for the nearest `ktx.yaml`, then falls back
to the current directory.

## Common workflows

```bash
# Start or resume setup
ktx setup

# Check readiness
ktx status

# Build one configured connection
ktx ingest warehouse

# Build every configured connection
ktx ingest

# Search semantic sources and wiki pages
ktx sl "revenue"
ktx wiki "revenue recognition"

# Print a known wiki page or semantic source
ktx wiki read revenue-definitions
ktx sl --connection-id warehouse read orders

# Execute read-only SQL
ktx sql --connection warehouse "select count(*) from public.orders"

# Start the local MCP server for agent clients
ktx mcp start
```