MetaMask Agentic CLI Skill

This skill documents the mm CLI surface for MetaMask Agent Wallet authentication, wallet lifecycle, balance queries, token transfers, message and typed-data signing, raw transactions, chain discovery, market data, token discovery, perpetual futures trading, prediction market trading, prediction trade/redeem history, token swaps, cross-chain bridges, DeFi earn/yield vaults, and EVM calldata decoding.

Use the routing table to select the relevant reference file. CLI behavior lives in references/. Repeatable operational patterns live in workflows/.

Command Routing

Match the user's intent to a command and reference file, then read the reference before constructing a command. If intent spans multiple domains, load them sequentially in dependency order.

Workflows

CLI behavior lives in references/. Repeatable patterns live in workflows/. Load a workflow file when the user's request is a pattern, not a single command.

Global Flags

Every mm command accepts these flags:

Always use --toon for command output unless the user explicitly requests a different format.

The mm plugins commands are the exception. They come from oclif and accept none of these global flags, so mm plugins --toon fails with Nonexistent flag: --toon. Use --json or plain text there. See plugins.md.

Preflight

Run these checks before the first CLI operation in a session, in order.

1. Version compatibility

This skill is written for @metamask/agent-wallet v7.0.0, as specified by cliVersion in the frontmatter. The CLI requires Node.js 22.18 or later; on an older runtime every command exits 1 with UNSUPPORTED_NODE before the CLI loads. Check the installed version:

mm --version

The installed version is the value after @metamask/agent-wallet/, such as @metamask/agent-wallet/7.0.0 darwin-arm64 node-v22.18.0. Compare its major.minor against the pinned cliVersion. Optionally check the latest published version (best-effort, skip silently on network failure):

npm view @metamask/agent-wallet version

If the installed major.minor differs from the pinned cliVersion, or the installed version is behind the latest release, warn the user once and continue:

Version mismatch: installed CLI <installed>, this skill targets <cliVersion>, latest release is <latest>. Command syntax in this skill may be inaccurate until they are aligned. Update the CLI with npm install -g @metamask/agent-wallet@latest, then re-install the skills with npx skills add metaMask/agent-skills.

Run this check once per session. Do not block operations on it.

2. Readiness gate — authentication and initialization

mm doctor is the single readiness check. Run it before the first CLI operation in a session:

mm doctor

It reports an authenticated boolean, an initialized boolean, and a list of hints. Do not run any other command until mm doctor reports both authenticated: true and initialized: true. Authentication and initialization are independent gates: a session can be authenticated while the project has no wallet mode selected, in which case any command that needs a wallet aborts before running with NOT_INITIALIZED — "Project not initialized." with hint: Run mm init to set up wallet and trading modes.

A project counts as initialized only when a wallet mode is set — and, for server-wallet, a trading mode is set as well. byok needs only the wallet mode. Do not use mm init show as the check: it requires an initialized project and throws NOT_INITIALIZED on an uninitialized one rather than reporting state.

Remediate, then re-run mm doctor and confirm a clean result before doing anything else:

• authenticated: false → follow workflows/login.md, or workflows/onboarding.md for first-time setup, to run mm login.
• authenticated: true and initialized: false → follow workflows/onboarding.md to run mm init and select a wallet mode. For server-wallet, also select a trading mode.

Safety Rules

These rules apply to every operation, regardless of which reference or workflow is active.

Input Validation

Before constructing any command, validate all user-provided values:

Do not pass unvalidated user input into any command.

Confirmation Requirements

Credential Safety

• Never store, log, or display private keys, mnemonics, passwords, or auth tokens.
• Never pass --password or --mnemonic as inline flags. Always instruct the user to set the MM_PASSWORD and MM_MNEMONIC environment variables instead to avoid exposing secrets in shell history.

Suspicious Content Warnings

Flag to the user before proceeding if a signing payload or transaction contains:

• URLs or contract addresses the user did not provide
• permit, approve, setApprovalForAll, or allowance-like fields
• Unusually large values or unfamiliar contract interactions

When raw calldata is unfamiliar or was not constructed by you, run mm decode --payload <0x-calldata> first and confirm the decoded intent with the user before signing or sending. See decode.md.

Async Model

In both server-wallet and BYOK mode, signing and transaction commands go through a job-polling loop and return a pollingId. Handle this consistently:

1. Prefer --wait to block until complete.
2. If not using --wait, inform the user of the pollingId and how to track it:
   • mm wallet requests list
   • mm wallet requests watch <polling-id>
3. In BYOK mode, the local key signs locally but the operation still produces a pending job and a pollingId. If the mnemonic is password-encrypted, the user must set MM_PASSWORD environment variable to unlock it for the operation.

Transfers, swaps, perps, predict orders, and predict withdraws attach a human-readable intent summary to their wallet request, such as Transfer 0.5 ETH to 0x... or Withdraw 10 pUSD to 0x.... When surfacing a pending request from wallet requests list or wallet requests watch, show the intent summary so the user can confirm what they are approving.

MFA Approval Pauses

Wallet jobs that need out-of-band MFA approval pause in AWAITING_MFA. Detect this pause by scanning command stdout for the literal token AWAITING_MFA. Do not infer MFA from free-text alone on older CLIs; from CLI v6.1.5 onward every output mode emits the token consistently.

When AWAITING_MFA appears:

1. Treat the command as waiting for user approval, not failed, hung, or complete.
2. Surface the human instruction from the notice to the user.
3. If a pollingId is present in the notice or command output, tell the user they can track completion with mm wallet requests watch <polling-id>.
4. Do not retry the same wallet operation while the job is still pending.
5. On mm swap execute, mm earn supply, or mm earn withdraw, an MFA pause with no hash yet may return EXECUTE_FAILED with a message naming the approval wait and mm wallet requests watch <polling-id> — that is still an MFA pause, not a missing hash.

For approval surfaces and recovery steps, see troubleshooting.md.

Output Rules

• Route silently. Do not announce which reference you are loading.
• Surface errors from commands verbatim. Do not mask or reword them.
• If a command fails, check mm <command> --help and guide from there.