CLI reference

The fx CLI is published as @fabricorg/experiments.

Databricks target packs

Discover and diagnose built-in packs without making a workspace mutation:

fx targets list
fx targets list --json
fx targets doctor sql-delta
fx targets doctor lakeflow-jobs --json

Live execution is deliberately fail-closed:

fx targets run sql-delta --live
fx targets run lakeflow-jobs --live \
  --required jobs-orchestration \
  --evidence reports/jobs.json \
  --junit reports/jobs.xml

--live sets the same explicit gate as DBX_TEST_LIVE=1. Doctor validates alternative authentication, workspace/warehouse requirements, pack-specific configuration, and every required check before the runner creates or mutates a resource.

Publish pack-aware evidence using the active secure profile:

fx login
fx targets publish reports/jobs.json

The CLI derives a stable suite name from the pack metadata. Use --suite only when organization policy requires another exact name. See Databricks target packs for available pack IDs, maturity, configuration, and limitations.

For a Databricks Apps API in CI, set DATABRICKS_HOST, FX_QUALITY_DATABRICKS_CLIENT_ID, and FX_QUALITY_DATABRICKS_CLIENT_SECRET for direct OAuth M2M. Use --databricks-profile <name> with an interactive Databricks CLI profile. The Fabric API key still enforces the organization and role after the Databricks gateway authenticates the caller.

Harness operator and Fiber

Inspect the tenant-scoped operator without mutating an experiment:

fx harness list
fx harness doctor
fx harness run quality-status

Open Fabric Harness Fiber against the same hosted profile:

fx harness fiber
fx harness fiber --plain

Run finite jobs from CI or a shell:

fx harness run srm-watcher --input '{"apply":false,"metric":"signup"}'
fx harness run analyst --input '{"experimentId":"<id>","deliver":false}'

SRM changes require "apply":true; analyst delivery requires "deliver":true. The defaults are preview-only. Fiber connects through a localhost-only bridge so the Fabric API key and Databricks bearer are not placed in child-process arguments. See Harness agents and Fiber for roles, job schemas, Quality evidence, and troubleshooting.

Customer-owned agents are enrolled using an already-pinned Ed25519 release key:

fx harness register-key --input '{"keyId":"release-2026","publicKeyHex":"<64 hex chars>"}'
fx harness enroll --input "$(cat signed-agent-envelope.json)"
fx harness revoke-key release-2026

The enrollment envelope pins the implementation digest, Harness runtime, capabilities, model policy, and optional Unity Catalog Agent Service request. See Deploying a Harness worker on Databricks Apps for signing and reconciliation details.

Install globally:

npm install -g @fabricorg/experiments
fx --version

Use it directly:

fx --help
fx login --api-key fx_key_...
fx doctor
fx harness doctor
fx harness fiber
fx validate experiments/
fx dev
fx plan experiments/
fx apply experiments/
fx push experiments/ --api-url https://api.example.com --api-key fx_key_... --tenant <orgId>
fx report homepage-cta
fx kill homepage-cta --reason "Web Vitals regression"
fx init databricks-tests ./quality-tests
fx test publish ./quality-tests/reports/evidence.json

If you cannot install globally, run the same commands with npx @fabricorg/experiments.

Local workflow

Local mode uses .fx/ in your workspace:

fx validate experiments/
fx plan experiments/
fx apply experiments/
fx dev

fx plan compares YAML to .fx/store.json.
fx plan uses detailed exit codes: 0 means the workspace is in sync, 2 means the plan is valid and contains changes, and 1 means an error. In CI, treat 0 and 2 as successful plan evaluation.
fx apply invokes local domain actions and writes .fx/manifest.json.
fx dev signs and serves the local manifest, its JWKS and revocation record, plus local exposure/conversion ingest endpoints. Browser and Node SDKs use the same fail-closed verification path locally as they do in production.

Hosted push

Create a scoped API key in Studio Settings → API keys, then configure a private local profile:

fx login --api-key fx_key_...
fx doctor
fx profile show

fx login starts from https://studio.experiments.fabric.pro, discovers the current Databricks Apps API, validates the key, reads its organization and role, and stores the profile with owner-only file permissions. If the App is protected by Databricks OAuth, it uses the active Databricks CLI login; select another one with --databricks-profile <name>.

Use multiple environments without rewriting commands:

fx login --profile staging --api-key fx_key_...
fx profile list
fx profile use staging
fx doctor --profile staging
fx logout staging

Precedence is explicit flags → environment variables → active profile. Secrets are never printed by fx profile or fx doctor.

Use fx push to reconcile local YAML into a hosted API organization:

fx push experiments/

fx push:

validates local YAML using the shared @fabricorg/experiments-yaml parser,
fetches hosted experiments for the target org,
prints the same Terraform-style plan as local fx plan,
invokes hosted domain actions,
publishes the hosted manifest unless --no-publish is set.

Useful flags:

fx push experiments/ --dry-run
fx push experiments/ --allow-deletes
fx push experiments/ --no-publish

Environment variable equivalents:

export FX_API_URL=https://api.example.com
export FX_API_KEY=fx_key_...
export FX_ORG_ID=<orgId>
fx push experiments/

Create API keys in Studio at /app/{orgSlug}/settings.

Databricks BDD and Quality Center

# Scaffold a standalone TypeScript/Gherkin suite.
fx init databricks-tests ./databricks-tests

# Publish Fabric BDD JSON, Databricks live-suite JSON, standard JUnit XML,
# or generic Fabric CLI check JSON.
fx test publish reports/evidence.json --suite "Data contracts"
fx test publish reports/junit.xml --suite "dbt tests"
fx test publish reports/experiment-preflight.json

With a profile, fx test publish needs no URL, key, or tenant flag. For CI it also reads FX_API_URL, FX_API_KEY, and FX_ORG_ID, with --api-url, --api-key, and --tenant equivalents. --external-id makes uploads idempotent outside GitHub Actions; --run-url attaches a CI link. Generic JSON uses "kind": "fabric-cli" and a cases array. A/B exposure and conversion analytics remain on the Experiments result pages; Quality stores test and preflight evidence. See Quality Center for schemas, CI examples, redaction, and Studio behavior.

Mojito-parity commands

# Migrate a directory of Mojito waves to Fabric YAML. Existing output files are
# preserved unless you pass --force; add --strict to fail on manual-review
# warnings. A wave with fewer than two recipes fails rather than emit invalid YAML.
fx import-mojito ./waves --out ./experiments

# Mint a signed preview link for a variant. Local mode (default) signs with a
# per-workspace secret in .fx/preview-secret; pass --api-url + --api-key to
# sign via the hosted /v1/orgs/{orgId}/preview/sign endpoint instead.
fx preview hero-cta-color --variant green-action \
  --origin https://staging.example.com \
  --ttl 600

Preview tokens are bearer credentials in URLs. Default TTL is 900s; the server clamps to [60, 3600]. Pages that may receive preview links should set Referrer-Policy: no-referrer to prevent token leakage via the Referer header. See Migrating from Mojito for the end-to-end workflow.