Command reference

The examples assume fa resolves to the installed CLI. Run fa help to print the same command inventory from the installed generation.

Global automation options

--format text|table|json|yaml|jsonl may appear on any command that produces structured data. --json remains an alias for --format json. JSONL emits one item per line when the result is an array. Human-readable text or tables remain the default.

Use --file - to read a JSON manifest or mutation request from stdin. Use --correlation-id <id> to propagate a trace identifier into a governed mutation and --timeout <seconds> to bound remote calls. Neither option can override identity, organization, policy, or approvals.

Run fa help <group> for focused help, fa commands --json for the machine-readable command contract, and fa completion bash|zsh|fish for shell completion. The generated command index is built from that same manifest.

Remote commands require AIRLIFT_API_URL and DATABRICKS_TOKEN. Mutation commands also require a stable, non-secret --idempotency-key prefix. See authenticated automation for identity and retry semantics.

Modernization and measurement commands are documented together in Modernization and value commands. Source capability commands and their evidence-authority split are documented in Capability commands.

The executable Synapse manifest compiler and governed registration flow are documented in Synapse golden-path commands.

Executable SQL Server, Snowflake, Redshift, Oracle, Teradata, and Hadoop manifest compilation, governed registration, and certification are documented in migration-pack commands.

Native ADF import and file generation, plus normalized-manifest routing for SSIS, PowerCenter, SAS, DataStage, Talend, ODI, dbt, and Airflow, are documented in pipeline import and generation.

Business-semantic SAP BDC and Dataverse compilation is documented in enterprise application-pack commands. Existing Databricks estate modernization is documented in Databricks-native commands.

Portable Databricks Apps and Lakebase foundation/module planning, same-digest evidence qualification, and the fa versus fr boundary are documented in application-kit commands.

Qualification, reusable delivery kits, connector policies, external value claims, activation evidence, and public-content checks are documented in delivery and claim commands.

Deployment-access inspection and admitted preflight recording (fa access) are documented in Databricks access and integrations. Evaluation-candidate freeze, rehearsal, and window inspection (fa evaluator) are documented in Evaluator readiness. Unity Catalog evidence recording (fa uc-evidence) is documented in Unity Catalog evidence.

Organization provisioning and retirement are platform-installer-only actions in the airlift-platform tenant; no tenant CLI command exists. See the local lifecycle cookbook.

Parity certification is recorded by the admitted worker through airlift.parity_certify; no caller-authored parity command exists. See Parity certificates.

Waiver requests and approvals are App decision-card surfaces; the CLI deliberately exposes no waiver subcommand. See Waivers and staleness.

`fa organization membership set`

fa organization membership set \
  --file membership-changes.json \
  --idempotency-key membership-grant-2026-08

Apply governed organization membership grants and revocations through airlift.organization_membership_set. The file holds one tenant-free changes array; the authenticated API derives the organization from the caller's membership. Requires the admin role (airlift:membership:manage) and refuses to leave an organization without an active admin. See Organization membership.

`fa engagement list|show`

fa engagement list
fa engagement show eng_01ARZ3NDEKTSV4RRFFQ69G5FAV --json

Query engagements in the organization derived from the authenticated Databricks principal. There is no organization selection flag.

`fa engagement preflight`

fa engagement preflight eng_01ARZ3NDEKTSV4RRFFQ69G5FAV
fa engagement preflight eng_01ARZ3NDEKTSV4RRFFQ69G5FAV --json

Evaluate every scoped source variant against the evidence level implied by the engagement services. Exit status 1 means the engagement is blocked. The result includes missing or stale claims, next actions, governed human lanes, and the requested support level.

`fa engagement create|update`

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

fa engagement update \
  --file engagement-update.json \
  --idempotency-key project-42-scope-v2

The create file accepts name, one or more services, owner, and optional target dates, estate IDs, and structured external references. The update file includes engagementId plus at least one changed field. The API validates referenced estates and rejects edits after scope is frozen.

`fa engagement activate|freeze`

fa engagement activate eng_01ARZ3NDEKTSV4RRFFQ69G5FAV \
  --idempotency-key project-42-activate

fa engagement freeze eng_01ARZ3NDEKTSV4RRFFQ69G5FAV \
  --idempotency-key project-42-freeze

Activation moves a draft scope to active. Freeze computes and records the canonical scope digest. A frozen engagement rejects later edits.

`fa connection list|register`

fa connection list --engagement-id eng_01ARZ3NDEKTSV4RRFFQ69G5FAV
fa connection register \
  --file source-binding.json \
  --idempotency-key project-42-synapse-binding

The registration file contains the engagement ID, display name, direction, capabilities, and an opaque credentialRef such as databricks-connection://migration/synapse-metadata. It never contains a password, token, private key, or connection string.

`fa connection verify|retire`

fa connection verify bnd_01ARZ3NDEKTSV4RRFFQ69G5FAV \
  --digest aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa \
  --idempotency-key project-42-synapse-verify

fa connection retire bnd_01ARZ3NDEKTSV4RRFFQ69G5FAV \
  --reason "Credential rotated" \
  --idempotency-key project-42-synapse-retire

Verification records an admitted SHA-256 evidence digest and authenticated verifier. Retirement is terminal for that binding; register a new binding for a rotated reference.

`fa estate list|show|register`

fa estate list --json
fa estate show est_01ARZ3NDEKTSV4RRFFQ69G5FAV
fa estate register --file estate.json --idempotency-key estate-synapse-1

Register a source estate or query the tenant-scoped estate projection. Registration accepts a source profile ID, owner, environment, priority, and optional opaque connection reference.

`fa assessment list|status|start|record|accept|export`

fa assessment list --estate-id est_01ARZ3NDEKTSV4RRFFQ69G5FAV
fa assessment status asm_01ARZ3NDEKTSV4RRFFQ69G5FAV --json
fa assessment start --file assessment-start.json --idempotency-key assess-start-1
fa assessment record --file assessment-record.json --idempotency-key assess-record-1
fa assessment accept --file assessment-accept.json --idempotency-key assess-accept-1
fa assessment export --file assessment-export.json --idempotency-key assess-export-1

Start and record compose the configured worker/source-adapter lifecycle. Acceptance is a human decision that binds normalized inventory and accepted dependency digests. Export returns a content-digested pack containing the accepted assessment, inventory, dependencies, and applicable plan scenarios.

`fa inventory list|register`

fa inventory list --estate-id est_01ARZ3NDEKTSV4RRFFQ69G5FAV \
  --assessment-id asm_01ARZ3NDEKTSV4RRFFQ69G5FAV --json
fa inventory register --file object.json --idempotency-key object-sales-1

Inventory registration normalizes one source object into the governed migration ledger. Use repeated idempotent calls for objects emitted by an assessment adapter. Filter by --assessment-id whenever an estate has multiple snapshots so results cannot be mixed.

`fa inventory graph-*`

fa inventory graph list --assessment-id asm_01ARZ3NDEKTSV4RRFFQ69G5FAV
fa inventory graph show dpg_01ARZ3NDEKTSV4RRFFQ69G5FAV --json
fa inventory graph start --file graph-start.json --idempotency-key graph-start-1
fa inventory graph record --file graph-batch.json --idempotency-key graph-batch-1
fa inventory graph accept --file graph-accept.json --idempotency-key graph-accept-1

One graph declares its expected edge count. Each record call accepts at most 500 edges. A human operator accepts the complete graph and Airlift computes its digest and cycle count.

`fa plan list|show|compare|generate|select|freeze`

fa plan list --engagement-id eng_01ARZ3NDEKTSV4RRFFQ69G5FAV
fa plan compare --engagement-id eng_01ARZ3NDEKTSV4RRFFQ69G5FAV --json
fa plan show pln_01ARZ3NDEKTSV4RRFFQ69G5FAV
fa plan generate --file plan.json --idempotency-key plan-parity-1
fa plan select pln_01ARZ3NDEKTSV4RRFFQ69G5FAV --idempotency-key plan-select-1
fa plan freeze pln_01ARZ3NDEKTSV4RRFFQ69G5FAV --idempotency-key plan-freeze-1

Generation maps accepted objects to Databricks target patterns, topologically groups candidate waves, detects cycles, and calculates transparent effort/value estimates. Freeze requires a selected scenario, frozen engagement scope, and no blocking issues.

`fa wave list`

fa wave list
fa wave list --estate-id est_01ARZ3NDEKTSV4RRFFQ69G5FAV --json

Query materialized execution waves. Plan candidates remain part of the frozen plan until the operator materializes execution waves through governed wave actions.

`fa cutover` and `fa hypercare`

fa cutover list
fa cutover status wav_01J00000000000000000000000 --json
fa cutover freeze --file wave-freeze.json --idempotency-key wave-freeze-v1
fa cutover runbook --file runbook.json --idempotency-key runbook-v1
fa cutover rehearse --file rehearsal.json --idempotency-key rehearsal-v1
fa cutover observe --file observation.json --idempotency-key parallel-run-v1
fa cutover certify-effector --file effector.json --idempotency-key effector-v1
fa cutover approve wav_01J00000000000000000000000 --idempotency-key approval-1
fa cutover start wav_01J00000000000000000000000 --window 2030-09-14T02:00Z --reason "Approved production window"
fa cutover workflow-status airlift-v2-wav_<digest>

fa hypercare start --file start.json --idempotency-key hypercare-v1
fa hypercare observe --file observation.json --idempotency-key hypercare-observe-1
fa hypercare complete --file decision.json --idempotency-key hypercare-decision-1
fa hypercare decommission --file disposition.json --idempotency-key disposition-1

These commands operate Airlift-owned migration cutover policy and its durable workflow. They do not deploy or promote release artifacts and do not create monitoring state. See the complete cutover command reference.

`fa artifact list|show|register`

fa artifact list --engagement-id eng_01J00000000000000000000000
fa artifact list --object-id obj_01J00000000000000000000000 --json
fa artifact show art_01J00000000000000000000000
fa artifact register --file artifact.json --idempotency-key artifact-v1

Query or register immutable artifact references. Registration requires the artifact store reference, SHA-256 digest, media type, producer generation, and engagement/object lineage. Artifact bodies and credentials are never uploaded to Airlift.

`fa conversion list|show|diff`

fa conversion list --object-id obj_01J00000000000000000000000
fa conversion show cnv_01J00000000000000000000000 --json
fa conversion diff obj_01J00000000000000000000000 --json

Read the conversion-attempt ledger. diff returns the same object's ordered attempt records for comparing method, tool/model/prompt generation, content digests, diagnostic, and validation reference. Fetch code bodies from the artifact store.

`fa conversion batch-*`

fa conversion batch list --engagement-id eng_01J00000000000000000000000
fa conversion batch show cbh_01J00000000000000000000000 --json
fa conversion batch create --file batch.json --idempotency-key batch-1
fa conversion batch start --file batch-start.json --idempotency-key batch-1-start
fa conversion batch complete --file batch-start.json --idempotency-key batch-1-complete

Create an accepted-scope batch, admit worker attempts, and reconcile terminal results. Completion derives counts and blocks on missing attempts, missing artifact lineage, or failed objects without residue.

`fa conversion attempt-*|retry`

fa conversion attempt start --file attempt-start.json --idempotency-key object-1-start
fa conversion attempt record --file attempt-result.json --idempotency-key object-1-result
fa conversion retry --file retry-start.json --idempotency-key object-1-retry-2

retry is an explicit alias for starting another conversion attempt. Use a new stable key and an eligible rework object. Airlift preserves prior attempts.

`fa residue list|show|create|estimate|assign|resolve|review|cancel`

fa residue list --engagement-id eng_01J00000000000000000000000
fa residue show res_01J00000000000000000000000 --json
fa residue create --file residue.json --idempotency-key residue-1
fa residue estimate --file estimate.json --idempotency-key residue-1-estimate
fa residue assign --file assignment.json --idempotency-key residue-1-assign
fa residue resolve --file resolution.json --idempotency-key residue-1-resolve
fa residue review --file review.json --idempotency-key residue-1-review
fa residue cancel --file cancellation.json --idempotency-key residue-1-cancel

Operate the remediation lifecycle. Assignment works directly from an open case and, like review, requires natural-person authority. estimate is optional delivery-planning metadata; it is not required before assignment. Resolution requires an artifact from the same object plus a validation evidence reference. The resolver cannot review the same case. In the App, cancellation is disclosed separately and requires a reason plus explicit confirmation.

`fa transfer list|status|plan|run|checkpoint|pause|resume|reconcile|reconcile-record|fail|cancel`

fa transfer list --engagement-id eng_01J00000000000000000000000
fa transfer status xfr_01J00000000000000000000000 --json
fa transfer plan --file transfer-plan.json --idempotency-key transfer-plan-v1
fa transfer run xfr_01J00000000000000000000000 --idempotency-key transfer-run-v1
fa transfer pause xfr_01J00000000000000000000000 --reason "Source maintenance" --idempotency-key transfer-pause-1
fa transfer resume xfr_01J00000000000000000000000 --idempotency-key transfer-resume-1
fa transfer reconcile xfr_01J00000000000000000000000 --idempotency-key transfer-reconcile-1

plan, run, pause, resume, reconcile, and cancel are operator controls. checkpoint, reconcile-record, and fail submit runner evidence and require admitted automation; a natural-person invocation is rejected. See data transfer and reconciliation for input schemas and the Temporal execution boundary.

`fa deployment list|status|require`

fa deployment list --engagement-id eng_01J00000000000000000000000
fa deployment status dpr_01J00000000000000000000000 --json
fa deployment require --file deployment-requirement.json --idempotency-key wave-3-release

require declares the Runway operation, environment, immutable artifacts, and terminal state needed by the migration. Airlift computes the desired digest. The admitted Runway integration records observations and reconciliation; caller-authored observe, sync, and reconcile commands do not exist. Use fr for deployment execution. See Deploy with Fabric Runway.

`fa migration-ir qualify`

fa migration-ir qualify \
  --file generated/artifact-set.json \
  --root generated \
  --bindings release-bindings.json \
  --resolutions residue-resolutions.json \
  --proof hermetic_proven \
  --output qualification.json

The command verifies generated bytes, invokes Databricks bundle validation, checks runtime binding and residue evidence, and optionally evaluates matching Runway and Experiments workspace evidence. It is read-only and never writes a provider verdict to the Airlift ledger. See release qualification.

`fa validation list|status|runs|readiness|run|cancel`

fa validation run --file validation-request.json --idempotency-key wave-2-validation-v3
fa validation list --engagement-id "$ENGAGEMENT_ID"
fa validation status "$VALIDATION_EXECUTION_ID" --json
fa validation runs --object-id "$OBJECT_ID" --json
fa validation readiness --object-id "$OBJECT_ID" --json
fa validation cancel "$VALIDATION_EXECUTION_ID" --reason "Superseded suite" --idempotency-key validation-cancel-v1

run creates Airlift validation scope; the durable worker delegates the generated suite to Experiments. runs shows admitted provider runs. readiness shows derived track observations. Cancellation is governed and leaves external provider state subject to reconciliation.

`fa discrepancy list|show|create|triage|accept|resolve|verify`

fa discrepancy list --object-id "$OBJECT_ID"
fa discrepancy show "$DISCREPANCY_ID" --json
fa discrepancy create --file discrepancy.json --idempotency-key discrepancy-42-create
fa discrepancy triage --file triage.json --idempotency-key discrepancy-42-triage
fa discrepancy accept --file triage-acceptance.json --idempotency-key discrepancy-42-accept
fa discrepancy resolve --file resolution.json --idempotency-key discrepancy-42-resolution
fa discrepancy verify --file verification.json --idempotency-key discrepancy-42-verify

Human operators can triage, accept eligible low/medium differences, and submit remediation. create and verify are admitted automation operations. Verification takes a validationRunId and succeeds only for a passing Experiments run belonging to the same object and matching the resolution evidence identity.

`fa certificate list|show|mint|invalidate`

fa certificate list --object-id "$OBJECT_ID"
fa certificate show "$CERTIFICATE_ID" --json
fa certificate mint --file certificate-mint.json --idempotency-key object-42-mint-v1
fa certificate invalidate --file certificate-invalidate.json --idempotency-key object-42-stale-v1

List and show are authenticated reads. Mint and invalidate call the system-owned certificate actions and normally require the admitted worker principal. They do not replace offline certificate inspect and certificate verify.

`fa evidence export`

fa evidence export --file evidence-export.json --idempotency-key wave-2-evidence-v1

Creates a content-digested governed evidence pack for an object or wave. The export contains references and policy evidence, not artifact bodies or credentials.

`fa help`

fa help
fa --help
fa -h

Print every command and the CLI mutation boundary. Exit 0.

`fa version`

fa version
fa --version
fa -V

Print the installed CLI version. Exit 0.

`fa docs [topic]`

fa docs
fa docs sources/sql-server
fa docs migration/validation --json

Print https://airlift.fabric.pro/docs, optionally with the URL-encoded topic appended. This command prints a URL; it does not launch a browser.

`fa sources`

fa sources
fa sources --json

List the installed source profiles with archetype, evidence-derived level, implementation routing (non-evidence), variants, applicable Lakebridge capabilities, program track, and migration-area metadata.

`fa sources export --plans`

fa sources export --plans --format jsonl
fa sources export --plans --json

Export one canonical plan record per source × variant in the installed registry. Each record wraps a compiled plan with sourceSystem, sourceVariant, implementationRoutingLevel, externalGates, a docsUrl, and a contentDigest computed over the plan alone, so unchanged plans keep the same digest across CLI releases for incremental re-indexing. The default text output emits the same JSONL form as --format jsonl; --json emits a single canonical array instead. --plans is required; omitting it returns exit 2.

`fa source inspect <source>`

fa source inspect sql_server
fa source inspect mssql --json
fa source inspect teradata

Resolve a profile ID or alias and print its variants, archetype, implementation routing (non-evidence), adapter contract, workload surfaces, applicable Lakebridge routing, transfer strategy, validation checks, residue, and modernization targets. Unknown sources fail with exit 1. Run fa sources --json for canonical IDs and variants.

`fa source plan <source>`

fa source plan synapse
fa source plan dynamics_365 --variant dynamics_365_finance_operations --json

Generate the deterministic archetype-aware plan. Each phase contains specialist adapter commands or boundaries, exact governed Airlift action IDs, outputs, and exit criteria. --variant selects a registered specialization. There is no legacy schema selector. Generating a plan does not create governed state.

`fa source certification-check <file>`

fa source certification-check source-certification.json
fa source certification-check source-certification.json --json

Validate an immutable live-run manifest and report evidence missing for its requested support level. Eligible returns 0; missing required evidence returns 1. The command does not promote the registry or mint a certificate.

`fa doctor`

fa doctor
fa doctor --profile local
fa doctor --profile production --json

Check Node, persistence, authorization, evidence registry, signing and verification, Databricks forwarded identity, Lakebridge job binding, Temporal mode, and the cutover effector boundary. Production profile failures return exit 1; warnings do not.

doctor validates configuration shape. It cannot prove connectivity, validate client data, or certify a cutover effector.

`fa actions`

fa actions
fa actions --json

Print every governed action with its version, required permissions, policies, and emitted events. The command reads the installed contract; it never invokes an action.

`fa profiles`

fa profiles
fa profiles --json

Print built-in object validation profiles, their canonical SHA-256 digests, and required readiness tracks. These are certificate profiles, not source-system profiles.

`fa certificate inspect <file>`

fa certificate inspect migration-certificate.json
fa certificate inspect migration-certificate.json --json

Parse the certificate schema and show its identity, profile, issuer, key, signed digest, computed digest, and digest match. Inspection does not verify the signature.

`fa certificate verify <file>`

fa certificate verify migration-certificate.json --keys public-keys.json
AIRLIFT_EVIDENCE_PUBLIC_KEYS_JSON='{"airlift-prod":"...PEM..."}' \
  fa certificate verify migration-certificate.json

Verify both envelope digest and Ed25519 signature. --keys accepts a JSON object mapping key IDs to public PEM strings. Without it, the command reads Airlift's verifier configuration from the environment. Valid returns 0; invalid returns 1.

Usage failures

Unknown commands, missing required arguments, or unsupported subcommands print a concise message plus Run 'fa help' for usage. and return exit 2. Remote authentication returns 3, not found returns 4, blocked/conflict returns 5, and dependency outage returns 6. Malformed local files, unknown source profiles, and failed diagnostics return 1.

Command reference

On this page