@mightybot/mbcli

The MightyBot mb CLI and local design-time MCP server, distributed over npm so it can be run with npx.

mb is a single Go binary. This package is a thin launcher: the binary ships in a per-platform optional dependency (@mightybot/mbcli-<platform>), and npm installs only the one matching your machine.

Start here — one command

With Node.js 16+, this one command is the entire setup — it signs you in and registers the MCP server with your AI agents:

npx @mightybot/mbcli@latest setup

setup = mb auth login (browser sign-in) + mb mcp install --agent all. npx fetches the right platform binary on demand — nothing to install first.

Run any other command the same way:

npx @mightybot/mbcli@latest workflow list
npx @mightybot/mbcli@latest version

Prefer a permanent mb on your PATH? npm i -g @mightybot/mbcli@latest, then run mb <cmd> (re-run the install to upgrade). The MCP server installs to the stable ~/.mightybot/mcp/mb either way.

Release channels

• @latest — the stable release. Use this. (recommended for everyone)
• @preprod — the newest build, ahead of @latest; use it to try the most recent changes before they're promoted.

@latest is promoted from a tested @preprod build — same bytes, no rebuild.

Always getting the newest

npx caches by version spec. To avoid running a stale cached copy, either pin the channel tag or force a registry check:

npx @mightybot/mbcli@latest version          # re-resolves the latest tag
npx --prefer-online @mightybot/mbcli version  # revalidates cache against the registry

Release-age cooldown

If your npm config (or your organization's .npmrc) sets min-release-age as a supply-chain guard, npm refuses any version published in the last N days — so a same-day release fails with ENOVERSIONS / "No versions available for @mightybot/mbcli" even though it published fine. Override the cooldown to install a fresh build:

npx --min-release-age=0 @mightybot/mbcli@latest          # CLI flag, or
npm_config_min_release_age=0 npx @mightybot/mbcli@latest  # env var

Once the build is older than the cooldown window, plain npx … works with no flag. (This guard is intentional — it protects against installing a freshly-compromised package; the override is only for trusted same-day builds.)

Commands

Every example below uses the bare mb (after a global install or inside mb setup). With npx, prefix any command: npx @mightybot/mbcli@latest <command>.

Get machine-readable help any time:

mb help            # human-readable usage
mb help --json     # full command catalog (command, usage, backend method/path)
mb version         # build info (version, commit, build date) as JSON

Builder-step configuration writes (workflow schemas, file processing, validation, policies, agent compiler, data trail, views) are MCP-native — done by an agent through the mb mcp server, not these shell subcommands. The shell commands below cover auth, setup, fleet ops, tests, SDLC, deploy/release, and evidence. After mb setup, an agent should start with the MCP tool mightybot.start_here.

mb setup — one-step provisioning

mb setup [auth flags]   # mb auth login + mb mcp install --agent all

Logs in (browser device auth) and registers the MCP server with all detected agents. Auth flags pass through (for example, --profile dev --base-url https://platform-dev.mightybot.ai). The installed MCP launcher defaults to prod; start mb --profile dev mcp for a profile-specific server.

mb auth — platform authentication

| Command | What it does | |---|---| | mb auth login [--profile NAME] | Browser device-code login; stores the token in a global named profile. | | mb auth inspect | Show the active profile/backend and token status. | | mb auth profile | Print the current auth profile (tenant, user, backend URL). | | mb auth configure | Set/switch the backend (base URL, environment). | | mb auth probe-write | Pre-flight check that the token can perform writes. |

Profiles live under ~/.mightybot/mb/profiles/ and work from every worktree. Omit --profile for built-in production, or run commands with mb --profile dev .... No last-used selection is persisted.

mb mcp — local design-time MCP server

| Command | What it does | |---|---| | mb mcp | Run the MCP server on stdio (what agents launch). | | mb mcp install [--agent codex,claude,opencode\|all] | Copy the binary to ~/.mightybot/mcp/mb and register it with the chosen agents. | | mb mcp register | Register an already-installed server with an agent. | | mb mcp update | Re-copy/re-register after a CLI upgrade. | | mb mcp uninstall | Remove the server registration. | | mb mcp status / mb mcp doctor | Show registration health / diagnose problems. | | mb mcp start / mb mcp stop | Start/stop the managed server. |

mb surface — inspect the workflow surface

mb surface overview      # high-level map of the workflow definition
mb surface resources     # resources referenced by the workflow
mb surface operations    # available builder operations
mb surface step          # step-level detail

mb workflow — workflow definitions (read/SDLC)

| Command | What it does | |---|---| | mb workflow list | List workflow definitions. | | mb workflow inspect <id> | Show a definition's full configuration. | | mb workflow create / update / duplicate / delete | Manage definitions. | | mb workflow export <id> | Write a definition's config to a local file (for diffing/backup). | | mb workflow fork <id> --target-org <id-or-name> | Copy a workflow into another organization you administer. Stages a background job. | | mb workflow export-job <job_id> | Check one copy job. | | mb workflow jobs <id> | List a workflow's recent copy/deploy/release jobs. | | mb workflow diff | Diff two definitions/versions. | | mb workflow versions / version / version-history / version-diff | Inspect version history and compare versions. |

Three verbs copy a workflow — pick by destination. export writes config to your local disk. duplicate copies within the same organization. fork copies into another organization you administer.

# Copy into another org. Lands a DRAFT there with secrets blanked.
mb workflow fork expense-approver --target-org "Acme Corp"
# → {"status_code": 202, "body": {"export_job_id": "...", "status": "PENDING"}}
# Like every mb command, the response is wrapped — read .body.export_job_id:
mb workflow fork expense-approver --target-org "Acme Corp" | jq -r .body.export_job_id

# Block until the copy — and its Git sync — settles. Exits non-zero if it failed,
# so this works as a CI gate.
mb workflow fork expense-approver --target-org "Acme Corp" --wait

# Or poll it yourself.
mb workflow export-job <export_job_id>
mb workflow jobs expense-approver

--target-org takes an organization id or an exact name. Omit it entirely to stage a same-org export. Other flags: --repo owner/name (target workflow repo), --branch (source branch to copy from), --no-config (shell only), --no-sync-to-git (skip the Git branch sync).

Forking needs platform super-admin, or admin in both the source and target organization, and the backend must run with WORKFLOW_CROSS_ORG_EXPORT_ENABLED.

mb git — git ↔ workflow sync state

mb git branches          # branches relevant to workflow definitions
mb git sync-status       # git/DB sync status
mb git auto-merge        # auto-merge eligible changes
mb git resource-state    # per-resource git state
mb git pr-status         # PR status for workflow changes

mb instance — workflow instances & their files

| Command | What it does | |---|---| | mb instance list / get <id> / stats | List, fetch, and summarize instances. | | mb instance create / patch / delete / close | Manage instances. | | mb instance repair / backfill | Maintenance operations. | | mb instance data | Inspect/manage instance data entries. | | mb instance file upload … | Upload a file to an instance. |

mb run — workflow runs (tests & evidence)

| Command | What it does | |---|---| | mb run test | Run a workflow end-to-end as a test. | | mb run create / partial | Start a full or partial run. | | mb run rerun | Re-execute a prior run. | | mb run list / inspect <id> | List runs / inspect one. | | mb run result <id> / files <id> | Fetch a run's result / output files. |

mb eval — evaluations

mb eval lists | list        # list eval sets / evals
mb eval run                 # run an evaluation
mb eval result              # fetch results
mb eval annotation          # annotations
mb eval comment | review    # commenting / review
mb eval packet              # export an eval packet

mb deploy — deploys

| Command | What it does | |---|---| | mb deploy draft / preview | Stage and preview a deploy. | | mb deploy release | Cut a release/deploy. | | mb deploy status / release-status | Check deploy/release status. | | mb deploy list / releases | List deploys / releases. |

mb release — release tagging

mb release tag suggest      # suggest the next release tag
mb release tag create       # create a release tag

mb view-serving — view-serving checks

mb view-serving smoke       # smoke-test served views
mb view-serving test        # run view-serving tests

Global flags

• --home <dir> — override HOME (where ~/.mightybot lives); useful for isolated/CI runs.
• --json after help — emit the full command catalog as JSON.

Under the hood

setup copies the binary to a stable location (~/.mightybot/mcp/mb, alongside its docs, re-signed for macOS) and registers that path — so the long-lived MCP server does not depend on the ephemeral npx cache. Re-run setup after an upgrade, then restart your agent so it reloads MCP.

Supported platforms

macOS arm64 (Apple Silicon), macOS x64 (Intel), Linux x64, Linux arm64, Windows x64 — npm installs only the package matching your machine.