Automation with the Airlift CLI

Humans run the guided migration journey in the Databricks App. This section is the Automation surface: @fabricorg/airlift-cli installs one executable, fa, for scripts and CI. The name follows the Fabric family convention: Harness uses fh, Runway uses fr, and Airlift uses fa.

Use fa to operate a migration or modernization engagement: assess scope, plan waves, convert code, transfer data, evaluate readiness, and inspect evidence. It is not a general Databricks deployment CLI. Fabric Runway's fr command owns release deployment, promotion, rollback, and reconciliation.

Authenticated remote commands use the same governed Airlift actions as the Databricks App; local catalog and verification commands never mutate engagement state. Every mutation below names the governed action it invokes — there is no second mutation path.

Common automation recipes

Each recipe names its governed action and permission. All remote mutations take a stable, non-secret --idempotency-key prefix: the CLI appends a canonical digest of the action and parameters, so an exact retry collapses to the original invocation and changed content cannot reuse the old content-bound key. Persist the prefix with your pipeline job — never mint a fresh timestamp or random value per retry — and use a fresh key after a policy denial, because a denied key stays denied. See authenticated automation for identity, tenant derivation, and the full retry contract.

Create an engagement

fa engagement create --file engagement.json --idempotency-key project-42-engagement

Invokes airlift.engagement_create (airlift:engagement:create). Admitted for the service-principal automation role, so CI can onboard engagements unattended.

Register a connection binding

fa connection register --file source-binding.json --idempotency-key project-42-binding

Invokes airlift.connection_binding_register (airlift:connection:register); automation-admitted. The file carries an opaque secret reference, never credentials. A binding becomes verified only against a recorded connectivity diagnostic — follow the digest recipe in authenticated automation.

Accept an assessment

fa assessment accept --file assessment-accept.json --idempotency-key project-42-assess-accept-1

Invokes airlift.assessment_accept (airlift:assessment:accept). Acceptance is a human decision: it requires the operator role on an authenticated person. The automation service-principal role is denied — it may start, record, and export assessments but never accept scope.

Freeze a plan

fa plan freeze pln_01ARZ3NDEKTSV4RRFFQ69G5FAV --idempotency-key project-42-plan-freeze-1

Invokes airlift.plan_freeze (airlift:plan:freeze); human operator role, denied to automation. Freeze requires a selected scenario, frozen engagement scope, and no blocking issues.

Export evidence

fa evidence export --file evidence-export.json --idempotency-key project-42-wave-2-evidence

Invokes airlift.evidence_export (airlift:evidence:export; human operator, approver, or validator role). The export is a content-digested governed pack of references and policy evidence — never artifact bodies or credentials.

Install

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

For an ephemeral or CI-pinned invocation, use npx:

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

What can I do with it?

Use --format text|table|json|yaml|jsonl on data-producing commands. --json is the concise JSON form. JSON is canonical and deterministic; JSONL emits one array item per line. Both are safe to diff in CI or feed into project scaffolding:

fa source plan snowflake --json > .airlift/snowflake-plan.json
fa actions --json > .airlift/action-contract.json

Read JSON from stdin with --file -. Use --correlation-id <id> to connect a governed mutation to your pipeline trace, and --timeout <seconds> to bound remote calls. These options never change identity, organization, policy, or approval authority.

The help system is resource-first:

fa help inventory
fa inventory graph list --assessment-id asm_<id>
fa conversion batch create --file batch.json --idempotency-key batch-42
fa application-kit module list
fa commands --json
fa completion zsh

The CLI has no deprecated command aliases. Use the exact resource hierarchy printed by fa commands; obsolete flat or verb-first spellings fail with exit status 2.

See the generated command index for the exact surface shipped by the current CLI.

Continue with the complete command reference, or use source planning commands to start a migration integration.

Airlift versus Runway

Use fa deployment require only when a migration engagement needs a particular Runway release outcome. Airlift stores the requirement and verified foreign references; it does not execute the release.

If a customer is already using Databricks and is not running a migration or modernization engagement, use Runway directly:

fr catalog
fr deploy
fr promote

Runway's console and API own detailed deployment status and reconciliation. Do not create an Airlift estate solely to obtain deployment commands.

Exit status

Security boundary

Set AIRLIFT_API_URL to the deployed Airlift Databricks App URL and supply a short-lived DATABRICKS_TOKEN through your shell or CI secret provider. The CLI never prints the token. It sends no actor or organization field: Harness authenticates the principal and the API resolves exactly one admitted organization membership.

The CLI accepts no actor, tenant, approval, waiver, --force, or unsafe override. It never creates a production Airlift runtime or writes the durable store directly. The CLI exposes the same action contract to authorized automation, but it cannot grant itself approval, waiver, certificate, policy, or cutover authority. Platform Host still enforces the caller's admitted role and agent/system bounds.