# @mutmutco/cli

The command-line engine for MMI Future org tooling. It delivers the org-managed `.gitignore` block, reads and claims GitHub Project work, and exposes the model-agnostic commands used by the MMI plugin and non-Claude agents. Personal agent guides (`AGENTS.md` / `CLAUDE.md`) are developer-owned and gitignored.

This package is published from [mutmutco/MMI-Hub](https://github.com/mutmutco/MMI-Hub). The release train derives its version, publication target, and artifact identity from the shared surface registry and bill of materials alongside every active host adapter.

The CLI carries the org **Hub endpoint** intrinsically (override with the `MMI_HUB_URL` env var), so a product repo needs **no committed control-plane config** to reach the Hub — board coords, deploy coordinates, OAuth, and the secrets layout are all discovered from the Hub registry at runtime.

## Install

```powershell
npm install -g @mutmutco/cli
```

Authenticate GitHub once for Hub session issuance and Project board operations:

```powershell
gh auth login --hostname github.com --git-protocol https --web --scopes "project"
```

Then verify the installed command:

```powershell
mmi-cli --version
mmi-cli doctor --json
```

## Main Commands

- `mmi-cli devops org rules gitignore [--write]` verifies or updates this repo's org-managed `.gitignore` block; personal agent guides remain developer-owned.
- `mmi-cli devops bootstrap org-ruleset` drift-checks the codified org no-agent-files push ruleset (`mmi-no-agent-files-org`) against the live org config; read-only, never mutates.
- `mmi-cli vault secrets where|list|set|rm|use` manages the full own-project vault for project-admins without logging values; org-infra remains master-gated and exactly grantable. `where` prints the layout, and values move only through stdin/TLS/keyless command injection—never an argument or stdout. Operational grant/catalog commands are available through all-command discovery.
- `mmi-cli oracle org project list|get|doctor|heal|set` reads and repairs the Hub v3 registry; `org project deploy get` resolves deploy coordinates. `doctor --json` diagnoses central deploy/secrets readiness, `heal --apply` fixes only registry-owned defaults, and `set` is master-only except for the explicit project-admin self-service routes.
- `mmi-cli oracle org config get` reads org-level constants from the registry (`ORG#config`).
- `mmi-cli vault org oauth plan|verify` prints a repo's canonical Google OAuth URI set when the registry declares an `oauth` block and verifies the client is port-agnostic.
- `mmi-cli oracle issue create` creates typed, prioritized GitHub issues (priority sets the board field, not a label) and queues related-issue discovery. `--parent <ref>` files the new issue as a native GitHub sub-issue of a parent (works cross-repo); `mmi-cli oracle issue link-child <parent> <child>` links two existing issues the same way.
- `mmi-cli learning report` files a friction report on the Hub board with your GitHub identity, deduping against the open `report`-labeled issues (a confident duplicate becomes a +1 comment, not a new issue). No repo-local `.env`, no API key, no copied report script.
- `mmi-cli learning skill-lesson --skill <name>` files a **skill-lesson** on the Hub board when a skill's own instructions misfire — the cross-skill generalization of grind's Retro. GitHub identity, its own `skill-lesson` label + dedup pool (a confident duplicate becomes a +1 comment), and a footer pinning the source checkout + plugin SHA. Advisory: the fix lands via a reviewed PR to the skill in MMI-Hub, never a live edit.
- `mmi-cli devops pr create`, `pr merge`, and **`pr land`** (train probe → checks-wait → merge --auto — #1440) create and land PRs. **`mmi-cli devops ci audit`** / **`ci reconcile`** scan fleet merge-readiness. Local workspace lifecycle is host-owned.
- `mmi-cli oracle board read|claim|show|move|done` reads and moves GitHub Project work.
- `mmi-cli devops runtime tenant control <owner/repo> <stage> <status|start|stop|restart>` runs bounded dev/rc box control for project-admins through the Hub API; main remains master-only.
- `mmi-cli stage`, `stage start`, `stage stop`, `stage run`, and `stage port-range <repo>` manage the local gitignored stage and its port block; `stage --live` is the personal IP-gated cloud dev stage. Remote rc/live environments move only via `/rcand` · `/release` · `/hotfix`.
- `mmi-cli devops rcand`, `release`, and `hotfix` render guarded train plans; product trains trigger the Hub's central tenant deployer, while MMI-Hub releases directly from `development` to `main`.
- `mmi-cli devops bootstrap`, `bootstrap verify`, and `bootstrap apply` plan, audit, and seed repo onboarding.
- `mmi-cli oracle org access audit` checks collaborator roles and train-branch allowlists.
- `mmi-cli doctor` checks GitHub auth, repo config, CLI availability, plugin install/config/version state, and stale MMI plugin cache dirs, auto-repairing the safe gaps.

Hub API calls do not send the raw GitHub token on every request. The CLI exchanges it at `/auth/session`
for a Hub-issued session credential, caches that credential outside repo-tracked files, and uses it for
registry, secrets, train-authority, and tenant-control calls until it nears expiry.
The cache is bound to the current local GitHub token fingerprint, so switching `gh auth` users forces a
new Hub session instead of reusing the previous user's bearer credential.

Run `mmi-cli --help` for the task map, `mmi-cli commands --json` for bounded machine routes, and
`mmi-cli explain <command> --json` for exact arguments/options/examples. The exhaustive
`mmi-cli commands --all --json` manifest names every implementation module and consumer. That inventory
is checked when the runtime tree is assembled, so a sixth command domain cannot land ownerless.

## Capability seams — mmi-cli vs jerv-cli (#3000)

`mmi-cli` is the **org** CLI (rules delivery, board/issue/PR work, registry, secrets, release train,
deploy plane). `jerv-cli` is Suphi's **personal** power-tools CLI (Jerv's Memory continuity, fusion
lanes, personal workflow). The 2026-07 audit (#2994) pinned the boundary; these are the seams, so
they don't get re-derived or re-litigated per session:

- **Workspace ownership.** The agent and host own local worktree lifecycle. MMI carries issue, PR, CI,
  merge, and board facts only; its retained worktree verbs are legacy compatibility and never set the
  workspace policy.
- **Session observability flows org → personal, never back.** `mmi-cli learning report session` exists to feed
  `jerv-cli save` (a machine summary of touched issues/PRs/worktrees/deploys for a memory save or
  handoff). jerv-cli never writes org state; mmi-cli never writes Jerv's Memory.
- **Intentional duplicates — keep both.** `skill-lesson` exists in both CLIs by design: each files to
  its own owning board. `doctor`, `whoami`, `commands`, and `explain` are per-CLI meta
  infrastructure; a shared library across the two repos is not worth the version churn.

## Repo-Local Fallback

When working inside an `MMI-Hub` checkout before npm is available, use the committed bundle directly:

```powershell
node cli/dist/index.cjs --version
node cli/dist/index.cjs doctor --json
```

The Claude Code plugin also ships its own `bin/mmi-cli` launcher, so plugin-enabled Bash sessions can use the bundled command even without a global npm install. Codex and other non-Claude surfaces use the standalone npm package or this repo-local fallback.