mb CLI reference

The mb CLI is the developer interface to Möbius. Use it to push governance artifacts from your local machine or CI pipeline, attach warehouse connectors, inspect certification history, and manage governed tables. Get a CLI token from Integration → CLI in the dashboard, or run mb auth login for a browser sign-in.

Installation

Requires Node.js 18+.

npm install -g @mobiusdt/mb

Verify the install:

mb --version

Authentication

Two ways to authenticate:

Browser sign-in (recommended for people):

mb auth login

Opens a browser-based device authorization flow and writes credentials to a named profile in ~/.mb/config.json (default profile: default). Add --profile <name> to keep multiple workspaces or environments side by side. mb auth login refuses to start a new sign-in while the target profile still holds a live token; pass --force to override.

Static token (for scripts and CI):

mb auth set --token <your-cli-token> --base https://your-mobius-url.com

Check current credentials at any time:

mb auth status
# API_BASE:  https://mobius.acme.com
# API_TOKEN: mb_live_••••••••••••5f3a

mb auth logout [--profile <name>] clears stored credentials — a single profile, or the whole config file if --profile is omitted.

Global options

Every command accepts:

Command reference

Table-creation commands (push, delete) only operate on Mode A (connector-backed) tables. Everything else — list, status, gate *, certify, reject, quarantine, config — works on any table regardless of custody mode; the token is workspace-scoped, not mode-scoped.

mb push <file>

Push a governance artifact (SQL view, YAML schema, or JSON definition) to Möbius. Mode A only — mb push always registers a connector-backed, no-custody table; there is no CSV/row-upload path through this command. A new artifact is registered in QUARANTINED state and an auto-baseline gate run kicks off immediately; a steward then opens the tracking URL to complete the semantic contract and move it toward certification.

mb push models/customer_risk_profile.sql
# Pushed: customer_risk_profile
# Governance ID: clxyz456...
# Tracking URL:  https://mobius.acme.com/tables/clxyz456
# Status: QUARANTINED — auto-baseline running

Options:

• --connector <id> — attach a warehouse connector at push time. Required to run Gate 1 predicate SQL and to serve live preview data.
• --source <schema.table> — the warehouse identity this artifact governs. Required unless the artifact declares it itself (a qualified CREATE VIEW schema.name in SQL, or a source: / "source" key in YAML/JSON). There is no silent fallback to the filename.
• --replace <governanceId> — update an existing artifact after a schema or SQL change. Required on a name collision; Möbius refuses a push without it to prevent accidental overwrites. A --replace push resets the table to QUARANTINED and triggers recertification if it was previously CERTIFIED. It cannot be used to overwrite a Mode B (custody) table.
• --wait — block until the auto-baseline job finishes (recommended for CI).

# First push — registers a new governance artifact
mb push models/customer_risk_profile.sql
# Schema changed — re-push to update the existing artifact
mb push models/customer_risk_profile.sql --replace gov_abc123

mb delete <id>

Soft-delete a governance artifact by its governance ID. Mode A only — Möbius refuses a delete against a custody (Mode B) table with a 400; Mode B tables are managed through the dashboard or API instead. The source warehouse object is never touched — only the governance record is removed. Requires confirmation unless --yes is passed. Only the table owner or a workspace admin may delete.

mb delete clxyz456
# Delete governance artifact clxyz456? (y/N) y
# Deleted.

mb list

mb list
# ID                  NAME                       MODE      STATE                  GATE
# dyn_8b3f9c2a        customer_profiles          MODE_A    BASELINE_VERIFIED      ENFORCING
# dyn_a1c2e3f4        orders                     MODE_A    CORE                   ENFORCING
# dyn_4d5e6f7g        ml_training_set            MODE_B    QUARANTINED            ADVISORY

mb status <tableId>

mb status dyn_8b3f9c2a
# Table:        customer_profiles
# Mode:         A (no-custody)
# Lifecycle:    BASELINE_VERIFIED
# Active jobs:
#   [job-bb-01] gate-baseline-auto  RUNNING  17s  (4/6 predicates)

--watch polls every few seconds and streams updates until no active gate-run jobs remain (NDJSON under --json).

mb versions list <tableId>

Shows the immutable certification history — one entry per point-in-time snapshot written when the table reached CERTIFIED.

mb versions list clxyz456
# V#   Certified At          Certified By      Grain
# 3    2026-04-18 09:12:00   user@acme.com     One row per customer, keyed by customer_id...
# 2    2026-04-10 14:03:00   steward@acme.com  One row per customer...

mb versions restore <tableId> --to <version> --reason <text>

Puts an earlier certified contract's content back onto the live contract. Nothing is undone or deleted — a new version is cut recording the restore and who did it. If the table is currently CERTIFIED, a recertification request is filed instead of minting a new certification claim. --reason is required. --env <label> asserts the table's environment; a mismatch is refused. Cross-environment restore is not supported.

mb connectors list

mb connectors list
# ID            NAME              TYPE      STATUS    ENV
# conn_abc123   prod-postgres     POSTGRES  ACTIVE    Production

mb contract set-intent <tableId>

Sets a table's semantic-contract primitives: --intent <METRIC|DECISION|OPERATIONAL|EXPLORATORY> (decision class) and --allowed-consumers <HUMAN,AI,AUTOMATION,EXTERNAL> (which consumer classes may read it), plus an optional structured grain declaration (--grain-type + --grain-key <col>[,<col>...]). Grain, meaning, and other contract fields carry forward unchanged unless you also pass --grain / --meaning.

mb env promote <tableId> --to <env>

Promotes a table's governance artifact to another environment. --dest-profile <name> relays across two CLI profiles (e.g. two separate Möbius workspaces); --bundle-out <file> / --bundle-in <file> export and import the artifact as a portable JSON bundle instead of promoting directly.

Gate commands

The 6 baseline Gate 1 predicates (record count, column presence, grain uniqueness, null rate, referential integrity, numeric bounds) always run on certification. For stricter checks — regex on a column, custom SQL bounds, cross-column arithmetic — declare them in a gate1.yml file and apply it to the contract. Möbius never infers patterns from column names; if you want a check, declare it.

patternChecks:
  - name: customer_email_format
    column: email
    regex: "^[^@]+@[^@]+\.[^@]+$"
    severity: HARD_FAIL

customPredicates:
  - name: positive_balance
    sql: '"balance" >= 0'
    severity: HARD_FAIL

fieldOverrides:
  - field: customer_id
    nullRate:
      warn: 0.0
      fail: 0.0

mb gate apply dyn_8b3f9c2a -f gate1.yml
# ✓ Applied to dyn_8b3f9c2a
#   Recertification: triggered (table was CERTIFIED)

mb gate run dyn_8b3f9c2a --gate 3 --baseline report_abc123
# ⚠️  DETACHED RUN — evidence only, not a certification
# Gate 3 run: job_xyz (QUEUED)
# Track via: mb gate status job_xyz --gate 3

File formats

mb push accepts three file types. The table name and columns are extracted automatically — no manual registration needed.

YAML (.yml / .yaml) — use table: or name: for the table name, columns: or fields: for columns. Best for human-authored governance specs.

table: customer_risk_profile
decision_context: Used by credit risk team to gate loan approvals.
columns:
  - customer_id
  - risk_score
  - risk_band
  - assessed_at

SQL (.sql) — the table name comes from CREATE OR REPLACE VIEW <name>; columns are inferred from the SELECT aliases. Best for dbt views and warehouse-defined datasets. Möbius always publishes the certified projection as a plain SQL view, regardless of what you pushed — the default schema is certified_<env>.

CREATE OR REPLACE VIEW certified_prod.customer_risk_profile AS
SELECT
  c.id          AS customer_id,
  r.score       AS risk_score,
  r.band        AS risk_band,
  r.assessed_at AS assessed_at
FROM customers c
JOIN risk_scores r ON r.customer_id = c.id;

JSON (.json) — use table or name, with a type per column for richer schema inference. Best for programmatically generated artifact definitions.

CI/CD integration

Unattended pipelines that only need to author or replace a governance definition should call POST /api/workspace/definitions directly (see the REST reference), using a management service token stored as a CI secret — not a personal CLI token. There is no mb wrapper over that door: every mb verb carries the logged-in user's authority, and a CI-authored artifact push is a machine action with its own, narrower credential.

- name: Push governance artifact
  env:
    MOBIUS_TOKEN:   ${{ secrets.MOBIUS_MGMT_TOKEN }}
    MOBIUS_API_URL: ${{ secrets.MOBIUS_BASE_URL }}
  run: |
    jq -n --arg filename "models/customer_risk_profile.sql" \
          --arg mimeType "sql" \
          --arg connectorId "${{ vars.CONNECTOR_ID }}" \
          --rawfile content models/customer_risk_profile.sql \
          '{filename:$filename, mimeType:$mimeType, connectorId:$connectorId, content:$content}' \
      | curl --fail-with-body -X POST "$MOBIUS_API_URL/api/workspace/definitions" \
          -H "Authorization: Bearer $MOBIUS_TOKEN" \
          -H "Content-Type: application/json" \
          -d @-

Store the returned governance ID in a CI variable or a lock file committed to your repo — it stays stable across pushes and is what you pass as replaceId on the next schema change.

Error reference

Best practices

• Commit artifacts to source control. Treat .sql and .yml governance files like code — version them alongside the models they describe.
• Store governance IDs in a lock file after the first push, for use with --replace in later CI runs.
• Attach a connector at push time (--connector) to unlock live preview and Gate 1 predicate checks during certification.
• Never commit CLI tokens. Use CI secrets or a secrets manager; revoke and rotate if exposed.
• Use --yes carefully in CI. The delete confirmation prompt exists to prevent accidents — gate automated deletes on an explicit approval step.