---
title: CLI Reference
description: All khotan CLI commands — init, add, generate, migrate, plug, plug vars, wire, flows, and mappings.
section: Get Started
url: /docs/cli
---

# CLI Reference

All khotan CLI commands. The CLI is designed to scaffold source files, manage the standard runtime, and return JSON-friendly operational output that agents and scripts can use directly.

## Command Types

Think of the CLI in four groups:

- **Project setup**: `init`
- **Scaffolding**: `add`
- **Schema management**: `generate`, `migrate`
- **Runtime operations**: `plug`, `plug vars`, `wire`, `flows`, `mappings`

Rule of thumb:

- If you are creating files, use `add`.
- If you are applying DB table changes, use `generate` or `migrate`.
- If you are debugging or operating live integrations, use `plug`, `wire`, `flows`, and `mappings`.

## init

Initialize khotan in your project.

```bash
npx khotan init          # Minimal: config + core files
npx khotan init --full   # Full: + drizzle, shadcn, all deps
npx khotan init --yes    # Auto-accept agent skills prompt
```

Creates, without overwriting existing files:

| File | Purpose |
|------|---------|
| `khotan.config.ts` | CLI config that sets `outputDir` |
| `{outputDir}/khotan.ts` | Factory config where you register resources and plugs |
| `src/app/api/khotan/[...all]/route.ts` or `app/api/khotan/[...all]/route.ts` | Catch-all runtime route |
| `AGENTS.md` | Root router for built-in khotan skills when skills are installed |

The `--full` flag also installs Drizzle, Postgres, Drizzle Kit, initializes shadcn, and installs the shadcn components khotan commonly uses. It additionally scaffolds a `drizzle.config.ts` and a `db` instance (`src/db/index.ts` or `db/index.ts`) so the factory's `@/db` import resolves and `migrate` works out of the box.

## add

Scaffold a component, block, or agent skill into your project.

```bash
npx khotan add <name> [flags]
```

| Flag | Description |
|------|-------------|
| `-f, --force` | Overwrite existing files |
| `-y, --yes` | Auto-accept all prompts |
| `--without-ui` | Skip React component scaffolding |

`add` is safe to run non-interactively (agents, CI, piped stdin): when there is no TTY it skips existing files instead of blocking on an overwrite prompt — pass `--force` to overwrite. `add schema` also never writes over your factory config: with no `drizzle.config.ts` it falls back to a conventional `db/schema` directory.

### Installable components

#### Data and runtime foundations

- `schema` — Drizzle table definitions for khotan
- `plug` — HTTP client with auth, retry, pagination, vars, hooks, and endpoint metadata
- `wire` — webhook subscription lifecycle and signature verification hooks
- `catch` — durable webhook event processing
- `pass` — durable webhook event forwarding
- `inflow` — durable external-service to app data flow
- `outflow` — durable app to external-service data flow
- `relay` — durable external-service to external-service data flow

#### UI and operations

- `hub` — dashboard UI for plugs and flows
- `mapping-browser` — reusable mappings browser UI
- `runs` — run history UI
- `logs` — combined runs and webhook events UI
- `plug-debugger` — interactive debug panel for plug requests

#### Built-in agent skills

- `skill-build` — end-to-end integration workflow (orchestrator)
- `skill-setup`
- `skill-plug`
- `agent-skill`
- `skill-flow`
- `skill-webhook`
- `skill-cache`
- `skill-mappings`
- `skill-frontend`

### Installable blocks

- `config-page-1` — ready-made `/config` page with Hub
- `mappings-page-1` — ready-made `/mappings` page with the mappings browser
- `graph` — ready-made `/graph` page with topology canvas
- `logs-page-1` — ready-made `/logs` page with runs and webhook events
- `debug-page-1` — ready-made `/debug` and `/debug/[plugName]` routes

Components auto-resolve dependencies. Running `npx khotan add wire --yes` will also add `plug` and `schema` if missing.

## generate

Scaffold the Drizzle schema file for khotan tables.

```bash
npx khotan generate           # non-destructive — refuses to clobber
npx khotan generate --force   # overwrite an existing schema file
```

Detects your Drizzle schema directory, writes `khotan.ts` with table definitions, updates `drizzle.config.ts` glob if needed, and adds the barrel re-export.

`generate` is non-destructive: if the schema file already exists it stops and asks you to pass `--force` (or `--yes`) rather than overwriting your edits.

## migrate

Generate and apply database migrations for khotan tables.

```bash
npx khotan migrate          # drizzle-kit generate + migrate
npx khotan migrate --push   # drizzle-kit push (no migration files)
```

Requires `DATABASE_URL`. Runs `generate` first if the schema file doesn't exist.

## plug

Inspect and test plugs through the debug route. Output is JSON on stdout.

Requires a running dev server with `KHOTAN_DEBUG=1`.

`probe` remains available as a legacy alias, but `plug` is the canonical command name.

```bash
npx khotan plug --list                              # List all plugs
npx khotan plug <plugName> --info                  # Show plug metadata + endpoints
npx khotan plug <plugName> GET /products           # Fire a GET request
npx khotan plug <plugName> POST /items --body '{}' # Fire with body
npx khotan plug <plugName> --endpoint listProducts # Fire via named endpoint
npx khotan plug <plugName> --endpoint listProducts --compare  # Compare response vs schema
```

| Flag | Description |
|------|-------------|
| `--port <n>` | Dev server port (default: `.env.local` → `.env` → 3000) |
| `--base-path <p>` | API base path (default: `/api/khotan`) |
| `--list` | List registered plugs |
| `--info` | Show plug metadata and endpoints |
| `--endpoint <name>` | Resolve method + path from a named endpoint |
| `--compare` | Diff response body against declared Zod schema |
| `--body <json>` | Request body (JSON string) |
| `--params <json>` | Query params (JSON string) |
| `--headers <json>` | Extra headers (JSON string) |

### plug vars

Manage stored plug variables through the standard Khotan API. This does not require `KHOTAN_DEBUG=1`.

```bash
npx khotan plug vars --list
npx khotan plug vars <plugName>
npx khotan plug vars <plugName> --show-secrets
npx khotan plug vars <plugName> set --json '{"apiKey":"secret","orgId":"org_live"}'
npx khotan plug vars <plugName> clear
```

Code-defined var `defaultValue`s are seeded into the database on init. After that, Hub and CLI updates edit the stored DB value. Secret fields are redacted in read output by default — pass `--show-secrets` to reveal them in plaintext.

| Action | Behavior |
|--------|----------|
| `--list` | List all plugs and their current variable state |
| `<plugName>` | Show masked values and var field metadata |
| `set --json '{...}'` | Merge new values into existing stored values |
| `clear` | Remove all stored values for the plug |

### Plug output

Fire mode returns:

```json
{
  "ok": true,
  "request": { "method": "GET", "path": "/products", "params": null, "body": null },
  "response": { "status": 200, "timing": 342, "size": "1.4kb", "body": { ... } },
  "matchedEndpoint": "listProducts"
}
```

With `--compare`, adds a `comparison` object:

```json
{
  "comparison": {
    "match": false,
    "mismatches": [
      { "path": "$.total", "issue": "missing" },
      { "path": "$.count", "issue": "extra" }
    ]
  }
}
```

Mismatch issues: `missing` (in schema, not in response), `extra` (in response, not in schema), `type_mismatch` (same key, different type). Paths use JSONPath notation.

## wire

Inspect, connect, and disconnect wires through the running Khotan API. Output is JSON on stdout.

Unlike `plug` request/debug mode, `wire` does not require `KHOTAN_DEBUG=1` because it talks to the standard `/api/khotan/wires/*` routes.

```bash
npx khotan wire --list                                           # List plugs + wire state
npx khotan wire pollinate --info                                 # Show current wire record
npx khotan wire pollinate connect                                # Register using KHOTAN_WEBHOOK_URL
npx khotan wire pollinate connect --webhook-origin https://x.ngrok.app
npx khotan wire pollinate connect --callback-url https://x.ngrok.app/api/khotan/webhook/pollinate
npx khotan wire pollinate disconnect                             # Remove current wire
```

Default callback URLs always use the catch-all webhook route:

```text
<origin>/api/khotan/webhook/<plugName>
```

That means one public endpoint per source plug, with fan-out to any number of internal `catch` and `pass` handlers behind it.

| Flag | Description |
|------|-------------|
| `--port <n>` | Dev server port (default: `.env.local` → `.env` → `3000`) |
| `--base-path <p>` | API base path (default: `/api/khotan`) |
| `--list` | List registered plugs and whether they have a wire |
| `--info` | Show current wire state for the plug |
| `--callback-url <url>` | Explicit callback URL to register |
| `--webhook-origin <url>` | Origin used to build the default callback URL |
| `--wire-id <id>` | Explicit wire ID to disconnect (otherwise current wire is used) |

## flows

Inspect and operate registered flows through the running Khotan API. Output is JSON on stdout.

```bash
npx khotan flows list
npx khotan flows list --plug pollinate
npx khotan flows info pollinate-products --plug pollinate
npx khotan flows trigger pollinate-products --plug pollinate --variant full
npx khotan flows trigger pollinate-products --plug pollinate --variant delta
npx khotan flows runs pollinate-products --plug pollinate
npx khotan flows cancel <runId>
```

Subcommands:

- `list` — list all registered flows, optionally scoped to one plug
- `info` — show one flow by name or ID
- `trigger` — start a run for a variant (run mode). Pass the variant as a positional argument (`khotan flows trigger <flow> delta`) or via `--variant <name>`. The variant sets `ctx.variant`, which your flow code branches on to control what gets fetched, written, or skipped (e.g. `default`, `delta`, `full`, `healthcheck`). With no variant, the `default` variant runs. `--run-type <type>` is accepted as a **deprecated** alias that maps to `--variant`.
- `runs` — list historical runs for one flow
- `cancel` — cancel a running Workflow-backed run by khotan run ID

## mappings

Inspect and operate first-class mappings through the running Khotan API. All mappings commands emit JSON on stdout for both success and failure cases.

```bash
npx khotan mappings list customers
npx khotan mappings list customers --limit 25 --offset 50 --search "alice@example.com"
npx khotan mappings lookup customers --connect-value "alice@example.com"
npx khotan mappings lookup customers --plug shopify --ref "gid://shopify/Customer/123"
npx khotan mappings upsert customers --connect-value "alice@example.com" --refs '{"shopify":"gid://shopify/Customer/123"}'
npx khotan mappings update mapping-1 --resource customers --connect-value "alice@example.com" --refs '{"shopify":"gid://shopify/Customer/123","cin7":"cust_456"}'
npx khotan mappings delete mapping-1
```

Subcommands:

- `list` — resolve a resource by name, then return paginated mapping rows plus paging metadata
- `lookup` — resolve one mapping either by canonical `connectValue` or by `plug + ref`
- `upsert` — create or update one mapping using `connectValue`, `refs`, and optional `metadata`
- `update` — replace one mapping row by ID
- `delete` — delete one mapping row by ID

Notes:

- `list`, `lookup`, and `upsert` resolve the resource from the registered runtime config before issuing the request
- `--refs` and `--metadata` accept JSON objects
- composite resource identities still resolve to one canonical stored `connectValue`

## Agent Skills

Install agent skills to teach AI assistants how to work with khotan:

```bash
npx khotan add skill-build        # End-to-end integration workflow (orchestrator)
npx khotan add skill-setup        # Project setup guidance
npx khotan add skill-plug         # Plug authoring guidance
npx khotan add agent-skill        # Plug CLI guidance
npx khotan add skill-flow         # Inflow/outflow/relay guidance
npx khotan add skill-webhook      # Webhook/wire guidance
npx khotan add skill-cache        # Caching guidance
npx khotan add skill-mappings     # Resource/mappings guidance
npx khotan add skill-frontend     # Frontend components/blocks guidance
```

During `npx khotan init`, khotan prompts to install all skills automatically. With `--yes`, that prompt is auto-accepted.

Skills install to all detected agent directories:

- `.cursor/skills/...`
- `.claude/skills/...`
- `.agents/skills/...`
- `.github/skills/...`
- `.kiro/skills/...`
- `.roo/rules/...`

If no agent directories are detected, khotan defaults to Cursor plus Claude Code.

## Environment Variables

| Variable | Used by | Purpose |
|----------|---------|---------|
| `DATABASE_URL` | migrate | Postgres connection string |
| `KHOTAN_SECRET` | runtime | Encryption key for plug and wire variables |
| `KHOTAN_DEBUG` | plug, debugger | Enables debug routes |
| `KHOTAN_WEBHOOK_URL` | wire | Public origin for default webhook callbacks |
| `PORT` | plug, wire | Dev server port detection |