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.

--install-dir <path>

Installs project-scoped agent configuration into the specified directory. The path is resolved against the current directory and created if it doesn't exist. Use it to install .claude/, .mcp.json, and rules where you open your agent (for example, --install-dir .). This option is mutually exclusive with --global and --local.

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 and codex backends use local authentication instead of Anthropic API key or Vertex flags. After you choose a backend, ktx setup writes that backend's per-role model preset to ktx.yaml. To change a model, edit the matching llm.models.<role> value in ktx.yaml.

With --no-input, ktx setup does not assume a default LLM provider, because every backend needs credentials only you can supply. Pass --llm-backend explicitly. Note that --target selects the agent integration, not the LLM provider: ktx setup --target claude-code --no-input still needs --llm-backend claude-code to use your Claude subscription for ktx LLM calls.

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.

--database-schema maps to the driver's scope field: schemas for PostgreSQL, MySQL, and SQL Server; schema_names for Snowflake; dataset_ids for BigQuery; and databases for ClickHouse.

A BigQuery --database-schema value may be qualified as project.dataset to scan a dataset hosted in another project (such as bigquery-public-data.austin_311); a bare value stays in the credentials' project. Setup does not discover foreign-project datasets, so supply qualified entries explicitly. See Primary sources → BigQuery.

With --no-input, scope for a scope-bearing driver (PostgreSQL, MySQL, ClickHouse, SQL Server, BigQuery, Snowflake) must come from --database-schema or from existing connection config in ktx.yaml (for example connections.<id>.dataset_ids). When neither is set, the database step fails fast and prints the missing scope flag and config key — non-interactive setup never auto-discovers and scans every schema. SQLite has no scope and is unaffected.

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. Later ktx ingest runs build enriched context and need a configured model and embeddings, including when query history is enabled.

When query history is enabled for PostgreSQL, Snowflake, or BigQuery, ktx setup runs a non-blocking readiness probe after the connection test passes. A failed probe still writes setup changes, prints the warehouse-specific grant or extension remediation, and skips query-history processing until you fix the prerequisite. If the later schema-context build also fails, interactive setup offers Disable query history and retry so you can finish database setup with connections.<id>.context.queryHistory.enabled: false.

After the schema scan completes, setup can derive query-history service-account filters from in-scope history. If ktx finds clear operational roles, it prints each proposed exclusion with a reason and writes connections.<id>.context.queryHistory.filters.serviceAccounts only when you apply the proposal. In non-interactive setup with --yes, the proposal is applied automatically. Existing serviceAccounts blocks are never overwritten.

For BigQuery, the remediation tells you to grant roles/bigquery.resourceViewer on the BigQuery project, or grant a custom role that contains bigquery.jobs.listAll.

Context Sources

In interactive setup, after you configure a database, choose Skip context sources to leave optional context-source setup complete with no sources. This is equivalent to passing --skip-sources in scripted setup.

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 for ktx LLM calls
ktx setup \
  --project-dir ./analytics \
  --llm-backend claude-code

# Configure **ktx** to use local Codex authentication for LLM work
ktx setup --llm-backend codex --no-input

When you choose --llm-backend codex, setup prints a warning if the public Codex SDK and CLI surface cannot prove full Claude-Code-style isolation. The backend restricts ktx runtime MCP tools to each run, but Codex may still load user Codex config and built-in command execution or read-only file capabilities.

# 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

# Add a Notion source that crawls selected root pages
ktx setup \
  --source notion \
  --source-connection-id notion-main \
  --source-auth-token-ref env:NOTION_TOKEN \
  --notion-crawl-mode selected_roots \
  --notion-root-page-id abc123def456

# Add a Sigma source
ktx setup \
  --source sigma \
  --source-connection-id sigma-main \
  --source-client-id your-client-id \
  --source-client-secret-ref env:SIGMA_CLIENT_SECRET

# 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