CLI workflow reference

Quick reference for the Builder CLI (aifabrix / af) integration ladder. Run aifabrix <command> --help for flags. Full index: CLI reference.

Prerequisites

Builder CLI installed; Node 18+
aifabrix auth status green
Integration folder under integration/<systemKey>/

Where it lives

Commands run from your workstation against the controller/dataplane for your configured environment — local JSON under integration/<systemKey>/ remains source of truth until upload.

How to set

Follow this gate order for a new integration:

Auth — session before online commands.
Scaffold — create, copy fixtures, repair.
Validate — schema + application manifest alignment.
Test — unit, integration, E2E against sandbox credentials.
Publish — upload --probe, then upload, show --online.
Certify — operations, trust, governance pillars, lifecycle.

Example minimal scaffold identity on datasource JSON:

{
  "key": "example-customers",
  "displayName": "Customers",
  "systemKey": "example-crm",
  "entityType": "recordStorage",
  "resourceType": "customer",
  "primaryKey": ["externalId"]
}

Defaults and examples

Auth

aifabrix auth status
aifabrix login

Generate

aifabrix create <systemKey> --type external
aifabrix repair <systemKey> --auth apikey
aifabrix repair <systemKey> --rbac --expose

Validate and fix

aifabrix validate <systemKey>
aifabrix repair <systemKey> [--dry-run] [--rbac] [--expose]
aifabrix json <systemKey>

Test

aifabrix test <systemKey>
aifabrix test-integration <systemKey>
aifabrix test-e2e <systemKey>
aifabrix datasource test-e2e <datasourceKey> --app <systemKey>

Publish

aifabrix upload <systemKey> [--probe] [--dry-run]
aifabrix deploy <systemKey> [--probe]
aifabrix show <systemKey> --online

Enterprise AI Certification (after upload, in order):

aifabrix verify-operations <systemKey>
aifabrix verify-trust <systemKey>
aifabrix verify-governance <systemKey> [--subject-email <email>]
aifabrix lifecycle <systemKey>

Lifecycle maintenance

aifabrix download <systemKey>
aifabrix repair <systemKey> [--dry-run]
aifabrix delete <systemKey>

Recommended gate order:

validate → test → upload --probe → upload → test-integration → test-e2e
  → verify-operations → verify-trust → verify-governance → lifecycle

Validate

Never stop at verify-trust — operations and governance pillars are required for full certification.

Use --dry-run on repair and upload in CI before mutating shared environments.

Common mistakes

Mistake	Fix
Upload before validate	Fix schema locally first
Skipping `upload --probe`	Add CI probe gate
Certify unpublished JSON	Upload then pillars
Wrong environment token	Match scopes to target env

Limits

Command availability and permissions depend on your controller/dataplane environment. See Builder CLI documentation for full command matrix and required permissions.

Optional OpenAPI import commands exist — this reference prioritizes create + repair + validate` as the CLI-first path documented across Build AI-ready systems.

Protection commands use datasource key arguments — not systemKey — when running protection validate / protection upload.

Use datasource validate when iterating on one JSON file — full validate <systemKey> is slower and obscures which datasource introduced a regression during multi-file commits.

CI pipelines should fail on upload --probe before integration tests — probe catches auth and schema issues without mutating shared tenant config.

Pin Builder CLI versions in CI images when reproducible certification matters — command flags and default probe behavior evolve between minor releases.

The validate → test → upload → certify sequence is mandatory — skipping test-integration before pillars wastes time on trust failures caused by stale credentials.

Reference Test ladder and protection when choosing which test proves which risk — not every command belongs in every CI stage.

Protection and governance commands require datasource key CLI arguments — document those keys in runbooks alongside systemKey to prevent on-call mistakes during incidents.

Use --dry-run on upload in shared tst environments even after green local validate — probe semantics differ when platform promotion gates are enabled.

Document which environment each CI stage targets in pipeline variables — mismatched environment values are the fastest way to get green dev certification and red tst upload failures in the same commit.

Documentation Index