ktx setup

ktx setup is the guided configuration flow for a local ktx project. It can create or resume ktx.yaml, configure LLM and embedding providers, add database and context-source connections, prepare required runtime features, build initial context, and install agent integrations.

When you run bare ktx in an interactive terminal outside any ktx project, the CLI starts this same setup flow. Inside an existing project, ktx setup resumes from incomplete setup state or opens the setup menu.

Command signature

ktx setup [options]

Visible Options

The help output intentionally keeps setup focused on the common interactive flags. Automation flags are accepted by the same command and are documented below.

Use the global --project-dir <path> option when setup should target a specific directory.

Automation Options

These flags are useful for repeatable setup in examples, tests, CI fixtures, and scripted project creation. They are not shown in ktx setup --help.

Project Creation

Setup resumes an existing ktx.yaml when one is present. When no project exists, interactive setup prompts for where to create it. In scripts, pass --project-dir <dir> --no-input --yes to create the target directory without prompts.

LLM Provider

Choose only one Anthropic credential source. Anthropic credential flags are only valid with the Anthropic backend; Vertex flags are only valid with the Vertex backend. The claude-code backend uses local Claude Code authentication instead of Anthropic API key or Vertex flags. For Claude Code, --llm-model accepts sonnet, opus, haiku, or a full Claude model ID.

Embeddings

sentence-transformers uses the ktx-managed Python runtime. Choose only one embedding credential source.

Runtime

Setup prepares the managed Python runtime when your selected configuration needs it. In the full setup flow, the runtime step runs after database and context-source setup and before the initial context build.

ktx prepares the core runtime feature when query-history ingest, Looker context-source ingest, database introspection fallback, or daemon-backed context build paths need it. ktx prepares the local-embeddings runtime feature when you choose managed local sentence-transformers embeddings. Existing external daemon URLs, such as KTX_DAEMON_URL or KTX_SQL_ANALYSIS_URL, satisfy the matching dependency and skip managed runtime installation for that dependency.

ktx setup --agents doesn't prepare runtime features or build context. It only installs agent configuration and rules. Start MCP with ktx mcp start before using HTTP-based agents; MCP startup prepares the runtime it needs.

Interactive setup prompts before installing runtime features. Use --yes to install them without prompting. Use --no-input to fail fast when required runtime features are missing.

Databases

ktx needs at least one database connection before it can build database context. Use --skip-databases only when intentionally leaving the project incomplete.

Query History

Query history setup is supported for Postgres, BigQuery, and Snowflake. The window flag applies to BigQuery and Snowflake; Postgres reads the current pg_stat_statements aggregate data instead of a time-windowed history table. Enabling query history makes deep ingest readiness matter for later ktx ingest runs.

Context Sources

Choose only one source location: --source-path or --source-git-url.

Examples

# Run the interactive setup wizard
ktx setup

# Run setup for a specific project directory
ktx setup --project-dir ./analytics

# Use Claude Code with Opus for ktx LLM calls
ktx setup \
  --project-dir ./analytics \
  --llm-backend claude-code \
  --llm-model opus

# Script a Postgres connection that reads its URL from the environment
ktx setup \
  --project-dir ./analytics \
  --no-input \
  --yes \
  --skip-llm \
  --skip-embeddings \
  --database postgres \
  --database-connection-id warehouse \
  --database-url env:DATABASE_URL \
  --database-schema public

# Enable Postgres query history while setting up a database
ktx setup \
  --project-dir ./analytics \
  --database postgres \
  --database-connection-id warehouse \
  --database-url env:DATABASE_URL \
  --enable-query-history \
  --query-history-min-executions 5

# Add a Metabase source mapped to an existing warehouse connection
ktx setup \
  --source metabase \
  --source-connection-id prod_metabase \
  --source-url https://metabase.example.com \
  --source-api-key-ref env:METABASE_API_KEY \
  --source-warehouse-connection-id warehouse \
  --metabase-database-id 1

# Install project-scoped agent integration for Codex
ktx setup --agents --target codex

Output

Interactive setup renders prompts and progress messages. Use ktx status to check setup and context readiness after setup exits.

ktx project: /home/user/analytics
Project ready: yes
LLM ready: yes (claude-sonnet-4-6)
Embeddings ready: yes (text-embedding-3-small)
Databases configured: yes (postgres-warehouse)
Context sources configured: yes (dbt-main)
Runtime ready: yes (core)
ktx context built: yes
Agent integration ready: yes (codex:project)

Use ktx status for repeatable readiness checks after setup exits.

Common errors