CLI · Build, plan, apply

The core lifecycle: bootstrap a project, preview what would change, apply it, and verify that what is deployed matches what the generator owns.

kiri init

First-run data-warehouse project bootstrap. Scaffolds the project tree, kiri.yml, git repo and (optionally) the GitHub remote plus per-project CI.

Usage: kiri init [OPTIONS] NAME

Flag	Description	Default
--path	Parent directory for the new project	.
--silver-technique	flat | data_vault | kimball_dimensional. Required; locked after the first silver contract.
--layout	Project file layout: per_domain | per_source	per_domain
--adapter	Primary target adapter (e.g. databricks)
--mode	DPA mode: contract (user-owned contracts/) | auto (Kiri-owned .kiri/contracts/) | hybrid	contract
--target-name	Name of the primary target	dev
--no-git	Skip git init + initial commit	off
--remote	Add this URL as origin after the initial commit
--push	git push -u origin <branch> after adding the remote	off
--github	Create the GitHub remote repo and push so the scaffolded CI runs automatically	off
--private / --public	With --github: repo visibility (private by default — DW projects are sensitive)	private

kiri project scaffold is the non-interactive equivalent used by tooling; it adds --ci (emit a GitHub Actions workflow) and --overwrite.

kiri use

Set, show, or clear the active project so other verbs resolve without --project.

Usage: kiri use [OPTIONS] [DIRECTORY]

Omit DIRECTORY to show the current active project; --clear forgets it. Project resolution order everywhere in the CLI: KIRIMANA_PROJECT env var, the nearest kiri.yml above the current directory, then the kiri use active project.

kiri project

Project lifecycle: status, validation, and safe machine edits of kiri.yml.

• kiri project status — active-project identity + summary. --format json|text; --ledger <file> stamps per-chunk status into a markdown ledger between sentinels (idempotent).
• kiri project validate — validate the project’s kiri.yml.
• kiri project checksum — SHA-256 of kiri.yml, used as an optimistic lock.
• kiri project commit --content <file> [--checksum <sha>] — atomic kiri.yml write; refuses if the on-disk hash differs from --checksum.
• kiri project patch --op <op> [--args <json>] [--apply] — closed-menu patch ops: add_target, remove_target, set_default_target, set_silver_technique, add_domain, remove_domain, set_vault_provider, set_naming_override, set_reconcile_tolerance, set_governance_mode. Dry-run by default.
• kiri project probe --target <t> — read-only probe of a named target.
• kiri project normalize [--layout per_domain|per_source] — move flat source/contract files into the declared layout.

kiri targets

List configured targets (dev/test/prod) from kiri.yml.

kiri targets --project .

kiri plan

Show what would happen on apply, without touching the platform.

Usage: kiri plan [OPTIONS]

Flag	Description	Default
--project	Project directory
--target, -t	Named profile (dev|test|prod). Falls back to KIRIMANA_TARGET or the project’s default_target.
--strict / --no-strict	Exit non-zero if any metadata conflict is detected	off
--format	text (Rich console) or json (machine-readable summary)	text

kiri apply

Run the full pipeline: ingestion → AI description → contracts → build.

Usage: kiri apply [OPTIONS]

Flag	Description	Default
--project	Project directory
--target, -t	Named profile; falls back to KIRIMANA_TARGET / default_target
--skip-dbt	Skip the silver/gold dbt build step	off
--skip-fetch	Skip implicit REST/DATABASE fetch (use existing landing files)	off
--contract	Run only the named contract (its name field, not the filename). dbt build is skipped implicitly so the re-run stays local.
--domain	Run only contracts in the given domain (contracts/<domain>/…, medallion-layer subfolders skipped). Same scoped-run semantics as --contract.
--window	Backfill a bounded watermark window <START>..<END> for the targeted flat watermark contract(s). Bounds this run’s upper watermark to END; the cursor advances to END only on success. Cannot be combined with --skip-dbt, --contract or --domain — advancing the cursor without materialising would lose data, so the apply refuses.
--reset	With --window: use START as this run’s lower bound so the bounded range reprocesses (idempotent via the model’s pre-hook window-delete). No cursor mutation up front.	off
--materialize	Force the dbt build even on a scoped run — what an orchestrator task uses so a scheduled single-contract run actually materialises instead of no-opping.	off

Example — reprocess a bad week for one watermark contract:

kiri apply --target prod --window "2026-06-01..2026-06-08" --reset

kiri compile

Compile contracts into runnable platform artefacts without applying them.

kiri compile layer

Compile per-(domain, layer) contracts.

Usage: kiri compile layer [OPTIONS] LAYER

LAYER is bronze | silver | gold | all. Key flags: --domain (required), --target (required — the target binding declared in the layer contract), --out (default 05-shadow-build), --compile-target to override the layer contract’s kiri.compile_target (sql, sql-full-snapshot, dlt-with-expectations, dlt-with-apply-changes, dlt-with-append-flows, view, materialized-view), and --project-adapter (e.g. databricks, required for dlt-with-apply-changes).

kiri compile range

Compile a depth-range × breadth-selector slice of the project.

kiri compile range --domain sales --target dev --from silver --upto gold
kiri compile range --domain sales --target dev --upto silver

Selectors: --include / --exclude take comma-separated fnmatch patterns of the form <layer>.<table> (e.g. 'silver.SAT_*,bronze.raw_*'); --dv-kind hub|link|satellite|reference and --dv-name filter Data Vault objects. The selection is closure-expanded by default; --no-closure refuses instead and reports missing dependencies.

kiri compile bronze / kiri compile silver

Lower-level single-layer compilers. kiri compile bronze --target <t> --contracts <dir> --output <file> supports targets dlt, copy-into, streaming-table, sql, dlt-with-apply-changes, dlt-with-append-flows (--adapter databricks required for apply-changes). kiri compile silver --target dlt-with-expectations --contracts <dir> --output <file> compiles silver contracts to a DLT notebook.

kiri verify

Compare observed platform state to the declared project state.

Usage: kiri verify [OPTIONS] [PROJECT]

kiri verify-generated / kiri list-generated

kiri list-generated [PROJECT_ROOT] enumerates files the kiri generator owns. kiri verify-generated [PROJECT] re-emits generator artefacts and asserts the on-disk copies match — the drift gate for hand-edited generated files.

kiri reload

Rebuild a Delta bronze table from its landing files.

kiri reload --source air_quality --table measurements --target dev

kiri upgrade

Release upgrade lifecycle for a deployed Kirimana installation.

• kiri upgrade --check [--to <version>] [--format json|text] — read-only pre-flight dry-run (required in this release).
• kiri upgrade snapshot [--out .kiri-snapshots] [--tag <label>] [--dry-run] — capture a restorable pre-upgrade snapshot of the automation database.
• kiri upgrade rollback [--snapshot <dir>] [--revision <n>] [--dry-run] — reverse an upgrade: Helm revert, then database restore.