Skip to main content
Private Preview·Early access by invitation.Request access →
Kirimana.
Docs · Getting started

Install Kirimana

Kirimana is a data contract platform for Databricks. You install one thing on your machine — the kiri CLI — and the rest of the runtime lives in your Databricks workspace. This page gets you from an empty laptop to a CLI that can talk to your workspace.

Private beta. Kirimana is at v1.0.0-beta.1. Access to the repository at github.com/kirimana/kirimana and to support channels is invitation-gated during the private beta. If you don’t have an invitation yet, request one.

Prerequisites

RequirementWhy
macOS, Linux, or Windows with WSL2Supported CLI platforms
uvInstalls and isolates the CLI; manages its own Python 3.12, so you don’t need a system Python
gitKirimana projects are git repositories
A Databricks workspacePremium tier, Unity Catalog enabled, at least one SQL warehouse running
Workspace accessYour identity (or a service principal) added as a workspace user, with USE CATALOG on your catalog and CREATE SCHEMA on a schema you can write to

You do not need dbt-core, the Databricks CLI, or the Databricks SDK installed separately — the CLI brings what it needs as dependencies.

If you don’t have uv yet:

curl -LsSf https://astral.sh/uv/install.sh | sh

Install the CLI

The CLI ships on PyPI as kiri-cli:

uv tool install kiri-cli

This puts a single kiri binary on your PATH, isolated from any other Python tooling you have installed. The install is idempotent — re-run the same command to upgrade to the latest release. There is no auto-update; you decide when to upgrade, and kiri --version prints a notice when a newer version exists.

To pin a specific version:

uv tool install kiri-cli==1.0.0b1

First-run check

Verify the binary landed:

kiri --version
kiri --help

kiri --help should print the top-level command list (apply, audit, catalog, contract, databricks, flows, ingest, suggest, and friends). If the command is missing, your shell hasn’t picked up uv’s tool directory — restart the shell or check that ~/.local/bin is on your PATH.

Point the CLI at your Databricks workspace

A Kirimana project is a directory with a kiri.yml, plus sources/, contracts/, and models/. Create one:

kiri init my-dw-project --silver-technique data_vault --adapter databricks
cd my-dw-project

Then open kiri.yml and fill in your workspace coordinates under targets::

name: my-dw-project
default_target: dev
adapter: databricks

silver:
  technique: data_vault

targets:
  dev:
    adapter: databricks
    host: https://adb-XXXXXXXXXXXXXXXX.X.azuredatabricks.net
    catalog: acme_dev          # the Unity Catalog catalog your platform team gave you
    warehouse_id: 0123abc456   # SQL warehouse id from the workspace UI

Two values come from outside the project:

  • host — the workspace URL, from your platform team. It looks like https://adb-<workspace-id>.<region-shard>.azuredatabricks.net.
  • warehouse_id — in the Databricks UI under SQL → Warehouses; click the warehouse and copy the id from the URL.

Confirm the project loads and the target resolves:

kiri targets

You should see dev listed with adapter databricks.

Where credentials live

Notice that the kiri.yml above contains no token, no client secret, no personal access token. That is deliberate — credentials never live in project files.

For development, the CLI falls back to your Azure identity when no explicit credential is configured. Sign in once:

az login

Sign in with the account in the same Entra tenant as the workspace. The CLI picks up the cached token automatically via the default Azure credential chain, so once az login succeeds you can run kiri against the workspace without managing any secret yourself.

For production, teams use an Azure AD service principal as the Databricks execution identity, with its secret stored in Azure Key Vault and referenced from kiri.yml as a vault ref:

    token: ${vault:databricks/prod:token}

Vault refs resolve at run time; the literal secret never touches the repository. The deploy guide covers the service-principal setup end to end.

Verify the wiring

Before you run anything that writes to the workspace, run the health check:

kiri databricks health --target dev

It probes connectivity, authentication, and every Unity Catalog permission the CLI needs (USE CATALOG, CREATE SCHEMA, CREATE TABLE, MODIFY, SELECT). Any FAIL comes with a remediation line naming the exact GRANT to ask your platform team for. Don’t proceed until every probe reports OK or WARN.

Troubleshooting

kiri: command not found after install. uv installs tools to ~/.local/bin. Add it to your PATH (uv tool update-shell does this for you) and open a new shell.

az login succeeded but the workspace returns 401. You are signed in to a different tenant than the workspace. Run az account list, then switch with az account set --subscription <id>. If the tenant is right, your platform team hasn’t added you as a workspace user yet — that is a one-line fix on their side (Workspace settings → Identity and access → Users → Add).

kiri databricks health reports a permission FAIL. Read the remediation line on the failing probe — it names the exact grant (for example GRANT CREATE SCHEMA ON CATALOG acme_dev TO <you>) to request from your platform team. Don’t work around it; the probe set exists so that permission problems surface here, not halfway through your first apply.

Uninstall

uv tool uninstall kiri-cli

Project directories are plain git repositories — deleting them removes everything project-local.

Next steps

Updated 5 July 2026 · v1.0.0-beta.1