diff --git a/README.md b/README.md index 5b39ced..eac2b62 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # MetaMask Agent CLI Skills -SKILLs for the MetaMask Agent CLI. These skills enable AI agents to authenticate, manage wallets, swap tokens, bridge across chains, trade perpetual futures, and more using the MetaMask Agent CLI. +SKILLs for the MetaMask Agent CLI (`@metamask/agentic-cli` v1.0.0). These skills enable AI agents to authenticate, manage wallets, swap tokens, bridge across chains, trade perpetual futures, and more using the MetaMask Agent CLI. ## Skills diff --git a/skills/metamask-agent-wallet/SKILL.md b/skills/metamask-agent-wallet/SKILL.md index 681e0fe..4f646cb 100644 --- a/skills/metamask-agent-wallet/SKILL.md +++ b/skills/metamask-agent-wallet/SKILL.md @@ -4,7 +4,8 @@ description: Use when the user asks anything about blockchain wallets, transacti license: MIT metadata: author: metamask - version: "2.1.0" + version: "2.2.0" + cliVersion: "1.0.0" --- # MetaMask Agentic CLI Skill @@ -28,6 +29,8 @@ Match the user's intent to a command and reference file, then read the reference | Sign in via email OTP | `mm login email` | [auth.md](references/auth.md) | | Sign out | `mm logout` | [auth.md](references/auth.md) | | Reset CLI session | `mm reset` | [auth.md](references/auth.md) | +| Show CLI configuration | `mm config get` | [auth.md](references/auth.md) | +| Set CLI configuration | `mm config set` | [auth.md](references/auth.md) | | Set BYOK mnemonic encryption password | `mm wallet password set` | [auth.md](references/auth.md) | | Change BYOK mnemonic encryption password | `mm wallet password change` | [auth.md](references/auth.md) | | Remove BYOK mnemonic encryption password | `mm wallet password remove` | [auth.md](references/auth.md) | @@ -127,7 +130,29 @@ Always use `--toon` for command output unless the user explicitly requests a dif ## Preflight -Always run preflight before any CLI operation. +Run these checks before the first CLI operation in a session, in order. + +### 1. Version compatibility + +This skill is written for `@metamask/agentic-cli` **v1.0.0** (see `cliVersion` in the frontmatter). Check the installed version: + +```bash +mm --version +``` + +The installed version is the value after `@metamask/agentic-cli/` (e.g. `@metamask/agentic-cli/1.0.0 darwin-arm64 node-v24.14.1`). Compare its `major.minor` against the pinned `cliVersion`. Optionally check the latest published version (best-effort; skip silently on network failure): + +```bash +npm view @metamask/agentic-cli 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 ``, this skill is pinned to `1.0.0`, latest release is ``. Command syntax in this skill may be inaccurate until they are aligned. Update the CLI with `npm install -g @metamask/agentic-cli@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. Authentication ```bash mm auth status diff --git a/skills/metamask-agent-wallet/references/auth.md b/skills/metamask-agent-wallet/references/auth.md index 760f084..1f70aef 100644 --- a/skills/metamask-agent-wallet/references/auth.md +++ b/skills/metamask-agent-wallet/references/auth.md @@ -34,6 +34,10 @@ export MM_PASSWORD="mypassword" mm init --wallet byok ``` +### Note + +- In server-wallet mode, if the account already has a remote EVM wallet, `mm init` syncs it and loads the existing trading mode and policies instead of prompting for a new trading mode or creating a wallet. + ## `init show` Command Display the current initialization settings (wallet mode, trading mode, policies). @@ -130,9 +134,78 @@ This command does not support flags. mm logout ``` +## `config get` Command + +Show persisted CLI configuration. Does not require authentication. + +### Syntax + +```bash +mm config get [env|verbose|format] +``` + +### Supported Keys + +| Key | Description | +| --- | --- | +| `env` | Target API environment: `prod`, `dev`, or `uat` (defaults to `prod` when unset) | +| `verbose` | Whether verbose logging is persisted (`true` or `false`) | +| `format` | Default output format: `json`, `text`, `yaml`, `toml`, or `toon` | + +Omit the key to return all values. + +### Example + +```bash +mm config get +mm config get env +``` + +## `config set` Command + +Persist a CLI configuration value in `~/.metamask/config.json`. Does not require authentication. + +### Syntax + +```bash +mm config set +``` + +### Supported Keys + +| Key | Values | +| --- | --- | +| `env` | `prod`, `dev`, or `uat` | +| `verbose` | `true` or `false` | +| `format` | `json`, `text`, `yaml`, `toml`, or `toon` | + +### Overrides + +Persisted values can be overridden per invocation without changing `~/.metamask/config.json`: + +| Key | Override | +| --- | --- | +| `env` | `MM_ENV` environment variable | +| `verbose` | `--verbose` / `-v` flag | +| `format` | `--format`, `--json`, `--toon`, etc. | + +### Example + +```bash +mm config set env prod +mm config set env dev +mm config set env uat +mm config set format toon +``` + +### Note + +- Switch environments at any time with `mm config set env `. +- Non-prod sessions are stored in env-scoped files under `~/.metamask/` (e.g. `session.dev.json`, `session.uat.json`); prod uses `session.json`. + ## `reset` Command -Clear the local CLI session entirely. +Clear the local CLI session entirely, including auth credentials, wallet state, mnemonic, swap quotes, and persisted config. ### Syntax diff --git a/skills/metamask-agent-wallet/references/errors.md b/skills/metamask-agent-wallet/references/errors.md index 15696f3..93e68e4 100644 --- a/skills/metamask-agent-wallet/references/errors.md +++ b/skills/metamask-agent-wallet/references/errors.md @@ -78,7 +78,9 @@ This reference lists error codes the CLI actually emits. SDK-only or remapped co | `MISSING_ID` | Missing ID parameter | | `MISSING_QUOTE_ID` | Missing quote ID | | `MISSING_SWAP_PARAMS` | Missing swap parameters | -| `COMING_SOON` | Feature not yet available (e.g. `mm login qr`) | +| `COMING_SOON` | Feature not yet available (e.g. `mm login qr` on production) | +| `INVALID_CONFIG_KEY` | Unknown config key passed to `mm config get` or `mm config set` | +| `INVALID_CONFIG_VALUE` | Invalid value for a config key (e.g. env not in `prod|dev|uat`) | ## Swap & Bridge Errors diff --git a/skills/metamask-agent-wallet/workflows/login.md b/skills/metamask-agent-wallet/workflows/login.md index fcf689a..1ae13ec 100644 --- a/skills/metamask-agent-wallet/workflows/login.md +++ b/skills/metamask-agent-wallet/workflows/login.md @@ -6,9 +6,10 @@ Reference command syntax in `references/auth.md`. ## Flow -1. Ask the user which login method they want: MetaMask Mobile QR, Google, or Email. -2. Execute login. -3. Verify with token. +1. Confirm the target environment with `mm config get env` (set with `mm config set env` before login if not `prod`). +2. Ask the user which login method they want: MetaMask Mobile QR, Google, or Email. +3. Execute login. +4. Verify with token. ## Login diff --git a/skills/metamask-agent-wallet/workflows/onboarding.md b/skills/metamask-agent-wallet/workflows/onboarding.md index f4453f1..f2b3f44 100644 --- a/skills/metamask-agent-wallet/workflows/onboarding.md +++ b/skills/metamask-agent-wallet/workflows/onboarding.md @@ -7,10 +7,11 @@ Reference command syntax in `references/auth.md` and `references/wallet.md`. ## Flow 1. Check CLI installation. -2. Login. -3. Initialize wallet mode. -4. Verify auth status. -5. Show wallet address. +2. Configure environment (if not using production). +3. Login. +4. Initialize wallet mode. +5. Verify auth status. +6. Show wallet address. ## Check CLI Installation @@ -18,7 +19,22 @@ Reference command syntax in `references/auth.md` and `references/wallet.md`. mm --version ``` -If this fails, the CLI is not installed. Guide the user to install it before proceeding. +If this fails, the CLI is not installed. Guide the user to install it with `npm install -g @metamask/agentic-cli@latest` before proceeding. + +Then run the version compatibility check from the skill `Preflight` section: compare the installed `major.minor` against the pinned `cliVersion` and the latest published release, and warn the user if they are out of sync. + +## Configure Environment + +Production (`prod`) is the default. Set the target environment **before** login if the user needs dev or uat: + +```bash +mm config get env +mm config set env dev +``` + +For a one-off override without persisting, use `MM_ENV=dev mm login` (or `uat`). + +To switch environments, run `mm config set env `. ## Login Flow @@ -49,7 +65,11 @@ First check if the project is already initialized: mm init show ``` -If already initialized, skip this step. Otherwise, ask the user which wallet mode they want: +If already initialized, skip this step. + +For server-wallet mode, if the account already has a remote wallet, `mm init` syncs it and reuses the existing trading mode — no trading-mode prompt. + +Otherwise, ask the user which wallet mode they want: - `server-wallet` (recommended) — keys are hosted by MetaMask infrastructure. No need to manage private keys or mnemonics. - `byok` — bring your own mnemonic. The user manages their own keys locally. diff --git a/skills/metamask-agent-wallet/workflows/troubleshooting.md b/skills/metamask-agent-wallet/workflows/troubleshooting.md index d1e1742..c709871 100644 --- a/skills/metamask-agent-wallet/workflows/troubleshooting.md +++ b/skills/metamask-agent-wallet/workflows/troubleshooting.md @@ -8,6 +8,7 @@ Run or suggest these in order: ```bash mm --version +mm config get env mm auth status mm --help ``` @@ -20,7 +21,7 @@ If `auth status` reports anything other than authenticated, fix authentication b | --- | --- | --- | | `mm: command not found` | Binary not installed or not on `PATH` | Check install and PATH | | Async command returns a polling id and appears stuck | Request was dispatched without `--wait` | Use `mm wallet requests list` or `mm wallet requests watch --polling-id ` | -| Auth errors after previously working | Expired token or wrong environment | Check `mm auth status` and environment/session file | +| Auth errors after previously working | Expired token or wrong environment | Check `mm config get env`, `mm auth status`, and the env-scoped session file under `~/.metamask/` | | `CHAIN_ID_MISMATCH` on typed data | Payload `domain.chainId` differs from `--chain-id` | Align the two chain IDs | | `MNEMONIC_LOCKED` or `WRONG_PASSWORD` | BYOK mnemonic is encrypted and password was wrong or missing | Set the correct `MM_PASSWORD` environment variable and re-run | | `ALREADY_ENCRYPTED` on `wallet password set` | Mnemonic already has a password | Use `mm wallet password change` instead | diff --git a/skills/metamask-agent-workflows/SKILL.md b/skills/metamask-agent-workflows/SKILL.md index 4c60a2c..76f791f 100644 --- a/skills/metamask-agent-workflows/SKILL.md +++ b/skills/metamask-agent-workflows/SKILL.md @@ -4,7 +4,8 @@ description: Use when the user needs to perform multi-step operations with the M license: MIT metadata: author: metamask - version: "2.0.0" + version: "2.1.0" + cliVersion: "1.0.0" --- # MetaMask Agent Workflows @@ -30,7 +31,29 @@ Always use `--toon` for command output unless the user explicitly requests a dif ## Preflight -Always run preflight before any CLI operation. +Run these checks before the first CLI operation in a session, in order. + +### 1. Version compatibility + +This skill is written for `@metamask/agentic-cli` **v1.0.0** (see `cliVersion` in the frontmatter). Check the installed version: + +```bash +mm --version +``` + +The installed version is the value after `@metamask/agentic-cli/` (e.g. `@metamask/agentic-cli/1.0.0 darwin-arm64 node-v24.14.1`). Compare its `major.minor` against the pinned `cliVersion`. Optionally check the latest published version (best-effort; skip silently on network failure): + +```bash +npm view @metamask/agentic-cli 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 ``, this skill is pinned to `1.0.0`, latest release is ``. Command syntax in this skill may be inaccurate until they are aligned. Update the CLI with `npm install -g @metamask/agentic-cli@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. Authentication ```bash mm auth status diff --git a/skills/metamask-agent-workflows/workflows/login.md b/skills/metamask-agent-workflows/workflows/login.md index fcf689a..1ae13ec 100644 --- a/skills/metamask-agent-workflows/workflows/login.md +++ b/skills/metamask-agent-workflows/workflows/login.md @@ -6,9 +6,10 @@ Reference command syntax in `references/auth.md`. ## Flow -1. Ask the user which login method they want: MetaMask Mobile QR, Google, or Email. -2. Execute login. -3. Verify with token. +1. Confirm the target environment with `mm config get env` (set with `mm config set env` before login if not `prod`). +2. Ask the user which login method they want: MetaMask Mobile QR, Google, or Email. +3. Execute login. +4. Verify with token. ## Login diff --git a/skills/metamask-agent-workflows/workflows/onboarding.md b/skills/metamask-agent-workflows/workflows/onboarding.md index f4453f1..f2b3f44 100644 --- a/skills/metamask-agent-workflows/workflows/onboarding.md +++ b/skills/metamask-agent-workflows/workflows/onboarding.md @@ -7,10 +7,11 @@ Reference command syntax in `references/auth.md` and `references/wallet.md`. ## Flow 1. Check CLI installation. -2. Login. -3. Initialize wallet mode. -4. Verify auth status. -5. Show wallet address. +2. Configure environment (if not using production). +3. Login. +4. Initialize wallet mode. +5. Verify auth status. +6. Show wallet address. ## Check CLI Installation @@ -18,7 +19,22 @@ Reference command syntax in `references/auth.md` and `references/wallet.md`. mm --version ``` -If this fails, the CLI is not installed. Guide the user to install it before proceeding. +If this fails, the CLI is not installed. Guide the user to install it with `npm install -g @metamask/agentic-cli@latest` before proceeding. + +Then run the version compatibility check from the skill `Preflight` section: compare the installed `major.minor` against the pinned `cliVersion` and the latest published release, and warn the user if they are out of sync. + +## Configure Environment + +Production (`prod`) is the default. Set the target environment **before** login if the user needs dev or uat: + +```bash +mm config get env +mm config set env dev +``` + +For a one-off override without persisting, use `MM_ENV=dev mm login` (or `uat`). + +To switch environments, run `mm config set env `. ## Login Flow @@ -49,7 +65,11 @@ First check if the project is already initialized: mm init show ``` -If already initialized, skip this step. Otherwise, ask the user which wallet mode they want: +If already initialized, skip this step. + +For server-wallet mode, if the account already has a remote wallet, `mm init` syncs it and reuses the existing trading mode — no trading-mode prompt. + +Otherwise, ask the user which wallet mode they want: - `server-wallet` (recommended) — keys are hosted by MetaMask infrastructure. No need to manage private keys or mnemonics. - `byok` — bring your own mnemonic. The user manages their own keys locally. diff --git a/skills/metamask-agent-workflows/workflows/troubleshooting.md b/skills/metamask-agent-workflows/workflows/troubleshooting.md index d1e1742..c709871 100644 --- a/skills/metamask-agent-workflows/workflows/troubleshooting.md +++ b/skills/metamask-agent-workflows/workflows/troubleshooting.md @@ -8,6 +8,7 @@ Run or suggest these in order: ```bash mm --version +mm config get env mm auth status mm --help ``` @@ -20,7 +21,7 @@ If `auth status` reports anything other than authenticated, fix authentication b | --- | --- | --- | | `mm: command not found` | Binary not installed or not on `PATH` | Check install and PATH | | Async command returns a polling id and appears stuck | Request was dispatched without `--wait` | Use `mm wallet requests list` or `mm wallet requests watch --polling-id ` | -| Auth errors after previously working | Expired token or wrong environment | Check `mm auth status` and environment/session file | +| Auth errors after previously working | Expired token or wrong environment | Check `mm config get env`, `mm auth status`, and the env-scoped session file under `~/.metamask/` | | `CHAIN_ID_MISMATCH` on typed data | Payload `domain.chainId` differs from `--chain-id` | Align the two chain IDs | | `MNEMONIC_LOCKED` or `WRONG_PASSWORD` | BYOK mnemonic is encrypted and password was wrong or missing | Set the correct `MM_PASSWORD` environment variable and re-run | | `ALREADY_ENCRYPTED` on `wallet password set` | Mnemonic already has a password | Use `mm wallet password change` instead |