Getting Started with ObsessionDB

Connect chkit to ObsessionDB without copying URLs or tokens by hand: scaffold a project and pick a connection in one prompt, or sign up and claim a free dev instance straight from the CLI.

Connect in one step

When you scaffold a project with bun create chkit@latest or run chkit init in an existing one, chkit asks how you want 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

• Claim a free dev instance signs you up with a one-time email code, creates a personal organization, provisions a free instance, and writes the selected service to .chkit/obsessiondb.json.
• Existing ObsessionDB account logs in and lets you pick a service.
• Existing ClickHouse instance prints the environment variables to set.

Preselect a path with --connect <claim|account|clickhouse|later> to skip the prompt — useful in scripts and non-interactive runs (see Non-interactive setup).

The rest of this page covers each path as standalone CLI commands, which is also what you run when adding ObsessionDB to a project that already exists.

Install the plugin

bun add -d @chkit/plugin-obsessiondb

Register it in your clickhouse.config.ts:

import { defineConfig } from '@chkit/core'
import { obsessiondb } from '@chkit/plugin-obsessiondb'

export default defineConfig({
  schema: './src/db/schema/**/*.ts',
  outDir: './chkit',
  plugins: [obsessiondb()],
})

You don’t need a clickhouse block — once a service is selected, the plugin routes SQL through the ObsessionDB API.

Sign up from the CLI

chkit obsessiondb signup is passwordless. It prompts for your email, sends a 6-digit code, and verifies it:

chkit obsessiondb signup

On first signup it creates a personal organization automatically. Returning users are logged straight in. Credentials are stored locally under ~/.config/chkit/ so subsequent commands don’t re-prompt.

Flag	Type	Description
--email	string	Email to sign up / log in with (skips the prompt).
--code	string	One-time code (skips the prompt). Its presence verifies without re-sending a code.
--request-only	boolean	Only send the code and print the follow-up command (step 1 of 2).
--org-name	string	Override the auto-created organization name.
--api-url	string	ObsessionDB API base URL, for non-default regions.

Claim a free instance

Once signed in, claim and provision a free dev instance:

chkit obsessiondb service claim

This checks eligibility, claims an instance, and polls until it reports running (up to a few minutes). The claimed service is written to .chkit/obsessiondb.json and becomes the default target. If your organization has already claimed its free instance, the command lists existing instances so you can select one instead.

Already have an account

Log in with the browser device-code flow instead of signing up:

chkit obsessiondb login

Verify the login:

chkit obsessiondb whoami

If you’re on a non-default ObsessionDB region, pass --api-url to login. See Services for credential storage details and how to switch regions.

Select a service

If you didn’t claim an instance during signup, list services across the organizations you belong to and pick one:

chkit obsessiondb service list
chkit obsessiondb service select

The selection is written to .chkit/obsessiondb.json next to your config file and becomes the default target for every chkit command after that.

Run your first command

Confirm the routing works:

chkit query "SELECT 1"

The query goes through the ObsessionDB API to your selected service. If it returns a row, you’re done — your schema commands (generate, migrate, status, drift, check) use the same target from here on.

Non-interactive setup

In CI, containers, and agent runs there’s no TTY to prompt against. chkit init, create-chkit, and chkit obsessiondb signup adapt instead of dead-ending.

Runbook on no TTY

When no TTY is detected and --connect isn’t given, onboarding prints every connect path as runnable commands rather than blocking on a prompt:

No TTY detected — connect a database non-interactively by running one of these:

  • Free ObsessionDB dev instance (2 steps, needs the emailed code):
      chkit obsessiondb signup --email <you@example.com>
      chkit obsessiondb signup --email <you@example.com> --code <CODE>
      chkit obsessiondb service claim

  • Existing ObsessionDB account:
      chkit obsessiondb login

  • Existing ClickHouse instance:
      set CLICKHOUSE_URL (and CLICKHOUSE_USER / CLICKHOUSE_PASSWORD / CLICKHOUSE_DB)

Two-step OTP signup

Signing up needs a code from your inbox, so the CLI splits it into two commands. Step one sends the code; step two verifies it. Passing --code skips re-sending — requesting a new code would invalidate the one you received.

# Step 1 — send the code (does not sign in)
chkit obsessiondb signup --email you@example.com --request-only

# Step 2 — verify with the emailed code (does not re-send)
chkit obsessiondb signup --email you@example.com --code 123456

# Then claim a free instance
chkit obsessiondb service claim

Structured JSON for agents

Pass --json to signup and service claim to get a machine-readable envelope instead of prose, so an agent or script can chain the flow without parsing text. Each call emits a single object with the current status and a next hint carrying the exact command to run next (next is null at a terminal state):

chkit obsessiondb signup --email you@example.com --json

{
  "command": "obsessiondb signup",
  "schemaVersion": 1,
  "status": "otp_sent",
  "email": "you@example.com",
  "next": {
    "needs": "code",
    "command": "chkit obsessiondb signup --email you@example.com --code <CODE>"
  }
}

signup moves through no_email → otp_sent → verified, and service claim reports claimed, provisioning, or already_claimed. Failures (no capacity, rate-limited, not logged in) emit a stable error envelope — { "ok": false, "error": { "code", "message" } }. In --json mode nothing else is written to stdout, so the output is always safe to pipe to jq.

Exit codes

When an explicit connect path is requested but can’t complete — for example --connect claim with no email, or a wrong code — chkit init and create-chkit exit non-zero instead of falling through to “next steps” with a success status, so scripts can detect the failure.

Next

• Engine Rewriting — what the plugin does to Shared* engines when you also target regular ClickHouse.
• Services — managing multiple services, per-command overrides, and aliases.