Authenticated automation

The CLI includes a versioned authenticated command/query transport for engagement, connection, assessment, inventory, dependency, and planning operations. Configure it with the Databricks App URL and a short-lived token admitted by that App's ingress:

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

fa engagement list --json

Do not put tokens in JSON inputs, command arguments, committed environment files, or shell history. The examples use placeholders; connect your normal CI secret provider.

For unattended automation, use an OAuth service principal with CAN_USE on the App and an explicit Airlift automation membership. A generic workspace user OAuth token or PAT is not a substitute for App ingress identity and can return HTTP 401 even when it works against workspace APIs. Interactive developers can perform the same governed operations in the App with Databricks SSO. Airlift does not provide a second login flow or accept caller-authored identity headers.

Identity and organization binding

The request body contains action, parameters, correlation metadata, and a content-bound idempotency key. It does not contain actor or organization. Harness authenticates the Databricks principal at the App boundary, then Airlift requires exactly one configured organization membership before the Platform action can run.

Human users receive their configured tenant role. A service principal must have the narrow automation role. The automation role may onboard engagements/connections, record assessment and inventory output, propose dependency graphs, export assessment packs, and generate plan scenarios. The automation role cannot accept dependency graphs or assessment scope, select/freeze plans, approve waves, accept business results, waive evidence, mint certificates, configure policy, execute cutover, or roll back.

Retry contract

Supply a stable, non-secret prefix with --idempotency-key. The CLI adds a canonical digest of the action and parameters. An exact retry collapses to the original action invocation and events; changed content cannot reuse the old content-bound key.

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

Persist the prefix with your deployment job. Do not generate a new timestamp or random value on each retry.

Verify a connection binding with recorded evidence

A binding becomes verified only against a connectivity diagnostic recorded by an admitted system principal through airlift.connection_diagnostic_record. The handler derives the diagnostic digest; a caller-chosen digest is rejected. Record the diagnostic, then verify the binding with that recorded digest:

fa connection diagnose <binding-id> --file probes.json --idempotency-key project-42-diagnose
fa connection test <binding-id> --json

fa connection verify <binding-id> \
  --digest <recorded-diagnostic-digest> \
  --idempotency-key project-42-verify

This recipe is for admitted automation. Interactive operators perform the same step in the App with Verify binding, which attaches the recorded diagnostic automatically and never asks anyone to paste a digest.

Remote migration operations

Local source planning, diagnostics, catalog inspection, and certificate verification remain read-only. Authenticated remote commands cover engagement and connection onboarding, assessment, inventory, planning, conversion batches, artifact lineage, remediation, transfer control, and deployment requirements.

Authority remains role-bounded. Operators can plan/control a transfer and declare a required Runway outcome. Admitted automation records checkpoints, runner failures, reconciliation, and Runway observations. The CLI transport does not turn a human token into runner authority, and it does not make a deployment requirement equivalent to Runway success.

An automation client remains a transport client. It must not accept --actor or --tenant as authority, write the Airlift database directly, or provide a bypass around approval, certificate, waiver, or cutover policy.