Skip to content
ch-kit Docs

chkit plugin

Lists registered plugins, lists a plugin’s commands, or runs a specific plugin command.

Synopsis

Section titled “Synopsis”
chkit plugin                                    # list all plugins
chkit plugin <plugin-name>                      # list commands for a plugin
chkit plugin <plugin-name> <command> [args...]   # run a plugin command

Flags

Section titled “Flags”

No command-specific flags. See global flags.

Behavior

Section titled “Behavior”

List all plugins

Section titled “List all plugins”

With no arguments, lists every registered plugin with its name, version, and available commands.

List plugin commands

Section titled “List plugin commands”

With a plugin name, lists the commands available for that plugin with their descriptions.

Run a plugin command

Section titled “Run a plugin command”

With both a plugin name and command name, executes the command. Any additional arguments are forwarded to the plugin command handler.

CLI shortcuts

Section titled “CLI shortcuts”

Some plugins have top-level CLI shortcuts:

  • chkit codegen is equivalent to chkit plugin codegen codegen
  • chkit pull is equivalent to chkit plugin pull schema (TypeScript; in Python pull is a built-in command with no plugin behind it)
  • chkit ingest <subcommand> is equivalent to chkit plugin ingest <subcommand> (see chkit ingest)

Plugin registration

Section titled “Plugin registration”

Plugins are registered inline in the plugins array of your config:

import { codegen } from '@chkit/plugin-codegen'


plugins: [codegen({ outFile: './types.ts' })]

Plugin lifecycle hooks

Section titled “Plugin lifecycle hooks”

Plugins can register hooks that run at various points in the CLI lifecycle:

  • onConfigLoaded — after config is parsed
  • onSchemaLoaded — after schema definitions are loaded (can modify definitions); runs for generate and snapshot rebuild, so both write the same snapshot
  • onPlanCreated — after migration plan is computed (can modify the plan)
  • onBeforeApply — before migration SQL is executed (can transform statements)
  • onAfterApply — after migration SQL is executed
  • onCheck — during chkit check evaluation
  • onCheckReport — for custom check result formatting

onConfigLoaded and onSchemaLoaded receive the running command as context.command. During chkit snapshot rebuild it is snapshot; a hook that rewrites definitions only when the command is generate makes the rebuilt snapshot differ from the one generate writes.

Examples

Section titled “Examples”

List all plugins:

Terminal window
chkit plugin

List commands for a specific plugin:

Terminal window
chkit plugin backfill

Run a plugin command:

Terminal window
chkit plugin backfill plan --target analytics.events --from 2025-01-01 --to 2025-02-01

Exit codes

Section titled “Exit codes”
CodeMeaning
0Success
1No plugins configured, or plugin/command not found

JSON output

Section titled “JSON output”

List all plugins

Section titled “List all plugins”
{
  "command": "plugin",
  "schemaVersion": 1,
  "plugins": [
    {
      "name": "codegen",
      "version": "1.0.0",
      "commands": [
        { "name": "codegen", "description": "Generate TypeScript types" }
      ]
    }
  ]
}

List plugin commands

Section titled “List plugin commands”
{
  "command": "plugin",
  "schemaVersion": 1,
  "plugin": "backfill",
  "commands": [
    { "name": "plan", "description": "Create a backfill plan" },
    { "name": "run", "description": "Execute a backfill plan" }
  ]
}
Section titled “Related”