Press CTRL+K to open search

CLI workflow reference

  • Updated on Oct 16, 2026
  • Published on Jun 29, 2026
  • 4 minute(s) read
  • MR
  • EB
 Prev Next

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

The JSON blocks below are illustrative manifest fragments, not complete deployable manifests. Merge them into the appropriate generated Business Entity manifest, then run the validation commands before upload.

Follow this gate order for a new integration:

  1. Auth — session before online commands.
  2. Scaffold — create, BID integration-definition apply, copy fixtures, repair.
  3. Validate — schema + application manifest alignment.
  4. Test — unit, integration, E2E against sandbox credentials.
  5. Publish — upload --probe, then upload, show --online.
  6. 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

Agent Kit (customer workspace — not an integration gate). How-to:
Prepare a managed coding workspace.
On an administrator-provisioned workspace host, use the fastest path:

aifabrix onboarding

It reads the managed Controller, environment, work directory, and coding
platform, then prepares or resumes the workspace. If no coding platform is
configured, pass --coding claude, --coding codex, or --coding cursor; this
first choice is saved. An existing platform setting is preserved when --coding
selects another platform for one run. Use --name or --repo to select a different
workspace or repository.

On portable Linux/macOS without managed configuration,
aifabrix agent-kit setup <controllerUrl> signs in, creates a local workspace,
and starts Codex; GitHub is optional unless --repo owner/name is supplied.
install does not start a session.

aifabrix agent-kit init cust-<name> --host all --approve-all --yes
aifabrix agent-kit install --host claude --approve-all --yes
aifabrix agent-kit start claude --remote-control --approve-all --yes
aifabrix agent-kit start claude --remote-control --detach
aifabrix agent-kit start codex
aifabrix agent-kit list
aifabrix agent-kit kill

Auth

aifabrix auth status
aifabrix login

Generate

aifabrix create <systemKey> --type external
aifabrix integration-definition validate ./bid.json
aifabrix integration-definition apply ./bid.json --dry-run
aifabrix integration-definition apply ./bid.json
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 datasource test <datasourceKey> --app <systemKey>
aifabrix test-integration <systemKey>
aifabrix datasource test-integration <datasourceKey> --app <systemKey>
aifabrix test-e2e <systemKey>
aifabrix datasource test-e2e <datasourceKey> --app <systemKey>
aifabrix role-assistant test <roleKey> --env dev

Publish

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

Enterprise AI Certification (individual pillar diagnostics and report; select required gates on upload for candidate qualification):

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 (wait for qualification; select required gates)
  → show --online → deploy when managed promotion is required

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.

agent-kit start needs tmux on PATH. Claude uses its Remote Control
workflow by default. Codex Remote Control requires the standalone managed
daemon; an npm-installed Codex CLI may need --no-remote-control for a
tmux-only session. A Codex desktop SSH app server is separate and can appear in
agent-kit list even when no tmux session exists.

Optional OpenAPI import commands exist — this reference lists create, BID apply, repair, and validate as CLI-first generate paths. How-tos: Apply an integration definition, Connected System tests, Role Assistant tests.

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 Connected System tests for structure / pipeline / E2E, and Test ladder and protection when choosing protection and certify commands — 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.

Related articles