khotan-dataalpha
View as Markdown
Get Started

CLI Reference

The CLI scaffolds source files, manages the standard runtime, and returns JSON-friendly operational output that agents and scripts can use directly.

Command Types

  • 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, and flows, plus mappings.

init

terminal
$ npx khotan init
$ npx khotan init --full
$ npx khotan init --yes
  • 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, and Drizzle Kit, initializes shadcn, and scaffolds a drizzle.config.ts plus a db instance so the factory's @/db import resolves and migrate works out of the box.

add

terminal
$ npx khotan add <name> [flags]
  • -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): with 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
  • plug
  • wire
  • catch
  • pass
  • inflow
  • outflow
  • relay

UI and operations:

  • hub
  • mapping-browser
  • runs
  • logs
  • plug-debugger

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
  • debug-page-1 — ready-made /debug routes

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

generate

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

Detects your Drizzle schema directory, writes khotan table definitions, updates the Drizzle config 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

terminal
$ npx khotan migrate
$ npx khotan migrate --push

Requires DATABASE_URL. Runs generate first if the schema file does not exist.

plug

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

terminal
$ npx khotan plug --list
$ npx khotan plug <plugName> --info
$ npx khotan plug <plugName> GET /products
$ npx khotan plug <plugName> POST /items --body '{}'
$ npx khotan plug <plugName> --endpoint listProducts
$ npx khotan plug <plugName> --endpoint listProducts --compare
  • --port <n>
  • --base-path <p>
  • --list
  • --info
  • --endpoint <name>
  • --compare
  • --body <json>
  • --params <json>
  • --headers <json>

plug vars

terminal
$ 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"}'
$ npx khotan plug vars <plugName> clear

Manage stored plug variables through the standard Khotan API. This does not require KHOTAN_DEBUG=1. Secret fields are redacted by default — pass --show-secrets to reveal them in plaintext.

wire

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

terminal
$ npx khotan wire --list
$ npx khotan wire pollinate --info
$ npx khotan wire pollinate connect
$ 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

Unlike plug, wire does not require KHOTAN_DEBUG=1.

flows

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

terminal
$ 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>
  • 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>. It sets ctx.variant, which your flow 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 is a deprecated alias that maps to --variant.
  • runs — list historical runs for one flow
  • cancel — cancel a running Workflow-backed run

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.

terminal
$ 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
  • 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

terminal
$ npx khotan add skill-build
$ npx khotan add skill-setup
$ npx khotan add skill-plug
$ npx khotan add agent-skill
$ npx khotan add skill-flow
$ npx khotan add skill-webhook
$ npx khotan add skill-cache
$ npx khotan add skill-mappings
$ npx khotan add skill-frontend

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

  • .cursor/skills/...
  • .claude/skills/...
  • .agents/skills/...
  • .github/skills/...
  • .kiro/skills/...
  • .roo/rules/...

Environment Variables

  • DATABASE_URL — Postgres connection string
  • KHOTAN_SECRET — encryption key for plug and wire variables
  • KHOTAN_DEBUG — enables debug routes
  • KHOTAN_WEBHOOK_URL — public origin for default webhook callbacks
  • PORT — dev server port detection