Cheatsheet
mm-harness is the runner; these are its commands.
mm-harness <command> [target] [flags], from inside any MetaMask checkout. The
product is auto-detected; the positional target forces it; everything else is a flag on the same
command. Filter by what you actually work on.
Daily loop
What you run many times a day. The overlay is auto-ensured; you do not install it by hand.
| Situation | Command |
|---|---|
| Where am I, what is live, what is next | mm-harness status |
| …without waiting for live probes | mm-harness status --fast |
| Launch the extension (fullscreen) | mm-harness launch |
| Launch into the sidepanel | mm-harness launch --sidepanel |
| Launch beside a dapp | mm-harness launch --sidepanel --url <dapp-url> |
| Start / relaunch iOS | mm-harness launch ios |
| Start / relaunch Android | mm-harness launch android |
| Pick the device explicitly | mm-harness launch ios --device <udid|name> |
| Native or bundler output changed — clean build | mm-harness launch --build |
| Launch, then wait until it is genuinely ready | mm-harness launch --verify |
| Tail the dev server and app logs | mm-harness logs |
| Stop what this checkout owns | mm-harness stop |
| Open Chrome DevTools over CDP | mm-harness debug |
| Service-worker DevTools | mm-harness debug --worker |
| Open React Native DevTools | mm-harness debug |
| Open the RN developer menu | mm-harness debug --dev-menu |
stop is scoped to this checkout, so parallel checkouts are untouched, and it is
idempotent — stopping nothing is success.
Discover
You never guess capabilities. These commands print what exists; anything not listed does not exist for this checkout.
| Situation | Command |
|---|---|
| Every action available here | mm-harness actions |
| Just the categories and counts | mm-harness actions --categories |
| One UI category | mm-harness actions --category ui |
| Search (typo-tolerant) | mm-harness actions positions |
| One wallet action's fields, in detail | mm-harness actions --action read_state |
| One Core action's fields, in detail | mm-harness actions --action read_positions |
What call accepts here | mm-harness call --list |
| Recipes you can run here | mm-harness run --list |
| What a recipe does before running it | mm-harness run <recipe> --describe |
| The raw registry, for tooling | mm-harness actions --raw --json |
Drive one action
call runs a single action as a one-node recipe through the real engine path — the
same trace and evidence a full run produces. Short names resolve when unambiguous.
| Situation | Command |
|---|---|
| Read wallet state (redacted) | mm-harness call read_state |
| Unlock if locked | mm-harness call ensure_unlocked |
| Navigate by page intent | mm-harness call navigate page=perps |
| Press by visible text | mm-harness call press text="Account 1" |
| Capture a screenshot | mm-harness call screenshot path=proof.png |
| Run a shell command (every adapter) | mm-harness call command cmd="echo hi" |
| Pass a field the explicit way | mm-harness call navigate --arg page=perps |
| Keep wallet evidence somewhere you chose | mm-harness call read_state --artifacts-dir ./out |
| Keep Core evidence somewhere you chose | mm-harness call read_positions mode=all --artifacts-dir ./out |
| More than one device connected | mm-harness call read_state --device <udid> |
Prove — run recipes
| Situation | Command |
|---|---|
| Validate without touching anything (exit 5 if invalid) | mm-harness run <recipe> --plan |
| Execute and write evidence | mm-harness run <recipe> |
| Evidence in a directory you chose | mm-harness run <recipe> --artifacts-dir ./out |
| A recipe with parameters | mm-harness run perps.clean-market-testnet market=BTC |
| A recipe file on disk | mm-harness run ./my-recipe.json |
| Add a team recipe library | mm-harness run <recipe> --library perps=/path/to/library |
| Record video of the whole run (Extension or iOS) | mm-harness run <recipe> --record-video=full-run |
| Streaming progress for an agent | mm-harness run <recipe> --json-stream |
| What did I last run, and how did it go | mm-harness last |
Extension and iOS can record full-run video through capture-helper. Android replay video is not implemented yet; use screenshot evidence there.
Health and repair
| Situation | Command |
|---|---|
| Full readiness check — no launch, read-only | mm-harness doctor |
| Repair runtime state without launching | mm-harness doctor --fix |
| Findings in machine form | mm-harness doctor --json |
| Is the overlay present and healthy | mm-harness verify |
| Install the overlay explicitly (CI, agents) | mm-harness install |
| Remove the overlay, restore the checkout | mm-harness cleanup |
| Install a cached dev client on a prepared simulator | mm-harness provision runway ios --adapter mobile |
doctor --fix repairs what the harness owns. It will not launch the app, invent
credentials, or choose a wallet fixture — those need a human.
Wallet fixtures
One canonical fixture per checkout, holding wallet data only. The password is read from the fixture and never typed.
| Situation | Command |
|---|---|
| Status and the safe next command | mm-harness fixtures |
| Create from a fixture you already have | mm-harness fixtures init --from <path> |
| Create a disposable public test wallet | mm-harness fixtures init --dev |
| Apply it to the app (no typing) | mm-harness fixtures set |
| Refresh the fixture files on the target | mm-harness fixtures sync |
| Render pre-launch profile state | mm-harness fixtures generate --fixture <path> --out <path> |
A --dev fixture is a public test wallet. It must never hold real funds.
Repo checks
| Situation | Command |
|---|---|
| Lint/format/test just your diff | mm-harness check diff --profile fast |
| …and typecheck too | mm-harness check diff --profile full |
| Fix what is fixable, then validate | mm-harness check diff --fix |
| Write validation artifacts | mm-harness check diff --artifacts-dir artifacts/validation |
check is bounded to the active git diff. It launches no app and runs no recipe.
For agents and scripts
| Flag / concept | What it does |
|---|---|
--json | Machine-readable output on most commands. This is the agent contract. |
--json-stream | Line-flushed JSONL progress plus a terminal event, on run and launch. |
--heal off | Fail fast, preserve the repro. Nothing is repaired under you. |
--heal infra-only | Heal transport, never wallet state. Default for run and call. |
--heal auto | Auto-ensure the overlay and heal. Default for launch. |
--adapter | Force the product when auto-detection is not what you want. |
--target <path> | Operate on a checkout other than the current directory. |
--library <name=path> | Add or override a recipe-library source. Repeatable. |
Exit codes
| Code | Meaning | Whose problem |
|---|---|---|
0 | Success | — |
1 | Runtime / action failure | The thing under test. A real result. |
2 | Invalid CLI usage | Your command line. |
3 | Infrastructure failure | The environment — app or dev server. |
4 | Bounded recovery refusal | Healing hit its limit and stopped rather than thrashing. |
5 | Validation / trust failure | The recipe. Nothing executed. |
The distinction that matters when triaging: 1 means it ran and failed;
3 and 5 mean it never got to run.
Setup and upkeep
| Situation | Command |
|---|---|
| Install or update | npm i -g @deeeed/metamask-harness@latest |
| Update in place | mm-harness update |
| Is there a newer version (no install) | mm-harness update --check |
| Tab completion for zsh / bash | mm-harness completions install |
| Silence the daily update nudge | MM_HARNESS_NO_UPDATE_CHECK=1 |
| Point at a source checkout instead of the global install | MM_HARNESS_BIN=/path/to/checkout/bin/mm-harness |
Nothing on this page applies to that platform.
Your terminal wins. The CLI ships fast, and every command carries its own help:
mm-harness --help for the map, mm-harness <command> --help for
flags and worked examples. Run mm-harness update first — most disagreements are a
stale global install.