# @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:

```bash
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:

```bash
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:

```bash
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:

```bash
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:

```bash
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

```bash
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

```bash
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.

```bash
# 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

```bash
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

```bash
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

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

### `mb view-serving` — view-serving checks

```bash
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.