mirror of
https://github.com/Kaelio/ktx.git
synced 2026-06-07 07:55:13 +02:00
254 lines
8 KiB
Text
254 lines
8 KiB
Text
---
|
|
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 \
|
|
--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 --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.
|