@mobiusdt/mb

The official Mobius CLI. Push governance artifacts, declare Gate 1 extensions, manage certification, and administer your Mobius workspace from the terminal.

One-line model: mb CREATES only warehouse-connected (Mode A) tables — push/delete are Mode A only. Every governance verb (gate *, certify, reject, quarantine, list/status, env promote) works on any table in either mode — the CLI's table-creation surface is Mode A only, but its governance-lifecycle surface is mode-agnostic.

| | Custody mode | Also called | What it means | |---|---|---|---| | Mode A | NO_CUSTODY | "Warehouse-Connected" | Mobius governs a table it does not store rows for — created via mb push against a resolved warehouse object (schema.table) + connector. | | Mode B | CUSTODY | "Mobius-Managed" | Mobius stores the rows itself — created via the UI / ingest, never mb push. |

Installation

npm install -g @mobiusdt/mb

Quick start

1. Authenticate

mb auth set --token <your-api-token> --base https://your-workspace.mobius.app

Confirm your identity:

mb auth status
mb whoami

Pointing at localhost

Every command accepts --base and --profile to target a specific API and credential set without touching your default profile — this is the way to run the CLI against a local dev stack. --profile selects which stored credential set in ~/.mb/config.json to use; --base overrides the API base URL for a single invocation (or store it against the profile with mb auth set):

mb auth set --token <local-dev-token> --base http://localhost:3000 --profile local
mb whoami --profile local
mb list --base http://localhost:3000 --profile local

MOBIUS_TOKEN and MOBIUS_API_URL environment variables are also honored as fallbacks when --token / --base are not passed.

2. Push a governance artifact

mb push schemas/customer_profiles.sql \
  --manifest schemas/customer_profiles.governance.yml \
  --connector snowflake-dev

Mobius creates a DynamicTable in QUARANTINED state and (Session 5a) auto-enqueues the baseline Gate 1 run. Track with mb status <id>.

3. Declare Gate 1 extensions

mb gate get <tableId> -o gate1.yml
# edit gate1.yml — add patternChecks, customPredicates, etc.
mb gate validate -f gate1.yml
mb gate apply <tableId> -f gate1.yml

apply is private editing — it persists rules to the contract and audits the change. It does not notify the steward. Run mb gate submit (Session 5b) when you're ready to hand off for review.

4. Read certified data

The CLI is a governance plane tool. To query data, use the REST / GraphQL / MCP gateways with an Integration Token. See the gateway docs.

Commands

Authentication

| Command | Scope | Description | |---|---|---| | mb auth set --token <t> --base <url> | — | Store API token + base URL in ~/.mb/config.json | | mb auth status | — | Show current CLI auth configuration | | mb auth logout | — | Clear stored credentials | | mb whoami [--json] | any | Show resolved identity + context — profile, API base, user, workspace, role, token scope, effective env scope. --json for scripting. |

Governance artifacts

| Command | Scope | Description | |---|---|---| | mb push <file> [--manifest <yml>] [--connector <name>] [--replace <id>] [--yes] | mb:push | Push a governance artifact (Mode A — registers against external warehouse table) | | mb list | mb:read | List all tables in the workspace | | mb status <tableId> | mb:read | Lifecycle status, certification state, schema drift, active gate-run jobs | | mb versions list <tableId> | mb:read | List certified versions for a governance artifact | | mb delete <tableId> | mb:manage | Deregister a Mode A artifact (refuses Mode B — UI only for those) |

Gate 1 extensions and gate-run lifecycle

| Command | Scope | Description | |---|---|---| | mb gate get <tableId> [-o <file>] | mb:read | Serialise current contract extensions to YAML | | mb gate validate -f <file> | — (offline) | Validate gate1.yml schema + SQL/regex safety. No server call. | | mb gate apply <tableId> -f <file> | mb:push | Persist rules to contract; emits GATE1_YAML_APPLIED audit; triggers recert if currently CERTIFIED. Does NOT notify steward. | | mb gate cancel <jobId> | mb:push | Cancel a queued or running gate-run job. Worker bails between predicates. |

Designed but not yet shipped (Session 5b):

| Command | What it will do | |---|---| | mb gate run <tableId> [--sample <strategy>] | Dry-run preview. Sampling permitted (head:N, tail:N, random:N, chunks:K@N). Banner: "DRY RUN — NOT a proof." Never persisted as proof. | | mb gate submit <tableId> | Steward handoff. Full-scan run; persists PendingReviewProof; transitions table to PENDING_REVIEW; notifies steward. Always full scan, never sampled. | | mb gate result <tableId> | Steward read — show declared rules + predicate results from latest submission | | mb certify <tableId> (extended) | If a fresh PendingReviewProof exists, stamp as final without re-running. Otherwise refuse per workspace freshness policy. | | mb reject <tableId> --reason <text> | Steward rejects a PENDING_REVIEW submission; returns to QUARANTINE; analyst notified. |

See docs/use-cases/gate1-v2-end-to-end-workflow.md for the full lifecycle narrative.

Review outcomes

| Command | Scope | Description | |---|---|---| | mb reject <tableId> --reason <text> | (interactive) | Reject a PENDING_REVIEW table — bounces back to QUARANTINED with an audit trail and analyst notification |

Semantic contracts

| Command | Scope | Description | |---|---|---| | mb contract set-intent <tableId> [--intent <type>] [--allowed-consumers <csv>] [--grain-type <type>] [--grain-key <cols>] | mb:push | Author semantic-contract primitives — decision class, allowed consumer classes, and structured-grain declaration for a table |

Environment promotion

| Command | Scope | Description | |---|---|---| | mb env promote <tableId> --to <env> [--profile <name>] [--dest-profile <name>] [--bundle-out <file>] [--bundle-in <file>] | mb:push | Promote a table to another environment. Supports logical promotion (same profile), physical cross-profile relay (--dest-profile), and bundle export/import (--bundle-out / --bundle-in) for air-gapped promotion |

Recertification requests

| Command | Scope | Description | |---|---|---| | mb recertification list [--table <id>] [--status <csv>] | mb:read | List recertification requests (drift, schema change, ingest, manual triggers). Defaults to open requests (PENDING, IN_REVIEW) | | mb recertification dismiss <requestId> [--notes <text>] | ADMIN | Dismiss a recertification request without re-certifying or rejecting the table |

Quarantine inspection

| Command | Scope | Description | |---|---|---| | mb quarantine list | mb:read | List all QUARANTINED tables (same format as mb list; pipe/grep compatible) | | mb quarantine open <tableId> [-o <path>] | mb:read | Fetch DDL for a table and write it to a local file (default: <tableId>.ddl.sql). Mode A returns an external-source reference; Mode B synthesises CREATE TABLE from column schema. Writes MB_QUARANTINE_OPEN audit entry. |

Workspace administration

| Command | Scope | Description | |---|---|---| | mb config list | mb:manage | Show current workspace configuration | | mb config set <key> <value> | mb:manage | Update a workspace configuration value | | mb config history <key> | mb:read | Show the change history for a single config key. Output: timestamp · actor email · old → new | | mb connectors list | mb:read | List all warehouse connectors | | mb certify <tableId> [--note <text>] [--evidence <file>] | (interactive) | Run certification engine on a table. --evidence hashes the file client-side — only metadata + hash sent to server. Requires --note when --evidence is present. |

Run mb --help or mb <command> --help for full flag reference.

Token scope hierarchy

| Scope | Minimum role | Permitted operations | |---|---|---| | mb:read | VIEWER+ | Inspect tables, connectors, versions, status, gate config | | mb:push | EDITOR+ | All read operations + push, apply gate rules, submit, cancel | | mb:manage | ADMIN+ | All push operations + delete, workspace config |

Stewardship decisions (certify, reject) require interactive browser auth — not a CLI token. This keeps long-lived tokens out of the governance trust chain.

Configuration

Credentials are stored in ~/.mb/config.json. Do not commit this file.

The CLI never caches workspace state — every command verifies the membership and license at request time. Token revocation is immediate on the server side.

Documentation

• Full lifecycle narrative: docs/use-cases/gate1-v2-end-to-end-workflow.md
• CLI workflow walkthrough: docs/use-cases/cli-governance-workflow.md
• Gate 1 v2.0 doctrine: docs/architecture/ADR-004-gate1-v2-doctrine.md
• Token security model: docs/architecture/mb-push-security-and-auth.md
• Mode A / Mode B surface coverage matrix: docs/project/mode-ab-rules.md
• Public docs: docs.mobius.app

License

MIT