Start with an example

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: two small tables and one migration.

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.

$ bun create chkit@latest

$ npm create chkit@latest

$ pnpm create chkit@latest

$ yarn create chkit

Pass a project directory and select hello explicitly:

$ bun create chkit@latest my-chkit-app --example hello

$ npm create chkit@latest my-chkit-app -- --example hello

$ pnpm create chkit@latest my-chkit-app --example hello

$ yarn create chkit 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 for the other paths, including the non-interactive signup commands.

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

$ bun create chkit@latest my-chkit-app --example clickbench

$ npm create chkit@latest my-chkit-app -- --example clickbench

$ pnpm create chkit@latest my-chkit-app --example clickbench

$ yarn create chkit 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. The same hello project can be cloned from examples/hello without the scaffolder.

Run your first migration

Once the scaffold completes and a database is connected:

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:

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 — the same loop from chkit init, including an insert and a schema change
CLI reference — every command and flag
Configuration — wire up clickhouse.config.ts
Add chkit to an existing project — the other path