---
title: CLI Overview
description: Command surface of the chkit CLI.
sidebar:
  order: 1
---

import { Image } from 'astro:assets';
import commandConnections from '../../../assets/command-connections.png';

Use the `chkit` CLI to define ClickHouse schemas in TypeScript or Python, review migrations, and check for drift. Add `@chkit/plugin-ingest` to run TypeScript API readers against those tables.

## Commands

| Command | Description |
|---------|-------------|
| [`chkit init`](/cli/init/) | Scaffold a new project with config and example schema |
| [`chkit add`](/cli/add/) | Copy a provider template and wire its schema and ingestion exports into a TypeScript project |
| [`chkit registry`](/cli/registry/) | Browse apps and integration guides, inspect sync coverage, or build source templates |
| [`chkit generate`](/cli/generate/) | Diff schema definitions against the last snapshot and produce migration SQL |
| [`chkit migrate`](/cli/migrate/) | Apply pending migration files to ClickHouse |
| [`chkit status`](/cli/status/) | Show migration status (total, applied, pending, checksum mismatches) |
| [`chkit drift`](/cli/drift/) | Compare snapshot against live ClickHouse and report differences |
| [`chkit check`](/cli/check/) | Run policy checks for CI gates (pending, checksums, drift, plugins) |
| [`chkit snapshot`](/cli/snapshot/) | Rebuild `snapshot.json` from schema definitions, for example after a merge conflict (TypeScript only) |
| [`chkit query`](/cli/query/) | Run an ad-hoc SQL query against the configured target |
| [`chkit pull`](/cli/pull/) | Introspect live ClickHouse and generate a schema file |
| [`chkit codegen`](/cli/codegen/) | Generate typed row models from schema definitions |
| [`chkit plugin`](/cli/plugin/) | List or run plugin commands |
| [`chkit ingest`](/cli/ingest/) | Run, list, or inspect API sync streams (`@chkit/plugin-ingest`, TypeScript only) |

## Install an app integration

Browse the [app registry](/integrations/) for supported integrations and their complete sync guides, or discover the same apps in the terminal:

```sh
bunx chkit registry list
bunx chkit registry inspect attio
bunx chkit add attio --dry-run
bunx chkit add attio
```

These commands prepare editable source and configuration without a ClickHouse connection. Follow the app's guide to configure credentials, review and apply migrations, and run the first sync. `registry list --json` includes resource coverage and guide links for automation.

## Connection requirements

Generate migrations from local files without a connection or credentials. Configure a ClickHouse connection to apply migrations or inspect a live database.

<Image src={commandConnections} alt="Two groups of commands. No connection: generate (diff schema vs snapshot), codegen (types from schema), and editing schema files. Connects to ClickHouse: migrate (apply SQL), pull (introspect), status (read journal), check and drift (compare live DB to code)." />

| Needs a connection | Offline |
|--------------------|---------|
| `migrate` (apply SQL), `pull` (introspect), `status` (read journal), `check` / `drift` (compare live DB to code) | `generate` (diff schema vs. snapshot), `snapshot rebuild` (rewrite the snapshot from schema), `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` / `clickhouse.config.py` | Path to the chkit config file |
| `--json` | boolean | `false` | Emit machine-readable JSON output |
| `--table <selector>` | string | n/a | Narrow some commands to matching tables (exact name or trailing wildcard prefix, e.g. `events_*`). Effect varies per command: see note below |
| `--help` | boolean | n/a | Show help text |
| `--version` | boolean | n/a | Print CLI version |

The effect of `--table` depends on the command:

- `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.
- `snapshot rebuild` rejects it: a rebuild always rewrites the whole snapshot.

Check the command reference before relying on table filtering.

## 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`](/cli/migrate/#journal). |

Read debug logs from stderr and `--json` output from stdout:

```sh
CHKIT_DEBUG=1 chkit migrate --apply
```