@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. 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.

Local stage recipes and printed plans use Bash on every platform. Windows requires Git Bash in its standard system or user installation, or SHELL set to the absolute bash.exe path. A missing Bash installation fails explicitly. Native Windows administration helpers remain independent of the stage shell.

Install

npm install -g @mutmutco/cli

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

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

Then verify the installed command:

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. This native MMI path requires no Jerv installation. mmi-cli learning report and mmi-cli oracle issue create are unaffected.
• 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 cloud dev stage without IP restrictions. 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.

Preparing a PR and reading status

mmi-cli devops pr create collects independent issue, claim, docs-index, test-policy and ref findings in one preparation report. Fix all listed findings before retrying. The read phase never posts claim markers. A same-branch resume restamps only after every required check passes; an unsuccessful restamp stops creation and is not retried automatically.

Preparation binds the head and target base commits and checks their identity again before writes. Docs and policy checks read those committed objects, including the candidate's policy and commit trailers, so a dirty local repair cannot certify the pushed branch. A different checkout or candidate objects unavailable locally produce an explicit skip; failed reads produce unavailable findings. These checks do not replace required CI or verification of the eventual combined candidate.

An absent same-repository head still publishes automatically when this checkout owns that exact branch and commit and its push target matches. Preparation observes that proof without writing; after every check passes, one push creates the absent ref and verifies the published commit. A competing ref, changed proof or ambiguous push stops creation without overwriting or retrying. When --base is omitted, branch.<head>.gh-merge-base wins over the repository default, matching gh pr create.

mmi-cli status --json retains successful legacy fields and adds typed observations for each source. An unavailable collection is null, never an empty array; unavailable stage state is null, never running: false. A successful empty read stays []. Board observations preserve source, build time, event cursor, credential provenance, partial-read warnings and explicit stale age. Text status labels unavailable and stale answers. A missing stage file means not running; malformed or unreadable state means unavailable. Repair the named read before treating a status count as current.

Auditing test-policy trailers

mmi-cli tests policy --json --base <base> uses the same override reader as the test-command gate. Its overriddenBy receipt retains the original commit SHA, complete Git-unfolded reason and scope. Ordinary trailers agree with git log --format='%(trailers:key=Test-Policy-Override,valueonly,unfold)'. If a final contiguous Co-authored-by: paragraph hides the prior trailer block, the reader removes only that paragraph and its optional --------- separator before running git interpret-trailers --parse --unfold. The receipt records messageTransform as strip-terminal-coauthors or strip-squash-separator-coauthors; the source commit is never rewritten. To audit that case, inspect the receipt's SHA with git show -s --format=%B <sha>, remove exactly the recorded terminal footer, and pass the remaining message to Git's interpreter. That message shape alone does not establish GitHub provenance. Intervening prose, mixed footer text, malformed wrapped reasons, unknown scopes and untrusted ranges remain subject to the existing refusals.

Native queues can append this footer even for a single source commit. Source preparation is not combined-message verification: install the matching shared reader in the CI consumer, then require the actual queue candidate to pass test policy and all other required checks.

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. Use mmi-cli learning skill-lesson for MMI skill feedback; mmi-cli learning report handles friction on org tooling. 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:

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

When reproducing or verifying CLI behavior from a checkout, always run the checkout's built node cli/dist/index.cjs — the globally installed mmi-cli can lag or diverge from this source (#6629), and a reproduction against the global install misreports the fix you are validating.

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.