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>
  sl
    list
    search <query>
    validate <sourceName>
    query
  sql
  status
  mcp
    start
    stop
    status
    logs
  admin
    init [directory]
    schema
    runtime
      install
      start
      stop
      status
    reindex
```

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

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

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

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