@mutmutco/cli

The command-line engine for MMI Future org tooling. It delivers the org spine, reads and claims GitHub Project work, records saga continuity notes, and exposes the model-agnostic commands used by the MMI plugin and non-Claude agents.

This package is published from mutmutco/MMI-Hub and its version matches the MMI Hub Claude Code and Codex plugin versions (the release train bumps all of them in lockstep).

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

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 rules sync delivers the org-owned AGENTS.md, CLAUDE.md, and Claude settings files.
• mmi-cli docs sync refreshes repo-owned README.md and architecture.md without clobbering dirty files.
• mmi-cli saga note, saga show, saga health, saga session, saga capture, and saga head-update write and inspect session continuity through a cached Hub session token. Saga writes are local-first: a transient server miss queues the note in a local pending file and a detached flush worker delivers it — a queued note is normal, not a failure.
• mmi-cli handoff open|list|accept|cancel|decline records explicit same-login, same-repo session handoffs bound to North Star slugs; SessionStart offers open handoffs alongside saga HEAD.
• mmi-cli kb get and kb list read the MM KB source (kb list [prefix] lists document paths, optionally under a prefix).
• mmi-cli northstar push|pull|list|status|sync|delete|graduate manages North Star, the per-user plan/SSOT store. northstar push accepts --body-file <path|-> to write and push in one step (or push an existing plans/<slug>.md). It is async by default — it queues a durable background push and prints a "queued" line, which is the expected success path. northstar pull/show auto-resolve a unique cross-project slug when manual list shows plans from other repos. northstar status shows pending/conflicted pushes; northstar sync (or push --wait) gives durable server confirmation. Never treat a queued push as failure. northstar graduate <slug> --merged-pr <url-or-number> --org-visible marks a built-and-merged plan for KB curation without echoing the plan body. mmi-cli plan remains a compatibility alias.
• mmi-cli secrets where|list|get|set|edit|rm|use|grant|revoke manages two-tier project/org secrets without logging values; where prints the vault layout + well-known keys, and values move over TLS in the request body — never an argument.
• mmi-cli project list|get|resolve|doctor|heal|readiness|set reads and repairs Hub-owned v2 readiness state. doctor --json diagnoses central deploy/secrets readiness, heal --apply fixes only registry-owned defaults, and readiness --update-issue updates the repo's v2 readiness issue; set is master-only and supports explicit field unsets.
• mmi-cli registry org reads org-level constants from the registry (ORG#config).
• mmi-cli 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 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 issue link-child <parent> <child> links two existing issues the same way.
• mmi-cli 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 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 pr create, pr merge, and pr land (train probe → checks-wait → merge --auto — #1440) create/land PRs with branch/worktree cleanup; mmi-cli ci audit / ci reconcile scan fleet merge-readiness; mmi-cli gc dry-runs cleanup of merged/closed PR branches + stale tracking refs.
• mmi-cli board read|claim|show|move|done|backfill-priority reads and moves GitHub Project work.
• mmi-cli 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 port-range <repo> manage the local gitignored stage and its port block; stage-live explains that remote rc/live move only via /rcand · /release · /hotfix.
• mmi-cli 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 bootstrap, bootstrap verify, and bootstrap apply plan, audit, and seed repo onboarding.
• mmi-cli 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 saga, North Star, 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 or mmi-cli <command> --help for the full command reference.

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

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.