Developer reference for frozen scopes, runbooks, rehearsals, operational evidence, durable execution, incidents, and source disposition.

Cutover and hypercare commands

fa cutover manages migration cutover truth and starts Airlift's durable workflow. fa deployment does not deploy releases; use the Runway CLI for release execution and then admit the resulting immutable reference through an Airlift deployment requirement.

Set the authenticated API boundary once:

export AIRLIFT_API_URL=https://<airlift-app-host>
export DATABRICKS_TOKEN=<short-lived-oauth-token>

The API derives organization and identity from authentication. No cutover command accepts an actor or organization override.

Inspect control state

fa cutover list --estate-id est_01J00000000000000000000000
fa cutover status wav_01J00000000000000000000000 --json

The response includes the frozen digest, runbook, rehearsal, operational evidence, effector certification, incidents, hypercare, source disposition, and any stale reason.

Freeze exact scope

wave-freeze.json

{
  "engagementId": "eng_01J00000000000000000000000",
  "waveId": "wav_01J00000000000000000000000",
  "transfers": {
    "applicability": "required",
    "ids": ["xfr_01J00000000000000000000000"]
  },
  "deployments": {
    "applicability": "required",
    "ids": ["dpr_01J00000000000000000000000"]
  },
  "releaseEvidenceRefs": [
    {
      "system": "runway",
      "type": "promoted_release",
      "id": "release-v42",
      "digest": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
    }
  ],
  "reason": "Freeze the certified production scope for the approved window."
}

fa cutover freeze --file wave-freeze.json --idempotency-key wave-freeze-v1

For a genuinely inapplicable transfer or deployment track, use {"applicability":"not_applicable","reason":"..."}. Airlift requires a reason; an empty list cannot silently bypass the track.

Configure and rehearse the runbook

runbook.json

{
  "waveId": "wav_01J00000000000000000000000",
  "version": "2026.09.14-1",
  "reason": "Pin the approved timed procedure and restore path.",
  "steps": [
    {
      "stepId": "checkpoint",
      "name": "Create routing checkpoint",
      "ownerRole": "cutover_operator",
      "offsetMinutes": -15,
      "expectedDurationMinutes": 5,
      "actionKind": "governed_action",
      "actionRef": "effector:checkpoint"
    },
    {
      "stepId": "switch",
      "name": "Apply consumer routing once",
      "ownerRole": "cutover_operator",
      "offsetMinutes": 0,
      "expectedDurationMinutes": 10,
      "actionKind": "governed_action",
      "actionRef": "effector:apply",
      "rollbackStepId": "restore"
    },
    {
      "stepId": "restore",
      "name": "Restore the checkpoint",
      "ownerRole": "cutover_operator",
      "offsetMinutes": 15,
      "expectedDurationMinutes": 10,
      "actionKind": "governed_action",
      "actionRef": "effector:compensate"
    }
  ]
}

fa cutover runbook --file runbook.json --idempotency-key runbook-v1
fa cutover rehearse --file rehearsal-result.json --idempotency-key rehearsal-v1

rehearse requires an admitted automation principal and immutable evidence reference. A human cannot author a passing rehearsal verdict.

Admit operational evidence

parallel-run.json

{
  "waveId": "wav_01J00000000000000000000000",
  "phase": "parallel_run",
  "providerRef": {
    "system": "radar",
    "type": "observation_window",
    "id": "window-42",
    "digest": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb"
  },
  "evidenceDigest": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
  "sloProfileId": "airlift.cutover.production_slo.v1",
  "observedFrom": "2030-09-13T00:00:00.000Z",
  "observedUntil": "2030-09-14T00:00:00.000Z",
  "verdict": "passed"
}

fa cutover observe --file parallel-run.json --idempotency-key parallel-run-v1

Only Radar or an admitted external monitor may provide operational evidence. Airlift retains the foreign reference, digest, window, SLO profile, and verdict; the monitor definition and raw observations remain with the provider.

Certify the effector and approve the wave

fa cutover certify-effector \
  --file effector-certification.json \
  --idempotency-key effector-cert-v1

fa cutover approve wav_01J00000000000000000000000 \
  --note "Change authority approval" \
  --idempotency-key wave-approval-1

Certification requires a passing rehearsal and a natural-person certifier. The file identifies the implementation and proves checkpoint, apply_once, verify, and compensate. Approval is a separate governed action and follows separation of duties.

Start the durable workflow

fa cutover start wav_01J00000000000000000000000 \
  --window 2030-09-14T02:00Z \
  --reason "Approved customer change window"

fa cutover workflow-status airlift-v2-wav_<digest>
fa cutover wake airlift-v2-wav_<digest>

start calls the dedicated workflow endpoint. It does not invoke airlift.cutover_execute from the CLI process. The worker re-reads governed readiness, waits durably for approvals, performs checkpoint/apply-once/verify, and records the outcome through Platform actions.

Incidents and hypercare

fa cutover incident-open --file incident.json --idempotency-key incident-1
fa cutover incident-resolve --file incident-resolution.json --idempotency-key incident-1-resolve

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

An open incident blocks readiness or hypercare acceptance. Resolution requires immutable evidence. Hypercare completion and source disposition are human decisions with separation-of-duties checks; agents and monitors cannot accept or decommission.

Exit behavior

Code	Meaning
`0`	request completed or attached to an existing workflow
`2`	invalid command arguments
`4`	authentication failed
`5`	authorization failed
`6`	dependency unavailable or invalid API response
`7`	governed readiness conflict

Cutover and hypercare commands

On this page