---
title: Start with an example
description: Scaffold the hello example with create-chkit and apply its first migration.
sidebar:
  order: 1
---

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

`create-chkit` scaffolds a working chkit project by downloading a curated example from the chkit repository and wiring it up against your chosen package manager. The default example is [`hello`](https://github.com/obsessiondb/chkit/tree/main/examples/hello): two small tables and one migration.

:::note[Working in Python?]
The `create-chkit` examples are TypeScript projects. For Python, start with `pip install chkit-py` and run `chkit init` in your project instead — see the [Python overview](/python/overview/).
:::

## Prerequisites

- Node.js 20+ or Bun 1.3.5+
- A database. The scaffold prompt claims a free ObsessionDB dev instance, or set `CLICKHOUSE_URL` (and optionally `CLICKHOUSE_USER` / `CLICKHOUSE_PASSWORD`) for an existing ClickHouse.

## Scaffold a project

Run the package without arguments to be prompted for a project name and to pick from the bundled examples. `hello` is the default in the repository manifest; pass `--example hello` to select it directly.

<PackagedCommand create="chkit@latest" />

Pass a project directory and select `hello` explicitly:

<PackagedCommand create="chkit@latest" args="my-chkit-app --example hello" />

The scaffold then asks how to connect:

```
Claim a free ObsessionDB dev instance   email code, ready in seconds
I already have an ObsessionDB account    log in and pick a service
I already have a ClickHouse instance     connect with env vars
Configure later
```

Choose **Claim a free ObsessionDB dev instance** and enter the emailed code. chkit creates a personal organization, provisions a free instance, and selects it. See [Getting Started with ObsessionDB](/obsessiondb/getting-started/) for the other paths, including the non-interactive signup commands.

For the full ClickBench schema and public dataset load, pass `--example clickbench` instead:

<PackagedCommand create="chkit@latest" args="my-chkit-app --example clickbench" />

## Options

| Flag | Description |
| --- | --- |
| `[project-directory]` | Target directory. Prompted if omitted. |
| `-e, --example <name>` | Example name or full GitHub URL. Prompted with the list of bundled examples if omitted. |
| `-m, --package-manager <pm>` | `npm`, `pnpm`, `yarn`, or `bun`. Auto-detected from the invoking package manager. |
| `--skip-install` | Skip installing dependencies after scaffolding. |

## Examples

| Name | Description |
| --- | --- |
| `hello` | Two small tables and one migration. Default. Claim a free ObsessionDB instance or use local ClickHouse. |
| `clickbench` | Full ClickBench schema and dataset load against ObsessionDB or ClickHouse. |

The list and default live in [`examples/manifest.json`](https://github.com/obsessiondb/chkit/blob/main/examples/manifest.json). The same `hello` project can be cloned from [`examples/hello`](https://github.com/obsessiondb/chkit/tree/main/examples/hello) without the scaffolder.

## Run your first migration

Once the scaffold completes and a database is connected:

```sh
cd my-chkit-app
bun run migrate
bunx chkit query "SELECT name FROM system.tables WHERE database = 'default' AND name IN ('users', 'events') ORDER BY name"
```

Both tables come back, `events` then `users`. They are empty.

For a local ClickHouse instead of the claimed instance, set the endpoint before migrating:

```sh
cd my-chkit-app
export CLICKHOUSE_URL=http://localhost:8123
# export CLICKHOUSE_PASSWORD=...
bun run migrate
bunx chkit query "SELECT name FROM system.tables WHERE database = 'default' AND name IN ('users', 'events') ORDER BY name"
```

## Where to next

- [Tutorial: your first schema](/tutorials/first-schema/) — the same loop from `chkit init`, including an insert and a schema change
- [CLI reference](/cli/overview/) — every command and flag
- [Configuration](/configuration/overview/) — wire up `clickhouse.config.ts`
- [Add chkit to an existing project](/getting-started/add-to-existing-project/) — the other path