ktx/docs-site/content/docs/getting-started/quickstart.mdx

---
title: Quickstart
description: Install KTX, run setup, and connect your coding agent.
---

import { CopyButton } from "@/components/copy-button";

This guide takes a local analytics project from empty to agent-ready. You'll
install the CLI, run one guided setup command, and hand the context to a
coding assistant.

If you're a coding assistant choosing a docs route, start with the
[Agent Quickstart](/docs/ai-resources/agent-quickstart) instead.

<div
  className="not-prose my-8 rounded-xl border p-5 sm:p-6"
  style={{
    borderColor: 'color-mix(in oklch, #ff8a4d 35%, transparent)',
    background: 'color-mix(in oklch, #ff8a4d 8%, transparent)',
  }}
>
  <div
    className="text-xs font-semibold uppercase tracking-wider"
    style={{ color: '#ff8a4d' }}
  >
    Need a warehouse to play with?
  </div>
  <div className="mt-2 text-base leading-relaxed text-fd-foreground">
    Try KTX against a real data stack - Postgres, dbt, Metabase, and Notion
    pre-loaded with the Orbit demo corpus. The page lists demo credentials
    you can paste straight into `ktx setup`.
  </div>
  <a
    href="https://kaelio.com/start"
    className="mt-4 inline-flex items-center gap-1 text-base font-semibold no-underline hover:underline"
    style={{
      color: '#ff8a4d',
      textDecorationColor: '#ff8a4d',
    }}
  >
    Get demo credentials at kaelio.com/start →
  </a>
</div>

<div
  className="not-prose my-6 rounded-lg border p-4"
  style={{
    borderColor: 'color-mix(in oklch, var(--color-fd-primary) 35%, transparent)',
    background: 'color-mix(in oklch, var(--color-fd-primary) 8%, transparent)',
  }}
>
  <div className="text-sm font-semibold text-fd-foreground">
    Run setup from an agent
  </div>
  <div className="mt-2 text-sm leading-6 text-fd-muted-foreground">
    You can ask an agent such as Claude Code, Codex, Cursor, or OpenCode to
    install and configure KTX for you. The{' '}
    <a href="/ktx/docs/agents-setup.md" className="font-medium underline">
      agent setup Markdown prompt
    </a>{' '}
    tells the agent how to check prerequisites, ask only for credentials or
    connection choices, run <code>ktx setup</code>, verify connections, and
    report the result.
  </div>
  <div className="mt-3 text-sm leading-6 text-fd-muted-foreground">
    Use a prompt like this from the project you want to configure:
  </div>
  <div className="mt-3 max-w-full overflow-hidden rounded-md border bg-fd-background">
    <div className="flex items-center justify-between gap-2 border-b px-3 py-2">
      <span className="text-xs font-semibold uppercase tracking-wide text-fd-muted-foreground">
        Prompt
      </span>
      <CopyButton
        text={`Follow instructions from
https://docs.kaelio.com/ktx/docs/agents-setup.md
to install and configure ktx`}
        className="-my-1"
      />
    </div>
    <div className="p-3 font-mono text-sm leading-6 text-fd-foreground">
      <div>Follow instructions from</div>
      <div className="break-all">https://docs.kaelio.com/ktx/docs/agents-setup.md</div>
      <div>to install and configure ktx</div>
    </div>
  </div>
</div>

## Install the CLI

Install the published package globally:

```bash
npm install -g @kaelio/ktx
```

KTX is open source. If you'd like to hack on it or run from a local checkout,
the source lives at [github.com/kaelio/ktx](https://github.com/kaelio/ktx) -
see [Contributing](/docs/community/contributing) to get set up.

## Run setup

From your project directory, run:

```bash
ktx setup
```

The wizard walks you through everything KTX needs in one pass:

1. **Project** - creates or resumes `ktx.yaml` in the current directory.
2. **LLM** - picks a Claude backend. The default uses your local Claude Code
   session, so no API key is required. You can also use an Anthropic API key
   or Vertex AI.
3. **Embeddings** - picks an embeddings backend. Choose OpenAI for hosted
   embeddings or `sentence-transformers` to run locally without an API key.
4. **Database** - adds at least one primary connection. Supported drivers:
   SQLite, PostgreSQL, MySQL, ClickHouse, SQL Server, BigQuery, and Snowflake.
5. **Context sources** - optionally adds dbt, MetricFlow, LookML, Looker,
   Metabase, or Notion. You can skip and add them later.
6. **Build** - runs the first ingest so semantic-layer sources and wiki pages
   are ready for agents.
7. **Agent integration** - installs project-local rules for Claude Code,
   Codex, Cursor, OpenCode, or universal `.agents`.

If you choose local `sentence-transformers` embeddings, KTX uses the managed
Python runtime. To prepare it before setup, run:

```bash
ktx dev runtime install --feature local-embeddings --yes
ktx dev runtime start --feature local-embeddings
```

During the database step, setup tests the saved connection and builds initial
schema context:

```text
Testing warehouse
  Connection test passed

Building schema context for warehouse
  Running fast database ingest
```

If setup exits early, rerun `ktx setup` in the same directory. KTX keeps
progress under `.ktx/setup/` and resumes from the remaining work.

> **Note:** Running bare `ktx` in an interactive terminal outside a KTX
> project opens the same wizard. Inside a project, it opens a menu for
> resuming setup, connecting an agent, checking status, or exploring a
> pre-built demo project.

## Verify

When setup finishes, check readiness:

```bash
ktx status
```

```text
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 (warehouse)
Context sources configured: yes (dbt_main)
KTX context built: yes
Agent integration ready: yes (codex:project)
```

For a structured check inside scripts, use `ktx status --json`.

When setup builds deep context, its final context check looks like:

```text
KTX context is ready for agents.

Databases:
  warehouse: deep context complete

Context sources:
  dbt_main: memory update complete
```

## Connect a coding agent

The setup wizard installs project-local agent rules in the last step. To
install or change targets later:

```bash
ktx setup --agents
```

Claude Code and Codex also support global installs with `--global`. Agent
rules point at the KTX CLI path that created them, so agents don't need a
separate `ktx` binary on `PATH`. If the CLI path changes, rerun
`ktx setup --agents`.

## What setup writes

KTX writes plain files so people and agents can review changes in git.

| Path | Purpose |
|------|---------|
| `ktx.yaml` | Project configuration |
| `.ktx/secrets/*` | Local secret files referenced from `ktx.yaml` - do not commit |
| `semantic-layer/<connection-id>/*.yaml` | Semantic sources for SQL generation |
| `wiki/global/*.md` | Shared business context and metric definitions |
| `.claude/skills/ktx/`, `.agents/skills/ktx/`, `.cursor/rules/ktx.mdc`, `.opencode/commands/ktx.md` | Installed agent rules |

## Scripted setup

For repeatable fixtures and automation, skip prompts with flags:

```bash
ktx setup \
  --project-dir ./analytics \
  --no-input \
  --skip-llm \
  --skip-embeddings \
  --database postgres \
  --new-database-connection-id warehouse \
  --database-url env:DATABASE_URL \
  --database-schema public
```

Then build context:

```bash
ktx ingest warehouse --fast
```

See [ktx setup](/docs/cli-reference/ktx-setup) for the full automation flag
surface.

## Common issues

| Symptom | Fix |
|---------|-----|
| `ktx: command not found` | Reinstall `@kaelio/ktx` and open a new shell |
| Setup resumes the wrong project | Pass `--project-dir <path>` |
| LLM or embeddings health check fails | Rerun setup and pick a different credential, model, or backend |
| Database test fails | Verify the same connection with the database's native client, then rerun setup |
| Agent integration is incomplete | Run `ktx setup --agents --target <target>` |

## Next steps

- Refresh context with [Building Context](/docs/guides/building-context).
- Edit semantic sources and wiki pages with
  [Writing Context](/docs/guides/writing-context).
- Connect more tools with [Agent Clients](/docs/integrations/agent-clients).
- Read [The Context Layer](/docs/concepts/the-context-layer) to understand
  the architecture.