Quickstart

The first path is the Databricks App. Open it, create an engagement, and follow the guided journey — the App walks each governed gate in order, shows why progress stopped and who acts next, and never asks you to paste a digest or author evidence by hand.

Start in the Databricks App

1. Open the Airlift Databricks App and choose Engagements → New engagement. Enter a program name, accountable owner, and the delivery services being requested, then Create draft. The draft is only the governed container; it does not connect to a source, run code, or claim readiness.
2. Follow Guided setup for the engagement: register the source estate, bind a secret-safe connection reference, verify source access with retained evidence, activate the engagement, request an assessment, and review and accept the discovered scope. Each step names the evidence it creates and unlocks only when its governed event is recorded.
3. Continue with the guided migration journey, which walks every phase — discover, plan, convert, move data, validate, certify, cut over — with its gate evidence and next actor.

The App and the CLI call the same Fabric Platform actions and read the same governed projections, so anything created in one surface appears in the other. See guided client onboarding for the full setup walkthrough and App walkthroughs for the stage-by-stage UI.

Automation

Use the CLI and SDK when you need the same governed operations in CI, scripts, or an integration service. This appendix is the automation entry point; the complete authenticated surface is documented under Airlift CLI, including authenticated automation for remote-endpoint identity, idempotency, and evidence recipes.

Install the CLI

Prerequisites: Node.js 22+ and npm, pnpm, or another Node.js package manager.

npm install --global @fabricorg/airlift-cli
fa help

Use a pinned, installation-free invocation in CI:

npx --yes --package @fabricorg/airlift-cli@0.18.4 fa sources --json

Generate a source migration plan

List the source profiles and generate a deterministic project contract before configuring credentials:

fa sources
fa source inspect synapse
fa source plan synapse --json > synapse-plan.json

The plan covers inventory, conversion, transfer, validation, security, downstream consumers, cutover, and modernization. Each step names its Airlift actions, expected outputs, and exit criteria. Planning commands never connect to a source or mutate an Airlift deployment.

Connect to a deployed Airlift App

After an administrator admits your Databricks principal to one Airlift organization, configure the authenticated remote endpoint:

export AIRLIFT_API_URL="https://<your-airlift-app>"
export DATABRICKS_TOKEN="$(your-secret-provider read databricks-token)"

Create engagement.json:

{
  "name": "Synapse modernization",
  "services": ["discovery", "migration_factory", "modernization"],
  "owner": "data-platform"
}

Then create and inspect the governed engagement:

fa engagement create \
  --file engagement.json \
  --idempotency-key synapse-program-engagement \
  --json

fa engagement list

The token authenticates the request but is not the organization selector. Airlift derives the actor and organization at the App boundary and rejects ambiguous memberships.

Add the SDK to an integration

Install the typed source registry, action contracts, schemas, and runtime composition surface in your Node.js project:

npm install @fabricorg/airlift

import {
  AIRLIFT_ACTION_IDS,
  createSourceMigrationPlan,
  resolveSourceSystemProfile,
} from '@fabricorg/airlift';

const source = resolveSourceSystemProfile('synapse');
const migrationPlan = createSourceMigrationPlan(source.id);

console.log(source.workloadSurfaces);
console.log(migrationPlan.steps.map((step) => ({
  id: step.id,
  actions: step.airliftActions,
  exitCriteria: step.exitCriteria,
})));
console.log(AIRLIFT_ACTION_IDS.assessmentRecord);

Your application invokes governed actions for assessment, inventory, waves, conversion attempts, validation runs, readiness observations, acceptance, certificate minting, cutover, rollback, and evidence export. Illegal transitions are rejected structurally; authorization and policy fail closed with an attributable reason.

Connect project adapters

The SDK is the governance and evidence layer—not a source credential manager. A complete project supplies narrow adapters for:

1. Lakebridge assessment and conversion jobs in the Databricks workspace.
2. Source-specific snapshot and incremental transfer with restart checkpoints.
3. Independent parity and performance validation.
4. Client-approved cutover checkpoint, apply-once, verification, and rollback effects.

Production cutover composition requires a client-certified CutoverEffector; selecting a runtime mode or setting an environment variable cannot enable an unverified effector.

Use the source developer workflow to implement those adapters, then follow the guide for your source system. Production deployment of the Airlift application and workers is delivered as a Databricks project; it is not installed from the private application repository.

Next commands

fa profiles
fa actions --json
fa doctor --profile production
fa docs sources/synapse

Continue with the complete CLI reference and the Synapse developer guide, or select another supported source.