---
title: Add to an existing project
description: Install chkit into an existing TypeScript project and run the first migration flow.
sidebar:
  order: 2
---

import PackagedCommand from '../../../components/PackagedCommand.astro';
import Command from '../../../components/Command.astro';

Install chkit alongside your existing application code, drop a minimal config and starter schema into the current directory, and produce your first migration. Use this path when you already have a TypeScript project that talks to ClickHouse.

## Prerequisites

- Node.js 20+ or Bun 1.3.5+
- A ClickHouse endpoint (`CLICKHOUSE_URL`, optionally `CLICKHOUSE_USER`, `CLICKHOUSE_PASSWORD`, `CLICKHOUSE_DB`)

## 1. Install chkit

Add `chkit` and `@chkit/core` as dev dependencies:

<PackagedCommand install="chkit @chkit/core" dev />

## 2. Initialize the config

`chkit init` writes `clickhouse.config.ts` (config with sensible defaults) and `src/db/schema/example.ts` (a starter `MergeTree` table). It's idempotent — running it on an existing project leaves both files untouched.

<PackagedCommand exec="chkit init" />

Edit `src/db/schema/example.ts` to match the table you actually want before moving on.

:::note
On an interactive run, `chkit init` also offers to connect a database — including claiming a **free ObsessionDB dev instance** with a one-time email code, no local ClickHouse required. This guide wires up a connection with environment variables instead (the steps below); pass `--yes` to skip the prompt. See [Getting Started with ObsessionDB](/obsessiondb/getting-started/) for the connect paths, or the [first-schema tutorial](/tutorials/first-schema/) for an end-to-end walkthrough using the free instance.
:::

## 3. Generate the initial migration

`chkit generate` diffs your schema definitions against the previous snapshot and writes migration SQL into `chkit/migrations/`. Pass `--name` to label the migration file.

<PackagedCommand exec="chkit generate --name init" />

## 4. Apply the migration

`chkit migrate --apply` runs unapplied migrations against the ClickHouse endpoint from your environment. Make sure `CLICKHOUSE_URL` (and any auth env vars) are set before running this.

<PackagedCommand exec="chkit migrate --apply" />

## 5. Verify

`chkit status` shows which migrations have been applied. `chkit check` confirms the live schema matches your TypeScript definitions.

<PackagedCommand exec="chkit status" />
<PackagedCommand exec="chkit check" />

## AI agent skill

chkit ships an agent skill so AI coding assistants (Claude Code, Cursor, GitHub Copilot, Codex, Windsurf, and others) understand chkit commands, schema DSL, and workflows.

On the first interactive run, chkit detects your agent and prompts to install the skill. To install it manually at any time:

<PackagedCommand exec="skills add obsessiondb/chkit" />

The skill is installed into your project's agent directory (e.g. `.claude/skills/chkit/`, `.cursor/skills/chkit/`).

## Where to next

- [CLI reference](/cli/overview/) — every command and flag
- [Configuration](/configuration/overview/) — wire up `clickhouse.config.ts`
- [Schema DSL](/schema/dsl-reference/) — define tables, views, and materialized views
- [Start with an example](/getting-started/with-an-example/) — the other path