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
[AI Resources](/docs/community/ai-resources) instead.

<div
  className="not-prose my-8 overflow-hidden rounded-2xl border"
  style={{
    borderColor: 'color-mix(in oklch, #ff8a4d 32%, transparent)',
    background:
      'linear-gradient(135deg, color-mix(in oklch, #ff8a4d 10%, transparent) 0%, color-mix(in oklch, #ff8a4d 3%, transparent) 100%)',
  }}
>
  <div className="flex flex-col gap-6 p-5 sm:p-7 md:flex-row md:items-center md:gap-10">
    <div className="min-w-0 flex-1">
      <div
        className="text-[11px] font-black uppercase tracking-[0.16em]"
        style={{ color: '#ff8a4d' }}
      >
        Need a warehouse to play with?
      </div>
      <div className="mt-2.5 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. Hit **copy agent setup** on the page
        for a one-shot prompt that has an agent install the full four-source demo,
        or grab the raw credentials to paste into `ktx setup` yourself.
      </div>
      <a
        href="https://www.kaelio.com/start"
        className="group mt-5 inline-flex items-center gap-2 rounded-full px-4 py-2.5 text-sm font-semibold text-white no-underline shadow-[inset_0_1px_0_rgba(255,255,255,0.35),0_2px_4px_rgba(255,138,77,0.2),0_10px_24px_-8px_rgba(255,138,77,0.55)] transition-all duration-200 hover:-translate-y-0.5 hover:shadow-[inset_0_1px_0_rgba(255,255,255,0.4),0_3px_6px_rgba(255,138,77,0.28),0_16px_30px_-8px_rgba(255,138,77,0.65)]"
        style={{
          background: 'linear-gradient(180deg, #ff9d63 0%, #f97316 100%)',
        }}
      >
        Get demo credentials at www.kaelio.com/start
        <svg
          width="14"
          height="14"
          viewBox="0 0 24 24"
          fill="none"
          stroke="currentColor"
          strokeWidth="2.4"
          strokeLinecap="round"
          strokeLinejoin="round"
          className="transition-transform duration-200 group-hover:translate-x-0.5"
          aria-hidden="true"
        >
          <line x1="5" y1="12" x2="19" y2="12" />
          <polyline points="12 5 19 12 12 19" />
        </svg>
      </a>
    </div>
    <div
      className="relative grid h-[152px] w-[152px] shrink-0 grid-cols-2 grid-rows-2 gap-2.5 self-center md:h-[168px] md:w-[168px]"
      aria-hidden="true"
    >
      {[
        { src: '/ktx/icons/postgresql.svg', tint: '#e9eef5', rotate: -7, name: 'Postgres' },
        { src: '/ktx/icons/metabase.svg', tint: '#e8f1fc', rotate: 6, name: 'Metabase' },
        { src: '/ktx/icons/dbt.svg', tint: '#fde6dc', rotate: -4, name: 'dbt' },
        { src: '/ktx/icons/notion.svg', tint: '#f0eee8', rotate: 8, name: 'Notion' },
      ].map((sticker) => (
        <div
          key={sticker.name}
          className="flex items-center justify-center rounded-2xl border border-fd-border bg-fd-card shadow-[0_2px_4px_rgba(20,18,12,0.04),0_14px_28px_-12px_rgba(20,18,12,0.22)]"
          style={{ transform: `rotate(${sticker.rotate}deg)` }}
        >
          <span
            className="flex h-full w-full items-center justify-center rounded-2xl"
            style={{ background: sticker.tint }}
          >
            <img
              src={sticker.src}
              alt=""
              width="38"
              height="38"
              style={{ objectFit: 'contain' }}
            />
          </span>
        </div>
      ))}
    </div>
  </div>
</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="flex flex-wrap items-center gap-x-3 gap-y-2">
    <div className="text-sm font-semibold text-fd-foreground">
      Or, ask an AI agent to install and configure **ktx** for you.
    </div>
    <div className="group relative ml-auto inline-flex">
      <button
        type="button"
        aria-describedby="agent-setup-overlay"
        className="inline-flex cursor-help items-center gap-1.5 rounded-full border border-fd-border bg-fd-background/70 px-2.5 py-1 text-xs font-medium text-fd-muted-foreground transition-colors hover:border-fd-primary/40 hover:text-fd-foreground focus:outline-none focus-visible:border-fd-primary/40 focus-visible:text-fd-foreground"
      >
        <svg
          width="12"
          height="12"
          viewBox="0 0 24 24"
          fill="none"
          stroke="currentColor"
          strokeWidth="2.4"
          strokeLinecap="round"
          strokeLinejoin="round"
          aria-hidden="true"
        >
          <circle cx="12" cy="12" r="10" />
          <path d="M9.09 9a3 3 0 0 1 5.83 1c0 2-3 3-3 3" />
          <line x1="12" y1="17" x2="12.01" y2="17" />
        </svg>
        What does it do?
      </button>
      <div
        id="agent-setup-overlay"
        role="tooltip"
        className="invisible absolute right-0 top-full z-20 translate-y-0.5 pt-2 opacity-0 transition-all duration-150 group-hover:visible group-hover:translate-y-0 group-hover:opacity-100 group-focus-within:visible group-focus-within:translate-y-0 group-focus-within:opacity-100"
      >
        <div className="w-[min(24rem,calc(100vw-2rem))] rounded-lg border border-fd-border bg-fd-popover p-3 text-sm leading-6 text-fd-popover-foreground shadow-xl">
          <div className="text-xs font-semibold uppercase tracking-wide text-fd-muted-foreground">
            The agent will
          </div>
          <ol className="mt-2 space-y-1.5 pl-0">
            {[
              <>Check prerequisites on your machine</>,
              <>Ask only for credentials and connection choices</>,
              <>Run <code className="whitespace-nowrap">ktx setup</code> in your project</>,
              <>Verify each connection it configured</>,
              <>Report what was installed and what is ready</>,
            ].map((item, index) => (
              <li key={index} className="flex gap-2.5">
                <span
                  className="mt-0.5 inline-flex h-5 w-5 shrink-0 items-center justify-center rounded-full text-[11px] font-bold tabular-nums"
                  style={{
                    background: 'color-mix(in oklch, var(--color-fd-primary) 18%, transparent)',
                    color: 'var(--color-fd-primary)',
                  }}
                >
                  {index + 1}
                </span>
                <span className="leading-6">{item}</span>
              </li>
            ))}
          </ol>
          <div className="mt-3 border-t border-fd-border pt-2 text-xs text-fd-muted-foreground">
            Works with any AI coding agent.
          </div>
        </div>
      </div>
    </div>
  </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={[
          'Run npx skills add Kaelio/ktx --skill ktx and use the ktx skill',
          'to install and configure ktx',
        ].join(' ')}
        className="-my-1"
      />
    </div>
    <div className="p-3 font-mono text-[13.5px] leading-6 text-fd-foreground">
      Run {'`npx skills add Kaelio/ktx --skill ktx`'} and use the ktx skill to install and configure ktx
    </div>
  </div>
</div>

## Install the CLI

Install the published package globally:

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

To upgrade an existing install later, re-run with the `@latest` tag:

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

**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:
   PostgreSQL, Snowflake, BigQuery, MySQL, ClickHouse, SQL Server, SQLite, and
   DuckDB.
5. **Context sources** - optionally adds dbt, MetricFlow, LookML, Looker,
   Metabase, or Notion. You can skip and add them later.
6. **Build** - offers to run the first ingest so semantic sources and wiki
   pages are ready for agents. If you skip it, build later with `ktx ingest`.
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 admin runtime install --feature local-embeddings --yes
ktx admin 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 database scan
```

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.

When the wizard finishes, it states where you stand and the single next action:

- **Context built** - **ktx** confirms it is ready for agents and points you to
  open your coding agent and ask a data question.
- **Build skipped** - **ktx** tells you setup is complete and that the only step
  left is to build context with `ktx ingest`.

Re-running `ktx setup` on an already-configured project goes straight to the
remaining step - building context or connecting an agent - instead of
re-asking every question. Once everything is ready, it confirms you are set
rather than reopening the configuration menu.

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

If you skipped the build, `ktx context built` shows `no`. Build it with
`ktx ingest` - there is no need to re-run `ktx setup`.

When setup finishes building context, its final context check looks like:

```text
ktx context is ready for agents.

Databases:
  warehouse: database context complete

Context sources:
  dbt_main: memory update complete
```

Before the build starts, **ktx** runs a live test for every connection the
build depends on. A context build can take several minutes, so if any required
connection is unreachable or misconfigured the build is blocked up front and
**ktx** names the failing connection by id and connector type:

```text
ktx cannot build context: a required connection failed its live test.

Failed connections:
  warehouse (postgres)

Each connection must be reachable before ktx builds context.
Run `ktx connection test <id>` to see the error, fix the connection, then retry.
```

Run `ktx connection test <connection-id>` to see the underlying error, fix the
connection, then continue. In interactive setup you can retry without
restarting; with `--no-input` the build exits non-zero and names the failing
connection so scripts can stop early.

## 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.
**ktx** initializes a git repository at the project directory and writes context
changes there. If the project directory is nested inside another repository,
**ktx** still keeps its own repo and does not commit to the parent repo.

Because **ktx** owns that repository, it will not adopt one it did not create. If
you point setup at a directory that is already a git repository's root - such as
an existing application checkout - **ktx** stops and asks you to pick a dedicated
directory instead. In the setup wizard choose the **New subfolder** option (for
example `ktx-project`), or pass a fresh `--project-dir` when running setup
non-interactively.

| 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 compilation |
| `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 \
  --yes \
  --skip-llm \
  --skip-embeddings \
  --database postgres \
  --database-connection-id warehouse \
  --database-url env:DATABASE_URL \
  --database-schema public
```

Then build context:

```bash
ktx ingest warehouse
```

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 | Use the setup recovery menu to retry or re-enter details; if it still fails, verify the same connection with the database's native client |
| Context build blocked: a connection failed its live test | Run `ktx connection test <connection-id>` to see the error, fix the connection, then retry the build |
| 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.