CLI Overview

The chkit CLI manages ClickHouse schemas, migrations, drift detection, and CI checks from the command line. It follows a workflow-oriented design: define your schema in TypeScript, generate migrations, apply them, and verify everything stays in sync.

Commands

Command	Description
chkit init	Scaffold a new project with config and example schema
chkit generate	Diff schema definitions against the last snapshot and produce migration SQL
chkit migrate	Apply pending migration files to ClickHouse
chkit status	Show migration status (total, applied, pending, checksum mismatches)
chkit drift	Compare snapshot against live ClickHouse and report differences
chkit check	Run policy checks for CI gates (pending, checksums, drift, plugins)
chkit query	Run an ad-hoc SQL query against the configured target
chkit pull	Introspect live ClickHouse and generate a TypeScript schema file
chkit codegen	Generate TypeScript types from schema definitions
chkit plugin	List or run plugin commands

Connection requirements

Some commands run entirely against local files; others read or write a live ClickHouse instance. Generating a migration is offline, so it needs no connection or credentials. Applying one, or introspecting a live database, connects.

Needs a connection	Offline
migrate (apply SQL), pull (introspect), status (read journal), check / drift (compare live DB to code)	generate (diff schema vs. snapshot), codegen (types from schema), editing schema files

Typical workflow

chkit init          # scaffold config + example schema
chkit generate      # diff schema → produce migration SQL + snapshot
chkit migrate       # apply pending migrations to ClickHouse
chkit status        # verify migration state
chkit check         # CI gate: pending, checksums, drift, plugins

Global flags

These flags are available on every command that loads a config file:

Flag	Type	Default	Description
--config <path>	string	clickhouse.config.ts	Path to the chkit config file
--json	boolean	false	Emit machine-readable JSON output
--table <selector>	string	—	Narrow some commands to matching tables (exact name or trailing wildcard prefix, e.g. events_*). Effect varies per command — see note below
--help	boolean	—	Show help text
--version	boolean	—	Print CLI version

--table is accepted by every command, but it is not a universal, whole-command filter — treat it as a scoping hint, not a guarantee:

• generate, migrate, and drift use it to narrow the schema/migration operations they plan or evaluate.
• check applies it only to its drift and plugin checks; the pending-migration and checksum checks still run across all tables, so chkit check --table app.users can still fail on an unrelated pending migration.
• status, codegen, and pull accept the flag but ignore it, so chkit status --table app.users still reports unscoped totals.

When you need a result strictly limited to specific tables, check the individual command’s page for its exact scoping behavior.

Environment variables

These environment variables affect every command:

Variable	Description
CHKIT_DEBUG	Set to 1 or true to emit structured debug logging to stderr. Covers config loading, command dispatch, plugin lifecycle hooks, ClickHouse queries with timing, journal operations, and per-command details.
CHKIT_JOURNAL_TABLE	Override the name of the migration journal table (default _chkit_migrations). See chkit migrate.

Debug logging is written to stderr, so it never contaminates --json output on stdout:

CHKIT_DEBUG=1 chkit migrate --apply