CLI Reference

Complete reference for creating, validating, testing, inspecting, and deploying Kite projects.

The Kite CLI manages the complete configuration workflow:

init -> validate -> dev -> diff -> deploy -> inspect

Install it globally and authenticate before working with Kite Cloud:

npm install --global @kitesdk/cli
kite auth login
kite whoami

See Installation for runtime requirements and troubleshooting.

Command overview

Command	Purpose
`kite auth`	Log in, inspect the current identity, or log out.
`kite init`	Create a project and generate a functional local model.
`kite validate`	Compile and validate local configuration.
`kite dev`	Run the event and state engine locally.
`kite deploy`	Deploy local configuration to `test` or `live`.
`kite config`	Diff, list, promote, pull, or roll back versions.
`kite events`	Send, list, or stream product events.
`kite customers`	List customers or inspect complete customer state.
`kite journeys`	Inspect a customer's journey progress.
`kite segments`	Inspect segment membership and statistics.
`kite rules`	Inspect rule execution logs.
`kite health`	Explain a customer's health score.
`kite diagnose`	Check project configuration and data.
`kite recompute`	Rebuild customer state from event history.
`kite ai`	Model, explain, and debug with sanitized project context.

Run kite <command> --help or kite <group> <command> --help for help from the installed version.

Option	Behavior
`--directory <path>`	Use a Kite project outside the current directory. Defaults to `.`.
`--env <environment>`	Target `test` or `live`. Defaults to `defaultEnvironment` in `.kite/config.json`.
`--json`	Print machine-readable output. Also formats command errors as JSON.
`--debug`	Print stack traces for errors. Place it before the command.

Use test while developing. Commands that can change shared state require confirmation where appropriate. --yes bypasses standard confirmation, but live deployment and promotion still require typing live.

Authentication

Starts browser-based device authentication and stores a revocable local session.

kite auth login

`kite whoami`

Shows the current user, organization, and API. kite auth status is equivalent.

kite whoami
kite auth status

`kite auth logout`

Revokes and removes the current local session.

kite auth logout

Project setup

`kite init`

Creates a remote Kite project and writes a complete starter model to an empty directory.

kite init [options]

Option	Description
`--name <name>`	Project display name.
`--slug <slug>`	Lowercase project identifier.
`--stack <stack>`	Primary stack: `node` or `python`.
`--env <environment>`	Initial default: `test` or `live`.
`--directory <path>`	Directory where files are generated.
`-y, --yes`	Accept supplied values and defaults without prompting.

kite init --name "Acme" --slug acme --stack node --env test --directory ./acme-kite --yes

The command prints test and live API keys once. Store them in a secret manager.

`kite validate`

Compiles every configured TypeScript source and checks schemas and cross-file references. It does not deploy configuration.

kite validate [--strict] [--json]

Option	Description
`--strict`	Treat warnings as validation errors.
`--directory <path>`	Kite project directory.
`--json`	Print the validation result as JSON.

Use strict validation in CI:

kite validate --strict --json

`kite dev`

Runs an in-memory event and state engine. Configuration reloads when a source file changes.

kite dev [--port 4401] [--no-watch]

Option	Default	Description
`--port <port>`	`4401`	Local HTTP port.
`--no-watch`	off	Disable automatic configuration reload.
`--directory <path>`	`.`	Kite project directory.

The local API accepts events at POST /events and POST /v1/events. Its state is disposable and resets when the process stops.

Events

`kite events send`

Sends one event to the selected environment.

kite events send <event> --customer <customerId> [options]

Option	Description
`--customer <customerId>`	Required stable customer ID.
`--props <json>`	Event properties as a JSON object.
`--idempotency-key <key>`	Key used to deduplicate retries.
`--env <environment>`	`test` or `live`.
`--json`	Print the API response as JSON.

kite events send feature.used \
  --customer customer_123 \
  --props '{"feature":"reports"}' \
  --idempotency-key usage_456 \
  --env test

`kite events list`

Lists ingested events with optional filters and cursor pagination.

kite events list [options]

Option	Default	Description
`--customer <customerId>`	all	Filter by customer.
`--type <event>`	all	Filter by event type.
`--status <status>`	all	`processed` or `pending`.
`--since <durationOrDate>`	all	Duration such as `7d`, or an ISO date.
`--limit <number>`	`20`	Maximum events returned.
`--cursor <cursor>`	none	Continue a paginated result.

kite events list --type feature.used --since 7d --env test

`kite events tail`

Streams events as Kite processes them. Press Ctrl+C to stop.

kite events tail [--customer <customerId>] [--type <event>] [--env test]

Customer state

`kite customers list`

kite customers list [options]

Option	Default	Description
`--lifecycle <state>`	all	Filter by lifecycle state.
`--segment <segmentId>`	all	Filter by segment membership.
`--inactive <duration>`	all	Filter by inactivity, for example `7d`.
`--limit <number>`	`50`	Maximum customers returned.
`--cursor <cursor>`	none	Continue a paginated result.

`kite customers inspect`

Shows complete computed state for one customer.

kite customers inspect <customerId> [--env test] [--json]

Decision inspection

Use focused commands to understand how Kite reached a result:

kite journeys inspect <customerId> <journeyId> [--env test] [--json]
kite segments inspect <segmentId> [--limit 50] [--cursor <cursor>] [--env test] [--json]
kite health explain <customerId> [--env test] [--json]

journeys inspect includes progress and step timing. segments inspect lists members and aggregate statistics. health explain shows the factors behind the current score.

`kite rules logs`

Lists rule evaluations and optionally expands their conditions and actions.

kite rules logs [options]

Option	Default	Description
`--customer <customerId>`	all	Filter by customer.
`--rule <ruleId>`	all	Filter by rule.
`--result <result>`	all	`pass`, `fail`, `skip`, or `error`.
`--since <durationOrDate>`	all	Duration such as `7d`, or an ISO date.
`--limit <number>`	`50`	Maximum logs returned.
`--detail`	off	Show condition and action details.

kite rules logs --customer customer_123 --result fail --detail --env test

Deployments

`kite deploy`

Validates and deploys local configuration as a new immutable version.

kite deploy [--env <test|live>] [options]

Option	Description
`--env <environment>`	Target `test` or `live`; defaults to the project setting.
`-y, --yes`	Bypass the confirmation prompt.
`--force`	Deploy despite validation warnings; errors still block deployment.
`--json`	Print machine-readable output.

kite validate --strict
kite config diff --env test
kite deploy --env test

Configuration versions

Command	Purpose
`kite config versions [--env test]`	List deployed versions and the active version.
`kite config diff [from] [to] [--env test]`	Compare two remote versions, or local config with the latest version.
`kite config promote --version <version>`	Promote an immutable `test` snapshot to `live`.
`kite config rollback --version <version> [--env test]`	Activate a previous version.
`kite config pull [--version <version>] [--env test]`	Download a compiled snapshot. Defaults to the latest version.

kite config versions --env test
kite config diff --env test
kite config diff v1 v2 --env test
kite config promote --version v2
kite config rollback --version v1 --env test
kite config pull --version v2 --env test

config pull writes .kite/pulled-config.json. It never overwrites authored TypeScript because a compiled snapshot cannot be safely converted back to source definitions. Promotion always moves a specific test version to live; it does not recompile local files.

Operations

`kite diagnose`

Checks project configuration and data for common problems.

kite diagnose [--env test] [--json]

`kite recompute`

Rebuilds customer state from raw event history after configuration changes.

kite recompute (--customer <customerId> | --all) [options]

Option	Description
`--customer <customerId>`	Recompute one customer.
`--all`	Recompute every customer.
`--dry-run`	Calculate aggregate impact and complete per-customer differences without persisting them.
`-y, --yes`	Confirm a global recompute without prompting.
`--no-wait`	Return after the job is queued.
`--env <environment>`	Target `test` or `live`.

Start with one customer or a dry run before recomputing an environment:

kite recompute --customer customer_123 --dry-run --env test
kite recompute --all --dry-run --env test

After completion, a dry-run prints aggregate lifecycle, health, and segment impact followed by each affected customer's lifecycle, health components, segments, journeys, predicted rule executions, and corrective emissions. Customers with no differences or predicted effects are omitted. Add --json to receive the complete result in result.customers; this is recommended for large runs and CI artifacts.

kite recompute --all --dry-run --env test --json > recompute-preview.json

See Backfill and recomputation for the response shape and field semantics.

AI assistant

AI commands send sanitized project context through the configured Kite API. Disable all AI commands with the global --no-ai option or KITE_NO_AI=1.

Command	Purpose
`kite ai model-success`	Generate a Customer Success model from guided product questions.
`kite ai suggest-events`	Analyze event coverage and produce an instrumentation plan.
`kite ai explain-config`	Explain the local Kite model.
`kite ai debug-customer <customerId>`	Diagnose state, event history, and rule logs.
`kite ai why-not-activated <customerId>`	Identify unmet activation conditions.
`kite ai generate-instrumentation-plan`	Generate framework-specific instrumentation examples.

Commands that call a model accept --model <deployment> where applicable. Customer and config commands accept --env; plan generators accept --output <path> and refuse to overwrite an existing file.

kite ai explain-config --env test
kite ai why-not-activated customer_123 --env test
kite ai generate-instrumentation-plan --output ./instrumentation.md
kite --no-ai validate

Automation and environment variables

Interactive login is recommended for local use. In CI, provide credentials through the secret store:

Variable	Purpose
`KITE_ACCESS_TOKEN`	Headless CLI access token.
`KITE_ORGANIZATION`	Organization ID used with the access token.
`KITE_API_URL`	Custom API base URL. Defaults to Kite Cloud.
`KITE_API_KEY_TEST`	Test ingestion key used by `events send`.
`KITE_API_KEY_LIVE`	Live ingestion key used by `events send`.
`KITE_API_KEY`	Fallback ingestion key for the selected environment.
`KITE_NO_AI=1`	Disable AI commands.

Never commit tokens or API keys. deploy automatically attaches available GitHub Actions provenance, including repository, commit, ref, workflow, and run metadata, to the deployed version.