---
title: "Overview"
description: "Command map and shared options for the KTX CLI."
---

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

## 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
  dev
    init [directory]
    schema
    runtime
      install
      start
      stop
      status
```

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

# Search semantic-layer sources and wiki pages
ktx sl search "revenue"
ktx wiki search "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
```